docs: 0.5.0 release notes + sync user docs with streaming work

- README + docs/index.md: add 'Streaming responses' subsection
- planning/engineering.md §1 + §8: mention stream() in project intent;
  mark Epic 4 SHIPPED in roadmap
- planning/deferred-work.md: close the 'Retry + streaming bodies' open
  item and update the v0.2-pivot StreamError-escape entry; add a new
  'Closed by the 0.5.0 streaming release' section
- planning/releases/0.5.0.md: new release notes

Author: lesnik512

README.md

@@ -61,6 +61,25 @@ async def main() -> None:
         user = await client.get("/users/1", response_model=User)
 ```
 
+### Streaming responses
+
+For large responses or server-sent events, stream the body chunk-by-chunk. `stream()` is an async context manager:
+
+```python
+from httpware import AsyncClient
+
+
+async def main() -> None:
+    async with AsyncClient(base_url="https://api.example.com") as client:
+        async with client.stream("GET", "/big-file") as response:
+            async for chunk in response.aiter_bytes():
+                process(chunk)
+```
+
+`stream()` auto-raises `StatusError` subclasses on 4xx/5xx with the response body pre-read, so `exc.response.content` is accessible from the caught exception.
+
+It does NOT pass through the middleware chain: `Retry`, `Bulkhead`, and any custom middleware are bypassed. (Retry separately refuses to retry any request — stream or non-stream — whose body was an async-iterable, since streams can't replay across attempts.)
+
 ## Errors
 
 All 4xx/5xx responses raise typed exceptions automatically: `NotFoundError`, `ServiceUnavailableError`, `RateLimitedError`, etc. — all subclasses of `httpware.StatusError`. Transport-layer transient failures raise `NetworkError`; the resilience middleware raise `RetryBudgetExhaustedError` and `BulkheadFullError`. Everything inherits `httpware.ClientError`.

docs/index.md

@@ -59,6 +59,25 @@ async def main() -> None:
         user = await client.get("/users/1", response_model=User)
 ```
 
+### Streaming responses
+
+For large responses or server-sent events, stream the body chunk-by-chunk. `stream()` is an async context manager:
+
+```python
+from httpware import AsyncClient
+
+
+async def main() -> None:
+    async with AsyncClient(base_url="https://api.example.com") as client:
+        async with client.stream("GET", "/big-file") as response:
+            async for chunk in response.aiter_bytes():
+                process(chunk)
+```
+
+`stream()` auto-raises `StatusError` subclasses on 4xx/5xx with the response body pre-read, so `exc.response.content` is accessible from the caught exception.
+
+It does NOT pass through the middleware chain: `Retry`, `Bulkhead`, and any custom middleware are bypassed. (Retry separately refuses to retry any request — stream or non-stream — whose body was an async-iterable, since streams can't replay across attempts.)
+
 ## Errors
 
 All 4xx/5xx responses raise typed exceptions automatically: `NotFoundError`, `ServiceUnavailableError`, `RateLimitedError`, etc. — all subclasses of `httpware.StatusError`. Transport-layer transient failures raise `NetworkError`; the resilience middleware raise `RetryBudgetExhaustedError` and `BulkheadFullError`. Everything inherits `httpware.ClientError`.

planning/deferred-work.md

@@ -4,10 +4,6 @@ Items raised in reviews that are real but not actionable now.
 
 ## Open
 
-### Retry + streaming bodies (Epic 4 interaction)
-
-- **`Retry` re-invokes `next(request)` with the same `httpx2.Request` on each attempt.** Safe for in-memory bytes/JSON bodies; unsafe for streaming/async-iterable bodies (consumed iterator can't replay). When Epic 4 ships `AsyncClient.stream` (`4-3`), Retry needs to refuse to retry streamed-body requests (or document that callers supply a body factory). Spec: `planning/specs/2026-06-05-retry-and-retry-budget-design.md` §"Open questions".
-
 ### Decoder-side
 
 - **`_get_adapter` `lru_cache` is module-global, not per-decoder instance** — keyed by `model` only; two `PydanticDecoder()` instances with different configurations (none today) would share adapters, and the cache survives across tests unless explicitly cleared. Revisit if/when a configurable `PydanticDecoder(mode=..., strict=...)` lands. (`src/httpware/decoders/pydantic.py:12-14`)
@@ -19,13 +15,18 @@ PR #21 (`feat/v0.3-pydantic-optional`) shipped 0.3.0 with pydantic moved to `[pr
 - **`pydantic` import not guarded the way `msgspec` is** — closed. `decoders/pydantic.py` now guards via `import_checker.is_pydantic_installed`; `PydanticDecoder.__init__` raises `ImportError` with the install hint; `AsyncClient(decoder=None)` fail-fast in `_default_pydantic_decoder()`.
 - **Empty/malformed payload tests** — closed. `tests/test_decoders_pydantic.py::test_malformed_payload_raises_validation_error` is a 7-case parametrized test pinning current pydantic-core behavior for `b""`, `b"null"`, `b"{}"`, malformed JSON, and invalid UTF-8.
 
+## Closed by the 0.5.0 streaming release (2026-06-05)
+
+- **`Retry` refuses streamed-body requests.** When `_request_with_body` is called with an async-iterable `content`/`data`/`files`, the request gets `extensions["httpware.streaming_body"] = True`. `Retry.__call__` reads the marker and re-raises with a PEP-678 note on retryable failures instead of retrying with a consumed iterator. Closes the prior Open entry.
+- **`httpx2.StreamError` family escape closed.** The new shared `_httpx2_exception_mapper` catches `httpx2.NetworkError` (which is the parent of `ReadError` / `WriteError` / `CloseError`), so stream-specific exceptions raised during body consumption now map to `httpware.NetworkError` consistently.
+
 ## Closed by the v0.2 thin-wrapper pivot (2026-06-03)
 
 The pivot retired Request/Response/Httpx2Transport/RecordedTransport. The following deferred items are no longer applicable because their host code has been removed or because the responsibility shifted to `httpx2`:
 
 - `extensions=dict(request.extensions)` opaque forwarding (host module removed).
 - Unbounded error body size on `StatusError.body` (the `body` field no longer exists; callers reach into `exc.response.content` themselves).
-- `httpx2.StreamError` family escape from the transport's `except httpx2.HTTPError` (mapping logic relocated to AsyncClient's terminal; revisit with Epic 4 streaming work).
+- `httpx2.StreamError` family escape from the transport's `except httpx2.HTTPError` (mapping logic relocated to AsyncClient's terminal; closed by 0.5.0 streaming work — exception mapping in _httpx2_exception_mapper covers the StreamError family via httpx2.NetworkError).
 - Header CRLF / log-injection at the transport seam (host module removed; httpx2 validates).
 - Userinfo on `StatusError.request_url` raw field (the field no longer exists; `__repr__` and summary still sanitize).
 - Concurrent `aclose()` ↔ `__call__` races on `Httpx2Transport` (host class removed; lifecycle is `httpx2`'s concern).

planning/engineering.md

@@ -4,7 +4,7 @@ This doc is the single distilled reference for `httpware` design rationale, prot
 
 ## 1. Project intent
 
-`httpware` is a thin opinionated wrapper around `httpx2`. It re-exports `httpx2.Request` and `httpx2.Response` as the public request/response surface and adds three things on top: typed response decoding (via a `ResponseDecoder` protocol; pydantic and msgspec are both opt-in extras as of 0.3.0), a middleware chain composed at client construction, and a status-keyed exception tree raised automatically on 4xx and 5xx. `AsyncClient(decoder=None)` defaults to constructing a `PydanticDecoder` and so requires the `pydantic` extra; callers can supply an explicit `decoder=` argument to escape the default. As of 0.4.0, the package ships a small resilience suite under `httpware.middleware.resilience` — a `Retry` middleware with a Finagle-style `RetryBudget`, plus a `Bulkhead` concurrency limiter — composed via the standard middleware chain.
+`httpware` is a thin opinionated wrapper around `httpx2`. It re-exports `httpx2.Request` and `httpx2.Response` as the public request/response surface and adds three things on top: typed response decoding (via a `ResponseDecoder` protocol; pydantic and msgspec are both opt-in extras as of 0.3.0), a middleware chain composed at client construction, and a status-keyed exception tree raised automatically on 4xx and 5xx. `AsyncClient(decoder=None)` defaults to constructing a `PydanticDecoder` and so requires the `pydantic` extra; callers can supply an explicit `decoder=` argument to escape the default. As of 0.4.0, the package ships a small resilience suite under `httpware.middleware.resilience` — a `Retry` middleware with a Finagle-style `RetryBudget`, plus a `Bulkhead` concurrency limiter — composed via the standard middleware chain. As of 0.5.0, `AsyncClient.stream()` provides a context-manager API for chunked response bodies; it bypasses the middleware chain by design (see planning/specs/2026-06-05-streaming-design.md).
 
 The 0.1.0 release attempted to own a full abstraction over the underlying HTTP client. v0.2 walks that back: `httpx2` is part of the public surface.
 
@@ -132,7 +132,7 @@ Post-pivot, the roadmap has three categories. Topic slugs in `planning/specs/` a
   - **Shipped in v0.4 slice 1:** `Retry` middleware + Finagle-style `RetryBudget` token bucket + `attempt_timeout=` parameter (folded-in 3-1). See [`planning/specs/2026-06-05-retry-and-retry-budget-design.md`](specs/2026-06-05-retry-and-retry-budget-design.md) and [`planning/plans/2026-06-05-retry-and-retry-budget-plan.md`](plans/2026-06-05-retry-and-retry-budget-plan.md).
   - **Shipped in v0.4 slice 2:** `Bulkhead` middleware (concurrency limiter via `asyncio.Semaphore` with bounded acquire wait). See [`planning/specs/2026-06-05-bulkhead-design.md`](specs/2026-06-05-bulkhead-design.md) and [`planning/plans/2026-06-05-bulkhead-plan.md`](plans/2026-06-05-bulkhead-plan.md).
   - **Remaining:** `3-6` extension-slot docs.
-- **Epic 4 — Streaming:** `4-3` `AsyncClient.stream` context manager (forwards to `httpx2.AsyncClient.stream`; no `StreamResponse` type).
+- **Epic 4 — Streaming:** SHIPPED in v0.5 (PR #…): `AsyncClient.stream()` context manager + Retry refuses streamed-body requests. See [`planning/specs/2026-06-05-streaming-design.md`](specs/2026-06-05-streaming-design.md) and [`planning/plans/2026-06-05-streaming-plan.md`](plans/2026-06-05-streaming-plan.md).
 - **Epic 5 — Observability:** `5-1` Layer 1 middleware hooks, `5-2` wire into resilience middlewares, `5-4` OpenTelemetry middleware (will declare the `otel` extra at the same time the code lands), `5-5` logging policy CI grep.
 - **Epic 6 — Ship v1.0:** `6-2` docs site (`mkdocs`), `6-3` benchmarks, `6-5` release flow (Trusted Publishers + Sigstore).
 - **Carry-forward decoder:** `1-6` msgspec decoder via extras — second `ResponseDecoder` adapter, already implemented; verified surviving in the pivot.

planning/releases/0.5.0.md

@@ -0,0 +1,54 @@
+# httpware 0.5.0 — Streaming responses
+
+**0.5.0 is additive. No breaking changes.** Code written against 0.4.0 continues to work unchanged.
+
+This release closes Epic 4 by adding `AsyncClient.stream()` for chunked response bodies, and closes two longstanding deferred-work items along the way.
+
+## New features
+
+- **`AsyncClient.stream(method, url, **kwargs)`** — async context manager that yields an `httpx2.Response` with a non-pre-read body. Consume via `response.aiter_bytes()`, `response.aiter_text()`, `response.aiter_lines()`, or `response.aiter_raw()`. Auto-raises `StatusError` subclasses on 4xx/5xx (with the body pre-read so `exc.response.content` works). Bypasses the middleware chain by design — `Retry`, `Bulkhead`, and user-installed middleware do not see `stream()` calls in v1.
+- **`Retry` refuses streamed-body requests.** When you call `client.post(content=async_gen())` (or `data=`, `files=`), the request is marked via `request.extensions["httpware.streaming_body"]`. If `Retry` would otherwise retry on a failure, it re-raises the original exception with a PEP 678 note instead — preventing the "consumed iterator can't replay" footgun.
+
+## Backwards compatibility
+
+Subclassing/extensions preserve every existing catch-block:
+
+- All previously-shipping methods (`get`, `post`, etc.) behave identically.
+- The internal refactor that extracted `_httpx2_exception_mapper` from `_terminal` is byte-for-byte equivalent in dispatch behavior. Tests prove this.
+- The streaming-body marker (`request.extensions["httpware.streaming_body"]`) only affects requests that genuinely have async-iterable bodies. Existing code passing bytes / dict / files-as-bytes is unaffected.
+
+## Usage
+
+```python
+from httpware import AsyncClient
+
+
+async def main() -> None:
+    async with AsyncClient(base_url="https://api.example.com") as client:
+        async with client.stream("GET", "/big-file") as response:
+            async for chunk in response.aiter_bytes():
+                process(chunk)
+```
+
+Catch typed status errors on streams the same way as on regular calls:
+
+```python
+from httpware import NotFoundError
+
+try:
+    async with client.stream("GET", "/maybe-missing") as response:
+        ...
+except NotFoundError as exc:
+    body_text = exc.response.text  # pre-read; accessible
+```
+
+## What's still ahead
+
+- Epic 5 (observability hooks + OTel middleware) is unstarted; logging of retry / bulkhead / stream decisions plumbs through then.
+- Whether `stream()` should compose with the middleware chain is deferred to real-user feedback. Adding it later is purely additive (`stream(..., apply_middleware: bool = False)` opt-in).
+
+## References
+
+- Spec: [`planning/specs/2026-06-05-streaming-design.md`](../specs/2026-06-05-streaming-design.md)
+- Plan: [`planning/plans/2026-06-05-streaming-plan.md`](../plans/2026-06-05-streaming-plan.md)
+- Roadmap: [`planning/engineering.md`](../engineering.md) §8