Documentation Architecture

May 3, 2026 ยท View on GitHub

Canonical governance for repository documentation quality and consistency.

Documentation Layers

LayerAudiencePrimary goal
Product entryNew operators and search visitorsExplain the project quickly, prioritize the right concepts first, and complete first successful login/check
User operationsDaily usersConfigure, run, recover, and report issues safely
ReferencePower users and maintainersExact command, setting, and path lookup
DevelopmentContributors and maintainersInternal architecture, flow, tests, and ownership

Source of Truth Map

ScopeFile
Project entryREADME.md
Docs portaldocs/README.md
Daily operator landingdocs/index.md
Onboardingdocs/getting-started.md
FAQdocs/faq.md
Public architecture overviewdocs/architecture.md
Feature mapdocs/features.md
Configuration guidedocs/configuration.md
Troubleshooting guidedocs/troubleshooting.md
Privacy and data handlingdocs/privacy.md
Upgrade and migrationdocs/upgrade.md
Command referencedocs/reference/commands.md
Public API contractdocs/reference/public-api.md
Error contract referencedocs/reference/error-contracts.md
Settings referencedocs/reference/settings.md
Storage path referencedocs/reference/storage-paths.md
Docs style contractdocs/STYLE_GUIDE.md
Docs governance (this file)docs/DOCUMENTATION.md
Architecture internalsdocs/development/ARCHITECTURE.md
Runtime rotation implementation guidedocs/development/ARCHITECTURE.md
GitHub metadata guidancedocs/development/GITHUB_DISCOVERABILITY.md
IA/findability audit (2026-03-01)docs/development/IA_FINDABILITY_AUDIT_2026-03-01.md
Config fields internalsdocs/development/CONFIG_FIELDS.md
Config flow internalsdocs/development/CONFIG_FLOW.md
Repository ownership mapdocs/development/REPOSITORY_SCOPE.md
Testing and release gatesdocs/development/TESTING.md
TUI parity checklistdocs/development/TUI_PARITY_CHECKLIST.md
Benchmark methodologydocs/benchmarks/code-edit-format-benchmark.md
Historical audit snapshotsdocs/audits/

Canonical Policy

  1. Canonical package name: codex-multi-auth.
  2. Canonical account command family: codex-multi-auth ....
  3. Canonical storage root: ~/.codex/multi-auth unless explicitly overridden.
  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. Current stable release line is 2.x; foundational 0.x and pre-0.1.0 entries stay archived separately.
  7. Runtime rotation is documented as default-on unless a future release intentionally changes that policy.
  8. Audit evidence under docs/audits/ is historical snapshot material. Do not rewrite captured evidence to look current; add snapshot notes or new audit artifacts instead.

Update Rules

When runtime behavior changes:

  1. Update README.md and docs/getting-started.md first.
  2. Update docs/faq.md and docs/architecture.md when the first-time-user story or public system framing changes.
  3. Update docs/features.md for capability coverage changes.
  4. Update relevant command/settings/path references.
  5. Update docs/troubleshooting.md with new failure signatures or recovery steps.
  6. Update development docs when architecture, config flow, or GitHub-facing metadata guidance changes.
  7. Update docs/upgrade.md for migration-impacting behavior.
  8. Update docs/reference/storage-paths.md when runtime files, app bind files, or official Codex state interactions change.
  9. Update SECURITY.md, CONTRIBUTING.md, and CODE_OF_CONDUCT.md when governance or safe usage guidance changes.
  10. Keep issue/PR templates aligned with validation expectations.

Documentation QA Checklist

Before merge:

  1. Every documented command is executable as written.
  2. CLI flags documented in references match runtime parser/usage output.
  3. Paths match runtime modules (lib/runtime-paths.ts, lib/storage.ts, lib/config.ts).
  4. Internal links are valid.
  5. Cross-platform instructions exist for OS-sensitive operations.
  6. No conflicting guidance between README, docs, and governance files.
  7. Public landing pages use accurate discoverability terms without keyword stuffing or ranking promises.