docs: document send_with_response in index + Seam B contract

docs/index.md: new "Response metadata + typed body" subsection with a
Link-header pagination example; points body-only callers back at
client.get(..., response_model=).

planning/engineering.md: Seam B contract now names send_with_response
alongside send as the two call sites that wrap decoder exceptions.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: lesnik512

docs/index.md

@@ -81,6 +81,41 @@ async def main() -> None:
         user = await client.get("/users/1", response_model=User)
 ```
 
+### Response metadata + typed body
+
+When you need both the raw `httpx2.Response` (for headers, status, or the
+request URL) **and** a typed body, use `send_with_response`. It returns
+both atomically and routes the decode through the configured
+`ResponseDecoder`, so decoder failures surface as `DecodeError` — caught
+by `except httpware.ClientError` like every other failure mode.
+
+Canonical use case: RFC 5988 Link-header pagination.
+
+```python
+from httpware import AsyncClient
+from pydantic import BaseModel
+
+
+class Tag(BaseModel):
+    name: str
+
+
+async def main() -> None:
+    async with AsyncClient(base_url="https://gitlab.example/api/v4") as client:
+        url = "/projects/1/repository/tags"
+        params: dict[str, str] | None = {"per_page": "100", "page": "1"}
+        while url:
+            request = client.build_request("GET", url, params=params)
+            response, tags = await client.send_with_response(request, response_model=list[Tag])
+            for tag in tags:
+                process(tag)
+            url = next_link(response.headers.get("link"))   # caller's parser
+            params = None                                    # next link carries query
+```
+
+For the body-only case, prefer `client.get(..., response_model=...)`.
+`send_with_response` is not for streaming responses — use `stream()`.
+
 ### Streaming responses
 
 For large responses or server-sent events, stream the body chunk-by-chunk. `stream()` is an async context manager:

planning/engineering.md

@@ -39,7 +39,7 @@ The 0.1.0 seams numbered 1 (Middleware↔Transport) and 4 (Transport↔httpx2) h
 ### Seam B: `Client`/`AsyncClient` ↔ `ResponseDecoder`
 
 - **Where:** `src/httpware/client.py` ↔ `src/httpware/decoders/`.
-- **Contract:** the decoder is invoked when the caller passes `response_model=`. The protocol is `decode(content: bytes, model: type[T]) -> T`. Any exception raised by `decode` is wrapped by `Client.send` / `AsyncClient.send` into `httpware.DecodeError` (a `ClientError` subclass carrying `response`, `model`, `original`). Decoder implementers do not need to raise `DecodeError` directly.
+- **Contract:** the decoder is invoked when the caller passes `response_model=`. The protocol is `decode(content: bytes, model: type[T]) -> T`. Any exception raised by `decode` is wrapped by the call sites in `client.py` — `Client.send` / `AsyncClient.send` (when `response_model=` is set) and `Client.send_with_response` / `AsyncClient.send_with_response` — into `httpware.DecodeError` (a `ClientError` subclass carrying `response`, `model`, `original`). Decoder implementers do not need to raise `DecodeError` directly.
 - **Rule:** the decoder must operate on raw bytes in a single parse pass. Two-pass decoding (`json.loads` then `validate_python`) is rejected: a single bytes-in / typed-object-out pass avoids the redundant intermediate `dict` allocation and parses faster. The Pydantic adapter implements this as `TypeAdapter(model).validate_json(content)`, with the `TypeAdapter` itself memoized via `@functools.lru_cache(maxsize=1024)` on a module-level `_get_adapter(model)` factory (the adapter is the expensive part to build). The msgspec adapter implements it as `msgspec.json.decode(content, type=model)`.
 
 ### Seam C: `httpware ↔ optional extras`