Style contract for all docs in this repository.
- Fast onboarding for first-time operators.
- Precise references for maintainers and automation users.
- Stable wording for commands, flags, paths, and version policy.
- Consistent structure across user and maintainer docs.
User-facing docs should generally follow:
- Title and one-line lead.
- Quick path commands.
- Core operational workflow.
- Troubleshooting or failure handling.
- Related links.
Use short sections and scan-friendly tables where they improve clarity.
- Prefer direct, actionable language.
- Use runnable command examples.
- Explain expected outcomes after critical commands.
- Keep terminology consistent with runtime names.
- Avoid speculative language when behavior is deterministic.
- Canonical command family is
codex auth .... - Canonical runtime root is
~/.codex/multi-auth. - Legacy command/path references belong only in migration contexts.
- Compatibility aliases (
codex multi auth,codex multi-auth,codex multiauth) belong only in command reference, troubleshooting, or migration contexts. - Keep command flags aligned with runtime usage text.
- Behavior changes must update docs and tests together.
- New flags/settings/paths must be reflected in
docs/reference/*. - Migration-impacting changes must update
docs/upgrade.md. - Governance-impacting changes must review
SECURITY.mdandCONTRIBUTING.md. - Keep PR/issue templates aligned with validation gates.
Avoid:
- non-runnable command snippets
- conflicting path guidance across docs
- legacy-first onboarding language
- undocumented behavior drift between runtime and docs