docs(index): sync with shipped 0.4 features

- Drop '0.1.0 alpha' from the status line
- Rewrite the project description (pre-v0.2 wording claimed 'owns the
  abstraction layer / consumers never import the transport' — both
  walked back in v0.2)
- Add the pydantic extra to the install block (was added in 0.3.0)
- Add a 'With resilience middleware' subsection mirroring the README
- Add an 'Errors' section
- Fix the dead 'Engineering Notes' link (target file doesn't exist in
  docs/ tree; point to GH URL of planning/engineering.md instead)
- Fix the now-incorrect 'five protocol seams' claim (v0.2 collapsed to three)
- Add a Release notes link

Author: lesnik512

docs/index.md

@@ -1,8 +1,8 @@
 # httpware
 
-A Python async HTTP client framework for building resilient service clients. `httpware` owns the abstraction layer above the underlying HTTP client (`httpx2` by default); consumers never import the transport directly.
+A Python async HTTP client framework for building resilient service clients. `httpware` is a thin opinionated wrapper around `httpx2` — it re-exports `httpx2.Request`/`httpx2.Response` as the public request/response surface, adds a middleware chain (with a built-in resilience suite: `Retry` + `RetryBudget`, `Bulkhead`), opt-in typed response decoding, and a status-keyed exception tree raised automatically on 4xx/5xx.
 
-> **Status:** Pre-1.0 (0.1.0 alpha). Public API is subject to change between minor releases until v1.0.
+> **Status:** Pre-1.0. Public API is subject to change between minor releases until v1.0. Streaming and observability are not yet shipped.
 
 ## Install
 
@@ -13,6 +13,7 @@ pip install httpware
 Optional extras:
 
 ```bash
+pip install httpware[pydantic]   # PydanticDecoder (the default decoder path)
 pip install httpware[msgspec]    # MsgspecDecoder
 ```
 
@@ -39,10 +40,34 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
+### With resilience middleware
+
+Compose resilience middleware at construction; `Bulkhead` goes outside `Retry` so one slot covers all retry attempts.
+
+```python
+from httpware import AsyncClient, Bulkhead, Retry
+
+
+async def main() -> None:
+    async with AsyncClient(
+        base_url="https://api.example.com",
+        middleware=[
+            Bulkhead(max_concurrent=10),  # cap total in-flight
+            Retry(),                       # default: 3 attempts, full-jitter backoff
+        ],
+    ) as client:
+        user = await client.get("/users/1", response_model=User)
+```
+
+## 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`.
+
 ## Where to go next
 
-- **[Engineering Notes](dev/engineering.md)** — design invariants, the five protocol seams, exception contract, module layout, testing patterns, optional-extras pattern.
+- **[Engineering Notes](https://github.com/modern-python/httpware/blob/main/planning/engineering.md)** — design invariants, the three protocol seams, exception contract, module layout, testing patterns, optional-extras pattern. Lives in the repo at `planning/engineering.md`.
 - **[Contributing](dev/contributing.md)** — setup, conventions, workflow.
+- **[Release notes](https://github.com/modern-python/httpware/releases)** — per-version changelogs.
 
 ## Part of `modern-python`