diff --git a/CHANGELOG.md b/CHANGELOG.md
index 26e34f7b..4fb8f5ee 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,6 +1,6 @@
-# changelog
+# Changelog
 
-all notable changes to this project. dates are ISO format (YYYY-MM-DD).
+All notable changes to this project. Dates are ISO format (YYYY-MM-DD).
 
 ## [unreleased]
 
@@ -260,7 +260,7 @@ Full Changelog: https://github.com/ndycode/codex-multi-auth/compare/v4.12.1...v4
 - Proactive token refresh - Refreshes tokens 5 minutes before expiry
 - Zod schemas - Runtime validation as single source of truth
 - ### Stats
-- Tests: 580 → 631 (+51)
+- Tests: 580 -> 631 (+51)
 - All passing on Windows with `--pool=forks`
 
 ### Bug Fixes
@@ -372,30 +372,33 @@ Full Changelog: https://github.com/ndycode/codex-multi-auth/compare/v4.9.7...v4.
 
 ### Changelog
 
-Full Changelog: https://github.com/ndycode/codex-multi-auth/compare/v4.9.5...v4.9.7
+Full Changelog: https://github.com/ndycode/codex-multi-auth/compare/v4.9.6...v4.9.7
 
-## [4.9.5] - 2026-01-28
+## [4.9.6] - 2026-02-08
 
 ### Improvements
-- When your ChatGPT subscription didn't include Codex access, the plugin kept rotating through all accounts and retrying forever because it thought it was a temporary rate limit.
-- You get an immediate, clear error: "This model is not included in your ChatGPT subscription."
 
-### Bug Fixes
-- Account error handling - Fixes infinite retry loop when account doesn't have access to Codex models. `usage_not_included` errors now return 403 Forbidden instead of being treated as rate limits. Clear error message explaining the subscription issue. Prevents pointless account rotation for non-recoverable errors. (#16, thanks @rainmeter33-jpg!)
+- tui auth gating: non-tty/ui auth attempts now return a clear instruction to run `codex auth login` in a terminal shell.
+- error-mapping simplification: consolidated entitlement/rate-limit mapping in fetch helpers for a single handling path.
 
 ### Changelog
 
-Full Changelog: https://github.com/ndycode/codex-multi-auth/compare/v4.9.4...v4.9.5
+Full Changelog: https://github.com/ndycode/codex-multi-auth/compare/v4.9.5...v4.9.6
 
-## [4.9.6] - 2026-02-08
+## [4.9.5] - 2026-01-28
 
 ### Improvements
-- tui auth gating: non-tty/ui auth attempts now return a clear instruction to run `codex auth login` in a terminal shell.
-- error-mapping simplification: consolidated entitlement/rate-limit mapping in fetch helpers for a single handling path.
+
+- When your ChatGPT subscription didn't include Codex access, the plugin kept rotating through all accounts and retrying forever because it thought it was a temporary rate limit.
+- You get an immediate, clear error: "This model is not included in your ChatGPT subscription."
+
+### Bug Fixes
+
+- Account error handling - Fixes infinite retry loop when account doesn't have access to Codex models. `usage_not_included` errors now return 403 Forbidden instead of being treated as rate limits. Clear error message explaining the subscription issue. Prevents pointless account rotation for non-recoverable errors. (#16, thanks @rainmeter33-jpg!)
 
 ### Changelog
 
-Full Changelog: https://github.com/ndycode/codex-multi-auth/compare/v5.0.0...v4.9.6
+Full Changelog: https://github.com/ndycode/codex-multi-auth/compare/v4.9.4...v4.9.5
 
 ## [4.9.4] - 2026-01-27
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 705166c7..b51f7be3 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -36,10 +36,10 @@ All contributions MUST:
 ## Code Standards
 
 - **TypeScript:** All code must be TypeScript with strict type checking
-- **Testing:** Include tests for new functionality (we maintain 200+ unit tests)
+- **Testing:** Include tests for new functionality and keep coverage gate healthy (80% threshold)
 - **Documentation:** Update README.md for user-facing changes
-- **Modular design:** Keep functions focused and under 40 lines
-- **No external dependencies:** Minimize dependencies (currently only @openauthjs/openauth)
+- **Validation gate:** Run `npm run typecheck`, `npm run lint`, `npm test`, and `npm run build` before opening a PR
+- **Dependencies:** Minimize new dependencies and justify them in the PR
 
 ## Pull Request Process
 
@@ -48,7 +48,7 @@ All contributions MUST:
 3. **Include tests** for new functionality
 4. **Update documentation** (README.md, config examples, etc.)
 5. **Ensure compliance** with guidelines above
-6. **Test thoroughly** with actual ChatGPT Plus/Pro account
+6. **Run the validation gate** (`npm run typecheck`, `npm run lint`, `npm test`, `npm run build`)
 7. **Submit PR** with clear description of changes
 
 ## Reporting Issues
diff --git a/README.md b/README.md
index 9757df39..13c55ea5 100644
--- a/README.md
+++ b/README.md
@@ -51,6 +51,7 @@ codex auth check
 | `codex auth check` | Quick health + live session checks |
 | `codex auth forecast --live` | Choose best next account |
 | `codex auth fix --dry-run` | Preview safe fixes |
+| `codex auth fix --live --model gpt-5-codex` | Run fix with live probe on a specific model |
 | `codex auth fix` | Apply safe fixes |
 | `codex auth doctor --fix` | Diagnose + repair common issues |
 | `codex auth report --live --json` | Export machine-readable status |
@@ -67,7 +68,7 @@ Main dashboard:
 - `Enter`: select
 - `1-9`: quick switch
 - `/`: search
-- `?` or `H`: help
+- `?`: toggle help
 - `Q`: back/cancel
 
 Account detail menu:
@@ -97,6 +98,30 @@ Reference: [docs/reference/settings.md](docs/reference/settings.md)
 
 * * *
 
+## Stable Env Overrides
+
+Use these stable overrides first:
+
+| Variable | Purpose |
+| --- | --- |
+| `CODEX_MULTI_AUTH_DIR` | Override the multi-auth root (`settings`, accounts, cache, logs) |
+| `CODEX_MULTI_AUTH_CONFIG_PATH` | Load plugin config from an alternate file |
+| `CODEX_HOME` | Override Codex home used to resolve default paths |
+| `CODEX_MODE` | Toggle Codex mode |
+| `CODEX_TUI_V2` | Toggle TUI v2 |
+| `CODEX_TUI_COLOR_PROFILE` | Set TUI color profile (`truecolor`, `ansi256`, `ansi16`) |
+| `CODEX_TUI_GLYPHS` | Set glyph mode (`ascii`, `unicode`, `auto`) |
+| `CODEX_AUTH_FETCH_TIMEOUT_MS` | Override upstream request timeout |
+| `CODEX_AUTH_STREAM_STALL_TIMEOUT_MS` | Override stream stall timeout |
+| `CODEX_MULTI_AUTH_SYNC_CODEX_CLI` | Toggle Codex CLI state synchronization |
+| `CODEX_CLI_ACCOUNTS_PATH` / `CODEX_CLI_AUTH_PATH` | Override Codex CLI state file locations |
+| `CODEX_MULTI_AUTH_REAL_CODEX_BIN` | Force forwarded Codex binary path |
+| `CODEX_MULTI_AUTH_BYPASS` | Disable local auth interception and always forward |
+
+Advanced/internal toggles are documented in [docs/development/CONFIG_FIELDS.md](docs/development/CONFIG_FIELDS.md).
+
+* * *
+
 ## Documentation
 
 Start here:
diff --git a/SECURITY.md b/SECURITY.md
index 2cc17a0d..938784d2 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -2,12 +2,12 @@
 
 ## Supported Versions
 
-We provide security updates for the latest version of the plugin.
+Security fixes are prioritized for the latest release line.
 
-| Version | Supported          |
-| ------- | ------------------ |
-| Latest  | ✅ Active support |
-| < 1.0   | ❌ No longer supported |
+| Version line | Supported |
+| --- | --- |
+| Latest release line | ✅ Active support |
+| Older release lines | ⚠️ Best effort only; upgrade recommended |
 
 ## Security Considerations
 
@@ -28,6 +28,7 @@ This plugin handles sensitive OAuth tokens. To protect your security:
 - Regularly review authorized apps at [ChatGPT Settings](https://chatgpt.com/settings/apps)
 - Remove local plugin auth files when done on shared systems (default: `~/.codex/multi-auth/openai-codex-*.json`; use `CODEX_MULTI_AUTH_DIR` if overridden)
 - Enable debug logging (`ENABLE_PLUGIN_REQUEST_LOGGING=1`) only when troubleshooting
+- Avoid `CODEX_PLUGIN_LOG_BODIES=1` unless required for short-lived local debugging
 
 ### Reporting a Vulnerability
 
@@ -72,7 +73,7 @@ The following are **not** security vulnerabilities:
 ### Third-Party Dependencies
 
 This plugin minimizes dependencies for security:
-- Runtime dependencies include OAuth/auth libraries, plugin host SDK dependencies, `hono`, and `zod`
+- Runtime dependencies include OAuth/auth libraries, `@codex-ai/plugin`, `hono`, and `zod`
 - Regular dependency updates for security patches
 - No telemetry or analytics dependencies
 - CI/local guardrail: run `npm run audit:ci` before release or after dependency updates
diff --git a/config/README.md b/config/README.md
index bb362ff4..1cbfd09a 100644
--- a/config/README.md
+++ b/config/README.md
@@ -14,6 +14,8 @@ These files are example model/provider templates for `codex-multi-auth`.
 
 - These templates are optional for the OAuth account manager flow.
 - Core auth commands use `codex auth login`.
+- Prefer `codex-modern.json` for new setup; use `codex-legacy.json` only for compatibility testing.
+- Verify account readiness after template updates with `codex auth forecast --live` and `codex auth fix --live --model gpt-5-codex`.
 
 ## Defaults Included
 
diff --git a/docs/DOCUMENTATION.md b/docs/DOCUMENTATION.md
index f4a6a3b8..ad4ee5c1 100644
--- a/docs/DOCUMENTATION.md
+++ b/docs/DOCUMENTATION.md
@@ -82,6 +82,7 @@ When runtime behavior changes:
 6. Update `docs/upgrade.md` when migration steps, command routing, or paths changed.
 7. Keep `SECURITY.md` aligned with current storage paths and credential handling.
 8. Update npm script references whenever build/install workflow changes.
+9. Keep CLI usage text in docs aligned with `lib/codex-manager.ts` usage output.
 
 * * *
 
@@ -95,6 +96,7 @@ Before merge:
 4. Internal links are valid.
 5. Cross-platform examples are present for OS-sensitive flows.
 6. No conflicting duplicate guidance across pages.
+7. `test/documentation.test.ts` passes.
 
 * * *
 
diff --git a/docs/configuration.md b/docs/configuration.md
index f4f900b4..01c969a7 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -1,6 +1,6 @@
 # Configuration
 
-Configure behavior from one settings root with optional environment overrides.
+Configure behavior from one settings root with stable env overrides and optional advanced toggles.
 
 ---
 
@@ -55,18 +55,36 @@ Keep these enabled for most users:
 
 ---
 
-## Environment Overrides
+## Stable Environment Overrides
+
+These overrides are stable and intended for day-to-day use:
 
 | Variable | Effect |
 | --- | --- |
-| `CODEX_MULTI_AUTH_DIR` | Override settings/accounts root |
-| `CODEX_MULTI_AUTH_CONFIG_PATH` | Read config from alternate file |
+| `CODEX_MULTI_AUTH_DIR` | Override settings/accounts/cache/log root |
+| `CODEX_MULTI_AUTH_CONFIG_PATH` | Read plugin config from alternate file |
+| `CODEX_HOME` | Change Codex home used for default path resolution |
 | `CODEX_MODE=0/1` | Disable/enable Codex mode |
 | `CODEX_TUI_V2=0/1` | Disable/enable TUI v2 |
 | `CODEX_TUI_COLOR_PROFILE=truecolor\|ansi256\|ansi16` | TUI color profile |
 | `CODEX_TUI_GLYPHS=ascii\|unicode\|auto` | TUI glyph style |
 | `CODEX_AUTH_FETCH_TIMEOUT_MS=<ms>` | Override request timeout |
 | `CODEX_AUTH_STREAM_STALL_TIMEOUT_MS=<ms>` | Override stream stall timeout |
+| `CODEX_MULTI_AUTH_SYNC_CODEX_CLI=0/1` | Disable/enable Codex CLI state sync |
+| `CODEX_CLI_ACCOUNTS_PATH=<path>` | Override Codex CLI accounts file path |
+| `CODEX_CLI_AUTH_PATH=<path>` | Override Codex CLI auth file path |
+| `CODEX_MULTI_AUTH_REAL_CODEX_BIN=<path>` | Force official Codex binary used by wrapper |
+| `CODEX_MULTI_AUTH_BYPASS=1` | Bypass local auth handling and forward all commands |
+
+---
+
+## Advanced/Internal Overrides
+
+Advanced runtime controls (failover policy, refresh lease internals, testing toggles) are documented in:
+
+- [development/CONFIG_FIELDS.md](development/CONFIG_FIELDS.md)
+
+Treat those settings as maintainers-only unless explicitly advised.
 
 ---
 
diff --git a/docs/development/ARCHITECTURE.md b/docs/development/ARCHITECTURE.md
index 80fa941c..ef61862f 100644
--- a/docs/development/ARCHITECTURE.md
+++ b/docs/development/ARCHITECTURE.md
@@ -107,6 +107,7 @@ Canonical root: `~/.codex/multi-auth`.
 2. Dist folder is generated output only.
 3. Non-auth `codex` commands are always forwarded to official Codex CLI.
 4. Canonical account-management commands remain `codex auth ...`.
+5. CLI usage/help output must stay in sync with parser-supported flags.
 
 * * *
 
diff --git a/docs/development/CONFIG_FIELDS.md b/docs/development/CONFIG_FIELDS.md
index 9a3ee4cf..08b7b75d 100644
--- a/docs/development/CONFIG_FIELDS.md
+++ b/docs/development/CONFIG_FIELDS.md
@@ -22,9 +22,9 @@ Top-level shape:
 
 * * *
 
-## Plugin-Host Provider Options (`provider.openai.options`)
+## Provider Options (`provider.openai.options`)
 
-Used only for host plugin mode through the host runtime config file.
+Used in plugin-host runtime configuration.
 
 | Key | Type | Common values | Effect |
 | --- | --- | --- | --- |
@@ -183,12 +183,15 @@ Used only for host plugin mode through the host runtime config file.
 
 * * *
 
-## Environment Overrides
+## Stable Environment Overrides
+
+### Stable (User-Facing)
 
 | Variable | Purpose |
 | --- | --- |
 | `CODEX_MULTI_AUTH_DIR` | Custom root for settings/accounts/cache/logs |
-| `CODEX_MULTI_AUTH_CONFIG_PATH` | Alternate config file input |
+| `CODEX_MULTI_AUTH_CONFIG_PATH` | Alternate plugin config file input |
+| `CODEX_HOME` | Override Codex home path used for default resolution |
 | `CODEX_MODE` | Toggle Codex mode |
 | `CODEX_TUI_V2` | Toggle TUI v2 |
 | `CODEX_TUI_COLOR_PROFILE` | TUI color profile |
@@ -196,15 +199,107 @@ Used only for host plugin mode through the host runtime config file.
 | `CODEX_AUTH_FETCH_TIMEOUT_MS` | Request timeout override |
 | `CODEX_AUTH_STREAM_STALL_TIMEOUT_MS` | Stream stall timeout override |
 | `CODEX_MULTI_AUTH_SYNC_CODEX_CLI` | Toggle Codex CLI state sync |
-| `CODEX_MULTI_AUTH_REAL_CODEX_BIN` | Force official Codex binary path |
-| `CODEX_MULTI_AUTH_BYPASS` | Bypass local auth handling |
+| `CODEX_CLI_ACCOUNTS_PATH` | Override Codex CLI accounts state path |
+| `CODEX_CLI_AUTH_PATH` | Override Codex CLI auth state path |
+| `CODEX_MULTI_AUTH_REAL_CODEX_BIN` | Force official Codex binary path for wrapper forwarding |
+| `CODEX_MULTI_AUTH_BYPASS` | Bypass local auth handling in wrapper |
+| `ENABLE_PLUGIN_REQUEST_LOGGING` | Enable request logging |
+| `CODEX_PLUGIN_LOG_BODIES` | Include payload bodies in logs (sensitive) |
+| `DEBUG_CODEX_PLUGIN` | Enable debug logging |
+| `CODEX_PLUGIN_LOG_LEVEL` | Set log level (`debug`, `info`, `warn`, `error`) |
+| `CODEX_CONSOLE_LOG` | Emit logs to console in addition to app logger |
+
+### Advanced (Runtime Tuning)
+
+| Variable | Purpose | Stability |
+| --- | --- | --- |
+| `CODEX_AUTH_UNSUPPORTED_MODEL_POLICY` | Override unsupported-model policy (`strict`/`fallback`) | Advanced |
+| `CODEX_AUTH_FAST_SESSION` | Toggle fast-session mode | Advanced |
+| `CODEX_AUTH_FAST_SESSION_STRATEGY` | Override fast session strategy (`hybrid`/`always`) | Advanced |
+| `CODEX_AUTH_FAST_SESSION_MAX_INPUT_ITEMS` | Max fast-session input items retained | Advanced |
+| `CODEX_AUTH_RETRY_ALL_RATE_LIMITED` | Toggle all-accounts retry loop on full rate-limit exhaustion | Advanced |
+| `CODEX_AUTH_RETRY_ALL_MAX_WAIT_MS` | Max wait for all-accounts retry loop (`0` means unlimited) | Advanced |
+| `CODEX_AUTH_RETRY_ALL_MAX_RETRIES` | Max retry rounds for all-accounts retry loop | Advanced |
+| `CODEX_AUTH_FALLBACK_UNSUPPORTED_MODEL` | Legacy fallback policy toggle | Legacy |
+| `CODEX_AUTH_FALLBACK_GPT53_TO_GPT52` | Legacy GPT-5.3 -> GPT-5.2 fallback toggle | Legacy |
+| `CODEX_AUTH_TOKEN_REFRESH_SKEW_MS` | Refresh token skew window | Advanced |
+| `CODEX_AUTH_RATE_LIMIT_TOAST_DEBOUNCE_MS` | Rate-limit toast debounce interval | Advanced |
+| `CODEX_AUTH_TOAST_DURATION_MS` | UI toast duration | Advanced |
+| `CODEX_AUTH_PER_PROJECT_ACCOUNTS` | Toggle per-project account storage mode | Advanced |
+| `CODEX_AUTH_SESSION_RECOVERY` | Toggle session recovery module | Advanced |
+| `CODEX_AUTH_AUTO_RESUME` | Toggle automatic session resume in recovery | Advanced |
+| `CODEX_AUTH_PARALLEL_PROBING` | Toggle parallel account probing | Advanced |
+| `CODEX_AUTH_PARALLEL_PROBING_MAX_CONCURRENCY` | Max probe concurrency | Advanced |
+| `CODEX_AUTH_EMPTY_RESPONSE_MAX_RETRIES` | Max retries for empty/malformed responses | Advanced |
+| `CODEX_AUTH_EMPTY_RESPONSE_RETRY_DELAY_MS` | Delay between empty-response retries | Advanced |
+| `CODEX_AUTH_PID_OFFSET_ENABLED` | Toggle PID-based candidate offset | Advanced |
+| `CODEX_AUTH_LIVE_ACCOUNT_SYNC` | Toggle file-watch account sync | Advanced |
+| `CODEX_AUTH_LIVE_ACCOUNT_SYNC_DEBOUNCE_MS` | Live sync debounce interval | Advanced |
+| `CODEX_AUTH_LIVE_ACCOUNT_SYNC_POLL_MS` | Live sync poll fallback interval | Advanced |
+| `CODEX_AUTH_SESSION_AFFINITY` | Toggle session affinity | Advanced |
+| `CODEX_AUTH_SESSION_AFFINITY_TTL_MS` | Session affinity ttl | Advanced |
+| `CODEX_AUTH_SESSION_AFFINITY_MAX_ENTRIES` | Session affinity entry cap | Advanced |
+| `CODEX_AUTH_PROACTIVE_GUARDIAN` | Toggle proactive refresh guardian | Advanced |
+| `CODEX_AUTH_PROACTIVE_GUARDIAN_INTERVAL_MS` | Guardian tick interval | Advanced |
+| `CODEX_AUTH_PROACTIVE_GUARDIAN_BUFFER_MS` | Guardian pre-expiry buffer window | Advanced |
+| `CODEX_AUTH_NETWORK_ERROR_COOLDOWN_MS` | Cooldown applied after network errors | Advanced |
+| `CODEX_AUTH_SERVER_ERROR_COOLDOWN_MS` | Cooldown applied after 5xx errors | Advanced |
+| `CODEX_AUTH_STORAGE_BACKUP_ENABLED` | Toggle storage backup/WAL safety artifacts | Advanced |
+| `CODEX_AUTH_PREEMPTIVE_QUOTA_ENABLED` | Toggle preemptive quota deferral | Advanced |
+| `CODEX_AUTH_PREEMPTIVE_QUOTA_5H_REMAINING_PCT` | 5h quota deferral threshold percent | Advanced |
+| `CODEX_AUTH_PREEMPTIVE_QUOTA_7D_REMAINING_PCT` | 7d quota deferral threshold percent | Advanced |
+| `CODEX_AUTH_PREEMPTIVE_QUOTA_MAX_DEFERRAL_MS` | Max quota deferral wait | Advanced |
+
+### Advanced / Internal (Maintainers)
+
+| Variable | Purpose | Stability |
+| --- | --- | --- |
+| `CODEX_AUTH_ACCOUNT_ID` | Force workspace/account id for login/request routing | Advanced |
+| `CODEX_AUTH_FAILOVER_MODE` | Stream failover profile (`aggressive`/`balanced`/`conservative`) | Advanced |
+| `CODEX_AUTH_STREAM_FAILOVER_MAX` | Max failover attempts for streaming requests | Advanced |
+| `CODEX_AUTH_STREAM_STALL_SOFT_TIMEOUT_MS` | Soft timeout for stream failover decisions | Advanced |
+| `CODEX_AUTH_STREAM_STALL_HARD_TIMEOUT_MS` | Hard timeout for stream failover abort | Advanced |
+| `CODEX_AUTH_PREWARM` | Toggle startup prompt prewarm | Advanced |
+| `CODEX_AUTH_REFRESH_LEASE` | Toggle cross-process refresh lease | Advanced |
+| `CODEX_AUTH_REFRESH_LEASE_DIR` | Refresh lease state directory | Advanced |
+| `CODEX_AUTH_REFRESH_LEASE_TTL_MS` | Refresh lease ttl | Advanced |
+| `CODEX_AUTH_REFRESH_LEASE_WAIT_MS` | Refresh lease wait timeout | Advanced |
+| `CODEX_AUTH_REFRESH_LEASE_POLL_MS` | Refresh lease poll interval | Advanced |
+| `CODEX_AUTH_REFRESH_LEASE_RESULT_TTL_MS` | Refresh lease result ttl | Advanced |
+| `CODEX_AUTH_SYNC_CODEX_CLI` | Legacy Codex CLI sync toggle | Legacy |
+| `CODEX_MULTI_AUTH_EXPOSE_ADMIN_TOOLS` | Expose advanced plugin tools (`codex-metrics`, `codex-import`, etc.) | Internal |
+| `CODEX_SKIP_EMAIL_HYDRATE` | Skip email hydrate fallback for account metadata | Internal |
+| `CODEX_THREAD_ID` | Request correlation seed | Internal |
+| `CODEX_COLLABORATION_MODE` | Request transformer collaboration mode override | Internal |
+
+### Tooling / Test-Only
+
+| Variable | Purpose |
+| --- | --- |
+| `NODE_ENV`, `VITEST`, `VITEST_WORKER_ID` | Test/runtime mode toggles |
+| `CODEX_BIN`, `CODEX_MATRIX_TIMEOUT_MS`, `CODEX_MODELS_TIMEOUT_MS` | Script-only benchmarking/model-matrix controls |
+
+### Platform / Shell Detection (Informational)
+
+These variables affect runtime detection behavior, not plugin features:
+
+- `FORCE_INTERACTIVE_MODE`
+- `CODEX_TUI`, `CODEX_DESKTOP`
+- `TERM_PROGRAM`, `TERM`, `WT_SESSION`, `ELECTRON_RUN_AS_NODE`
+- `PATH`, `PATHEXT`
+- `APPDATA`, `XDG_DATA_HOME`
+
+Notes:
+
+- Non-plugin shell variables (`PATH`, `PATHEXT`, `TERM`, `WT_SESSION`, etc.) are intentionally excluded from user-facing guidance.
+- Prefer stable overrides; advanced/internal variables may change across releases.
 
 * * *
 
 ## Concurrency and Windows Notes
 
 - Storage writes use temp-file + rename semantics; Windows may surface transient `EPERM`/`EBUSY` during rename.
-- Cross-process refresh coordination relies on lease/state files; avoid manually editing those files while the CLI is running.
+- Cross-process refresh lease coordination relies on lease/state files; avoid manually editing those files while the CLI is running.
 - Live account sync combines `fs.watch` with polling fallback to handle Windows watcher edge cases.
 - Backup/WAL artifacts may exist briefly during writes and recovery; they are part of normal safety behavior.
 
diff --git a/docs/development/CONFIG_FLOW.md b/docs/development/CONFIG_FLOW.md
index a349add8..6a72aed1 100644
--- a/docs/development/CONFIG_FLOW.md
+++ b/docs/development/CONFIG_FLOW.md
@@ -24,7 +24,17 @@ Canonical target is `~/.codex/multi-auth` when no override is set.
 - `dashboardDisplaySettings`
 - `pluginConfig`
 
-If legacy config exists, compatibility load and migration path still apply.
+Plugin config load order:
+
+1. `CODEX_MULTI_AUTH_CONFIG_PATH` (explicit file override)
+2. Unified settings (`~/.codex/multi-auth/settings.json` -> `pluginConfig`)
+3. Legacy config files, only when present:
+   - `~/.codex/multi-auth/config.json`
+   - `~/.codex/codex-multi-auth-config.json`
+   - `~/.codex/openai-codex-auth-config.json`
+4. `DEFAULT_PLUGIN_CONFIG` defaults
+
+Legacy sources are compatibility-only; next save migrates toward unified settings.
 
 * * *
 
@@ -33,7 +43,7 @@ If legacy config exists, compatibility load and migration path still apply.
 For plugin runtime values:
 
 1. Environment override
-2. `CODEX_MULTI_AUTH_CONFIG_PATH` (when set)
+2. Explicit config file (`CODEX_MULTI_AUTH_CONFIG_PATH`) when set
 3. Unified/compat config value
 4. Hardcoded default in `DEFAULT_PLUGIN_CONFIG`
 
@@ -86,7 +96,7 @@ For dashboard display values:
 ## 8) Live Runtime Sync Flow
 
 1. File watcher detects account-file updates.
-2. Debounce and reload in-memory account manager.
+2. Debounce + poll fallback reload in-memory account manager.
 3. Session affinity and guardian processes continue with updated state.
 
 * * *
diff --git a/docs/development/REPOSITORY_SCOPE.md b/docs/development/REPOSITORY_SCOPE.md
index 74dba997..5ad969b4 100644
--- a/docs/development/REPOSITORY_SCOPE.md
+++ b/docs/development/REPOSITORY_SCOPE.md
@@ -16,6 +16,7 @@ Ownership map for source paths and documentation paths.
 | `config/` | Plugin-host config examples |
 | `assets/` | Static project assets |
 | `dist/` | Generated build output (do not edit directly) |
+| `CHANGELOG.md`, `SECURITY.md`, `CONTRIBUTING.md` | Release, security, and contribution governance |
 
 * * *
 
@@ -43,6 +44,7 @@ Ownership map for source paths and documentation paths.
 | Reference docs | `docs/reference/*` |
 | Maintainer docs | `docs/development/*`, `docs/DOCUMENTATION.md` |
 | Style and consistency | `docs/STYLE_GUIDE.md` |
+| Governance linkage | `README.md`, `CHANGELOG.md`, `SECURITY.md`, `CONTRIBUTING.md` |
 
 * * *
 
@@ -78,3 +80,4 @@ When adding a new feature:
 4. Update references if command/setting/path changed.
 5. Update architecture/config flow docs for cross-cutting behavior.
 6. Update `docs/upgrade.md` and any npm-script references when command flow/build steps changed.
+7. Update governance docs (`CHANGELOG.md`, `SECURITY.md`, `CONTRIBUTING.md`) if release/security/contributor workflow changed.
diff --git a/docs/development/TESTING.md b/docs/development/TESTING.md
index 9292b906..6728a2c8 100644
--- a/docs/development/TESTING.md
+++ b/docs/development/TESTING.md
@@ -33,6 +33,7 @@ npm run test:watch
 npm run test:coverage
 npm run test:model-matrix:smoke
 npm run bench:edit-formats:smoke
+npm run audit:ci
 ```
 
 * * *
@@ -43,7 +44,8 @@ npm run bench:edit-formats:smoke
 2. `npm run lint`
 3. `npm test`
 4. `npm run build`
-5. run docs command checks for newly documented command paths
+5. `npm run audit:ci` (release/dependency-sensitive changes)
+6. run docs command checks for newly documented command paths
 
 * * *
 
@@ -101,6 +103,7 @@ Optional plugin-host smoke:
 2. Cross-check path references against runtime modules.
 3. Confirm cross-links are valid.
 4. Keep feature matrix in sync with implemented features.
+5. Run `vitest run test/documentation.test.ts` before merge.
 
 * * *
 
diff --git a/docs/privacy.md b/docs/privacy.md
index dd1f6af4..f18976a2 100644
--- a/docs/privacy.md
+++ b/docs/privacy.md
@@ -25,7 +25,12 @@
 | Codex CLI auth state | `~/.codex/accounts.json`, `~/.codex/auth.json` | Official Codex CLI account/auth files |
 
 Legacy compatibility files from older versions may still be read during migration-only compatibility checks.
-If `CODEX_MULTI_AUTH_DIR` or `CODEX_MULTI_AUTH_CONFIG_PATH` is set, these locations move to the configured override path.
+
+Path overrides:
+
+- `CODEX_MULTI_AUTH_DIR` changes the multi-auth root (`settings`, accounts, cache, logs).
+- `CODEX_MULTI_AUTH_CONFIG_PATH` points plugin config reads/writes to an alternate file.
+- `CODEX_CLI_ACCOUNTS_PATH` and `CODEX_CLI_AUTH_PATH` override the Codex CLI state file paths.
 
 * * *
 
@@ -48,6 +53,7 @@ CODEX_PLUGIN_LOG_BODIES=1
 ```
 
 prompt/response payload text can be written to local logs. Treat those logs as sensitive.
+`ENABLE_PLUGIN_REQUEST_LOGGING=1` and `DEBUG_CODEX_PLUGIN=1` also increase local log verbosity.
 
 * * *
 
diff --git a/docs/reference/commands.md b/docs/reference/commands.md
index 0799efb8..df781c66 100644
--- a/docs/reference/commands.md
+++ b/docs/reference/commands.md
@@ -44,10 +44,10 @@ Common flags:
 | Flag | Applies to | Meaning |
 | --- | --- | --- |
 | `--json` | verify-flagged/forecast/report/fix/doctor | machine-readable output |
-| `--live` | forecast/report | use live quota/session probes |
+| `--live` | forecast/report/fix | use live quota/session probes |
 | `--dry-run` | verify-flagged/fix/doctor | preview without mutation |
 | `--fix` | doctor | apply repairs |
-| `--model <model>` | forecast/report | choose forecast model |
+| `--model <model>` | forecast/report/fix | choose probe model |
 | `--out <path>` | report | write report file |
 | `--no-restore` | verify-flagged | verify only, do not restore |
 
@@ -104,6 +104,7 @@ Repair workflow:
 
 ```bash
 codex auth fix --dry-run
+codex auth fix --live --model gpt-5-codex
 codex auth fix
 codex auth doctor --fix
 ```
diff --git a/docs/reference/settings.md b/docs/reference/settings.md
index 6a74c72a..ef682557 100644
--- a/docs/reference/settings.md
+++ b/docs/reference/settings.md
@@ -113,36 +113,44 @@ Typical controls:
 
 * * *
 
-## Recommended Defaults
-
-For most users, keep:
-
-- smart sort enabled
-- auto-fetch limits enabled
-- live sync enabled
-- session affinity enabled
-- preemptive quota deferral enabled
-- proactive refresh guardian enabled
-
-* * *
-
-## Environment Overrides
+## Stable Environment Overrides
 
-Important env overrides that can supersede file settings:
+Important stable overrides that supersede file settings:
 
 - `CODEX_MULTI_AUTH_DIR`
 - `CODEX_MULTI_AUTH_CONFIG_PATH`
+- `CODEX_HOME`
 - `CODEX_MODE`
 - `CODEX_TUI_V2`
+- `CODEX_TUI_COLOR_PROFILE`
+- `CODEX_TUI_GLYPHS`
 - `CODEX_AUTH_FETCH_TIMEOUT_MS`
 - `CODEX_AUTH_STREAM_STALL_TIMEOUT_MS`
+- `CODEX_MULTI_AUTH_SYNC_CODEX_CLI`
+- `CODEX_CLI_ACCOUNTS_PATH`
+- `CODEX_CLI_AUTH_PATH`
+- `CODEX_MULTI_AUTH_REAL_CODEX_BIN`
+- `CODEX_MULTI_AUTH_BYPASS`
 
-Full field inventory:
+Advanced/internal toggles are documented in maintainer docs:
 
 - [../development/CONFIG_FIELDS.md](../development/CONFIG_FIELDS.md)
 
 * * *
 
+## Recommended Defaults
+
+For most users, keep:
+
+- smart sort enabled
+- auto-fetch limits enabled
+- live sync enabled
+- session affinity enabled
+- preemptive quota deferral enabled
+- proactive refresh guardian enabled
+
+* * *
+
 ## Validation
 
 After changing settings:
diff --git a/lib/codex-manager.ts b/lib/codex-manager.ts
index 12c6d136..83842af8 100644
--- a/lib/codex-manager.ts
+++ b/lib/codex-manager.ts
@@ -1047,7 +1047,7 @@ function printUsage(): void {
 			"  codex-multi-auth auth verify-flagged [--dry-run] [--json] [--no-restore]",
 			"  codex-multi-auth auth forecast [--live] [--json] [--model <model>]",
 			"  codex-multi-auth auth report [--live] [--json] [--model <model>] [--out <path>]",
-			"  codex-multi-auth auth fix [--dry-run] [--json]",
+			"  codex-multi-auth auth fix [--dry-run] [--json] [--live] [--model <model>]",
 			"  codex-multi-auth auth doctor [--json] [--fix] [--dry-run]",
 			"",
 			"Notes:",
diff --git a/test/documentation.test.ts b/test/documentation.test.ts
index 9fbe0055..96f283fe 100644
--- a/test/documentation.test.ts
+++ b/test/documentation.test.ts
@@ -28,6 +28,7 @@ const scopedLegacyAllowedFiles = new Set([
   'docs/releases/v0.1.0.md',
   'docs/releases/v0.1.0-beta.0.md',
 ]);
+const pinnedChangelogPatchOrder = ['4.9.7', '4.9.6', '4.9.5'];
 
 function read(filePath: string): string {
   return readFileSync(join(projectRoot, filePath), 'utf-8');
@@ -116,6 +117,77 @@ describe('Documentation Integrity', () => {
     }
   });
 
+  it('keeps fix flag docs aligned across README, command reference, and CLI usage text', () => {
+    const readme = read('README.md');
+    const commandRef = read('docs/reference/commands.md');
+    const managerPath = 'lib/codex-manager.ts';
+    expect(existsSync(join(projectRoot, managerPath)), `${managerPath} should exist`).toBe(true);
+    const manager = read(managerPath);
+
+    expect(readme).toContain('codex auth fix --live --model gpt-5-codex');
+    expect(commandRef).toContain('| `--live` | forecast/report/fix |');
+    expect(commandRef).toContain('| `--model <model>` | forecast/report/fix |');
+    expect(manager).toContain(
+      'codex auth fix [--dry-run] [--json] [--live] [--model <model>]',
+    );
+    expect(manager).toContain(
+      'codex-multi-auth auth fix [--dry-run] [--json] [--live] [--model <model>]',
+    );
+  });
+
+  it('keeps dashboard help key docs consistent with current hotkey behavior', () => {
+    const readme = read('README.md');
+    const commandRef = read('docs/reference/commands.md');
+
+    expect(readme).toContain('`?`: toggle help');
+    expect(readme).not.toContain('`?` or `H`');
+    expect(commandRef).toContain('| `?` | Toggle help |');
+    expect(commandRef).not.toContain('| `H` |');
+  });
+
+  it('documents stable overrides separately from advanced/internal overrides', () => {
+    const configGuide = read('docs/configuration.md');
+    const settingsRef = read('docs/reference/settings.md');
+    const fieldInventoryPath = 'docs/development/CONFIG_FIELDS.md';
+    expect(
+      existsSync(join(projectRoot, fieldInventoryPath)),
+      `${fieldInventoryPath} should exist`,
+    ).toBe(true);
+    const fieldInventory = read(fieldInventoryPath);
+
+    expect(configGuide).toContain('## Stable Environment Overrides');
+    expect(configGuide).toContain('## Advanced/Internal Overrides');
+    expect(settingsRef).toContain('## Stable Environment Overrides');
+    expect(settingsRef).toContain('Advanced/internal toggles are documented');
+    expect(fieldInventory).toContain('### Stable (User-Facing)');
+    expect(fieldInventory).toContain('### Advanced (Runtime Tuning)');
+    expect(fieldInventory).toContain('### Advanced / Internal (Maintainers)');
+    expect(fieldInventory).toContain('## Concurrency and Windows Notes');
+    expect(fieldInventory).toContain('Windows');
+    expect(fieldInventory).toContain('EPERM');
+    expect(fieldInventory).toContain('EBUSY');
+    expect(fieldInventory).toContain('refresh lease');
+    expect(fieldInventory).toContain('Cross-process');
+    expect(fieldInventory).toContain('Refresh token skew window');
+    expect(fieldInventory.toLowerCase()).toContain('refresh token');
+  });
+
+  it('keeps changelog casing and patch-line ordering intact', () => {
+    const changelog = read('CHANGELOG.md');
+    expect(changelog.startsWith('# Changelog')).toBe(true);
+
+    const positions = pinnedChangelogPatchOrder.map((version) =>
+      changelog.indexOf(`## [${version}]`),
+    );
+    for (const position of positions) {
+      expect(position).toBeGreaterThan(-1);
+    }
+    for (let index = 0; index < positions.length - 1; index += 1) {
+      expect(positions[index]).toBeLessThan(positions[index + 1]);
+    }
+    expect(changelog).toContain('legacy package');
+  });
+
   it('has valid internal links in README.md', () => {
     const content = read('README.md');
     const links = extractInternalLinks(content);