sylius-auth-md — one source for auth.md and agent_auth.

Two versions of the same information drift apart as soon as one of them changes.

An agent that wants to find out how to authenticate with your shop reads two things: the prose document at /auth.md and the machine-readable agent_auth block of the OAuth metadata. If both are maintained separately, they drift apart — it is enough for one of the two sides to change. The agent then believes the wrong one and fails without anyone finding out: there is no error that surfaces anywhere, only a login that never happens.

That is why /auth.md is not stored but generated. Both outputs come from the same descriptors of the installed authentication methods. A method you add or remove therefore changes both versions at once — drift is no longer a matter of discipline but structurally impossible.

If no method is registered, the route deliberately returns 404 rather than an empty document. An auth.md that names no way in is not neutral information — to an agent it reads as “this shop rejects agents”. The absence of the file is the more honest answer: nothing has been configured here yet.