Docs: `project_doc_max_bytes` documented as per-file on one page, cumulative on another (code is cumulative)

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?

• Per-file wording: https://learn.chatgpt.com/docs/config-file/config-advanced ("Project Instructions Discovery" section)
• Cumulative wording: https://learn.chatgpt.com/codex/agent-configuration/agents-md

Both verified as currently live at the time of filing.