docs: stop the README promising evidence the default command cannot produce

[jothimani-rajendran]

What this changes

A full audit of README.md and docs/ against the source, rather than against the last release's delta. Six findings, verified by running the code.

The contributing section promised a witness the command does not produce. It told a reader that one command "reports what your version actually does, and the result becomes a verified record". Running it:

$ python3 tools/experiment.py run --agent cursor --report --agent-version 3.21.18 --reporter @test
driver: reference   basis: vendor-docs

Without --driver harness the driver falls back to reference, which answers from the vendor's documented contract and never touches the contributor's installed agent. evidence_report.validate() then refuses to let that claim a live basis, so anyone following the README produced a report this project cannot accept as evidence. The command now carries the flag and the paragraph explains what the fallback is for.

The quick start said install writes into --repo. Two of the twelve adapters write into the invoking user's home directory instead, because that is where the vendor reads them: ~/.junie/config.json and ~/.kimi-code/config.toml. The agent table below was already honest about those paths; the prose above it was not, and a reader trying the quick start in a scratch directory got two files in their home with no warning.

Other corrections, each checked against the data:

Claim	Said	Source
Probe surface	8 × 3 × 16 agents	only 12 agents have an adapter; the rest cannot be probed
Evidence bases	"the other 8 rest on documentation or a third-party install"	seven do; Gemini CLI rests on vendor-source, which the grade ceiling treats as strictly stronger
Permission systems that provably exist	four agents	the data file uses that phrase for five; Junie was missing
Observability	"one JSONL/OTel stream"	the example writes JSONL and suggests feeding it to OTel; nothing exports OTel

One generated page was flatly wrong. examples/generated/README.md said "Junie, Replit and Tabnine have no adapter here yet", eight lines below the table linking junie.md and tabnine.md. Only Replit and Copilot are adapterless. It is CI-locked, so it would never have self-corrected. Fixed in the generator that hardcodes the string and regenerated.

Claim check

• No capability claim is widened without a mechanism behind it — every change here narrows a claim to what the code does
• Any new/changed MATRIX row carries a verified record — no matrix row changed
• Payload shapes come from a primary source — unchanged

Checks

• pytest -q passes (1850 passed, 4 skipped)
• ruff check . and ruff format --check . pass
• Runtime path is still stdlib-only — no runtime file touched
• Commits are signed off
• python examples/generate.py --check clean after regenerating

Notes for the reviewer

The --driver harness fix is the one worth reading closely. CONTRIBUTING.md already warned about the reference driver; the README did not, and the README is where the "no code required" invitation lives.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CzNYfzP8ymU3r4JB9Sz8Ha

---

Generated by Claude Code