codex-docs: Instructions file for Codex

AGENTS Notes

Scope

• This repository is a periodic mirror for Codex-related docs and references.
• Keep changes focused on sync automation, output quality, and release hygiene.

Generated content boundaries

• Treat docs/codex_capabilities.json, docs/codex_cli_surface.json, docs/cli-surface/**, docs/codex_models.json, docs/docs_manifest.json, docs/sync_summary.json, docs/source_coverage.json, docs/freshness.json, docs/developers.openai.com/**, docs/learn.chatgpt.com/**, docs/feature-flags/**, docs/github.openai.com/**, docs/platform.openai.com/**, dot_codex/skills/dot_system/**, system_prompts/codex-cli/**, weekly/events/**, and weekly/YYYY-MM-DD.md as generated output.
• Do not hand-edit mirrored docs, skills, or prompts unless doing a temporary emergency fix.
• Fix the responsible generator and regenerate affected output. scripts/fetch_codex_docs.py coordinates sync; scripts/model_catalog.py, scripts/cli_observations.py, and scripts/semantic_history.py own the pure model, platform, and event transformations. scripts/collect_cli_surface.py collects help observations; scripts/snapshot_feature_flags.py builds feature snapshots.

Local workflow

1. Preferred command runner: use just.
2. Setup environment:
   • just setup
3. Run offline quality checks:
   • just lint
   • just test
4. Run sync:
   • just sync for full source discovery, or just sync-release for strict release-only generation using a verified existing web mirror.
5. Validate local idempotence + scope:
   • just check-strict for two full strict syncs, freshness, idempotence, and changed-file scope. just check is the non-strict local variant.
6. For feature-flag snapshot changes:
   • just feature-flags
   • just check-feature-flags

Validation expectations

• After changing sync logic, run sync twice and confirm second run is idempotent (no new diffs).
• Verify docs/docs_manifest.json and docs/sync_summary.json are updated consistently, including Codex CLI version metadata for CLI-backed changes.
• The manifest fails closed when invalid (or missing while coverage exists) and is the transaction's commit point: write it last and atomically, and advance summary and coverage only after it. A rerun must reconcile every managed file to the plan.
• Verify docs/source_coverage.json updates consistently and includes expected counts, including complete ChatGPT Learn discovery and mirror coverage.
• Preserve existing events in weekly/events/YYYY-MM-DD.json; daily Markdown is their deterministic rollup. Repeated identical syncs must add neither events nor timestamp-only changes. Do not rewrite older daily reports during migration.
• Keep web content provenance independent of CLI releases. Existing web-page CLI-version lists are frozen historical observations; new web pages must not acquire them.
• Model catalogs and feature snapshots must match the CLI release tag and immutable source commit. Model provenance mismatches fail freshness even inside the release-lag grace period.
• CLI removals require a newer descendant release on every previously observed platform. Unknown/divergent ancestry or an unavailable collector must retain last-known-good evidence; semantic history must not report false removals.
• Run CLI introspection in temporary isolated homes with sanitized subprocess environments; never capture real credentials, sessions, history, or inherited GitHub tokens.
• Keep the repository otherwise unchanged while just check-strict runs: its scope check snapshots the whole working tree.
• For feature-flag automation or source-input changes, verify docs/feature-flags/** with just check-feature-flags; snapshots must use the source commit resolved from the CLI release tag.