Codex documentation and compatibility research
This directory contains the maintained Codex user guides plus the dated research that supports them. Probe results, decision records, measurements, and superseded options are evidence—not a promise that every historical observation still describes the current Codex release.
For the short, maintained, user-facing summary, see the dual-harness compatibility guide. The guide is the right link for users and plugin authors; this directory is the right place to preserve the evidence behind it.
How to read this directory
| Area | Contents | Audience |
|---|---|---|
| Compatibility and install guide | Marketplace setup, invocation, updates, and the 28-plugin support matrix | Users and plugin authors |
| Standalone skill installs | Discovery locations, one-skill installer, updates, and uninstall | Codex users and maintainers |
| Release checklist | Version, publish, refresh, and cache-verification procedure | Maintainers |
| Explicit-only invocation policy | Claude/Codex explicit-only policy mirror, risk inventory, and live Codex probe | Maintainers |
| Evidence | compat-matrix.md, *-under-codex.md, *-semantics.md, install-from-git.md, and path-resolution-evidence.md |
Maintainers rechecking behavior |
| Decisions | adr-*.md, path-resolution-options.md, and rename-viability.md |
Maintainers reviewing trade-offs |
| Measurements | skill-description-budget.md, skill-description-rewrites.md, and proposed-descriptions.json |
Maintainers changing discovery metadata |
The remaining evidence and decision files are intentionally retained because a Codex upgrade can invalidate a conclusion without changing this repository. They are not polished support documentation and may contain historical issue references, internal decision language, or scratch-probe detail.
Maintained guides and historical evidence
The compatibility guide and standalone-skills.md are the user-facing guides. The release guide is the maintainer runbook. The other files preserve dated research and should not be treated as current setup instructions unless the maintained guide links to a specific finding.
Version-sensitive evidence
Every runtime claim should be read with its test version and date. The current archive spans codex-cli 0.144.6 through 0.147.0; findings from one build must not be silently generalized to another. Reverify after any Codex upgrade, especially claims about skill discovery, hook environments, frontmatter, command surfaces, and cache layout.
When adding or revising a probe, record:
- the exact
codex --versionoutput; - the test date and whether the run used an isolated
CODEX_HOME; - the observed result, including a failure result; and
- the guide or decision that should change if the result moves.
What belongs in Beads
Beads is the task and decision-status record: capture the conclusion, scope, follow-up, and a link to the relevant evidence there. Do not use an issue note as a replacement for a reproducible probe log, and do not use this archive as a task queue. The durable split is:
- Beads: what was decided, what remains, and who/what is blocked;
- the compatibility guide: the current user-facing contract;
- this archive: why the contract says that, including dated evidence; and
- the scripts: repeatable measurements and report generation.
If an archive document is superseded, keep it and mark the newer result in the guide rather than rewriting history. Delete raw material only when its result has been captured elsewhere and the probe can no longer help explain or reproduce a compatibility decision.
Public-safety boundary
Only the compatibility guide and standalone-skills.md are intended as public-facing user guides. The release guide is public maintainer documentation. The remaining files are research records; before linking one from user documentation, remove internal process references and confirm that paths, issue identifiers, and scratch details are appropriate to publish.