Thanks to visit codestin.com
Credit goes to github.com

Skip to content

docs: realign maintainer docs with the 2.8.0 architecture - #645

Merged
ndycode merged 2 commits into
mainfrom
docs/architecture-refresh-2026-07-29
Jul 29, 2026
Merged

docs: realign maintainer docs with the 2.8.0 architecture#645
ndycode merged 2 commits into
mainfrom
docs/architecture-refresh-2026-07-29

Conversation

@ndycode

@ndycode ndycode commented Jul 29, 2026 •
edited by greptile-apps Bot
Loading

Copy link
Copy Markdown
Owner

Audit of every markdown file in the repo against the v2.8.0 source, then a rewrite of what had gone stale.

What was already correct

Worth stating up front, because it bounds the problem. Machine-checked against the code and found clean:

  • Internal links — 0 broken across all 151 tracked markdown files
  • npm run references — every one resolves to a real script
  • Repo path references — every backticked lib/…, scripts/…, test/… path exists
  • All 54 pluginConfig defaults in settings.md — byte-match DEFAULT_PLUGIN_CONFIG
  • Error-contract codes — exactly the three the proxy emits
  • Documented env vars — all 62 still exist in shipped code

The docs are partly guarded by test/documentation.test.ts, which is why the structural surface held up. The drift was semantic, in maintainer docs, and dated to 2.7.1/2.8.0 landing after those files were last touched.

What was stale

Runtime rotation described a flow that no longer exists. ARCHITECTURE.md and CONFIG_FLOW.md both said the wrapper always creates a shadow CODEX_HOME and rewrites config.toml. Since #639 there are three transports selected in createRuntimeRotationProxyContextIfEnabled:

Branch Predicate Transport
Interactive TUI no forwarded subcommand canonical CODEX_HOME + ephemeral -c overrides; no shadow, no sync-back, config.toml untouched
codex app forwarded command is app app runtime helper + shadow home
Everything else request-bearing command shadow home + config.toml rewrite

Documented all three, plus why the interactive branch can safely skip locking.

First-run setup was missing its third step. Docs listed app bind + launcher. 2.8.0 added the cli_auth_credentials_store pin, marker versioning (FIRST_RUN_MARKER_VERSION = 2), and in-place v1 migration — including why a failed auth-store step deliberately records the pre-v2 version so it retries.

CONFIG_FIELDS.md claimed a complete inventory but omitted 21 real env vars. Added in five verified groups. Three of my first-pass descriptions were wrong when checked against source and were corrected: RUNTIME_SHADOW_COPY_GENERATED_DIRS is a boolean (not a dir list), CODEX_THREAD_ID takes precedence over the prompt cache key, and STREAM_FAILOVER_MAX is clamped to a ceiling of 1.

Three reference docs were stamped 2.6.1 through 2.7.0, 2.7.1, and 2.8.0. Corrected and pinned to package.json by a new documentation.test.ts case — same failure class the existing AGENTS.md check guards. Confirmed the new guard fails when a stamp is wrong.

Also

  • unsupportedCodexFallbackChain and rotation reset-runtime were undocumented
  • lib/codex-cli/ was absent from both ownership maps despite being the published ./cli export and the home of the 2.8.0 change
  • Both command runbooks were rewritten around the CLI_COMMAND_HANDLERS dispatcher, documenting the two-registry trap: registering a command without adding it to ACCOUNT_MANAGER_COMMANDS silently breaks the bare codex-multi-auth <name> form
  • Test counts corrected from 4909/317 to the measured 5274 across 336 files
  • The 14 April-2026 local-governance planning docs read as live status for work shipped in 2.1.0/2.2.0; marked historical rather than deleted — removal is a maintainer call

Judgment calls

  • docs/release-local-governance in two planning tables is a git branch name, not a path. Left alone.
  • Planning docs archived in place, not deleted.

Verification

  • npm run typecheck — clean
  • npm run lint — clean
  • Full suite — 5268 passed, 6 skipped (336 files)
  • test/documentation.test.ts — 29/29
  • 0 broken internal links

Docs and one test file only; no runtime code touched.

🤖 Generated with Claude Code

https://claude.ai/code/session_01BaAqj4XiyF9WUFXCQn7oiQ

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 realigns maintainer documentation with the 2.8.0 architecture.

  • documents canonical-home and shadow-home runtime rotation transports.
  • documents first-run auth-store migration, command registration, configuration fields, and repository ownership.
  • archives completed governance plans and updates reference versions and test counts.
  • adds vitest guards for package-version stamps, environment-variable references, and reset-runtime documentation.

Confidence Score: 5/5

the pr appears safe to merge.

no blocking failure remains.

Important Files Changed
Filename Overview
docs/development/ARCHITECTURE.md documents the three runtime transports, first-run migration, token safety, windows filesystem handling, and explicit concurrency boundaries.
docs/development/CONFIG_FIELDS.md expands the environment-variable inventory and clarifies effective defaults and precedence.
docs/development/CONFIG_FLOW.md updates configuration flow for canonical-home and shadow-home runtime rotation.
docs/development/RUNBOOK_ADD_AUTH_COMMAND.md documents both command registries and the required dispatch coverage.
docs/development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md explains the two-registry dispatch contract and bare-command failure mode.
docs/reference/commands.md updates the package stamp and documents current command behavior.
docs/reference/settings.md updates the package stamp and aligns configuration references with current defaults.
test/documentation.test.ts adds vitest coverage for reference-version stamps, environment names, and reset-runtime documentation.

Flowchart

 
%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[forwarded codex invocation] --> B{runtime rotation enabled?}
  B -- no --> C[official codex cli]
  B -- yes --> D{forwarded command}
  D -- interactive tui --> E[canonical CODEX_HOME plus ephemeral overrides]
  D -- codex app --> F[app helper plus shadow CODEX_HOME]
  D -- other request command --> G[inline shadow CODEX_HOME]
  E --> H[loopback rotation proxy]
  F --> H
  G --> H
  H --> I[official codex backend]
Loading

Reviews (2): Last reviewed commit: "docs: address review findings on the 2.8..." | Re-trigger Greptile

@ndycode @claude
docs: realign maintainer docs with the 2.8.0 architecture
85e9300 
An audit of every markdown file against the v2.8.0 source. Structural
claims were already sound — internal links, npm-script references, repo
paths, all 54 pluginConfig defaults, and the error-contract codes all
verified clean, and no documented env var has been removed. The drift was
semantic, concentrated in maintainer docs, and traceable to 2.7.1 and
2.8.0 landing after those files were last touched.

Runtime rotation transports. ARCHITECTURE.md and CONFIG_FLOW.md both
described a single path: always create a shadow CODEX_HOME and rewrite
config.toml. Since #639 there are three transports, chosen in
createRuntimeRotationProxyContextIfEnabled. Interactive TUI sessions
(no forwarded subcommand) now run against the canonical CODEX_HOME with
the provider passed as ephemeral -c overrides — no shadow copy, no
sync-back, and config.toml is never rewritten on that path. Documented
all three branches with their predicates, plus why the interactive branch
can skip locking.

First-run setup. Documented only app bind and launcher; 2.8.0 added a
third step that pins cli_auth_credentials_store, along with marker
versioning and in-place v1 migration. Added both, including why a failed
auth-store step deliberately records the pre-v2 version.

Env inventory. CONFIG_FIELDS.md claimed a complete inventory while
omitting 21 env vars that exist in shipped code. Added them in four
groups (Codex CLI state paths, rotation transport internals, auth flow,
plugin-host pipeline, benchmark scripts), each description read off the
source rather than inferred.

Version stamps. commands.md, public-api.md, and settings.md were stamped
2.6.1 across three releases. Corrected, and pinned to package.json by a
new documentation.test.ts case so they cannot drift again silently —
the same failure class the existing AGENTS.md check already guards.

Also: added the missing unsupportedCodexFallbackChain setting and the
rotation reset-runtime subcommand to the references; added lib/codex-cli/
to both ownership maps, where it was absent despite being a published
export; rewrote both command runbooks around the CLI_COMMAND_HANDLERS
dispatcher, including the two-registry trap where skipping
ACCOUNT_MANAGER_COMMANDS silently breaks the bare command form; corrected
test counts to the measured 5274 across 336 files; and marked the 14
April-2026 local-governance planning docs as historical, since they read
as live status for work that shipped in 2.1.0 and 2.2.0.

Verified: typecheck, ESLint, and the full suite (5268 passed, 6 skipped)
green; 0 broken internal links.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_01BaAqj4XiyF9WUFXCQn7oiQ
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Jul 29, 2026

Copy link
Copy Markdown

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

coderabbitai Bot commented Jul 29, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 6947554d-6859-4ea1-bced-4241c664a00b

📥 Commits

Reviewing files that changed from the base of the PR and between 85e9300 and a33e25d.

📒 Files selected for processing (23)
  • docs/development/ARCHITECTURE.md
  • docs/development/CONFIG_FIELDS.md
  • docs/development/CONFIG_FLOW.md
  • docs/development/RUNBOOK_ADD_AUTH_COMMAND.md
  • docs/development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md
  • docs/development/implementation-plans/subagent-handoffs/README.md
  • docs/development/implementation-plans/subagent-handoffs/pr-01-roadmap-local-governance.md
  • docs/development/implementation-plans/subagent-handoffs/pr-02-usage-ledger-core.md
  • docs/development/implementation-plans/subagent-handoffs/pr-03-usage-command.md
  • docs/development/implementation-plans/subagent-handoffs/pr-04-account-policy-controls.md
  • docs/development/implementation-plans/subagent-handoffs/pr-05-routing-profiles-core.md
  • docs/development/implementation-plans/subagent-handoffs/pr-06-budget-guard.md
  • docs/development/implementation-plans/subagent-handoffs/pr-07-model-capability-matrix.md
  • docs/development/implementation-plans/subagent-handoffs/pr-08-runtime-policy-integration.md
  • docs/development/implementation-plans/subagent-handoffs/pr-09-monitor-command.md
  • docs/development/implementation-plans/subagent-handoffs/pr-10-local-bridge-core.md
  • docs/development/implementation-plans/subagent-handoffs/pr-11-local-client-tokens.md
  • docs/development/implementation-plans/subagent-handoffs/pr-12-integration-generators.md
  • docs/development/implementation-plans/subagent-handoffs/pr-13-release-local-governance.md
  • docs/reference/commands.md
  • test/AGENTS.md
  • test/README.md
  • test/documentation.test.ts

Cache: Disabled due to data retention organization setting

Knowledge base: Disabled due to data retention organization setting

📝 Walkthrough

Minor-risk documentation-only update (no runtime code/behavior changes). Security/data-loss risk appears low; the main security-related work is clarifying keychain handling boundaries (no security CLI interaction; only top-level TOML assignment rewrites) and interactive transport guarantees, while regression coverage was strengthened via documentation tests and a new guard preventing reference-doc version-stamp drift. Reviewers should focus on the v2.8.0-aligned architectural descriptions: runtime-rotation’s three transport branches and selection predicates, first-run auth-store/marker/version migration semantics, and the command-dispatch “two-registry” contract (CLI_COMMAND_HANDLERS + ACCOUNT_MANAGER_COMMANDS), including reset-runtime behavior.

  • Updated architecture/runtime-rotation documentation: three transport modes, transport-branch predicates, shadow-vs-canonical CODEX_HOME behavior, proxy startup details, rotation triggers/cleanup/sync, and interactive-mode correctness/invariants.
  • Expanded first-run setup documentation: auth-store configuration, marker versioning, v1 migration behavior, and explicit repair expectations.
  • Completed/corrected configuration documentation: added a comprehensive environment-variable inventory with corrected descriptions, including rotation transport internals, auth/OAuth overrides, plugin-host pipeline/failover controls, and tooling timeouts.
  • Documented new/changed concepts: unsupportedCodexFallbackChain and rotation reset-runtime; clarified interactive persistence, session-state locking scope, failover defaults, and reset-runtime semantics.
  • Updated operational/docs tooling: command runbooks rewritten around CLI_COMMAND_HANDLERS and the two-registry requirement; fixed stale version stamps and corrected documentation structure (including heading violation and handoff-banner path issues); added documentation guardrails for shipped env/state legacy aliases and reset-runtime.
  • Refreshed ownership/documentation scope: added lib/codex-cli/ to ownership maps and updated repository scope mapping.
  • Marked legacy local-governance planning docs as historical and corrected test-count metadata.
  • Added verification to prevent doc drift: documentation tests plus a new test asserting (package x.y.z) reference-doc stamps match package.json packageVersion.

Verification reported: typechecking, linting, full test suite, documentation tests, and internal-link checks all passed.

Walkthrough

the pr updates runtime-rotation architecture, configuration, command runbooks, release references, historical planning notices, and documentation-integrity metadata. it adds a test that checks reference-document package versions against package.json.

Changes

runtime-rotation documentation

Layer / File(s) Summary
transport, state, and configuration flow
docs/development/ARCHITECTURE.md, docs/development/CONFIG_FLOW.md		 documents three runtime-rotation transports, startup auth-store reconciliation, first-run migration behavior, shadow-home synchronization, keychain boundaries, and interactive canonical-home invariants.
configuration inventory
docs/development/CONFIG_FIELDS.md		 documents Codex CLI state paths, transport internals, OAuth overrides, plugin-host controls, and benchmark timeouts.

repository and command guidance

Layer / File(s) Summary
ownership and command workflows
docs/development/REPOSITORY_SCOPE.md, docs/development/RUNBOOK_ADD_AUTH_COMMAND.md, docs/development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md		 expands ownership and command-dispatch guidance, including dual registration, injected dependencies, stable JSON output, documentation/testing updates, and lint usage.

reference and planning documentation

Layer / File(s) Summary
reference contracts and validation
docs/reference/commands.md, docs/reference/public-api.md, docs/reference/settings.md, test/documentation.test.ts		 updates package references to 2.8.0, documents reset-runtime and unsupportedCodexFallbackChain, and validates reference version stamps against package.json.
historical planning notices
docs/development/implementation-plans/**/*.md		 marks planning and handoff documents as historical artifacts and links them to current reference documentation.
test metadata
test/AGENTS.md, test/README.md		 updates generated test-suite counts and version metadata.

Estimated code review effort: 2 (Simple) | ~15 minutes

Possibly related PRs

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Title check ⚠️ Warning it uses docs: but the required conventional form needs a type(scope): summary title, so the scope is missing. change it to docs(architecture): realign maintainer docs with 2.8.0 architecture or similar.
✅ Passed checks (4 passed)
Check name Status Explanation
Description check ✅ Passed it covers the main sections with summary, changes, verification, and governance context, and the missing template headings are non-critical.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ 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 docs/architecture-refresh-2026-07-29
✨ Simplify code
  • Create PR with simplified code
  • Commit simplified code in branch docs/architecture-refresh-2026-07-29

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

test/documentation.test.ts

Oops! Something went wrong! :(

ESLint: 10.0.0

Error: The 'jiti' library is required for loading TypeScript configuration files. Make sure to install it.
at /node_modules/eslint/lib/config/config-loader.js:145:10
at async loadTypeScriptConfigFileWithJiti (/node_modules/eslint/lib/config/config-loader.js:144:3)
at async loadConfigFile (/node_modules/eslint/lib/config/config-loader.js:265:11)
at async ConfigLoader.calculateConfigArray (/node_modules/eslint/lib/config/config-loader.js:588:23)
at async #calculateConfigArray (/node_modules/eslint/lib/config/config-loader.js:369:19)
at async Promise.all (index 0)
at async findFiles (/node_modules/eslint/lib/eslint/eslint-helpers.js:635:25)
at async ESLint.lintFiles (/node_modules/eslint/lib/eslint/eslint.js:1014:21)
at async Object.execute (/node_modules/eslint/lib/cli.js:386:14)
at async main (/node_modules/eslint/bin/eslint.js:175:19)

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

Comment @coderabbitai help to get the list of available commands.

coderabbitai[bot]
coderabbitai Bot requested changes Jul 29, 2026
View reviewed changes

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 8

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
docs/development/RUNBOOK_ADD_AUTH_COMMAND.md (1)

20-45: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

include upgrade and npm-script guidance in the workflow.

this runbook covers adding a user-visible command, but its file list and implementation steps stop at runtime, reference, readme, and test updates. add docs/upgrade.md plus an explicit check for affected npm scripts so future command changes do not omit release guidance.

as per path instructions, behavior changes require updated upgrade notes and npm-script references.

🤖 Prompt for 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.

In `@docs/development/RUNBOOK_ADD_AUTH_COMMAND.md` around lines 20 - 45, Update
the runbook’s file checklist and implementation steps to include docs/upgrade.md
for user-visible behavior changes and an explicit review or update of affected
npm scripts. Ensure the guidance requires adding release/upgrade notes and
keeping npm-script references aligned, while preserving the existing
documentation and testing steps.

Source: Path instructions

🤖 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 `@docs/development/ARCHITECTURE.md`:
- Around line 58-60: Update the interactive transport wording at
docs/development/ARCHITECTURE.md lines 58-60 and 168, and
docs/development/CONFIG_FLOW.md lines 76-78, to consistently state “no
provider/config transport rewrite.” Preserve the exception that auth-store
reconciliation may modify the top-level cli_auth_credentials_store assignment in
the real config.
- Line 180: Narrow the no-lock concurrency statement in the architecture
documentation to exclude canonical config.toml updates performed by
ensureCodexCliFileAuthStore and atomicWriteText. State that the guarantee
applies only to non-config state copying/sync, or alternatively add
cross-process config save locking and concurrent interactive/official CLI
regression coverage in test/codex-bin-wrapper.test.ts.

In `@docs/development/CONFIG_FIELDS.md`:
- Around line 298-308: Extend the environment-variable inventory assertion in
config-save tests around the existing CODEX_MULTI_AUTH_DIR,
CODEX_MULTI_AUTH_CONFIG_PATH, and CODEX_HOME entries to include
CODEX_CLI_AUTH_PATH, CODEX_CLI_ACCOUNTS_PATH, CODEX_CLI_CONFIG_PATH, and
CODEX_AUTH_SYNC_CODEX_CLI. Ensure the assertion validates these documented names
against the runtime-supported state-path configuration and legacy alias.
- Around line 338-341: Clarify the CODEX_AUTH_STREAM_FAILOVER_MAX documentation
to distinguish the per-mode pre-cap defaults of 2/2/1 from the effective
post-cap defaults of 1/1/1. Update the table and capStreamFailoverMax
description so operators can identify the actual configured behavior implemented
by the stream failover logic.

In `@docs/development/implementation-plans/subagent-handoffs/README.md`:
- Around line 3-10: Update the architecture cross-link in the handoff notices
from ../ARCHITECTURE.md to ../../ARCHITECTURE.md in
docs/development/implementation-plans/subagent-handoffs/README.md (lines 3-10),
pr-01-roadmap-local-governance.md (lines 3-10), pr-02-usage-ledger-core.md
(lines 3-10), pr-03-usage-command.md (lines 3-10),
pr-04-account-policy-controls.md (lines 3-10), and
pr-05-routing-profiles-core.md (lines 3-10); leave the other links unchanged.

In `@docs/development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md`:
- Around line 33-39: Update the testing requirement for the new command in
test/codex-manager-cli.test.ts to cover both dispatch forms: codex-multi-auth
auth <name> and bare codex-multi-auth <name>. For auth or storage commands that
exercise these collaborators, add deterministic coverage for token-refresh races
and Windows filesystem cleanup, ensuring concurrency and cleanup behavior is
stable across runs.

In `@docs/reference/commands.md`:
- Line 137: Align both descriptions of codex-multi-auth reset-runtime in
docs/reference/commands.md with its actual CLI behavior, specifically whether it
changes packaged app binding or only resets runtime state and observability
counters. Inspect the reset-runtime implementation to establish the contract,
update both documentation locations consistently, and add a focused assertion in
the relevant documentation test alongside the existing version-stamp checks.

In `@test/AGENTS.md`:
- Around line 6-7: Insert a blank line between the “## OVERVIEW” heading and the
following descriptive paragraph in test/AGENTS.md to satisfy markdownlint MD022.

---

Outside diff comments:
In `@docs/development/RUNBOOK_ADD_AUTH_COMMAND.md`:
- Around line 20-45: Update the runbook’s file checklist and implementation
steps to include docs/upgrade.md for user-visible behavior changes and an
explicit review or update of affected npm scripts. Ensure the guidance requires
adding release/upgrade notes and keeping npm-script references aligned, while
preserving the existing documentation and testing steps.
🪄 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 Plus

Run ID: 7651d170-0b8c-480a-9f23-9db6b7322c4e

📥 Commits

Reviewing files that changed from the base of the PR and between 78aa9b5 and 85e9300.

📒 Files selected for processing (31)
  • docs/development/ARCHITECTURE.md
  • docs/development/CONFIG_FIELDS.md
  • docs/development/CONFIG_FLOW.md
  • docs/development/REPOSITORY_SCOPE.md
  • docs/development/RUNBOOK_ADD_AUTH_COMMAND.md
  • docs/development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md
  • docs/development/implementation-plans/decisions.md
  • docs/development/implementation-plans/local-governance-roadmap.md
  • docs/development/implementation-plans/open-issues.md
  • docs/development/implementation-plans/pr-description-template.md
  • docs/development/implementation-plans/status.md
  • docs/development/implementation-plans/subagent-handoffs/README.md
  • docs/development/implementation-plans/subagent-handoffs/pr-01-roadmap-local-governance.md
  • docs/development/implementation-plans/subagent-handoffs/pr-02-usage-ledger-core.md
  • docs/development/implementation-plans/subagent-handoffs/pr-03-usage-command.md
  • docs/development/implementation-plans/subagent-handoffs/pr-04-account-policy-controls.md
  • docs/development/implementation-plans/subagent-handoffs/pr-05-routing-profiles-core.md
  • docs/development/implementation-plans/subagent-handoffs/pr-06-budget-guard.md
  • docs/development/implementation-plans/subagent-handoffs/pr-07-model-capability-matrix.md
  • docs/development/implementation-plans/subagent-handoffs/pr-08-runtime-policy-integration.md
  • docs/development/implementation-plans/subagent-handoffs/pr-09-monitor-command.md
  • docs/development/implementation-plans/subagent-handoffs/pr-10-local-bridge-core.md
  • docs/development/implementation-plans/subagent-handoffs/pr-11-local-client-tokens.md
  • docs/development/implementation-plans/subagent-handoffs/pr-12-integration-generators.md
  • docs/development/implementation-plans/subagent-handoffs/pr-13-release-local-governance.md
  • docs/reference/commands.md
  • docs/reference/public-api.md
  • docs/reference/settings.md
  • test/AGENTS.md
  • test/README.md
  • test/documentation.test.ts
📜 Review details
🧰 Additional context used
📓 Path-based instructions (24)
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 as codex-multi-auth Features instead 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 is codex-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

Organize repository documentation according to the defined layers: product entry, user operations, reference, and development.

docs/**/*.md: Do not describe codex-multi-auth as replacing @openai/codex or publishing the global codex binary; preserve the official CLI's ownership of codex.
Use codex-multi-auth for account management, and reserve codex-multi-auth-codex or mcodex for intentionally forwarding official Codex commands th...

Files:

  • docs/development/implementation-plans/open-issues.md
  • docs/development/implementation-plans/subagent-handoffs/pr-03-usage-command.md
  • docs/development/implementation-plans/subagent-handoffs/pr-04-account-policy-controls.md
  • docs/development/implementation-plans/subagent-handoffs/README.md
  • docs/development/implementation-plans/pr-description-template.md
  • docs/development/implementation-plans/status.md
  • docs/development/implementation-plans/subagent-handoffs/pr-11-local-client-tokens.md
  • docs/development/implementation-plans/subagent-handoffs/pr-08-runtime-policy-integration.md
  • docs/development/implementation-plans/subagent-handoffs/pr-12-integration-generators.md
  • docs/reference/settings.md
  • docs/development/implementation-plans/decisions.md
  • docs/development/implementation-plans/subagent-handoffs/pr-05-routing-profiles-core.md
  • docs/development/implementation-plans/subagent-handoffs/pr-01-roadmap-local-governance.md
  • docs/development/implementation-plans/local-governance-roadmap.md
  • docs/development/implementation-plans/subagent-handoffs/pr-06-budget-guard.md
  • docs/reference/public-api.md
  • docs/development/REPOSITORY_SCOPE.md
  • docs/development/implementation-plans/subagent-handoffs/pr-13-release-local-governance.md
  • docs/development/implementation-plans/subagent-handoffs/pr-02-usage-ledger-core.md
  • docs/development/implementation-plans/subagent-handoffs/pr-09-monitor-command.md
  • docs/reference/commands.md
  • docs/development/RUNBOOK_ADD_AUTH_COMMAND.md
  • docs/development/implementation-plans/subagent-handoffs/pr-07-model-capability-matrix.md
  • docs/development/CONFIG_FLOW.md
  • docs/development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md
  • docs/development/CONFIG_FIELDS.md
  • docs/development/ARCHITECTURE.md
  • docs/development/implementation-plans/subagent-handoffs/pr-10-local-bridge-core.md
docs/development/**/*.md

📄 CodeRabbit inference engine (docs/DOCUMENTATION.md)

Keep internal architecture, configuration flow, repository ownership, testing, parity, metadata, and audit guidance in development documentation.

Prefer current architecture and reference documentation over historical plans and audit snapshots when describing the present system.

Files:

  • docs/development/implementation-plans/open-issues.md
  • docs/development/implementation-plans/subagent-handoffs/pr-03-usage-command.md
  • docs/development/implementation-plans/subagent-handoffs/pr-04-account-policy-controls.md
  • docs/development/implementation-plans/subagent-handoffs/README.md
  • docs/development/implementation-plans/pr-description-template.md
  • docs/development/implementation-plans/status.md
  • docs/development/implementation-plans/subagent-handoffs/pr-11-local-client-tokens.md
  • docs/development/implementation-plans/subagent-handoffs/pr-08-runtime-policy-integration.md
  • docs/development/implementation-plans/subagent-handoffs/pr-12-integration-generators.md
  • docs/development/implementation-plans/decisions.md
  • docs/development/implementation-plans/subagent-handoffs/pr-05-routing-profiles-core.md
  • docs/development/implementation-plans/subagent-handoffs/pr-01-roadmap-local-governance.md
  • docs/development/implementation-plans/local-governance-roadmap.md
  • docs/development/implementation-plans/subagent-handoffs/pr-06-budget-guard.md
  • docs/development/REPOSITORY_SCOPE.md
  • docs/development/implementation-plans/subagent-handoffs/pr-13-release-local-governance.md
  • docs/development/implementation-plans/subagent-handoffs/pr-02-usage-ledger-core.md
  • docs/development/implementation-plans/subagent-handoffs/pr-09-monitor-command.md
  • docs/development/RUNBOOK_ADD_AUTH_COMMAND.md
  • docs/development/implementation-plans/subagent-handoffs/pr-07-model-capability-matrix.md
  • docs/development/CONFIG_FLOW.md
  • docs/development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md
  • docs/development/CONFIG_FIELDS.md
  • docs/development/ARCHITECTURE.md
  • docs/development/implementation-plans/subagent-handoffs/pr-10-local-bridge-core.md
docs/development/implementation-plans/**/*.md

📄 CodeRabbit inference engine (docs/DOCUMENTATION.md)

Treat implementation plans as historical archives, not current architecture guidance.

Files:

  • docs/development/implementation-plans/open-issues.md
  • docs/development/implementation-plans/subagent-handoffs/pr-03-usage-command.md
  • docs/development/implementation-plans/subagent-handoffs/pr-04-account-policy-controls.md
  • docs/development/implementation-plans/subagent-handoffs/README.md
  • docs/development/implementation-plans/pr-description-template.md
  • docs/development/implementation-plans/status.md
  • docs/development/implementation-plans/subagent-handoffs/pr-11-local-client-tokens.md
  • docs/development/implementation-plans/subagent-handoffs/pr-08-runtime-policy-integration.md
  • docs/development/implementation-plans/subagent-handoffs/pr-12-integration-generators.md
  • docs/development/implementation-plans/decisions.md
  • docs/development/implementation-plans/subagent-handoffs/pr-05-routing-profiles-core.md
  • docs/development/implementation-plans/subagent-handoffs/pr-01-roadmap-local-governance.md
  • docs/development/implementation-plans/local-governance-roadmap.md
  • docs/development/implementation-plans/subagent-handoffs/pr-06-budget-guard.md
  • docs/development/implementation-plans/subagent-handoffs/pr-13-release-local-governance.md
  • docs/development/implementation-plans/subagent-handoffs/pr-02-usage-ledger-core.md
  • docs/development/implementation-plans/subagent-handoffs/pr-09-monitor-command.md
  • docs/development/implementation-plans/subagent-handoffs/pr-07-model-capability-matrix.md
  • docs/development/implementation-plans/subagent-handoffs/pr-10-local-bridge-core.md
docs/development/**/*.{md,mdx}

📄 CodeRabbit inference engine (docs/development/TESTING.md)

When documentation changes, verify every command snippet is runnable, path references match runtime modules, cross-links are valid, and the feature matrix matches implemented features.

Files:

  • docs/development/implementation-plans/open-issues.md
  • docs/development/implementation-plans/subagent-handoffs/pr-03-usage-command.md
  • docs/development/implementation-plans/subagent-handoffs/pr-04-account-policy-controls.md
  • docs/development/implementation-plans/subagent-handoffs/README.md
  • docs/development/implementation-plans/pr-description-template.md
  • docs/development/implementation-plans/status.md
  • docs/development/implementation-plans/subagent-handoffs/pr-11-local-client-tokens.md
  • docs/development/implementation-plans/subagent-handoffs/pr-08-runtime-policy-integration.md
  • docs/development/implementation-plans/subagent-handoffs/pr-12-integration-generators.md
  • docs/development/implementation-plans/decisions.md
  • docs/development/implementation-plans/subagent-handoffs/pr-05-routing-profiles-core.md
  • docs/development/implementation-plans/subagent-handoffs/pr-01-roadmap-local-governance.md
  • docs/development/implementation-plans/local-governance-roadmap.md
  • docs/development/implementation-plans/subagent-handoffs/pr-06-budget-guard.md
  • docs/development/REPOSITORY_SCOPE.md
  • docs/development/implementation-plans/subagent-handoffs/pr-13-release-local-governance.md
  • docs/development/implementation-plans/subagent-handoffs/pr-02-usage-ledger-core.md
  • docs/development/implementation-plans/subagent-handoffs/pr-09-monitor-command.md
  • docs/development/RUNBOOK_ADD_AUTH_COMMAND.md
  • docs/development/implementation-plans/subagent-handoffs/pr-07-model-capability-matrix.md
  • docs/development/CONFIG_FLOW.md
  • docs/development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md
  • docs/development/CONFIG_FIELDS.md
  • docs/development/ARCHITECTURE.md
  • docs/development/implementation-plans/subagent-handoffs/pr-10-local-bridge-core.md
docs/**/*.{md,mdx}

📄 CodeRabbit inference engine (docs/troubleshooting.md)

Document that codex-multi-auth-codex is the optional forwarding wrapper, while codex-multi-auth is the canonical account-manager command family; the package does not publish a global codex binary.

Document the canonical command names, runtime paths, configuration precedence, storage migration behavior, and upgrade procedures consistently across the referenced documentation.

Files:

  • docs/development/implementation-plans/open-issues.md
  • docs/development/implementation-plans/subagent-handoffs/pr-03-usage-command.md
  • docs/development/implementation-plans/subagent-handoffs/pr-04-account-policy-controls.md
  • docs/development/implementation-plans/subagent-handoffs/README.md
  • docs/development/implementation-plans/pr-description-template.md
  • docs/development/implementation-plans/status.md
  • docs/development/implementation-plans/subagent-handoffs/pr-11-local-client-tokens.md
  • docs/development/implementation-plans/subagent-handoffs/pr-08-runtime-policy-integration.md
  • docs/development/implementation-plans/subagent-handoffs/pr-12-integration-generators.md
  • docs/reference/settings.md
  • docs/development/implementation-plans/decisions.md
  • docs/development/implementation-plans/subagent-handoffs/pr-05-routing-profiles-core.md
  • docs/development/implementation-plans/subagent-handoffs/pr-01-roadmap-local-governance.md
  • docs/development/implementation-plans/local-governance-roadmap.md
  • docs/development/implementation-plans/subagent-handoffs/pr-06-budget-guard.md
  • docs/reference/public-api.md
  • docs/development/REPOSITORY_SCOPE.md
  • docs/development/implementation-plans/subagent-handoffs/pr-13-release-local-governance.md
  • docs/development/implementation-plans/subagent-handoffs/pr-02-usage-ledger-core.md
  • docs/development/implementation-plans/subagent-handoffs/pr-09-monitor-command.md
  • docs/reference/commands.md
  • docs/development/RUNBOOK_ADD_AUTH_COMMAND.md
  • docs/development/implementation-plans/subagent-handoffs/pr-07-model-capability-matrix.md
  • docs/development/CONFIG_FLOW.md
  • docs/development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md
  • docs/development/CONFIG_FIELDS.md
  • docs/development/ARCHITECTURE.md
  • docs/development/implementation-plans/subagent-handoffs/pr-10-local-bridge-core.md
**/*

📄 CodeRabbit inference engine (AGENTS.md)

Source changes belong in index.ts, lib/, and scripts/; dist/ is generated output and local temporary/cache directories must not be edited.

Files:

  • docs/development/implementation-plans/open-issues.md
  • docs/development/implementation-plans/subagent-handoffs/pr-03-usage-command.md
  • test/AGENTS.md
  • docs/development/implementation-plans/subagent-handoffs/pr-04-account-policy-controls.md
  • docs/development/implementation-plans/subagent-handoffs/README.md
  • docs/development/implementation-plans/pr-description-template.md
  • docs/development/implementation-plans/status.md
  • docs/development/implementation-plans/subagent-handoffs/pr-11-local-client-tokens.md
  • docs/development/implementation-plans/subagent-handoffs/pr-08-runtime-policy-integration.md
  • docs/development/implementation-plans/subagent-handoffs/pr-12-integration-generators.md
  • docs/reference/settings.md
  • docs/development/implementation-plans/decisions.md
  • docs/development/implementation-plans/subagent-handoffs/pr-05-routing-profiles-core.md
  • docs/development/implementation-plans/subagent-handoffs/pr-01-roadmap-local-governance.md
  • docs/development/implementation-plans/local-governance-roadmap.md
  • docs/development/implementation-plans/subagent-handoffs/pr-06-budget-guard.md
  • docs/reference/public-api.md
  • test/README.md
  • docs/development/REPOSITORY_SCOPE.md
  • docs/development/implementation-plans/subagent-handoffs/pr-13-release-local-governance.md
  • test/documentation.test.ts
  • docs/development/implementation-plans/subagent-handoffs/pr-02-usage-ledger-core.md
  • docs/development/implementation-plans/subagent-handoffs/pr-09-monitor-command.md
  • docs/reference/commands.md
  • docs/development/RUNBOOK_ADD_AUTH_COMMAND.md
  • docs/development/implementation-plans/subagent-handoffs/pr-07-model-capability-matrix.md
  • docs/development/CONFIG_FLOW.md
  • docs/development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md
  • docs/development/CONFIG_FIELDS.md
  • docs/development/ARCHITECTURE.md
  • docs/development/implementation-plans/subagent-handoffs/pr-10-local-bridge-core.md
docs/development/**/*

📄 CodeRabbit inference engine (docs/development/CONFIG_FLOW.md)

docs/development/**/*: Resolve the runtime root directory in this priority order: CODEX_MULTI_AUTH_DIR; explicit non-default CODEX_HOME using only $CODEX_HOME/multi-auth; existing account-storage roots under CODEX_HOME or ~/.codex; canonical fallback ~/.codex/multi-auth; and legacy paths only when storage signals exist.
Read dashboardDisplaySettings and pluginConfig from settings.json, while preserving compatibility loading and migration for legacy configuration.
Resolve runtime values in pluginConfig from the existing CODEX_MULTI_AUTH_CONFIG_PATH file first, then valid unified settings.json configuration, then the legacy compatibility path, and finally DEFAULT_PLUGIN_CONFIG; apply environment-variable overrides afterward.
Ignore a set but nonexistent CODEX_MULTI_AUTH_CONFIG_PATH during load, while creating it on the first save if the variable remains set.
Resolve dashboard display values from persisted dashboardDisplaySettings, followed by normalization and fallback defaults.
Resolve account storage by selecting the root directory, using the global accounts file by default, using a project-namespaced path when project-scoped mode is active, and attempting legacy project-file migration when applicable.
Normalize standalone manager bare subcommands to auth ...; normalize wrapper compatibility aliases; run auth-manager commands locally; forward out-of-scope wrapper commands to the official Codex CLI; and check runtime rotation for forwarded request-bearing commands.
When runtime rotation is enabled for a request-bearing command, start a loopback Responses proxy with a per-process client token, select the appropriate canonical-home or shadow-home transport, forward to official Codex, rotate managed accounts on applicable failures, and synchronize and clean up shadow state on exit.
For plugin-host requests, transform requests for Codex compatibility, select accounts using health/cooldown/quota/affinity criteria, apply timeout and retry ...

Files:

  • docs/development/implementation-plans/open-issues.md
  • docs/development/implementation-plans/subagent-handoffs/pr-03-usage-command.md
  • docs/development/implementation-plans/subagent-handoffs/pr-04-account-policy-controls.md
  • docs/development/implementation-plans/subagent-handoffs/README.md
  • docs/development/implementation-plans/pr-description-template.md
  • docs/development/implementation-plans/status.md
  • docs/development/implementation-plans/subagent-handoffs/pr-11-local-client-tokens.md
  • docs/development/implementation-plans/subagent-handoffs/pr-08-runtime-policy-integration.md
  • docs/development/implementation-plans/subagent-handoffs/pr-12-integration-generators.md
  • docs/development/implementation-plans/decisions.md
  • docs/development/implementation-plans/subagent-handoffs/pr-05-routing-profiles-core.md
  • docs/development/implementation-plans/subagent-handoffs/pr-01-roadmap-local-governance.md
  • docs/development/implementation-plans/local-governance-roadmap.md
  • docs/development/implementation-plans/subagent-handoffs/pr-06-budget-guard.md
  • docs/development/REPOSITORY_SCOPE.md
  • docs/development/implementation-plans/subagent-handoffs/pr-13-release-local-governance.md
  • docs/development/implementation-plans/subagent-handoffs/pr-02-usage-ledger-core.md
  • docs/development/implementation-plans/subagent-handoffs/pr-09-monitor-command.md
  • docs/development/RUNBOOK_ADD_AUTH_COMMAND.md
  • docs/development/implementation-plans/subagent-handoffs/pr-07-model-capability-matrix.md
  • docs/development/CONFIG_FLOW.md
  • docs/development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md
  • docs/development/CONFIG_FIELDS.md
  • docs/development/ARCHITECTURE.md
  • docs/development/implementation-plans/subagent-handoffs/pr-10-local-bridge-core.md
docs/development/**/*.{ts,md}

📄 CodeRabbit inference engine (docs/development/RUNBOOK_ADD_AUTH_COMMAND.md)

docs/development/**/*.{ts,md}: Keep the command name consistent across runtime code and documentation, and ensure help text matches the actual flags.
Do not mix unrelated settings or storage changes into the command addition.
Keep JSON output stable whenever the command exposes JSON output.

Files:

  • docs/development/implementation-plans/open-issues.md
  • docs/development/implementation-plans/subagent-handoffs/pr-03-usage-command.md
  • docs/development/implementation-plans/subagent-handoffs/pr-04-account-policy-controls.md
  • docs/development/implementation-plans/subagent-handoffs/README.md
  • docs/development/implementation-plans/pr-description-template.md
  • docs/development/implementation-plans/status.md
  • docs/development/implementation-plans/subagent-handoffs/pr-11-local-client-tokens.md
  • docs/development/implementation-plans/subagent-handoffs/pr-08-runtime-policy-integration.md
  • docs/development/implementation-plans/subagent-handoffs/pr-12-integration-generators.md
  • docs/development/implementation-plans/decisions.md
  • docs/development/implementation-plans/subagent-handoffs/pr-05-routing-profiles-core.md
  • docs/development/implementation-plans/subagent-handoffs/pr-01-roadmap-local-governance.md
  • docs/development/implementation-plans/local-governance-roadmap.md
  • docs/development/implementation-plans/subagent-handoffs/pr-06-budget-guard.md
  • docs/development/REPOSITORY_SCOPE.md
  • docs/development/implementation-plans/subagent-handoffs/pr-13-release-local-governance.md
  • docs/development/implementation-plans/subagent-handoffs/pr-02-usage-ledger-core.md
  • docs/development/implementation-plans/subagent-handoffs/pr-09-monitor-command.md
  • docs/development/RUNBOOK_ADD_AUTH_COMMAND.md
  • docs/development/implementation-plans/subagent-handoffs/pr-07-model-capability-matrix.md
  • docs/development/CONFIG_FLOW.md
  • docs/development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md
  • docs/development/CONFIG_FIELDS.md
  • docs/development/ARCHITECTURE.md
  • docs/development/implementation-plans/subagent-handoffs/pr-10-local-bridge-core.md
docs/development/implementation-plans/**/*

📄 CodeRabbit inference engine (docs/development/implementation-plans/local-governance-roadmap.md)

docs/development/implementation-plans/**/*: Keep governance data local by default; do not add remote telemetry or hosted dashboard behavior.
Do not store prompts, tokens, authorization headers, raw account emails, or raw sensitive account identifiers in usage ledger rows.
Preserve loopback-only runtime proxy invariants and per-process client authentication; do not bind the local bridge to public networks by default.
Use existing storage roots and project identity helpers instead of introducing new path rules.
Keep runtime rotation default behavior aligned with the current release documentation.
Do not add PostgreSQL, Docker, Kubernetes, Helm, TOTP authentication, broad proxy endpoints, chat completions, audio, image, transcription, or daemon installation as part of local governance.

Files:

  • docs/development/implementation-plans/open-issues.md
  • docs/development/implementation-plans/subagent-handoffs/pr-03-usage-command.md
  • docs/development/implementation-plans/subagent-handoffs/pr-04-account-policy-controls.md
  • docs/development/implementation-plans/subagent-handoffs/README.md
  • docs/development/implementation-plans/pr-description-template.md
  • docs/development/implementation-plans/status.md
  • docs/development/implementation-plans/subagent-handoffs/pr-11-local-client-tokens.md
  • docs/development/implementation-plans/subagent-handoffs/pr-08-runtime-policy-integration.md
  • docs/development/implementation-plans/subagent-handoffs/pr-12-integration-generators.md
  • docs/development/implementation-plans/decisions.md
  • docs/development/implementation-plans/subagent-handoffs/pr-05-routing-profiles-core.md
  • docs/development/implementation-plans/subagent-handoffs/pr-01-roadmap-local-governance.md
  • docs/development/implementation-plans/local-governance-roadmap.md
  • docs/development/implementation-plans/subagent-handoffs/pr-06-budget-guard.md
  • docs/development/implementation-plans/subagent-handoffs/pr-13-release-local-governance.md
  • docs/development/implementation-plans/subagent-handoffs/pr-02-usage-ledger-core.md
  • docs/development/implementation-plans/subagent-handoffs/pr-09-monitor-command.md
  • docs/development/implementation-plans/subagent-handoffs/pr-07-model-capability-matrix.md
  • docs/development/implementation-plans/subagent-handoffs/pr-10-local-bridge-core.md
docs/development/implementation-plans/**/*.{md,mdx}

📄 CodeRabbit inference engine (docs/development/implementation-plans/local-governance-roadmap.md)

Documentation for local governance must describe storage, privacy, release behavior, and testing while reflecting the current implementation rather than historical roadmap status.

Files:

  • docs/development/implementation-plans/open-issues.md
  • docs/development/implementation-plans/subagent-handoffs/pr-03-usage-command.md
  • docs/development/implementation-plans/subagent-handoffs/pr-04-account-policy-controls.md
  • docs/development/implementation-plans/subagent-handoffs/README.md
  • docs/development/implementation-plans/pr-description-template.md
  • docs/development/implementation-plans/status.md
  • docs/development/implementation-plans/subagent-handoffs/pr-11-local-client-tokens.md
  • docs/development/implementation-plans/subagent-handoffs/pr-08-runtime-policy-integration.md
  • docs/development/implementation-plans/subagent-handoffs/pr-12-integration-generators.md
  • docs/development/implementation-plans/decisions.md
  • docs/development/implementation-plans/subagent-handoffs/pr-05-routing-profiles-core.md
  • docs/development/implementation-plans/subagent-handoffs/pr-01-roadmap-local-governance.md
  • docs/development/implementation-plans/local-governance-roadmap.md
  • docs/development/implementation-plans/subagent-handoffs/pr-06-budget-guard.md
  • docs/development/implementation-plans/subagent-handoffs/pr-13-release-local-governance.md
  • docs/development/implementation-plans/subagent-handoffs/pr-02-usage-ledger-core.md
  • docs/development/implementation-plans/subagent-handoffs/pr-09-monitor-command.md
  • docs/development/implementation-plans/subagent-handoffs/pr-07-model-capability-matrix.md
  • docs/development/implementation-plans/subagent-handoffs/pr-10-local-bridge-core.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/development/implementation-plans/open-issues.md
  • docs/development/implementation-plans/subagent-handoffs/pr-03-usage-command.md
  • docs/development/implementation-plans/subagent-handoffs/pr-04-account-policy-controls.md
  • docs/development/implementation-plans/subagent-handoffs/README.md
  • docs/development/implementation-plans/pr-description-template.md
  • docs/development/implementation-plans/status.md
  • docs/development/implementation-plans/subagent-handoffs/pr-11-local-client-tokens.md
  • docs/development/implementation-plans/subagent-handoffs/pr-08-runtime-policy-integration.md
  • docs/development/implementation-plans/subagent-handoffs/pr-12-integration-generators.md
  • docs/reference/settings.md
  • docs/development/implementation-plans/decisions.md
  • docs/development/implementation-plans/subagent-handoffs/pr-05-routing-profiles-core.md
  • docs/development/implementation-plans/subagent-handoffs/pr-01-roadmap-local-governance.md
  • docs/development/implementation-plans/local-governance-roadmap.md
  • docs/development/implementation-plans/subagent-handoffs/pr-06-budget-guard.md
  • docs/reference/public-api.md
  • docs/development/REPOSITORY_SCOPE.md
  • docs/development/implementation-plans/subagent-handoffs/pr-13-release-local-governance.md
  • docs/development/implementation-plans/subagent-handoffs/pr-02-usage-ledger-core.md
  • docs/development/implementation-plans/subagent-handoffs/pr-09-monitor-command.md
  • docs/reference/commands.md
  • docs/development/RUNBOOK_ADD_AUTH_COMMAND.md
  • docs/development/implementation-plans/subagent-handoffs/pr-07-model-capability-matrix.md
  • docs/development/CONFIG_FLOW.md
  • docs/development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md
  • docs/development/CONFIG_FIELDS.md
  • docs/development/ARCHITECTURE.md
  • docs/development/implementation-plans/subagent-handoffs/pr-10-local-bridge-core.md
docs/development/implementation-plans/subagent-handoffs/**/*

📄 CodeRabbit inference engine (docs/development/implementation-plans/subagent-handoffs/README.md)

Before handoff, each roadmap PR must add or update a handoff file in the local-governance directory containing: Branch, Base, Scope, Files changed, Validation, and Follow-ups.

Files:

  • docs/development/implementation-plans/subagent-handoffs/pr-03-usage-command.md
  • docs/development/implementation-plans/subagent-handoffs/pr-04-account-policy-controls.md
  • docs/development/implementation-plans/subagent-handoffs/README.md
  • docs/development/implementation-plans/subagent-handoffs/pr-11-local-client-tokens.md
  • docs/development/implementation-plans/subagent-handoffs/pr-08-runtime-policy-integration.md
  • docs/development/implementation-plans/subagent-handoffs/pr-12-integration-generators.md
  • docs/development/implementation-plans/subagent-handoffs/pr-05-routing-profiles-core.md
  • docs/development/implementation-plans/subagent-handoffs/pr-01-roadmap-local-governance.md
  • docs/development/implementation-plans/subagent-handoffs/pr-06-budget-guard.md
  • docs/development/implementation-plans/subagent-handoffs/pr-13-release-local-governance.md
  • docs/development/implementation-plans/subagent-handoffs/pr-02-usage-ledger-core.md
  • docs/development/implementation-plans/subagent-handoffs/pr-09-monitor-command.md
  • docs/development/implementation-plans/subagent-handoffs/pr-07-model-capability-matrix.md
  • docs/development/implementation-plans/subagent-handoffs/pr-10-local-bridge-core.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/AGENTS.md
  • test/README.md
  • test/documentation.test.ts
docs/development/**/README.md

📄 CodeRabbit inference engine (docs/development/GITHUB_DISCOVERABILITY.md)

docs/development/**/README.md: README.md should open with a descriptive H1 title rather than a bare package name, e.g. 'codex-multi-auth: multi-account OAuth for the official Codex CLI'
README.md first paragraph must explain what the project is, who it is for, and how it relates to the official Codex CLI
README.md feature bullets should lead with outcomes (account switching, health checks, recovery, diagnostics, quota visibility, runtime rotation) rather than command dumps
README.md quick start section should be short and credible, with first-run instructions kept as concise as possible
README.md should explicitly explain local-only storage, loopback runtime rotation, reversible app bind, and the independent/non-official boundary to build trust
README.md should include badges for npm version, CI status, and license; avoid vanity badges unless they add real trust or decision value
Natural search terms (codex cli multi account, codex multi auth manager, chatgpt oauth codex cli, etc.) should appear naturally in README intro, feature list, and package metadata, not stuffed into every heading
README.md metadata and package keywords should be aligned with natural search terms: codex, cli, multi-account, oauth, account switching, runtime rotation, etc.

Update README.md only when the new command changes the recommended user workflow.

Files:

  • docs/development/implementation-plans/subagent-handoffs/README.md
docs/**/README.md

📄 CodeRabbit inference engine (docs/DOCUMENTATION.md)

Use README.md as the canonical project entry point.

Files:

  • docs/development/implementation-plans/subagent-handoffs/README.md
docs/development/implementation-plans/**/README.md

📄 CodeRabbit inference engine (docs/development/implementation-plans/pr-description-template.md)

Update README.md when user-visible behavior changes.

Files:

  • docs/development/implementation-plans/subagent-handoffs/README.md
docs/reference/**/*.md

📄 CodeRabbit inference engine (docs/STYLE_GUIDE.md)

New flags/settings/paths must be reflected in docs/reference/*

docs/reference/**/*.md: Keep command, API, error-contract, settings, and storage-path details in the canonical reference documentation.
Document compatibility aliases (codex multi auth, codex multi-auth, and codex multiauth) only in command-reference, troubleshooting, or migration sections.

docs/reference/**/*.md: Document pluginConfig as the persisted compatibility name for runtime settings, with defaults matching DEFAULT_PLUGIN_CONFIG in lib/config.ts.
Use ~/.codex/multi-auth/settings.json as the default settings file, relocating its root when CODEX_MULTI_AUTH_DIR is set.
Always show a sync preview before applying changes; blocked target states must not apply changes, the destination active selection must be preserved, and destination-only accounts must be retained.
Named backup exports must prompt for a filename, append .json when omitted, reject separators, traversal (..), .rotate., .tmp, and .wal suffixes, and fail safely on collisions without overwriting by default.
Keep backgroundResponses disabled by default unless callers intentionally send background: true.
Installed wrappers may perform a best-effort daily npm version check, but must not mutate the installed package; they should only print the installation command when an update is available.
After configuration changes, validate with codex-multi-auth status, codex-multi-auth check, codex-multi-auth forecast --live, and codex-multi-auth config explain.

Files:

  • docs/reference/settings.md
  • docs/reference/public-api.md
  • docs/reference/commands.md
**/*.{ts,js,mjs}

📄 CodeRabbit inference engine (AGENTS.md)

**/*.{ts,js,mjs}: Use ESM modules throughout the project; the package is configured with "type": "module".
Do not use as any, @ts-ignore, or @ts-expect-error.

Files:

  • test/documentation.test.ts
test/**/*.ts

📄 CodeRabbit inference engine (AGENTS.md)

Windows-sensitive filesystem tests and helpers must use retry handling for transient lock-related cleanup and write failures.

Files:

  • test/documentation.test.ts
**/*.{js,ts,mjs,cjs}

📄 CodeRabbit inference engine (README.md)

**/*.{js,ts,mjs,cjs}: Do not publish or replace a global codex binary; official OpenAI installation paths must retain ownership of the codex command.
Keep OAuth credentials local and restrict runtime rotation and local bridges to loopback interfaces.
Require hashed local client tokens to protect the optional loopback bridge.
Responses background: true compatibility must remain opt-in; requests using it must use stateful store=true routing rather than stateless store=false routing.
Never run npm install or update commands automatically; only display a manual upgrade notice when appropriate.
Experimental synchronization and backup flows must be non-destructive by default: preview before applying sync, preserve destination-only accounts, and fail safely on backup filename collisions.
Keep account storage project-scoped under the configured multi-auth root when operating in repo-specific workflows.

Files:

  • test/documentation.test.ts
test/**/*.{ts,tsx}

📄 CodeRabbit inference engine (test/AGENTS.md)

test/**/*.{ts,tsx}: Use Vitest globals such as describe, it, and expect in test files.
Maintain at least 80% coverage for statements, branches, functions, and lines.
Use fast-check for randomized property-based tests.
Do not hardcode ports other than 1455 for OAuth server tests.
Do not rely on dist/ in tests; import or exercise source files instead.
Do not skip tests without justification.
Use removeWithRetry instead of bare fs.rm for test cleanup, especially for Windows filesystem safety.
Use vi.useFakeTimers() for stream failover tests so assertions do not depend on real timeouts.

Files:

  • test/documentation.test.ts
docs/development/RUNBOOK_*.md

📄 CodeRabbit inference engine (docs/README.md)

Prefer the *_SAFELY and manager-command runbooks for new work; retain older short-name runbooks for continuity.

Files:

  • docs/development/RUNBOOK_ADD_AUTH_COMMAND.md
  • docs/development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md
docs/development/CONFIG_FLOW.md

📄 CodeRabbit inference engine (docs/development/RUNBOOK_ADD_CONFIG_FIELD.md)

Update docs/development/CONFIG_FLOW.md when source selection or precedence changes

Files:

  • docs/development/CONFIG_FLOW.md
docs/development/CONFIG_FIELDS.md

📄 CodeRabbit inference engine (docs/development/RUNBOOK_ADD_CONFIG_FIELD.md)

Update docs/development/CONFIG_FIELDS.md with field inventory details when adding new configuration fields

Maintain full field inventory in docs/development/CONFIG_FIELDS.md

Files:

  • docs/development/CONFIG_FIELDS.md
🧠 Learnings (3)
📓 Common learnings 
Learnt from: CR
Repo: ndycode/codex-multi-auth

Timestamp: 2026-07-29T10:23:25.031Z
Learning: Runtime rotation must be enabled by default, remain local and reversible, and provide explicit opt-out controls.

Learnt from: CR
Repo: ndycode/codex-multi-auth

Timestamp: 2026-07-29T10:23:41.867Z
Learning: Debug effective configuration with `codex-multi-auth status`, `codex-multi-auth report --json`, and `codex-multi-auth rotation status`; inspect `~/.codex/multi-auth/settings.json` and `~/.codex/multi-auth/openai-codex-accounts.json`.

Learnt from: CR
Repo: ndycode/codex-multi-auth

Timestamp: 2026-07-29T10:23:55.687Z
Learning: A new command must be registered in both command registries, documented appropriately, and added without expanding scope or breaking the existing CLI contract.

Learnt from: CR
Repo: ndycode/codex-multi-auth

Timestamp: 2026-07-29T10:23:55.687Z
Learning: Before completion, run `npm run lint`, `npm run typecheck`, the targeted CLI and documentation tests, and `npm run build`.

Learnt from: CR
Repo: ndycode/codex-multi-auth

Timestamp: 2026-07-29T10:24:11.449Z
Learning: Store usage data in a local JSONL ledger rather than using remote telemetry.

Learnt from: CR
Repo: ndycode/codex-multi-auth

Timestamp: 2026-07-29T10:24:11.449Z
Learning: Store only redacted usage metadata; never store prompts, tokens, raw email addresses, or sensitive identifiers.

Learnt from: CR
Repo: ndycode/codex-multi-auth

Timestamp: 2026-07-29T10:24:11.449Z
Learning: Use local API-key-style bridge tokens for loopback integrations, with bearer-token authentication.

Learnt from: CR
Repo: ndycode/codex-multi-auth

Timestamp: 2026-07-29T10:24:11.449Z
Learning: Provide model and account availability views using existing quota, entitlement, and capability surfaces rather than duplicating them.

Learnt from: CR
Repo: ndycode/codex-multi-auth

Timestamp: 2026-07-29T10:24:11.449Z
Learning: Generate deterministic client snippets for local integrations without adding hosted-service behavior.

Learnt from: CR
Repo: ndycode/codex-multi-auth

Timestamp: 2026-07-29T10:24:11.449Z
Learning: Do not add a hosted dashboard; the product remains a local CLI-first account manager.

Learnt from: CR
Repo: ndycode/codex-multi-auth

Timestamp: 2026-07-29T10:24:11.449Z
Learning: Do not add Docker, Kubernetes, or Helm deployment assets for the local bridge.

Learnt from: CR
Repo: ndycode/codex-multi-auth

Timestamp: 2026-07-29T10:24:11.449Z
Learning: Do not add PostgreSQL-backed storage; preserve local file-backed storage conventions.

Learnt from: CR
Repo: ndycode/codex-multi-auth

Timestamp: 2026-07-29T10:24:11.449Z
Learning: Do not implement remote gateway behavior; bridge behavior must remain loopback-only.

Learnt from: CR
Repo: ndycode/codex-multi-auth

Timestamp: 2026-07-29T10:24:11.449Z
Learning: Do not use TOTP authentication for the local bridge; use hashed bearer tokens for the loopback-only integration scope.

Learnt from: CR
Repo: ndycode/codex-multi-auth

Timestamp: 2026-07-29T10:24:11.449Z
Learning: Limit OpenAI-compatible bridge endpoints to health, models, and Responses API compatibility; do not implement a broad proxy.

Learnt from: CR
Repo: ndycode/codex-multi-auth

Timestamp: 2026-07-29T10:24:11.449Z
Learning: Use `getCodexMultiAuthDir()` for global local governance files.

Learnt from: CR
Repo: ndycode/codex-multi-auth

Timestamp: 2026-07-29T10:24:11.449Z
Learning: Use existing project identity helpers for project-aware data.

Learnt from: CR
Repo: ndycode/codex-multi-auth

Timestamp: 2026-07-29T10:24:11.449Z
Learning: Write JSON documents using a temp file followed by rename, including Windows retry behavior; serialize JSONL ledger appends through a local sidecar lock.

Learnt from: CR
Repo: ndycode/codex-multi-auth

Timestamp: 2026-07-29T10:24:11.449Z
Learning: Keep runtime enforcement out of core data-model changes; place it in the runtime-policy integration work instead.

Learnt from: CR
Repo: ndycode/codex-multi-auth

Timestamp: 2026-07-29T10:24:11.449Z
Learning: Filter runtime account candidates before selection, then pass only safe boosts through existing scoring paths.

Learnt from: CR
Repo: ndycode/codex-multi-auth

Timestamp: 2026-07-29T10:24:11.449Z
Learning: Append one usage row after each completed or failed runtime request, once runtime policy integration is in place.

Learnt from: CR
Repo: ndycode/codex-multi-auth

Timestamp: 2026-07-29T10:24:25.833Z
Learning: Every local governance PR must document its risk level and rollback plan.

Learnt from: CR
Repo: ndycode/codex-multi-auth

Timestamp: 2026-07-29T10:24:28.900Z
Learning: If a future baseline or PR validation gate fails, record the exact failure text in `open-issues.md`.

Learnt from: CR
Repo: ndycode/codex-multi-auth

Timestamp: 2026-07-29T10:24:36.153Z
Learning: Start PR 02 from a synchronized `main` branch.

Learnt from: CR
Repo: ndycode/codex-multi-auth

Timestamp: 2026-07-29T10:24:52.110Z
Learning: Before runtime account selection, call the usage-summary budget evaluator.

Learnt from: CR
Repo: ndycode/codex-multi-auth

Timestamp: 2026-07-29T10:24:55.957Z
Learning: Use the capability matrix data during runtime policy evaluation in the subsequent policy-evaluation work.

Learnt from: CR
Repo: ndycode/codex-multi-auth

Timestamp: 2026-07-29T10:25:04.166Z
Learning: Validate the monitor command changes with `npm run typecheck`, targeted monitor and runtime-policy tests, `npm run build`, and `npm run lint`.

Learnt from: CR
Repo: ndycode/codex-multi-auth

Timestamp: 2026-07-29T10:25:24.098Z
Learning: Validate the local governance documentation changes with `npm run lint`, `npm run typecheck`, `npm test -- test/documentation.test.ts`, `npm test`, `npm run build`, and `npm run clean:repo:check`.

Learnt from: CR
Repo: ndycode/codex-multi-auth

Timestamp: 2026-07-29T10:25:32.794Z
Learning: Run `codex-multi-auth uninstall` before `npm uninstall -g codex-multi-auth` so first-run setup artifacts and host integrations are removed reliably.

Learnt from: CR
Repo: ndycode/codex-multi-auth

Timestamp: 2026-07-29T10:25:41.180Z
Learning: For any intentional contract break, identify affected callers, provide concrete migration examples, update README, upgrade documentation, affected reference documentation, release notes, and changelog, and add transition tests when feasible.
📚 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
🪛 markdownlint-cli2 (0.23.1)
test/AGENTS.md

[warning] 6-6: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)

🔇 Additional comments (23)
docs/development/ARCHITECTURE.md (1)

50-52: LGTM!

Also applies to: 62-68, 114-115, 164-167, 169-179, 182-182, 220-230, 274-275, 304-306

docs/development/CONFIG_FLOW.md (1)

75-75: LGTM!

Also applies to: 79-83

docs/development/CONFIG_FIELDS.md (1)

310-337: LGTM!

Also applies to: 342-356

test/README.md (1)

5-5: LGTM!

docs/reference/commands.md (1)

3-3: LGTM!

docs/reference/public-api.md (1)

3-3: LGTM!

docs/reference/settings.md (1)

5-5: LGTM!

Also applies to: 206-206

test/documentation.test.ts (1)

246-271: LGTM!

docs/development/implementation-plans/subagent-handoffs/pr-06-budget-guard.md (1)

3-10: LGTM!

docs/development/implementation-plans/subagent-handoffs/pr-07-model-capability-matrix.md (1)

3-10: LGTM!

docs/development/implementation-plans/subagent-handoffs/pr-08-runtime-policy-integration.md (1)

3-10: LGTM!

docs/development/implementation-plans/subagent-handoffs/pr-09-monitor-command.md (1)

3-10: LGTM!

docs/development/implementation-plans/subagent-handoffs/pr-10-local-bridge-core.md (1)

3-10: LGTM!

docs/development/implementation-plans/subagent-handoffs/pr-11-local-client-tokens.md (1)

3-10: LGTM!

docs/development/implementation-plans/subagent-handoffs/pr-12-integration-generators.md (1)

3-10: LGTM!

docs/development/implementation-plans/subagent-handoffs/pr-13-release-local-governance.md (1)

3-10: LGTM!

docs/development/implementation-plans/decisions.md (1)

3-10: LGTM!

docs/development/implementation-plans/local-governance-roadmap.md (1)

3-10: LGTM!

docs/development/implementation-plans/open-issues.md (1)

3-10: LGTM!

docs/development/implementation-plans/pr-description-template.md (1)

3-10: LGTM!

docs/development/implementation-plans/status.md (1)

3-10: LGTM!

docs/development/REPOSITORY_SCOPE.md (1)

19-21: LGTM!

Also applies to: 32-35

docs/development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md (1)

50-50: LGTM!

Comment thread docs/development/ARCHITECTURE.md Outdated
Comment thread docs/development/ARCHITECTURE.md Outdated
Comment thread docs/development/CONFIG_FIELDS.md
Comment on lines +298 to +308
### Official Codex CLI state paths

These point the Codex-CLI state layer (`lib/codex-cli/state.ts`) at non-default files. Useful for sandboxes and tests; rarely set by operators.

| Variable | Purpose |
| --- | --- |
| `CODEX_HOME` | Official Codex home. When set to a non-default path, multi-auth resolves strictly to `$CODEX_HOME/multi-auth` and does not scan `~/.codex/multi-auth` |
| `CODEX_CLI_AUTH_PATH` | Override the official `auth.json` path |
| `CODEX_CLI_ACCOUNTS_PATH` | Override the official `accounts.json` path |
| `CODEX_CLI_CONFIG_PATH` | Override the official `config.toml` path |
| `CODEX_AUTH_SYNC_CODEX_CLI` | Legacy alias for `CODEX_MULTI_AUTH_SYNC_CODEX_CLI`; read only when the canonical name is unset |

@coderabbitai coderabbitai Bot Jul 29, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

add regression coverage for the expanded state-path inventory.

the supplied test/config-save.test.ts:29-35 only enumerates CODEX_MULTI_AUTH_DIR, CODEX_MULTI_AUTH_CONFIG_PATH, and CODEX_HOME; it does not protect the newly documented CODEX_CLI_AUTH_PATH, CODEX_CLI_ACCOUNTS_PATH, CODEX_CLI_CONFIG_PATH, or legacy alias. add a documentation/inventory assertion so these names cannot drift from runtime support.

as per path instructions, documentation changes must be validated against runtime paths and workflows.

🤖 Prompt for 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.

In `@docs/development/CONFIG_FIELDS.md` around lines 298 - 308, Extend the
environment-variable inventory assertion in config-save tests around the
existing CODEX_MULTI_AUTH_DIR, CODEX_MULTI_AUTH_CONFIG_PATH, and CODEX_HOME
entries to include CODEX_CLI_AUTH_PATH, CODEX_CLI_ACCOUNTS_PATH,
CODEX_CLI_CONFIG_PATH, and CODEX_AUTH_SYNC_CODEX_CLI. Ensure the assertion
validates these documented names against the runtime-supported state-path
configuration and legacy alias.

Source: Path instructions

Comment thread docs/development/CONFIG_FIELDS.md
Comment thread docs/development/implementation-plans/subagent-handoffs/README.md
Comment thread docs/development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md Outdated
Comment thread docs/reference/commands.md
Comment thread test/AGENTS.md
@ndycode @claude
docs: address review findings on the 2.8.0 docs realignment
a33e25d 
Eight review comments, each checked against source before acting.

Interactive-transport wording was too absolute. Three sites claimed the
interactive path never rewrites config.toml, but the auth-store reconcile
does persist cli_auth_credentials_store there on every transport. Narrowed
to "no provider/transport rewrite" and named the exception at each site.

The no-lock concurrency guarantee was overbroad. It now covers session
state only. config.toml is explicitly excluded: ensureCodexCliFileAuthStore
read-modify-writes the canonical file without cross-process serialization,
and is safe by idempotency plus atomic rename rather than by locking — so
a non-idempotent addition to that path would need a real lock.

Failover defaults were genuinely confusing: the table gave per-mode
defaults of 2/2/1 and then said capStreamFailoverMax clamps to 0..1.
Effective defaults are 1/1/1, and only 0 changes behaviour.

reset-runtime was described two different ways. commands.md:547 listed
only the observability reset while the summary row listed the app-bind
restart. Both now match the implementation: bind restart, rotation
tracker and circuit-breaker reset, observability clear.

Handoff banner links pointed at the right file but displayed the wrong
path — label ../ARCHITECTURE.md against target ../../ARCHITECTURE.md.
Targets always resolved, which is why the link checker passed; the
visible text was wrong in 14 files.

Also: the manager runbook now requires a test case per dispatch form,
since only the bare form catches a missing ACCOUNT_MANAGER_COMMANDS
entry; the auth runbook gained upgrade-notes and npm-script steps; and
a pre-existing MD022 heading violation in test/AGENTS.md is fixed.

Three new documentation tests. Documented env names must appear in
shipped code, the state-path group and legacy alias must stay
documented, and every behavioural reset-runtime description must mention
the bind restart. The env check is a substring presence test on purpose:
an earlier version enumerated access forms (process.env.X, quoted
literals) and reported twelve live variables as deleted because it
missed env.NAME. Both new guards were verified to fail on the exact
regression they target.

Reviewer asked to extend the envKeys array in test/config-save.test.ts
instead; that array is env-isolation bookkeeping for one suite, not an
inventory assertion, so the guard lives in documentation.test.ts where
the drift class actually is.

Verified: typecheck, ESLint, full suite (5271 passed, 6 skipped) green;
0 broken internal links. Test counts updated to the measured 5277.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_01BaAqj4XiyF9WUFXCQn7oiQ
@ndycode
ndycode merged commit 89ca969 into main Jul 29, 2026
1 check was pending
@coderabbitai coderabbitai Bot mentioned this pull request Aug 1, 2026
Merged
11 tasks
@coderabbitai coderabbitai Bot mentioned this pull request Aug 19, 2026
Merged
5 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@coderabbitai coderabbitai[bot] coderabbitai[bot] requested changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@ndycode