Server-tier helpers: build_server_card derives the card from a server's
identity fields, route builders and mount helpers serve the card at the
spec-reserved <streamable-http-path>/server-card and the catalog at
/.well-known/ai-catalog.json, and discovery_response is the single
compliance chokepoint (media type, CORS MUSTs, Cache-Control, strong
ETag with If-None-Match 304s, OPTIONS preflight). catalog_identifier
and server_card_entry build urn:air catalog entries, by URL or inline.

Client-tier helpers: fetch_server_card / fetch_ai_catalog /
discover_server_cards run every fetch through a hardened core
(https-only with loopback-http exception, SSRF address guard with
post-DNS re-check, manual redirect walking with per-hop re-admission,
response size and catalog entry/depth caps, Accept and media type
discipline) governed by DiscoveryPolicy. Probes collect per-entry
failures instead of raising, and CardListing exposes the listing chain
for consent UI. Stateless request/parse pairs support host-owned ETag
revalidation, and reconcile_server_card compares card claims to runtime
values without ever enforcing them.

New Advanced page covering serving a card, publishing on a brand
domain, static publishing, discovery and connect, ETag revalidation,
and the security model (advisory cards, endpoint-keyed dedup, host
scoped consent, SSRF policy defaults). Tutorials are pyright-checked
docs_src modules proved against the real SDK by
tests/docs_src/test_server_cards.py.

Discovery client:

- Bound each probe with DiscoveryPolicy.max_probe_entries (default 500),
  an aggregate budget over every card and nested-catalog entry one walk
  processes; exhaustion records a single "probe_budget" failure and drops
  the rest. Already-visited nested catalog URLs are never refetched, so
  cyclic or duplicated catalogs terminate. Without this the per-catalog
  entry cap and the depth cap compose multiplicatively (~entries**depth
  fetches from one hostile catalog).
- Catch OSError per entry too: an unresolvable host (socket.gaierror from
  the guard's own DNS resolution) or a tar-pit entry (TimeoutError from
  the per-fetch deadline) becomes a failure instead of killing the whole
  probe, as the DiscoveryResult contract promises. Both exceptions are
  now documented on the public fetchers.
- CardListing.listing_domain/hosting_domain return host[:port] built from
  the parsed hostname, never the raw netloc, and _admit_url rejects
  userinfo-carrying URLs outright, so https://github.com@evil.example/
  can neither be fetched nor rendered as a trusted brand in consent UI.
- _is_blocked_address unwraps IPv4-mapped IPv6 literals and applies the
  IPv4 rules, closing the ::ffff:100.64.0.1 CGNAT bypass (and the
  private-range leak on interpreters without the gh-113171 fix).
- discover_server_cards with http_client=None opens one credential-free
  client for the whole walk instead of one per fetched entry.
- Plain http is refused up front under the hardened policy (the loopback
  carve-out was unreachable: loopback fails the address guard anyway).
- DiscoveryErrorReason is re-exported from the public module, and one
  accept_header() helper replaces the duplicated Accept literals.

Models and server:

- Remote.required_variables now includes required headers that carry no
  value and no default, keyed by header name exactly as resolve_remote
  accepts them, so prompting from the property and then resolving works.
- mount_discovery documents that public_url is the app's public base URL.
- The discovery routes' CORSMiddleware allows only GET, so real browser
  preflights advertise the spec's method list.

Tests cover the budget walk (exact fetch sequence), visited-set dedup,
per-entry DNS-failure and timeout resilience, userinfo rejection and
display, mapped-IPv6 blocking, required-header prompting, Repository and
icons round-trips, and the preflight headers.

The extension spec's CORS section requires
'Access-Control-Allow-Headers: Content-Type, If-None-Match' and
'Access-Control-Expose-Headers: ETag' on hosted card and catalog
endpoints; the served responses allowed only Content-Type and exposed
nothing, which would stop a browser-based client from reading the ETag
or sending If-None-Match for a cross-origin 304 revalidation. Both the
explicit discovery_response headers and the CORSMiddleware preflight
config now emit the full set, with tests asserting the headers on the
card response and on a browser preflight requesting If-None-Match.

…ver-card

main now types Client.server_info as Implementation | None (serverInfo is
optional at 2026-07-28) and defaults server version to "" instead of None.

- ServerCard.from_server treats a derived empty version as unset, so a
  server without a version still fails card validation
- reconcile_server_card accepts server_info=None: an anonymous server makes
  no identity claim, so only the protocol version check applies