What is the type of issue?
Documentation is incorrect
What is the issue?
Two documentation pages describe project_doc_max_bytes in mutually exclusive ways, and the implementation only matches one of them.
Page A — per file:
project_doc_max_bytes: how much to read from each AGENTS.md file
Page B — cumulative across the chain:
Codex skips empty files and stops adding files once the combined size reaches the limit defined by project_doc_max_bytes (32 KiB by default).
These cannot both be true. "How much to read from each file" implies a per-file allowance where every file in the chain gets its own 32 KiB; "stops adding files once the combined size reaches the limit" implies one shared budget consumed in walk order.
The implementation matches Page B. In codex-rs/core/src/agents_md.rs, discovery seeds a single remaining counter from project_doc_max_bytes and decrements it across the whole root→cwd chain. When a file would overshoot, its content is truncated to whatever is left; once remaining hits zero the loop breaks and no further file is read at all. The default is DEFAULT_PROJECT_DOC_MAX_BYTES: usize = 32 * 1024 in codex-rs/config/src/config_toml.rs.
So the budget is cumulative and order-dependent, not per file.
Why this is worth fixing rather than just imprecise wording. The per-file reading predicts the opposite of the actual failure mode. Under Page A, a large root AGENTS.md costs nothing to a nested one — each is independently capped. Under the real behavior, a large root file can consume the entire budget and cause a nested AGENTS.md to be dropped in its entirety, silently. Anyone who splits instructions across nested directories to stay under a per-file cap — which is exactly what Page B recommends as the remedy — will not get the outcome the docs imply unless they also understand the total is shared.
This confusion appears to be live in the wild: #13386 describes the limit as "Codex silently truncates AGENTS.md at 32 KB" and reasons about a single file, which is the Page A model. That issue is about the absence of a warning and I'm not duplicating it here; I'm reporting only that the two pages disagree and one of them contradicts the code.
Suggested fix. Align Page A with Page B, e.g.:
project_doc_max_bytes: total bytes of project instructions to load, shared across every AGENTS.md in the chain from the repository root down to the working directory. Files are read in that order; once the budget is exhausted, remaining files are skipped.
Adding the words "shared" and "in order" is what makes the failure mode predictable.
Where did you find it?
Both verified as currently live at the time of filing.
What is the type of issue?
Documentation is incorrect
What is the issue?
Two documentation pages describe
project_doc_max_bytesin mutually exclusive ways, and the implementation only matches one of them.Page A — per file:
Page B — cumulative across the chain:
These cannot both be true. "How much to read from each file" implies a per-file allowance where every file in the chain gets its own 32 KiB; "stops adding files once the combined size reaches the limit" implies one shared budget consumed in walk order.
The implementation matches Page B. In
codex-rs/core/src/agents_md.rs, discovery seeds a singleremainingcounter fromproject_doc_max_bytesand decrements it across the whole root→cwd chain. When a file would overshoot, its content is truncated to whatever is left; onceremaininghits zero the loop breaks and no further file is read at all. The default isDEFAULT_PROJECT_DOC_MAX_BYTES: usize = 32 * 1024incodex-rs/config/src/config_toml.rs.So the budget is cumulative and order-dependent, not per file.
Why this is worth fixing rather than just imprecise wording. The per-file reading predicts the opposite of the actual failure mode. Under Page A, a large root
AGENTS.mdcosts nothing to a nested one — each is independently capped. Under the real behavior, a large root file can consume the entire budget and cause a nestedAGENTS.mdto be dropped in its entirety, silently. Anyone who splits instructions across nested directories to stay under a per-file cap — which is exactly what Page B recommends as the remedy — will not get the outcome the docs imply unless they also understand the total is shared.This confusion appears to be live in the wild: #13386 describes the limit as "Codex silently truncates
AGENTS.mdat 32 KB" and reasons about a single file, which is the Page A model. That issue is about the absence of a warning and I'm not duplicating it here; I'm reporting only that the two pages disagree and one of them contradicts the code.Suggested fix. Align Page A with Page B, e.g.:
Adding the words "shared" and "in order" is what makes the failure mode predictable.
Where did you find it?
Both verified as currently live at the time of filing.