Docs: project_doc_max_bytes semantics are undocumented — the 22.5KB root AGENTS.md leaves ~9.7KB before nested files are truncated

What is the type of issue? Documentation is missing

What is the issue?

The AGENTS.md loading budget has three behaviors that are implemented but documented nowhere in this repo (verified at 41ece455b7fa, 2026-08-11):

1. The cap: DEFAULT_PROJECT_DOC_MAX_BYTES = 32 * 1024 (codex-rs/config/src/config_toml.rs:70) limits the combined project-directory AGENTS.md chain.
2. Truncation order: files load root-first (agents_md.rs builds search dirs cwd→root then reverses), so when the budget runs out, data.truncate(remaining) (agents_md.rs:130) hits the deepest, most-specific file first — with only a tracing::warn! to show for it.
3. The global file is exempt: ~/.codex/AGENTS.md loads in full via codex-home/src/instructions/mod.rs:24-67 with no length check — outside the budget entirely.

Why it matters here concretely: this repo's own root AGENTS.md is 22,519 bytes — ~70% of the default budget. A contributor working under codex-rs/tui/src/bottom_pane/ gets root + the 564-byte nested file = 23,083 bytes, leaving 9,685 bytes of headroom for any future nested files before silent leaf-first truncation. Nothing warns an AGENTS.md author that growing the root file shrinks the budget for every nested file in the tree.

grep -rn project_doc_max_bytes docs/ codex-rs --include='*.md' returns zero results; docs/agents_md.md is a 3-line pointer to the external guide. A short paragraph — in docs/config.md or the external agents-md guide — covering the cap, the leaf-first truncation order, and the global-file exemption would make this legible to both contributors and users tuning project_doc_max_bytes.

Where did you find it? codex-rs/config/src/config_toml.rs, codex-rs/core/src/config/mod.rs, the AGENTS.md loader (agents_md.rs), codex-home/src/instructions/mod.rs, and docs/. Found during an automated AGENTS.md audit (rent-check); all line references re-verified against source before filing.

Start by reading docs/config.md and docs/agents_md.md, then verify the behavior in codex-rs/config/src/config_toml.rs, agents_md.rs, and codex-home/src/instructions/mod.rs. Document the 32 KiB project-directory cap, deepest-file-first truncation, and exemption for ~/.codex/AGENTS.md, either in the local configuration docs or the linked external guide.