docs: rewrite decoder narrative for multi-decoder routing

Author: lesnik512

README.md

@@ -15,12 +15,13 @@
 
 ```bash
 pip install httpware                # core only — no decoder
-pip install httpware[pydantic]      # + PydanticDecoder (the default-decoder path)
-pip install httpware[msgspec]       # + MsgspecDecoder
+pip install httpware[pydantic]      # + PydanticDecoder — handles BaseModel + dataclasses + primitives + generics
+pip install httpware[msgspec]       # + MsgspecDecoder — handles Struct + dataclasses + primitives + generics
+pip install httpware[pydantic,msgspec]   # both extras — both decoders register; BaseModel routes to pydantic, Struct to msgspec
 pip install httpware[all]           # everything declared above (pydantic, msgspec, otel)
 ```
 
-`AsyncClient()` with no `decoder=` argument defaults to constructing a `PydanticDecoder`; that path requires the `pydantic` extra and raises `ImportError` at `AsyncClient.__init__` if it is missing.
+`AsyncClient()` resolves `decoders=None` against installed extras: pydantic if installed (first), msgspec if installed (second), or an empty tuple if neither. `AsyncClient()` never raises on missing extras — failure is deferred to the first `response_model=` call, where `MissingDecoderError` fires *before* the HTTP request if no registered decoder claims the model.
 
 ## Quickstart
 

docs/errors.md

@@ -27,7 +27,8 @@ ClientError                          (catch-all for anything httpware raises)
 │       └── ServiceUnavailableError (503)
 ├── RetryBudgetExhaustedError       (a retry was needed but the budget refused)
 ├── BulkheadFullError                (acquire_timeout elapsed before a slot opened)
-└── DecodeError                      (response_model= decoder failed; HTTP call itself succeeded)
+├── DecodeError                      (response_model= decoder failed; HTTP call itself succeeded)
+└── MissingDecoderError              (no registered decoder claims response_model=; fires before the HTTP call)
 ```
 
 ## Status-to-exception mapping
@@ -155,6 +156,20 @@ except DecodeError as exc:
     raise
 ```
 
+## `MissingDecoderError`
+
+Raised by `send()` / `send_with_response()` / verb methods when `response_model=` is set but no registered decoder claims the model. Carries:
+
+- `model: type` — the `response_model=` value that wasn't claimed.
+- `registered_names: tuple[str, ...]` — class names of the registered decoders that all rejected the model. Empty tuple means no decoders were registered.
+
+Corrective action depends on the message hint:
+
+- `no decoders registered. Install pip install httpware[pydantic] or pip install httpware[msgspec], or pass decoders=[...] explicitly.` — install an extra or pass an explicit decoder list.
+- `registered decoders (PydanticDecoder + MsgspecDecoder) all rejected it.` — your `response_model` type is exotic enough that neither built-in claims it. Pass a custom `ResponseDecoder` via `decoders=[...]`.
+
+Unlike `DecodeError`, this error fires *before* the HTTP request — no traffic is sent.
+
 ## See also
 
 - **[Resilience reference](resilience.md)** — `AsyncRetry`, `RetryBudget`, `AsyncBulkhead` parameter tables.

docs/index.md

@@ -13,8 +13,9 @@ pip install httpware
 Optional extras:
 
 ```bash
-pip install httpware[pydantic]   # PydanticDecoder (the default decoder path)
-pip install httpware[msgspec]    # MsgspecDecoder
+pip install httpware[pydantic]   # PydanticDecoder — handles BaseModel + dataclasses + primitives + generics
+pip install httpware[msgspec]    # MsgspecDecoder — handles Struct + dataclasses + primitives + generics
+pip install httpware[pydantic,msgspec]   # both extras — both decoders register; BaseModel routes to pydantic, Struct to msgspec
 ```
 
 ## First request
@@ -64,6 +65,31 @@ async def main() -> None:
 
 Need the raw response **and** a decoded body from the same call (e.g., for header-based pagination)? See [Link header pagination](recipes/link-header-pagination.md) — it uses `send_with_response`.
 
+### Decoder dispatch
+
+When `response_model=` is set, the client walks `decoders` in order and picks
+the first decoder whose `can_decode(model)` returns `True`. Both built-in
+decoders claim broadly within their library; the ordering encodes your
+preference for shared shapes (`dict`, `list[Foo]`, dataclasses, primitives):
+
+```python
+# pydantic-first (the default when both extras are installed):
+# - BaseModel  -> pydantic
+# - Struct     -> msgspec
+# - dict, list -> pydantic (first in list)
+AsyncClient(decoders=[PydanticDecoder(), MsgspecDecoder()])
+
+# msgspec-first — same native routing, but shared shapes go to msgspec:
+# - BaseModel  -> pydantic
+# - Struct     -> msgspec
+# - dict, list -> msgspec
+AsyncClient(decoders=[MsgspecDecoder(), PydanticDecoder()])
+```
+
+If no registered decoder claims your `response_model`, the call raises
+`MissingDecoderError` *before* the HTTP request — see the
+[Errors reference](errors.md#missingdecodererror).
+
 ### With resilience middleware
 
 Compose resilience middleware at construction; `AsyncBulkhead` goes outside `AsyncRetry` so one slot covers all retry attempts.
@@ -109,7 +135,7 @@ All errors inherit `httpware.ClientError`. The categories:
 - **Status errors** (4xx/5xx responses) — raised automatically, no `raise_for_status()` needed: `NotFoundError`, `RateLimitedError`, `ServiceUnavailableError`, and the rest. All subclass `StatusError`.
 - **Transport errors** — connection / network / protocol failures before a response arrived. `NetworkError` (transient) subclasses `TransportError`.
 - **Resilience refusals** — `RetryBudgetExhaustedError` and `BulkheadFullError`, raised by the resilience middleware.
-- **Decode errors** — `DecodeError`, raised when `response_model=` decoding fails (HTTP call itself succeeded).
+- **Decode errors** — `DecodeError`, raised when `response_model=` decoding fails (HTTP call itself succeeded). `MissingDecoderError`, raised when no registered decoder claims the `response_model=` type — fires *before* the HTTP call.
 
 See the [Errors reference](errors.md) for the full tree and catching strategies.