From ca0af681f9fcf7d90c280e1433fa2911ae858ff6 Mon Sep 17 00:00:00 2001 From: ndycode Date: Sun, 1 Mar 2026 07:02:51 +0800 Subject: [PATCH 1/6] docs(ia): add 2026-03-01 findability audit baseline Co-authored-by: Codex --- .../IA_FINDABILITY_AUDIT_2026-03-01.md | 129 ++++++++++++++++++ 1 file changed, 129 insertions(+) create mode 100644 docs/development/IA_FINDABILITY_AUDIT_2026-03-01.md diff --git a/docs/development/IA_FINDABILITY_AUDIT_2026-03-01.md b/docs/development/IA_FINDABILITY_AUDIT_2026-03-01.md new file mode 100644 index 00000000..808ecac8 --- /dev/null +++ b/docs/development/IA_FINDABILITY_AUDIT_2026-03-01.md @@ -0,0 +1,129 @@ +# Information Architecture: CLI + Docs Findability Audit (2026-03-01) + +Scope: user-facing command taxonomy, runtime help labels, docs navigation hierarchy, and naming consistency. + +Evidence sources: +- Runtime command/help surfaces: `lib/codex-manager.ts`, `scripts/codex-routing.js` +- Docs navigation/reference surfaces: `README.md`, `docs/README.md`, `docs/reference/commands.md`, `docs/troubleshooting.md`, `docs/getting-started.md`, `docs/releases/v0.1.1.md` +- Governance/test contracts: `docs/DOCUMENTATION.md`, `docs/STYLE_GUIDE.md`, `test/documentation.test.ts` + +--- + +## Current Structure + +### Runtime command taxonomy (current) + +- `codex auth ` (canonical) + - Primary: `login`, `list`, `status`, `switch`, `check`, `features` + - Advanced: `verify-flagged`, `forecast`, `report`, `fix`, `doctor` +- Compatibility aliases: + - `codex multi auth ...` + - `codex multi-auth ...` + - `codex multiauth ...` +- Runtime usage labels before this audit mixed canonical and package-prefixed forms in some help/error paths. + +### Docs hierarchy (current) + +- Product entry + - `README.md` +- Docs portal + - `docs/README.md` +- User operations + - `docs/index.md` + - `docs/getting-started.md` + - `docs/troubleshooting.md` + - `docs/configuration.md` + - `docs/features.md` + - `docs/privacy.md` + - `docs/upgrade.md` +- Reference + - `docs/reference/commands.md` + - `docs/reference/settings.md` + - `docs/reference/storage-paths.md` +- Releases + - `docs/releases/v0.1.1.md` + - `docs/releases/v0.1.0.md` + - `docs/releases/v0.1.0-beta.0.md` + - `docs/releases/legacy-pre-0.1-history.md` + +Hierarchy depth is 3 or fewer levels. + +--- + +## Task-to-Location Mapping (Current) + +| User Task | Expected Location | Actual Location | Findability | +| --- | --- | --- | --- | +| Log in first account | `README.md` quick start / `docs/getting-started.md` | Match | Match | +| Find all auth commands and flags | `docs/reference/commands.md` | Match | Match | +| Understand alias availability | `docs/reference/commands.md` (or troubleshooting fallback) | Also shown in `README.md` and `docs/getting-started.md` | Near-miss | +| Interpret CLI usage output | Canonical `codex auth ...` labels | Mixed with `codex-multi-auth auth ...` in runtime usage strings | Near-miss | +| Check current stable release notes | `docs/releases/v0.1.1.md` via docs portal reference | `docs/README.md` reference table labeled `v0.1.0` as current stable | Near-miss | +| Find scoped legacy package guidance | Migration docs only (`docs/upgrade.md`, selected troubleshooting) | Also surfaced in stable release notes `docs/releases/v0.1.1.md` | Near-miss | + +Findability score (core tasks): 2/6 clear first-attempt match. + +--- + +## Naming Inconsistencies Found + +| Concept | Variant A | Variant B | Recommended | +| --- | --- | --- | --- | +| Canonical command label | `codex auth ...` | `codex-multi-auth auth ...` | `codex auth ...` for all primary user-facing help text | +| Alias placement policy | Reference/troubleshooting intent | Also in primary README/getting-started command flows | Keep aliases in reference/troubleshooting/migration contexts only | +| Stable release pointer | `v0.1.1` in user guides | `v0.1.0` labeled current stable in docs reference table | Use `v0.1.1` as current stable consistently | +| Scoped legacy package mention | Migration-only contexts | Stable release notes mention | Keep scoped package guidance migration-only | + +--- + +## Proposed Structure + +### Navigation model + +- Keep existing shallow hierarchy and layer model. +- Enforce one canonical location per task category: + - "How to run commands": `docs/reference/commands.md` + - "Fallback routing or alias recovery": `docs/troubleshooting.md` + - "Migration from legacy package/path": `docs/upgrade.md` + - "Current stable release": `docs/releases/v0.1.1.md` + +### Labeling model + +- Canonical command wording in runtime help/error text: `codex auth ...` +- Compatibility alias wording restricted to reference/troubleshooting/migration sections. +- Scoped legacy package guidance restricted to migration contexts. + +--- + +## Migration Path + +1. Canonicalize runtime usage/error strings to `codex auth ...`. +2. Remove alias examples from primary README/onboarding flows; keep fallback routing guidance in troubleshooting/reference. +3. Correct docs portal reference table to current stable release (`v0.1.1`). +4. Remove scoped package mention from stable release notes and point to upgrade guide for migration details. +5. Add test assertions for: + - canonical runtime usage wording, + - alias visibility boundaries, + - scoped package mention boundaries. + +--- + +## Task-to-Location Mapping (Proposed) + +| User Task | Location | Findability Improvement | +| --- | --- | --- | +| Run login/switch/check commands | `README.md` and `docs/getting-started.md` with canonical labels | Removes mixed labels in first-run paths | +| Discover full command/flag matrix | `docs/reference/commands.md` | Retains single authoritative command catalog | +| Recover from command routing problems | `docs/troubleshooting.md` | Alias fallback remains discoverable but contextual | +| Verify current stable release | `docs/README.md` -> `docs/releases/v0.1.1.md` | Eliminates stale stable-pointer ambiguity | +| Migrate from scoped legacy package | `docs/upgrade.md` | Prevents legacy naming bleed into stable operational docs | + +Target findability score for core tasks after remediation: 6/6 first-attempt match. + +--- + +## Out of Scope + +- Visual design or formatting redesign. +- Runtime behavior changes to command routing/alias support. +- Internal module naming unrelated to user-facing findability. From a8cb368dad0945f42a0be63b4eac1066d989597a Mon Sep 17 00:00:00 2001 From: ndycode Date: Sun, 1 Mar 2026 07:02:59 +0800 Subject: [PATCH 2/6] fix(cli): canonicalize auth usage labels in runtime help Co-authored-by: Codex --- lib/codex-manager.ts | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/lib/codex-manager.ts b/lib/codex-manager.ts index 7a404e7b..0202a6f3 100644 --- a/lib/codex-manager.ts +++ b/lib/codex-manager.ts @@ -281,17 +281,17 @@ function printUsage(): void { "Codex Multi-Auth CLI", "", "Usage:", - " codex-multi-auth auth login", - " codex-multi-auth auth list", - " codex-multi-auth auth status", - " codex-multi-auth auth switch ", - " codex-multi-auth auth check", - " codex-multi-auth auth features", - " codex-multi-auth auth verify-flagged [--dry-run] [--json] [--no-restore]", - " codex-multi-auth auth forecast [--live] [--json] [--model ]", - " codex-multi-auth auth report [--live] [--json] [--model ] [--out ]", - " codex-multi-auth auth fix [--dry-run] [--json] [--live] [--model ]", - " codex-multi-auth auth doctor [--json] [--fix] [--dry-run]", + " codex auth login", + " codex auth list", + " codex auth status", + " codex auth switch ", + " codex auth check", + " codex auth features", + " codex auth verify-flagged [--dry-run] [--json] [--no-restore]", + " codex auth forecast [--live] [--json] [--model ]", + " codex auth report [--live] [--json] [--model ] [--out ]", + " codex auth fix [--dry-run] [--json] [--live] [--model ]", + " codex auth doctor [--json] [--fix] [--dry-run]", "", "Notes:", " - Uses ~/.codex/multi-auth/openai-codex-accounts.json", @@ -3652,7 +3652,7 @@ async function runSwitch(args: string[]): Promise { setStoragePath(null); const indexArg = args[0]; if (!indexArg) { - console.error("Missing index. Usage: codex-multi-auth auth switch "); + console.error("Missing index. Usage: codex auth switch "); return 1; } const parsed = Number.parseInt(indexArg, 10); From c8227c4675565f44f412b3b572774af68652fdaf Mon Sep 17 00:00:00 2001 From: ndycode Date: Sun, 1 Mar 2026 07:03:12 +0800 Subject: [PATCH 3/6] docs(ia): align command findability and naming boundaries Co-authored-by: Codex --- README.md | 7 +------ docs/DOCUMENTATION.md | 6 ++++-- docs/README.md | 4 +++- docs/STYLE_GUIDE.md | 3 ++- docs/getting-started.md | 5 +++-- docs/releases/v0.1.1.md | 2 +- 6 files changed, 14 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index a34fd6ef..5c252112 100644 --- a/README.md +++ b/README.md @@ -129,11 +129,6 @@ codex auth doctor --fix | `codex auth fix --live --model gpt-5-codex` | Run repairs with live probe model | | `codex auth doctor --fix` | Diagnose and apply safe fixes | -Compatibility aliases are also supported: -- `codex multi auth ...` -- `codex multi-auth ...` -- `codex multiauth ...` - --- ## Dashboard Hotkeys @@ -226,7 +221,7 @@ codex auth login
Common symptoms -- `codex auth` unrecognized: run `where codex`, then try `codex multi auth status` +- `codex auth` unrecognized: run `where codex`, then follow `docs/troubleshooting.md` for routing fallback commands - Switch succeeds but wrong account appears active: run `codex auth switch `, then restart session - OAuth callback on port `1455` fails: free the port and re-run `codex auth login` - `missing field id_token` / `token_expired` / `refresh_token_reused`: re-login affected account diff --git a/docs/DOCUMENTATION.md b/docs/DOCUMENTATION.md index a4227c7b..a0e00941 100644 --- a/docs/DOCUMENTATION.md +++ b/docs/DOCUMENTATION.md @@ -34,6 +34,7 @@ Canonical governance for repository documentation quality and consistency. | Docs style contract | `docs/STYLE_GUIDE.md` | | Docs governance (this file) | `docs/DOCUMENTATION.md` | | Architecture internals | `docs/development/ARCHITECTURE.md` | +| IA/findability audit (2026-03-01) | `docs/development/IA_FINDABILITY_AUDIT_2026-03-01.md` | | Config fields internals | `docs/development/CONFIG_FIELDS.md` | | Config flow internals | `docs/development/CONFIG_FLOW.md` | | Repository ownership map | `docs/development/REPOSITORY_SCOPE.md` | @@ -48,8 +49,9 @@ Canonical governance for repository documentation quality and consistency. 1. Canonical package name: `codex-multi-auth`. 2. Canonical account command family: `codex auth ...`. 3. Canonical storage root: `~/.codex/multi-auth` unless explicitly overridden. -4. Legacy paths/flows belong only in migration and compatibility sections. -5. Public release line is `0.x`; historical pre-`0.1.0` entries are archived separately. +4. Compatibility aliases (`codex multi auth`, `codex multi-auth`, `codex multiauth`) belong only in command reference, troubleshooting, or migration sections. +5. Legacy paths/flows and scoped package references belong only in migration and compatibility sections. +6. Public release line is `0.x`; historical pre-`0.1.0` entries are archived separately. --- diff --git a/docs/README.md b/docs/README.md index 3f5706ca..4e01d1c9 100644 --- a/docs/README.md +++ b/docs/README.md @@ -37,7 +37,8 @@ Canonical documentation map for `codex-multi-auth`. | [reference/commands.md](reference/commands.md) | Commands, flags, and hotkeys | | [reference/settings.md](reference/settings.md) | Dashboard/backend settings and defaults | | [reference/storage-paths.md](reference/storage-paths.md) | Canonical and compatibility storage paths | -| [releases/v0.1.0.md](releases/v0.1.0.md) | Current stable release notes | +| [releases/v0.1.1.md](releases/v0.1.1.md) | Current stable release notes | +| [releases/v0.1.0.md](releases/v0.1.0.md) | Previous stable release notes | | [releases/v0.1.0-beta.0.md](releases/v0.1.0-beta.0.md) | Archived prerelease reference | | [releases/legacy-pre-0.1-history.md](releases/legacy-pre-0.1-history.md) | Archived pre-0.1 changelog history | @@ -49,6 +50,7 @@ Canonical documentation map for `codex-multi-auth`. | --- | --- | | [DOCUMENTATION.md](DOCUMENTATION.md) | Documentation governance contract | | [development/ARCHITECTURE.md](development/ARCHITECTURE.md) | Runtime architecture and invariants | +| [development/IA_FINDABILITY_AUDIT_2026-03-01.md](development/IA_FINDABILITY_AUDIT_2026-03-01.md) | IA/findability baseline, mismatches, and migration plan | | [development/CONFIG_FIELDS.md](development/CONFIG_FIELDS.md) | Complete field and env inventory | | [development/CONFIG_FLOW.md](development/CONFIG_FLOW.md) | Configuration resolution flow | | [development/REPOSITORY_SCOPE.md](development/REPOSITORY_SCOPE.md) | Ownership map by repository path | diff --git a/docs/STYLE_GUIDE.md b/docs/STYLE_GUIDE.md index 9b563b06..5e0d3e95 100644 --- a/docs/STYLE_GUIDE.md +++ b/docs/STYLE_GUIDE.md @@ -42,7 +42,8 @@ Use short sections and scan-friendly tables where they improve clarity. 1. Canonical command family is `codex auth ...`. 2. Canonical runtime root is `~/.codex/multi-auth`. 3. Legacy command/path references belong only in migration contexts. -4. Keep command flags aligned with runtime usage text. +4. Compatibility aliases (`codex multi auth`, `codex multi-auth`, `codex multiauth`) belong only in command reference, troubleshooting, or migration contexts. +5. Keep command flags aligned with runtime usage text. --- diff --git a/docs/getting-started.md b/docs/getting-started.md index 1c893ec3..629fe5eb 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -89,9 +89,10 @@ If `codex auth` is not recognized: ```bash where codex -codex multi auth status ``` +Then continue with [troubleshooting.md](troubleshooting.md#verify-install-and-routing) for routing fallback commands. + If OAuth callback on `1455` fails: - Stop the process using port `1455`. @@ -111,4 +112,4 @@ codex auth check - [features.md](features.md) - [configuration.md](configuration.md) - [troubleshooting.md](troubleshooting.md) -- [reference/commands.md](reference/commands.md) \ No newline at end of file +- [reference/commands.md](reference/commands.md) diff --git a/docs/releases/v0.1.1.md b/docs/releases/v0.1.1.md index 290ba0a1..1e0fb7b3 100644 --- a/docs/releases/v0.1.1.md +++ b/docs/releases/v0.1.1.md @@ -107,7 +107,7 @@ All six PRs were audited, fixed, and unified into PR #14 before merge. ## Notes -- Legacy scoped package `@ndycode/codex-multi-auth` is migration-only. +- Legacy scoped prerelease package is migration-only (see `docs/upgrade.md`). - Canonical runtime paths are under `~/.codex/multi-auth`. - Per-project accounts shared across linked worktrees via repo identity root. - Settings writes use queued retry with EBUSY/EPERM/EAGAIN backoff (max 4 retries, exponential). From 98a21aa8a460f5dd286d0f4bbb0c642db1ce9fda Mon Sep 17 00:00:00 2001 From: ndycode Date: Sun, 1 Mar 2026 07:03:21 +0800 Subject: [PATCH 4/6] test(docs): enforce alias scoping and stable release reference checks Co-authored-by: Codex --- test/documentation.test.ts | 25 ++++++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/test/documentation.test.ts b/test/documentation.test.ts index cbced9b3..9075c12f 100644 --- a/test/documentation.test.ts +++ b/test/documentation.test.ts @@ -33,6 +33,12 @@ const scopedLegacyAllowedFiles = new Set([ 'docs/releases/v0.1.0-beta.0.md', ]); +const compatibilityAliasAllowedFiles = new Set([ + 'docs/reference/commands.md', + 'docs/troubleshooting.md', + 'docs/upgrade.md', +]); + function read(filePath: string): string { return readFileSync(join(projectRoot, filePath), 'utf-8'); } @@ -71,6 +77,7 @@ describe('Documentation Integrity', () => { expect(portal).toContain('releases/v0.1.0.md'); expect(portal).toContain('releases/v0.1.0-beta.0.md'); expect(portal).toContain('releases/legacy-pre-0.1-history.md'); + expect(portal).toContain('| [releases/v0.1.1.md](releases/v0.1.1.md) | Current stable release notes |'); const beta = read('docs/releases/v0.1.0-beta.0.md'); expect(beta).toContain('Archived'); @@ -117,6 +124,22 @@ describe('Documentation Integrity', () => { } }); + it('keeps compatibility command aliases scoped to reference, troubleshooting, or migration docs', () => { + const files = ['README.md', ...userDocs]; + const aliasPattern = /\bcodex (multi auth|multi-auth|multiauth)\b/; + + for (const filePath of files) { + const content = read(filePath); + const hasAlias = aliasPattern.test(content); + if (hasAlias) { + expect( + compatibilityAliasAllowedFiles.has(filePath), + `${filePath} should not include compatibility alias commands`, + ).toBe(true); + } + } + }); + it('keeps codex auth as the command standard in key docs', () => { const keyDocs = [ 'README.md', @@ -144,7 +167,7 @@ describe('Documentation Integrity', () => { expect(readme).toContain('codex auth fix --live --model gpt-5-codex'); expect(commandRef).toContain('| `--live` | forecast, report, fix |'); expect(commandRef).toContain('| `--model ` | forecast, report, fix |'); - expect(manager).toContain('codex-multi-auth auth fix [--dry-run] [--json] [--live] [--model ]'); + expect(manager).toContain('codex auth fix [--dry-run] [--json] [--live] [--model ]'); }); it('documents stable overrides separately from advanced and internal overrides', () => { From 541e87fd1287bb1d5707b011e44cbeb28a9d05bf Mon Sep 17 00:00:00 2001 From: ndycode Date: Sun, 1 Mar 2026 07:17:56 +0800 Subject: [PATCH 5/6] fix(review): address codrabbit actionable findings on PR16 Co-authored-by: Codex --- .../IA_FINDABILITY_AUDIT_2026-03-01.md | 25 +++++++++++++++---- test/documentation.test.ts | 5 +++- 2 files changed, 24 insertions(+), 6 deletions(-) diff --git a/docs/development/IA_FINDABILITY_AUDIT_2026-03-01.md b/docs/development/IA_FINDABILITY_AUDIT_2026-03-01.md index 808ecac8..82f2ebf6 100644 --- a/docs/development/IA_FINDABILITY_AUDIT_2026-03-01.md +++ b/docs/development/IA_FINDABILITY_AUDIT_2026-03-01.md @@ -20,7 +20,10 @@ Evidence sources: - `codex multi auth ...` - `codex multi-auth ...` - `codex multiauth ...` -- Runtime usage labels before this audit mixed canonical and package-prefixed forms in some help/error paths. +- Runtime usage labels before this audit mixed canonical and package-prefixed forms in help/error paths. + - Prior `printUsage()` output in `lib/codex-manager.ts` used package-prefixed forms such as `codex-multi-auth auth fix [--dry-run] [--json] [--live] [--model ]`. + - Prior `runSwitch()` error text in `lib/codex-manager.ts` used `Missing index. Usage: codex-multi-auth auth switch `. + - Post-fix regression baseline is now asserted in `test/documentation.test.ts` by checking canonical `codex auth ...` usage and switch-error strings. ### Docs hierarchy (current) @@ -52,6 +55,11 @@ Hierarchy depth is 3 or fewer levels. ## Task-to-Location Mapping (Current) +Scoring rubric: +- `Match`: task is discoverable in the expected location within one navigation hop. +- `Near-miss`: task is discoverable but appears in unexpected locations or requires extra context-switch hops. +- `Lost`: task is not discoverable through expected navigation. + | User Task | Expected Location | Actual Location | Findability | | --- | --- | --- | --- | | Log in first account | `README.md` quick start / `docs/getting-started.md` | Match | Match | @@ -63,6 +71,12 @@ Hierarchy depth is 3 or fewer levels. Findability score (core tasks): 2/6 clear first-attempt match. +Near-miss to remediation traceability: +- `Understand alias availability` -> resolved by scoping aliases to reference/troubleshooting/migration surfaces and removing alias examples from primary onboarding flows. +- `Interpret CLI usage output` -> resolved by canonicalizing runtime help and error usage strings to `codex auth ...` in `lib/codex-manager.ts`. +- `Check current stable release notes` -> resolved by updating docs portal stable pointer to `docs/releases/v0.1.1.md`. +- `Find scoped legacy package guidance` -> resolved by keeping scoped-package references in migration contexts and removing them from stable release notes. + --- ## Naming Inconsistencies Found @@ -101,10 +115,11 @@ Findability score (core tasks): 2/6 clear first-attempt match. 2. Remove alias examples from primary README/onboarding flows; keep fallback routing guidance in troubleshooting/reference. 3. Correct docs portal reference table to current stable release (`v0.1.1`). 4. Remove scoped package mention from stable release notes and point to upgrade guide for migration details. -5. Add test assertions for: - - canonical runtime usage wording, - - alias visibility boundaries, - - scoped package mention boundaries. +5. Maintain deterministic regression checks in `test/documentation.test.ts`: + - `uses scoped package only in explicit legacy migration notes` enforces scoped package boundaries. + - `keeps compatibility command aliases scoped to reference, troubleshooting, or migration docs` enforces alias-visibility boundaries with explicit allowlist files. + - `keeps canonical auth usage labels aligned across README, reference, and CLI usage text` enforces canonical runtime help/error wording. + - Keep cross-platform verification requirements explicit: Windows-oriented validation patterns (for example HOME/USERPROFILE handling and Windows path guidance checks already exercised in the CODEX config precedence test block) must be extended whenever new shell-sensitive command rendering is introduced. --- diff --git a/test/documentation.test.ts b/test/documentation.test.ts index 9075c12f..49629c9c 100644 --- a/test/documentation.test.ts +++ b/test/documentation.test.ts @@ -157,7 +157,7 @@ describe('Documentation Integrity', () => { } }); - it('keeps fix command flag docs aligned across README, reference, and CLI usage text', () => { + it('keeps canonical auth usage labels aligned across README, reference, and CLI usage text', () => { const readme = read('README.md'); const commandRef = read('docs/reference/commands.md'); const managerPath = 'lib/codex-manager.ts'; @@ -167,7 +167,10 @@ describe('Documentation Integrity', () => { expect(readme).toContain('codex auth fix --live --model gpt-5-codex'); expect(commandRef).toContain('| `--live` | forecast, report, fix |'); expect(commandRef).toContain('| `--model ` | forecast, report, fix |'); + expect(manager).toContain('codex auth login'); expect(manager).toContain('codex auth fix [--dry-run] [--json] [--live] [--model ]'); + expect(manager).toContain('Missing index. Usage: codex auth switch '); + expect(manager).not.toContain('codex-multi-auth auth switch '); }); it('documents stable overrides separately from advanced and internal overrides', () => { From 2ddf7184c51ab62884f6c4f76bc6af68c5814972 Mon Sep 17 00:00:00 2001 From: ndycode Date: Sun, 1 Mar 2026 07:28:39 +0800 Subject: [PATCH 6/6] docs(audit): add explicit test anchors for migration step Co-authored-by: Codex --- docs/development/IA_FINDABILITY_AUDIT_2026-03-01.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/development/IA_FINDABILITY_AUDIT_2026-03-01.md b/docs/development/IA_FINDABILITY_AUDIT_2026-03-01.md index 82f2ebf6..c0c7e4d1 100644 --- a/docs/development/IA_FINDABILITY_AUDIT_2026-03-01.md +++ b/docs/development/IA_FINDABILITY_AUDIT_2026-03-01.md @@ -116,10 +116,10 @@ Near-miss to remediation traceability: 3. Correct docs portal reference table to current stable release (`v0.1.1`). 4. Remove scoped package mention from stable release notes and point to upgrade guide for migration details. 5. Maintain deterministic regression checks in `test/documentation.test.ts`: - - `uses scoped package only in explicit legacy migration notes` enforces scoped package boundaries. - - `keeps compatibility command aliases scoped to reference, troubleshooting, or migration docs` enforces alias-visibility boundaries with explicit allowlist files. - - `keeps canonical auth usage labels aligned across README, reference, and CLI usage text` enforces canonical runtime help/error wording. - - Keep cross-platform verification requirements explicit: Windows-oriented validation patterns (for example HOME/USERPROFILE handling and Windows path guidance checks already exercised in the CODEX config precedence test block) must be extended whenever new shell-sensitive command rendering is introduced. + - `uses scoped package only in explicit legacy migration notes` (`test/documentation.test.ts:104`) enforces scoped package boundaries. + - `keeps compatibility command aliases scoped to reference, troubleshooting, or migration docs` (`test/documentation.test.ts:127`) enforces alias-visibility boundaries with explicit allowlist files. + - `keeps canonical auth usage labels aligned across README, reference, and CLI usage text` (`test/documentation.test.ts:160`) enforces canonical runtime help/error wording. + - Keep cross-platform verification requirements explicit: Windows-oriented validation patterns (for example HOME/USERPROFILE handling and Windows path guidance checks in `test/documentation.test.ts:244-245`) must be extended whenever new shell-sensitive command rendering is introduced, including explicit `codex auth` output-escaping checks for `cmd.exe` and `PowerShell`. ---