Documentation
Everything written down, and where it lives.
All of it is in the repository, so it is versioned with the code that it describes and it is readable without running anything. These cards are generated from what is actually on disk — a link here cannot outlive its file.
docs/agent-builders.md
The shortest path if you have an agent: point Beacon at it, measure how often it fails rather than whether it failed once, and fail CI when it regresses.
docs/architecture.md
The run lifecycle, and the boundary that keeps the core ignorant of any particular model provider or agent runtime.
docs/beacon-test-run.md
The manual test plan for this site, walked end to end against a dev server. Three defects and seven notes, written down whether or not they were flattering.
docs/failure-taxonomy.md
The 131 failure modes Beacon means to measure in taxonomy 1.2.0, the four tests a candidate has to pass to be one of them, and the 24 candidates that were rejected with the reason each was turned down.
docs/production-readiness.md
What Beacon is ready to be trusted with and what it is not, one limitation at a time, each with the file or command behind it and what would change the answer.
docs/protocol-contracts.md
What Beacon sends and expects over MCP, A2A and the JSONL bridge, message by message.
docs/releasing.md
How a version reaches PyPI, and the three pieces of state that live outside the repository: the trusted publisher, the environment, and the workflow switch a clone cannot see.
docs/running-it-yourself.md
Running against a real model or a GUI host. Where the API key goes — your environment, never the command line — and how to wire the MCP façade into a desktop client.
docs/verifying-a-checkout.md
Checking this repository yourself, from a clone: the two commands that gate a change, everything CI would have caught, and four exercises that try to falsify what the project claims about itself.
docs/windows.md
Why a literal python3 is a Store alias stub on Windows, and the two tests that spawned one and passed for weeks without running anything.
conformance/a2a-survey.md
Beacon's own A2A client, run against all five official SDKs as local servers. It found seven defects in the client — five of which would have reported a working agent as broken.
conformance/hosted-agent-probe.md
Twenty-nine hosted agents, graded offline from stored evidence bundles. Includes what the first pass got wrong and why re-grading was free.
conformance/hosted-mcp-survey.md
Beacon's MCP client against 200 hosted servers from the official registry. One initialize and one tools/list each; no tool calls were made.
Not documentation
The four places a reader actually goes next.
README.md
What works, what does not, and the sixty-second path from clone to an evidence bundle.
ROADMAP.md
What is committed next, what is still an open question, and what was considered and rejected. No dates on it, and a paragraph explaining why there are none.
schemas/
The published scenario and evidence JSON Schema, kept in step with the code by test.
examples/scenario-pack/
A worked pack that brings its own synthetic service, with a test that runs it from outside the repository.
examples/subjects/
The adversarial suite: subjects that behave the way a real agent plausibly does. Writing it caught Beacon returning the wrong verdict on six of the first thirteen.