|
| 1 | +# Information Architecture: CLI + Docs Findability Audit (2026-03-01) |
| 2 | + |
| 3 | +Scope: user-facing command taxonomy, runtime help labels, docs navigation hierarchy, and naming consistency. |
| 4 | + |
| 5 | +Evidence sources: |
| 6 | +- Runtime command/help surfaces: `lib/codex-manager.ts`, `scripts/codex-routing.js` |
| 7 | +- 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` |
| 8 | +- Governance/test contracts: `docs/DOCUMENTATION.md`, `docs/STYLE_GUIDE.md`, `test/documentation.test.ts` |
| 9 | + |
| 10 | +--- |
| 11 | + |
| 12 | +## Current Structure |
| 13 | + |
| 14 | +### Runtime command taxonomy (current) |
| 15 | + |
| 16 | +- `codex auth <subcommand>` (canonical) |
| 17 | + - Primary: `login`, `list`, `status`, `switch`, `check`, `features` |
| 18 | + - Advanced: `verify-flagged`, `forecast`, `report`, `fix`, `doctor` |
| 19 | +- Compatibility aliases: |
| 20 | + - `codex multi auth ...` |
| 21 | + - `codex multi-auth ...` |
| 22 | + - `codex multiauth ...` |
| 23 | +- Runtime usage labels before this audit mixed canonical and package-prefixed forms in help/error paths. |
| 24 | + - Prior `printUsage()` output in `lib/codex-manager.ts` used package-prefixed forms such as `codex-multi-auth auth fix [--dry-run] [--json] [--live] [--model <model>]`. |
| 25 | + - Prior `runSwitch()` error text in `lib/codex-manager.ts` used `Missing index. Usage: codex-multi-auth auth switch <index>`. |
| 26 | + - Post-fix regression baseline is now asserted in `test/documentation.test.ts` by checking canonical `codex auth ...` usage and switch-error strings. |
| 27 | + - Canonical baseline strings now used in runtime output are `codex auth fix [--dry-run] [--json] [--live] [--model <model>]` and `Missing index. Usage: codex auth switch <index>`. |
| 28 | + |
| 29 | +### Docs hierarchy (current) |
| 30 | + |
| 31 | +- Product entry |
| 32 | + - `README.md` |
| 33 | +- Docs portal |
| 34 | + - `docs/README.md` |
| 35 | +- User operations |
| 36 | + - `docs/index.md` |
| 37 | + - `docs/getting-started.md` |
| 38 | + - `docs/troubleshooting.md` |
| 39 | + - `docs/configuration.md` |
| 40 | + - `docs/features.md` |
| 41 | + - `docs/privacy.md` |
| 42 | + - `docs/upgrade.md` |
| 43 | +- Reference |
| 44 | + - `docs/reference/commands.md` |
| 45 | + - `docs/reference/settings.md` |
| 46 | + - `docs/reference/storage-paths.md` |
| 47 | +- Releases |
| 48 | + - `docs/releases/v0.1.1.md` |
| 49 | + - `docs/releases/v0.1.0.md` |
| 50 | + - `docs/releases/v0.1.0-beta.0.md` |
| 51 | + - `docs/releases/legacy-pre-0.1-history.md` |
| 52 | + |
| 53 | +Hierarchy depth is 3 or fewer levels. |
| 54 | + |
| 55 | +--- |
| 56 | + |
| 57 | +## Task-to-Location Mapping (Current) |
| 58 | + |
| 59 | +Scoring rubric: |
| 60 | +- `Match`: task is discoverable in the expected location within one navigation hop. |
| 61 | +- `Near-miss`: task is discoverable but appears in unexpected locations or requires extra context-switch hops. |
| 62 | +- `Lost`: task is not discoverable through expected navigation. |
| 63 | + |
| 64 | +| User Task | Expected Location | Actual Location | Findability | |
| 65 | +| --- | --- | --- | --- | |
| 66 | +| Log in first account | `README.md` quick start / `docs/getting-started.md` | Match | Match | |
| 67 | +| Find all auth commands and flags | `docs/reference/commands.md` | Match | Match | |
| 68 | +| Understand alias availability | `docs/reference/commands.md` (or troubleshooting fallback) | Also shown in `README.md` and `docs/getting-started.md` | Near-miss | |
| 69 | +| Interpret CLI usage output | Canonical `codex auth ...` labels | Mixed with `codex-multi-auth auth ...` in runtime usage strings | Near-miss | |
| 70 | +| 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 | |
| 71 | +| 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 | |
| 72 | + |
| 73 | +Findability score (core tasks): 2/6 clear first-attempt match. |
| 74 | + |
| 75 | +Verification evidence snapshot (2026-03-01): |
| 76 | +- Runtime source checks in `lib/codex-manager.ts` confirm canonical `codex auth ...` usage labels and switch-error wording. |
| 77 | +- Documentation checks in `test/documentation.test.ts` validate stable release pointer correctness and alias-scope allowlists. |
| 78 | +- Alias detection checks are case-insensitive to prevent false negatives on mixed-case docs labels. |
| 79 | + |
| 80 | +Near-miss to remediation traceability: |
| 81 | +- `Understand alias availability` -> resolved by scoping aliases to reference/troubleshooting/migration surfaces and removing alias examples from primary onboarding flows. |
| 82 | +- `Interpret CLI usage output` -> resolved by canonicalizing runtime help and error usage strings to `codex auth ...` in `lib/codex-manager.ts`. |
| 83 | +- `Check current stable release notes` -> resolved by updating docs portal stable pointer to `docs/releases/v0.1.1.md`. |
| 84 | +- `Find scoped legacy package guidance` -> resolved by keeping scoped-package references in migration contexts and removing them from stable release notes. |
| 85 | + |
| 86 | +--- |
| 87 | + |
| 88 | +## Naming Inconsistencies Found |
| 89 | + |
| 90 | +| Concept | Variant A | Variant B | Recommended | |
| 91 | +| --- | --- | --- | --- | |
| 92 | +| Canonical command label | `codex auth ...` | `codex-multi-auth auth ...` | `codex auth ...` for all primary user-facing help text | |
| 93 | +| Alias placement policy | Reference/troubleshooting intent | Also in primary README/getting-started command flows | Keep aliases in reference/troubleshooting/migration contexts only | |
| 94 | +| 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 | |
| 95 | +| Scoped legacy package mention | Migration-only contexts | Stable release notes mention | Keep scoped package guidance migration-only | |
| 96 | + |
| 97 | +--- |
| 98 | + |
| 99 | +## Proposed Structure |
| 100 | + |
| 101 | +### Navigation model |
| 102 | + |
| 103 | +- Keep existing shallow hierarchy and layer model. |
| 104 | +- Enforce one canonical location per task category: |
| 105 | + - "How to run commands": `docs/reference/commands.md` |
| 106 | + - "Fallback routing or alias recovery": `docs/troubleshooting.md` |
| 107 | + - "Migration from legacy package/path": `docs/upgrade.md` |
| 108 | + - "Current stable release": `docs/releases/v0.1.1.md` |
| 109 | + |
| 110 | +### Labeling model |
| 111 | + |
| 112 | +- Canonical command wording in runtime help/error text: `codex auth ...` |
| 113 | +- Compatibility alias wording restricted to reference/troubleshooting/migration sections. |
| 114 | +- Scoped legacy package guidance restricted to migration contexts. |
| 115 | + |
| 116 | +--- |
| 117 | + |
| 118 | +## Migration Path |
| 119 | + |
| 120 | +1. Canonicalize runtime usage/error strings to `codex auth ...`. |
| 121 | +2. Remove alias examples from primary README/onboarding flows; keep fallback routing guidance in troubleshooting/reference. |
| 122 | +3. Correct docs portal reference table to current stable release (`v0.1.1`). |
| 123 | +4. Remove scoped package mention from stable release notes and point to upgrade guide for migration details. |
| 124 | +5. Maintain deterministic regression checks in `test/documentation.test.ts`: |
| 125 | + - `uses scoped package only in explicit legacy migration notes` (`test/documentation.test.ts:104`) enforces scoped package boundaries. |
| 126 | + - `keeps compatibility command aliases scoped to reference, troubleshooting, or migration docs` (`test/documentation.test.ts:127`) enforces alias-visibility boundaries with explicit allowlist files. |
| 127 | + - `keeps fix command flag docs aligned across README, reference, and CLI usage text` (`test/documentation.test.ts:160`) enforces canonical runtime help/error wording. |
| 128 | + - 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`. |
| 129 | + |
| 130 | +--- |
| 131 | + |
| 132 | +## Task-to-Location Mapping (Proposed) |
| 133 | + |
| 134 | +| User Task | Location | Findability Improvement | |
| 135 | +| --- | --- | --- | |
| 136 | +| Run login/switch/check commands | `README.md` and `docs/getting-started.md` with canonical labels | Removes mixed labels in first-run paths | |
| 137 | +| Discover full command/flag matrix | `docs/reference/commands.md` | Retains single authoritative command catalog | |
| 138 | +| Recover from command routing problems | `docs/troubleshooting.md` | Alias fallback remains discoverable but contextual | |
| 139 | +| Verify current stable release | `docs/README.md` -> `docs/releases/v0.1.1.md` | Eliminates stale stable-pointer ambiguity | |
| 140 | +| Migrate from scoped legacy package | `docs/upgrade.md` | Prevents legacy naming bleed into stable operational docs | |
| 141 | + |
| 142 | +Target findability score for core tasks after remediation: 6/6 first-attempt match. |
| 143 | + |
| 144 | +--- |
| 145 | + |
| 146 | +## Out of Scope |
| 147 | + |
| 148 | +- Visual design or formatting redesign. |
| 149 | +- Runtime behavior changes to command routing/alias support. |
| 150 | +- Internal module naming unrelated to user-facing findability. |
0 commit comments