supersede: unify PRs #15 #16 #17 #18 #19 #20 #24 #25 into one branch

.github/workflows/ci.yml

@@ -34,6 +34,9 @@ jobs:
       - name: Security audit (CI policy)
         run: npm run audit:ci
 
+      - name: Lockfile floor guard
+        run: npm run test -- test/lockfile-version-floor.test.ts
+
       - name: Security audit (full dependency tree, non-blocking)
         continue-on-error: true
         run: npm run audit:all

.gitignore

@@ -8,6 +8,7 @@ opencode.json
 .opencode/
 .omx/
 tmp
+.tmp
 tmp*
 .tmp*/
 .tmp-*/

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
 <details>
 <summary><b>Common symptoms</b></summary>
 
-- `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 <index>`, 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
@@ -259,6 +254,8 @@ codex auth doctor --json
 - Configuration: [docs/configuration.md](docs/configuration.md)
 - Troubleshooting: [docs/troubleshooting.md](docs/troubleshooting.md)
 - Commands reference: [docs/reference/commands.md](docs/reference/commands.md)
+- Public API contract: [docs/reference/public-api.md](docs/reference/public-api.md)
+- Error contracts: [docs/reference/error-contracts.md](docs/reference/error-contracts.md)
 - Settings reference: [docs/reference/settings.md](docs/reference/settings.md)
 - Storage paths: [docs/reference/storage-paths.md](docs/reference/storage-paths.md)
 - Upgrade guide: [docs/upgrade.md](docs/upgrade.md)
@@ -268,9 +265,9 @@ codex auth doctor --json
 
 ## Release Notes
 
-- Current stable: [docs/releases/v0.1.3.md](docs/releases/v0.1.3.md)
-- Previous stable: [docs/releases/v0.1.2.md](docs/releases/v0.1.2.md)
-- Earlier stable: [docs/releases/v0.1.1.md](docs/releases/v0.1.1.md)
+- Current stable: [docs/releases/v0.1.4.md](docs/releases/v0.1.4.md)
+- Previous stable: [docs/releases/v0.1.3.md](docs/releases/v0.1.3.md)
+- Earlier stable: [docs/releases/v0.1.2.md](docs/releases/v0.1.2.md)
 - Archived prerelease: [docs/releases/v0.1.0-beta.0.md](docs/releases/v0.1.0-beta.0.md)
 
 ## License

SECURITY.md

@@ -75,6 +75,11 @@ The following are not treated as vulnerabilities in this repository:
 
 ## Dependency and Release Hygiene
 
+Security override rationale (`package.json` -> `overrides`):
+
+- `hono`: pinned to `^4.12.3` to keep builds out of the vulnerable `4.12.0-4.12.1` range reported in `GHSA-xh87-mx6m-69f3` (authentication bypass advisory).
+- `rollup`: pinned to `^4.59.0` to keep the Vite and Vitest transitive graph above the vulnerable `<4.59.0` range surfaced by `npm audit`.
+
 Before release and after dependency changes:
 
 ```bash
@@ -94,4 +99,4 @@ For non-vulnerability security questions, open a GitHub discussion.
 ---
 
 This project is not affiliated with OpenAI.
-For OpenAI platform security concerns, contact OpenAI directly.
+For OpenAI platform security concerns, contact OpenAI directly.

docs/DOCUMENTATION.md

@@ -29,11 +29,14 @@ Canonical governance for repository documentation quality and consistency.
 | Privacy and data handling | `docs/privacy.md` |
 | Upgrade and migration | `docs/upgrade.md` |
 | Command reference | `docs/reference/commands.md` |
+| Public API contract | `docs/reference/public-api.md` |
+| Error contract reference | `docs/reference/error-contracts.md` |
 | Settings reference | `docs/reference/settings.md` |
 | Storage path reference | `docs/reference/storage-paths.md` |
 | 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 +51,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.
 
 ---
 

docs/README.md

@@ -24,9 +24,9 @@ Canonical documentation map for `codex-multi-auth`.
 | [troubleshooting.md](troubleshooting.md) | Deterministic recovery playbooks |
 | [privacy.md](privacy.md) | Data handling and local storage behavior |
 | [upgrade.md](upgrade.md) | Migration from legacy package/path history |
-| [releases/v0.1.3.md](releases/v0.1.3.md) | Stable release notes |
-| [releases/v0.1.2.md](releases/v0.1.2.md) | Previous stable release notes |
-| [releases/v0.1.1.md](releases/v0.1.1.md) | Earlier stable release notes |
+| [releases/v0.1.4.md](releases/v0.1.4.md) | Stable release notes |
+| [releases/v0.1.3.md](releases/v0.1.3.md) | Previous stable release notes |
+| [releases/v0.1.2.md](releases/v0.1.2.md) | Earlier stable release notes |
 | [releases/v0.1.0-beta.0.md](releases/v0.1.0-beta.0.md) | Archived prerelease notes |
 
 ---
@@ -38,8 +38,11 @@ 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.3.md](releases/v0.1.3.md) | Current stable release notes |
+| [reference/public-api.md](reference/public-api.md) | Tiered public API stability and semver contract |
+| [reference/error-contracts.md](reference/error-contracts.md) | CLI, JSON, and helper error semantics contract |
+| [releases/v0.1.4.md](releases/v0.1.4.md) | Current stable release notes |
 | [releases/v0.1.0-beta.0.md](releases/v0.1.0-beta.0.md) | Archived prerelease reference |
+| [User Guides release notes](#user-guides) | Stable, previous, and archived release notes |
 | [releases/legacy-pre-0.1-history.md](releases/legacy-pre-0.1-history.md) | Archived pre-0.1 changelog history |
 
 ---
@@ -50,6 +53,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 |

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.
 
 ---
 

docs/development/DEEP_AUDIT_2026-03-01.md

@@ -0,0 +1,64 @@
+# Deep Audit Report (2026-03-01)
+
+## Scope
+
+- Full repository hardening audit from `origin/main` at commit `36cf5d4e5c4d30f5a98b44f5711379425c7c8b1a`.
+- Runtime, test, docs/governance, and dependency surfaces.
+- Executed in isolated worktree branch: `audit/deep-hardening-2026-03-01`.
+
+## Findings
+
+### AUD-001 (Blocker) - Documentation policy regression
+
+- Surface: docs integrity contract (`test/documentation.test.ts`).
+- Evidence: `uses scoped package only in explicit legacy migration notes` failed.
+- Root cause: `docs/releases/v0.1.1.md` contained a scoped package literal outside the allowlist.
+- Resolution: replaced scoped literal with generic migration-only wording and explicit link to upgrade guide.
+- Files:
+  - `docs/releases/v0.1.1.md`
+
+### AUD-002 (High) - Runtime dependency vulnerability (`hono`)
+
+- Surface: production dependency audit (`npm audit --omit=dev --audit-level=high`).
+- Evidence: `hono` high severity advisory (vulnerable range included locked version).
+- Resolution:
+  - Raised direct dependency floor to `^4.12.2`.
+  - Raised override floor to `^4.12.2`.
+  - Refreshed lockfile to patched resolved version.
+- Files:
+  - `package.json`
+  - `package-lock.json`
+
+### AUD-003 (High, dev tooling) - Unexpected `rollup` vulnerability in audit CI
+
+- Surface: `npm run audit:dev:allowlist`.
+- Evidence: high-severity `rollup` advisory was not allowlisted and failed `audit:ci`.
+- Resolution:
+  - Added override `rollup: ^4.59.0`.
+  - Refreshed lockfile to patched resolved version.
+- Files:
+  - `package.json`
+  - `package-lock.json`
+
+## Validation Evidence
+
+- `npm run lint` -> pass
+- `npm run typecheck` -> pass
+- `npm run build` -> pass
+- `npm test` -> pass (`87` files, `2071` tests)
+- `npm test -- test/documentation.test.ts` -> pass
+- `npm run audit:ci` -> pass
+  - `audit:prod` reports `0` vulnerabilities
+  - `audit:dev:allowlist` reports only allowlisted `minimatch` highs
+
+## Architect Verification
+
+- Verdict: `APPROVE` (no blockers).
+- Summary:
+  - Dependency strategy is minimal and compatible with current toolchain ranges.
+  - Docs change aligns with existing documentation integrity policy.
+
+## Residual Risk
+
+- Dev-only allowlisted `minimatch` findings remain visible in `audit:dev:allowlist`; currently non-blocking under repository policy.
+

docs/development/IA_FINDABILITY_AUDIT_2026-03-01.md

@@ -0,0 +1,150 @@
+# 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 <subcommand>` (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 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 <model>]`.
+  - Prior `runSwitch()` error text in `lib/codex-manager.ts` used `Missing index. Usage: codex-multi-auth auth switch <index>`.
+  - Post-fix regression baseline is now asserted in `test/documentation.test.ts` by checking canonical `codex auth ...` usage and switch-error strings.
+  - 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>`.
+
+### 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)
+
+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 |
+| 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.
+
+Verification evidence snapshot (2026-03-01):
+- Runtime source checks in `lib/codex-manager.ts` confirm canonical `codex auth ...` usage labels and switch-error wording.
+- Documentation checks in `test/documentation.test.ts` validate stable release pointer correctness and alias-scope allowlists.
+- Alias detection checks are case-insensitive to prevent false negatives on mixed-case docs labels.
+
+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
+
+| 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. Maintain deterministic regression checks in `test/documentation.test.ts`:
+   - `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 fix command flag docs 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`.
+
+---
+
+## 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.

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)
+- [reference/commands.md](reference/commands.md)

docs/reference/commands.md

@@ -115,5 +115,7 @@ codex auth doctor --fix
 ## Related
 
 - [../features.md](../features.md)
+- [public-api.md](public-api.md)
+- [error-contracts.md](error-contracts.md)
 - [settings.md](settings.md)
-- [../troubleshooting.md](../troubleshooting.md)
+- [../troubleshooting.md](../troubleshooting.md)