Document httpx2 exception migration and the TLS change in whats-new

Old except httpx.X handlers fail silently after the swap because httpx
usually stays co-installed transitively, so the migration guide now
calls out exception handlers, isinstance checks, and that httpx client
objects are not interchangeable at runtime. The whats-new silent-changes
list gains the certifi to system-trust-store entry.

No-Verification-Needed: documentation-only change

Author: maxisbey

docs/client/transports.md

@@ -56,7 +56,7 @@ Two things to notice:
 
 One TLS note: `httpx2` verifies certificates against the operating system trust store (via
 [`truststore`](https://pypi.org/project/truststore/)), not a bundled CA list. In an environment with
-no usable system CA store — some minimal containers — set the standard `SSL_CERT_FILE`/`SSL_CERT_DIR`
+no usable system CA store (some minimal containers), set the standard `SSL_CERT_FILE`/`SSL_CERT_DIR`
 environment variables or pass an explicit `verify=ssl_context` to your `httpx2.AsyncClient`
 (background in
 [`httpx` and `httpx-sse` replaced by `httpx2`](../migration.md#httpx-and-httpx-sse-replaced-by-httpx2)).

docs/migration.md

@@ -99,8 +99,8 @@ The SDK now depends on [`httpx2`](https://pypi.org/project/httpx2/) instead of
 `httpx`) with server-sent events support built in, so the separate `httpx-sse`
 dependency is gone.
 
-The swap itself does not change any SDK signatures — `streamable_http_client`
-and `sse_client` accept the same arguments as elsewhere in v2 — but the client
+The swap itself does not change any SDK signatures - `streamable_http_client`
+and `sse_client` accept the same arguments as elsewhere in v2 - but the client
 type they expect is now `httpx2.AsyncClient`. If you construct your own client to pass as
 `http_client` (or build an `httpx2.Auth` subclass for `auth`), import from
 `httpx2`:
@@ -125,13 +125,24 @@ http_client = httpx2.AsyncClient(follow_redirects=True)
 changes. To consume SSE directly, use `httpx2.EventSource` (or
 `AsyncClient.sse()`) instead of the `httpx-sse` helpers.
 
+Exception handlers need the same rename: the SDK now raises `httpx2`
+exceptions (`httpx2.ConnectError`, `httpx2.HTTPStatusError`, and so on), and
+this failure mode is silent. `httpx` usually stays installed as a transitive
+dependency of other packages, so an old `except httpx.ConnectError:` block
+keeps importing fine and simply never matches again. Audit `except httpx.`
+clauses and `isinstance` checks along with the imports. The same identity
+split applies to objects: `httpx` and `httpx2` types are not interchangeable
+at runtime, so an `httpx.AsyncClient` passed as `http_client` degrades in
+subtle ways (server-initiated messages stop arriving) instead of raising
+immediately.
+
 TLS verification also changes: `httpx` validated certificates against the
 bundled `certifi` CA list, while `httpx2` validates against the operating
 system trust store via [`truststore`](https://pypi.org/project/truststore/).
 If your environment has no usable system CA store (some minimal containers),
 or you relied on certifi's bundle specifically, point the standard
-`SSL_CERT_FILE` or `SSL_CERT_DIR` environment variable at a CA bundle —
-`httpx2` honors these before falling back to the system store — or pass an
+`SSL_CERT_FILE` or `SSL_CERT_DIR` environment variable at a CA bundle
+(`httpx2` honors these before falling back to the system store), or pass an
 explicit `verify=ssl_context` to your `httpx2.AsyncClient`. Passing a CA
 bundle path as `verify="ca.pem"` or using the `cert=` parameter is deprecated
 in `httpx2`; build an `ssl.SSLContext` and configure it instead.

docs/whats-new.md

@@ -138,6 +138,7 @@ The renames announce themselves. These do not:
 * **URI templates are real RFC 6570 now.** `{+path}`, `{?query}` and friends work, matching is exact instead of regex-loose, and path traversal in extracted values is rejected by default. Stricter templates fail at decoration time, not on the first request. **[URI templates](servers/uri-templates.md)**.
 * **The streamable HTTP lifespan runs once**, at startup, and its state is shared by every session and request. In v1 it ran once per session, and once per request under `stateless_http=True`. Pools and caches built in a lifespan get dramatically cheaper; anything that acquired a per-connection resource there belongs in the handler body now. **[Lifespan](handlers/lifespan.md)**.
 * **`mcp dev` and `mcp install` pin the environment they spawn** to your installed SDK version. Both commands run your server in a fresh `uv run --with ...` environment, which used to resolve `mcp` to the newest stable release rather than the version you are developing against. **[Migration Guide](migration.md#mcp-dev-and-mcp-install-pin-the-spawned-environment-to-your-sdk-version)**.
+* **TLS certificates verify against the operating system trust store, not certifi.** The SDK's HTTP client is now `httpx2`, which validates through `truststore` instead of certifi's bundled CA list. Most environments never notice; a minimal container with no system CA store, or a private CA that only certifi's bundle knew about, starts failing the TLS handshake. Set `SSL_CERT_FILE`/`SSL_CERT_DIR` or pass `verify=ssl_context` to your client. **[Migration Guide](migration.md#httpx-and-httpx-sse-replaced-by-httpx2)**.
 
 ### Removed outright