Documentation you can test: checking the docs against production

What the live check asserts

The live pass asserts the error code wherever the documentation names one, not just the HTTP status. A bare status code cannot distinguish documented behavior from a route that does not exist: both might be a 404. It also checks the OpenAPI version and path coverage against production.

Where two different rules could produce the same code for the same request, it asserts the reason as well. The multiply-encoded key targets that once resolved in production are checked this way, so the protection is tested and not only the status.

What verifying against production found

The previous API reference had six claims that were not true of the deployed system:

• The registration response shape was wrong: the level is nested under verification, and status, manifest_digest and links were missing.
• A 422 status was documented that the API never returns.
• POST /api/v1/verify was described as ManifestProof verification when it is a raw Ed25519 signature check.
• The error-code table conflated three separate namespaces, and the 503 registry-unavailable path was undocumented.
• The resolver's deliberate split, a 200 HTML card and a 404 JSON response for an unknown identifier, was documented as a flat 404.

Findings beyond the API reference

/api/retell/bind answered CORS preflight but sent no CORS header on its responses, so a cross-origin browser request cleared preflight and was then rejected. A test now requires preflight and response to agree.

SECURITY.md named a private vulnerability reporting channel that the host only offers on public repositories. Reporting is now enabled on the public spec and conformance repositories instead. The same review recorded that agenid.com publishes no MX records, so no security mailbox on that domain can receive mail; a reporting address that does not receive is worse than none.

Why this is a standard and not a cleanup

For a verification protocol, documentation is part of the trust surface. A reader who is told an endpoint exists, or that a level can be issued, will act on it. The same rule that forbids a badge from showing more than the evidence supports applies to prose. The check keeps the ceiling statement honest as well: The reference deployment at agenid.com issues nothing above L1_REGISTERED today: L2 and higher require a VerificationAssertion signed by a root authority key, and that key has not been created yet. L5 is reserved and is not issuable at all.

Which agent is acting is not the same question as what it is allowed to do. AgenID answers the first. Protocol v1.1.1 defines no signed authorization object, so permission stays with the operator and with the party on the other side.

How to try it

Inside the repository the static check runs as pnpm run check:docs and the production check as pnpm run check:docs:live. The implementation repository is public, and you can also run the same kind of check against production yourself: fetch https://www.agenid.com/api/v1/openapi.json, call a documented route with a bad input, and compare the error code with what the document describes. The onboarding guide lists the public routes. The public conformance suite tests the protocol side independently.