Two files, on a host you already control. A forge, a bare nginx and a static host all serve them identically, because they are fetched as plain HTTPS and no forge API is involved.
your-project/
.podshl/
agent.yaml
solutions/
wheel-missing-for-python.mdRather not write YAML? The builder writes both files from a form, and checks them with the same code that ingests them before you publish anything.
| A server | No — we mirror your files and serve from our copy |
| A model, or an inference bill | No — your file is matched, never generated |
| A signing key | No — control of the URL is the proof |
| A domain | No — whatever already serves your repository is enough |
| Answering support at 2am | No — the user's client does the reading and the acting |
agent.yamlThis is the worked example the specification ships, served here as the same bytes rather than retyped — so this page cannot drift from the format it describes. Download it.
loading…Most projects that would use this are in that position. A desktop environment gets the bug report when NVIDIA's driver and Wayland disagree and every window goes black — not because it is at fault, but because it is the thing the user can see. The question that stops people is not how do I write the file, it is am I allowed to name them.
Yes, and the format is built so that you cannot do anything else.
problem_classes names other people's software on purpose.
A project that repairs nvidia.driver behaviour has to be
able to write nvidia.driver, or it cannot say what it
fixes.The second worked example, served as its own bytes like the first. A desktop project answering for a driver and a display protocol, owning neither. Download it.
loading…Note the shape as well as the licence question: the decisive fact is a single environment variable — whether this is a Wayland session at all — and everything else refines it. Under X11 the same driver and the same application are fine, so a solution that matched without reading it would be advice given to the wrong half of the users. Cross-vendor problems usually turn on one reading nobody thinks to ask for.
A probe may carry both a read and a question. The reading is
tried first; the question is asked only if it comes back empty. One fact,
written once, able to arrive either way — and the report tells you which
happened, so an outcome that turned on an answer is not counted against a rule
it never tested.
Attach choices whenever you attach a question.
A bounded answer may travel to you; free text never does. Without them that
fact simply never reaches you.
Only what the read vocabulary already contains. An op or a tool outside it is refused when your file is fetched, not when a user is waiting — and the refusal names what would have been permitted.
The read vocabulary · The action vocabulary — both the same bytes the specification publishes.
Extending them is a client release, not a field you can set. That is the whole safety property: a publisher chooses an operation, it cannot ship one.
You are losing bug reports you never knew you had. Someone who got stuck used to file an issue. Now they ask an assistant, get unstuck in ninety seconds and close the tab. The problem was real and it happened to hundreds of people, and you hear about none of them — so the bug stays, and the next person hits it too.
This keeps the ninety seconds and gives you the signal back. Nothing reaches you below five distinct reporters, so what arrives is a pattern rather than an anecdote, and nobody had to write a paragraph or wait for triage.
It is a sharper signal than an issue ever was. Every report says which size of model was involved. A small one running on somebody's own laptop, solving your problem out of public knowledge, means the answer was already out there and your documentation or your interface failed to convey it — a defect you can locate, rather than a knowledge gap.
| observed | Read from the machine. A solution that matched on one of these and failed is a defect in your rule, and worth your time |
| stated | The person told us. A failure here may be nothing of the sort — they may simply have answered wrong |
| decided_on | The facts the answer actually turned on. Read this against stated first: that intersection is the whole question |
| dropped | Withheld. Anything identifying never travels, whoever supplied it |
| description | Free text the user read and agreed to send — usually the error message, which is the one thing no policy can generalise for you |
You cannot break a user's machine from here. The client owns both
vocabularies, every action is dry-run and reversible, and the user consents per
item with the refusing button holding focus. The worst outcome of a bad
agent.yaml is that it is refused when fetched and you are told why.