Gate every Markdown file: replace the AGENTS.md "Read when relevant" list with an action → file table

🤖 AI: What is the current behaviour and why should it be changed?

AGENTS.md ends with a "Read when relevant" list of five files, each described by its contents ("process, style, licensing"). A reader who is about to do something has to guess which contents they need. The list also covers five of the sixteen other Markdown files outside libs/, so the rest are found by luck or not at all. Two of the listed descriptions are narrower than their file: docs/agents/COMMENTING.md is indexed as "rules when commenting on GitHub" while its own heading is "Posting (comments, issues, discussions)", and CONTRIBUTING.md is indexed as "process, style, licensing" while it also owns testing, ownership, platforms and dependencies.

Every guidance file in this repo is for people and for agents alike. The difference is what a wrong guess costs. A person skims a heading and moves on; an agent loads the whole file into a context it pays for on every turn, or never loads it and works without the rule. Splitting documentation so that a reader loads a file only when needed (#3927) therefore works only if the trigger for loading it is unambiguous. That trigger is the gate.

Describe possible approaches

Replace the list with a gate table. A gate is the action you are about to take; the file answers only that action. Every Markdown file outside libs/ gets one row, so nothing in the tree is ungated. AGENTS.md is the one always-loaded file, so it holds the table and nothing that belongs behind a gate.

Each row is also the file's own opening sentence, so a reader arriving by any route sees the same gate. A rule lives in exactly one file: "Disclose AI-generated text" is currently in both AGENTS.md and COMMENTING.md and would stay in AGENTS.md only.

Three consequences. Trim applies to AGENTS.md alone. A gated file is read only by someone who is about to do that one thing, so it can be as long as the task needs: the length is paid once, by the reader it was written for, and never by a reader whose task lies behind another gate. Every file above is written for people and agents as one audience — docs/agents/ names the on-demand tier, not a separate reader, and nothing in it is off limits to a person. And the rows for src/sound/README.md, docs/agents/README.md and docs/README.md show how little those files hold; whether to merge them is a separate decision that the table makes visible.

Has this feature been discussed and generally agreed?

No. It grew out of #3927, where the on-demand split is being discussed for TESTING.md; this issue is the same idea applied to the whole tree.

🤖 This message was written by AI and reviewed by @mcfnord.

AGENTS.mdから始め、現在の「Read when relevant」リストを、提案されているアクションとファイルの対応表と比較します。libs/外にある、名前が挙げられているMarkdownファイル（CONTRIBUTING.md、TESTING.md、docs/README.md、docs/agents/COMMENTING.mdを含む）を確認します。完了とは、そのような各ファイルに曖昧さのないゲートが1つだけあり、AGENTS.mdには表だけが残り、重複したガイダンスが削除されている状態です。このアプローチについては、まだ広く合意されていないことに注意してください。