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](https://github.com/jamulussoftware/jamulus/blob/508f1f3d3ea41b0da76da128ee5d3f3f1b2fafc7/AGENTS.md#L68-L73) 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](https://github.com/jamulussoftware/jamulus/blob/508f1f3d3ea41b0da76da128ee5d3f3f1b2fafc7/docs/agents/COMMENTING.md#L1) is "Posting (comments, issues, discussions)", and `CONTRIBUTING.md` is indexed as "process, style, licensing" while it also owns [testing](https://github.com/jamulussoftware/jamulus/blob/508f1f3d3ea41b0da76da128ee5d3f3f1b2fafc7/CONTRIBUTING.md#L101), [ownership](https://github.com/jamulussoftware/jamulus/blob/508f1f3d3ea41b0da76da128ee5d3f3f1b2fafc7/CONTRIBUTING.md#L105), [platforms](https://github.com/jamulussoftware/jamulus/blob/508f1f3d3ea41b0da76da128ee5d3f3f1b2fafc7/CONTRIBUTING.md#L70) and [dependencies](https://github.com/jamulussoftware/jamulus/blob/508f1f3d3ea41b0da76da128ee5d3f3f1b2fafc7/CONTRIBUTING.md#L84).

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`](https://github.com/jamulussoftware/jamulus/blob/508f1f3d3ea41b0da76da128ee5d3f3f1b2fafc7/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`](https://github.com/jamulussoftware/jamulus/blob/508f1f3d3ea41b0da76da128ee5d3f3f1b2fafc7/CONTRIBUTING.md) |
| write a PR body — structure and the `CHANGELOG:` line | [`.github/pull_request_template.md`](https://github.com/jamulussoftware/jamulus/blob/508f1f3d3ea41b0da76da128ee5d3f3f1b2fafc7/.github/pull_request_template.md) |
| write a bug report or a feature specification | [`.github/ISSUE_TEMPLATE/bug_report.md`](https://github.com/jamulussoftware/jamulus/blob/508f1f3d3ea41b0da76da128ee5d3f3f1b2fafc7/.github/ISSUE_TEMPLATE/bug_report.md), [`feature_request.md`](https://github.com/jamulussoftware/jamulus/blob/508f1f3d3ea41b0da76da128ee5d3f3f1b2fafc7/.github/ISSUE_TEMPLATE/feature_request.md) |
| post any other text on GitHub — a comment, review, issue, or discussion | [`docs/agents/COMMENTING.md`](https://github.com/jamulussoftware/jamulus/blob/508f1f3d3ea41b0da76da128ee5d3f3f1b2fafc7/docs/agents/COMMENTING.md) |
| change how clients, servers and directories talk to each other | [`docs/JAMULUS_PROTOCOL.md`](https://github.com/jamulussoftware/jamulus/blob/508f1f3d3ea41b0da76da128ee5d3f3f1b2fafc7/docs/JAMULUS_PROTOCOL.md) |
| call or change the JSON-RPC API — generated, never edited by hand | [`docs/JSON-RPC.md`](https://github.com/jamulussoftware/jamulus/blob/508f1f3d3ea41b0da76da128ee5d3f3f1b2fafc7/docs/JSON-RPC.md) |
| touch `src/sound/` — the sound design is [not yet documented](https://github.com/jamulussoftware/jamulus/blob/508f1f3d3ea41b0da76da128ee5d3f3f1b2fafc7/src/sound/README.md#L51), so this file tells you that | [`src/sound/README.md`](https://github.com/jamulussoftware/jamulus/blob/508f1f3d3ea41b0da76da128ee5d3f3f1b2fafc7/src/sound/README.md) |
| translate the user interface | [`docs/TRANSLATING.md`](https://github.com/jamulussoftware/jamulus/blob/508f1f3d3ea41b0da76da128ee5d3f3f1b2fafc7/docs/TRANSLATING.md) |
| change the Debian packaging or the headless service unit | [`linux/debian/README.md`](https://github.com/jamulussoftware/jamulus/blob/508f1f3d3ea41b0da76da128ee5d3f3f1b2fafc7/linux/debian/README.md) |
| change the CI build scripts | [`.github/autobuild/README.md`](https://github.com/jamulussoftware/jamulus/blob/508f1f3d3ea41b0da76da128ee5d3f3f1b2fafc7/.github/autobuild/README.md) |
| report a vulnerability — never as an issue | [`SECURITY.md`](https://github.com/jamulussoftware/jamulus/blob/508f1f3d3ea41b0da76da128ee5d3f3f1b2fafc7/SECURITY.md) |
| describe the project to someone who has not used it | [`README.md`](https://github.com/jamulussoftware/jamulus/blob/508f1f3d3ea41b0da76da128ee5d3f3f1b2fafc7/README.md) |
| find documentation that is not in this repo — [release process, style and tone, administration](https://github.com/jamulussoftware/jamulus/blob/508f1f3d3ea41b0da76da128ee5d3f3f1b2fafc7/docs/README.md#L55) | [`docs/README.md`](https://github.com/jamulussoftware/jamulus/blob/508f1f3d3ea41b0da76da128ee5d3f3f1b2fafc7/docs/README.md) |
| know what `docs/agents/` is for | [`docs/agents/README.md`](https://github.com/jamulussoftware/jamulus/blob/508f1f3d3ea41b0da76da128ee5d3f3f1b2fafc7/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](https://github.com/jamulussoftware/jamulus/blob/508f1f3d3ea41b0da76da128ee5d3f3f1b2fafc7/AGENTS.md#L66) and [COMMENTING.md](https://github.com/jamulussoftware/jamulus/blob/508f1f3d3ea41b0da76da128ee5d3f3f1b2fafc7/docs/agents/COMMENTING.md#L7) 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.*

Inizia da AGENTS.md e confronta l’attuale elenco “Read when relevant” con la tabella proposta azione-file. Esamina i file Markdown indicati al di fuori di libs/, inclusi CONTRIBUTING.md, TESTING.md, docs/README.md e docs/agents/COMMENTING.md. Il lavoro è terminato quando ogni file di questo tipo ha un’unica condizione di accesso non ambigua, AGENTS.md conserva solo la tabella e le indicazioni duplicate sono state rimosse; nota che l’approccio non è ancora generalmente condiviso.

Scritto dal modello di indicizzazione a partire dal testo della issue.