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

[mcfnord]

🤖 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.

You are about to…	Read
build the software on any platform	COMPILING.md
verify that a change behaves, in a fork or here — rig, JSON-RPC, tcpdump, evidence to keep, hints from past missteps	TESTING.md (proposed in #3927)
submit a change to this repo: the diff, and your obligations for it afterwards — agree first, principles, style, licensing, ownership	CONTRIBUTING.md
write a PR body — structure and the CHANGELOG: line	.github/pull_request_template.md
write a bug report or a feature specification	.github/ISSUE_TEMPLATE/bug_report.md, feature_request.md
post any other text on GitHub — a comment, review, issue, or discussion	docs/agents/COMMENTING.md
change how clients, servers and directories talk to each other	docs/JAMULUS_PROTOCOL.md
call or change the JSON-RPC API — generated, never edited by hand	docs/JSON-RPC.md
touch src/sound/ — the sound design is not yet documented, so this file tells you that	src/sound/README.md
translate the user interface	docs/TRANSLATING.md
change the Debian packaging or the headless service unit	linux/debian/README.md
change the CI build scripts	.github/autobuild/README.md
report a vulnerability — never as an issue	SECURITY.md
describe the project to someone who has not used it	README.md
find documentation that is not in this repo — release process, style and tone, administration	docs/README.md
know what docs/agents/ is for	docs/agents/README.md

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.

[pljones]

I like this approach.

I like the point that finding the documentation you need applies whether you're a new contributor to the project looking for information either as a human or an AI Agent (one assumes learning is slowly retained - with AI agents starting to do this over time as well).

I like that it's a manageable format that could be used to drive specific improvement tasks where we're lacking or confusing currently.

I almost feel like I'd want to have CONTRIBUTING.md be the top level "read this first as a new contributor" (human or AI agent), splitting out the current complexity therein into more digestible components based on this gating format.

[ann0see]

AGENTS.md is a standard. Any harness should instruction the model to read it. Anything else might not be read.

[pljones]

Yes, that's right.