The AI Catalog specification does not treat /.well-known/ai-catalog.json as the only way to locate a catalog. Per Location Independence, "An AI Catalog document MAY be served from any URL" — it is identified by its media type, not its path — and "Use of the well-known URI is OPTIONAL. Hosts that publish catalogs at other locations are fully conformant."

The spec's discovery procedure defines two additional pointers, both checked ahead of the well-known path:

1. An HTTP Link header with rel="ai-catalog"
2. An HTML <link rel="ai-catalog"> in the document head
3. Optionally fall back to /.well-known/ai-catalog.json
4. Validate the retrieved document has a valid specVersion

Both link-relation forms are registered with IANA in the spec's registration sections.

We currently document and implement only the well-known path. That is a reasonable starting point — it is the only location reachable against a bare domain, with nothing fetched first — but stopping there means a client will miss any host that publishes a catalog somewhere other than the domain root. ADR-0011 notes this is specifically the enterprise-registry case, which cannot always use .well-known at all.

Scope

• SDK reference implementations — resolve a catalog by following the full precedence order rather than constructing the well-known URL directly. Worth deciding whether this ships alongside the existing reference implementations tracked in Reference implementations in Python and Go #16 or as a follow-up.
• docs/discovery.md — document the precedence order and the specVersion validation step.
• docs/best-practices.md — currently recommends .well-known as the single explained option and points here for the rest. Update once the above lands: servers should advertise via the link relations as well, and clients should honor them.

Not urgent

The well-known path is the common case and the one in-session discovery depends on, so nothing is blocked on this. Filing so the gap is tracked rather than rediscovered.