discovery

Discoverability

An endpoint that no agent ever finds is dead code. The build advertises each endpoint in the places agents actually look: the ## Optional section of llms.txt, a comment block in robots.txt, and Link headers on every page.

/.well-known/api-catalog

The Worker serves two more well-known URIs, both defined relative to the origin: /.well-known/mcp.json (with the server-card spelling beside it) and /.well-known/api-catalog.

The catalog follows RFC 9727, a specification that answers a question the documentation itself cannot: which API. A site that documents a product actually has two APIs: the product's own API, and this documentation's own read-only API under /api/docs. Until an agent reads the docs, it has no way to tell the two apart. The catalog states the difference in one fetch:

{
  "linkset": [
    { "anchor": "https://api.example.com/v1",
      "service-desc": [{ "href": "https://docs.example.com/openapi.json", "type": "application/openapi+json" }],
      "service-doc":  [{ "href": "https://docs.example.com/", "type": "text/html" }] },
    { "anchor": "https://docs.example.com/api/docs",
      "service-desc": [{ "href": "https://docs.example.com/api/docs/openapi.json", "type": "application/openapi+json" }],
      "service-doc":  [{ "href": "https://docs.example.com/", "type": "text/html" }],
      "status":       [{ "href": "https://docs.example.com/api/docs", "type": "application/json" }] }
  ]
}

Three details matter, and test/agents.test.mjs asserts each one rather than leaving it to review:

• The media type is application/linkset+json (RFC 9264), not application/json. A client negotiating for a linkset will not accept the generic type.
• Every relation's value is an array of link target objects, even when there is only one link. A bare object is well-formed JSON, but no generic client reads it correctly.
• The first entry is anchored on the API's own base URL, taken from the specification's servers[0].url, not on the page that describes it. This lets an agent holding a request URL match it against the catalog.