docs: polish README prose and repair stale facts

OmarAlJarrah · claude · OmarAlJarrah · commit f172ff1ffb4c · 2026-06-06T22:23:13.000+03:00
- Tighten the opening into a thesis plus design-philosophy paragraph
- Reorder sections: quick start before the core reference table, and
  contributor workspace setup moved into Development where it belongs
- Fix the packages table: core depends on furl (stale 'stdlib only'
  claim predated the Url migration); clarify the column covers
  third-party deps since every transport depends on core
- Smooth the architecture and highlights prose; drop em dashes

Co-Authored-By: Claude Opus 4.8 &lt;noreply@anthropic.com&gt;
diff --git a/README.md b/README.md
@@ -6,70 +6,40 @@
 [![Ruff](https://img.shields.io/badge/lint-ruff-blue.svg)](https://docs.astral.sh/ruff/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE.md)
 
-A toolkit for building Python HTTP client libraries — immutable models, a
-stage-based pipeline runtime, pluggable transports, and an authentication
-pillar including OAuth bearer tokens and RFC 7616 Digest. Targets Python
-3.12+, ships strict type annotations (`mypy --strict`), and keeps the core
-distribution dependency-free.
-
-The SDK is **not** an HTTP client. It defines the contracts (`HttpClient`,
-`AsyncHttpClient`) and supplies models, policies, and observability hooks;
-transport packages bring the actual networking. Pick the transport that
-matches your dependency constraints (or write your own — the Protocol is
-six lines).
+A toolkit for building Python HTTP client libraries. It provides immutable
+request and response models, a staged policy pipeline, pluggable transports,
+and an authentication pillar that speaks OAuth bearer tokens and RFC 7616
+Digest. Everything is typed end to end under `mypy --strict` and targets
+Python 3.12 or later.
+
+The SDK is deliberately not an HTTP client. It defines the contracts
+(`HttpClient`, `AsyncHttpClient`) and supplies the models, policies, and
+observability hooks that surround them; the networking itself arrives
+through a transport package of your choosing. Pick the adapter that fits
+your dependency budget, or write your own: the Protocol is six lines.
 
 ## Packages
 
 The repository is a [`uv`](https://docs.astral.sh/uv/)-managed workspace of
-five distributions sharing the `dexpace.sdk.*` namespace:
+five distributions sharing the `dexpace.sdk.*` namespace. Each transport
+package depends on `dexpace-sdk-core` and exactly one HTTP library.
 
-| Package                          | Purpose                                                           | Runtime dependencies        |
-|----------------------------------|-------------------------------------------------------------------|-----------------------------|
-| `dexpace-sdk-core`               | Toolkit: models, pipeline, policies, auth, observability          | None (stdlib only)          |
-| `dexpace-sdk-http-stdlib`        | `UrllibHttpClient` (sync) + `AsyncioHttpClient` (async)           | `dexpace-sdk-core`          |
-| `dexpace-sdk-http-httpx`         | `HttpxHttpClient` (sync) + `AsyncHttpxHttpClient`                 | `httpx`                     |
-| `dexpace-sdk-http-aiohttp`       | `AiohttpHttpClient` (async only)                                  | `aiohttp`                   |
-| `dexpace-sdk-http-requests`      | `RequestsHttpClient` (sync only)                                  | `requests`                  |
+| Package                     | Provides                                                  | Third-party dependencies |
+|-----------------------------|-----------------------------------------------------------|--------------------------|
+| `dexpace-sdk-core`          | Models, pipeline, policies, auth, observability           | `furl`                   |
+| `dexpace-sdk-http-stdlib`   | `UrllibHttpClient` (sync), `AsyncioHttpClient` (async)    | none (stdlib only)       |
+| `dexpace-sdk-http-httpx`    | `HttpxHttpClient` (sync), `AsyncHttpxHttpClient` (async)  | `httpx`                  |
+| `dexpace-sdk-http-aiohttp`  | `AiohttpHttpClient` (async)                               | `aiohttp`                |
+| `dexpace-sdk-http-requests` | `RequestsHttpClient` (sync)                               | `requests`               |
 
-End-users install only the transport they need:
+Install the core plus whichever transport you need:
 
 ```bash
 pip install dexpace-sdk-core dexpace-sdk-http-httpx
 ```
 
-## What's in `dexpace-sdk-core`
-
-| Subpackage                      | Surface                                                                                                  |
-|---------------------------------|----------------------------------------------------------------------------------------------------------|
-| `http.request`                  | `Request`, `RequestBody`, `FileRequestBody`, `LoggableRequestBody`, `MultipartRequestBody`, `Method`     |
-| `http.response`                 | `Response`, `AsyncResponse`, `ResponseBody`, `AsyncResponseBody`, `LoggableResponseBody`, `Status`       |
-| `http.common`                   | `Headers`, `HttpHeaderName`, `MediaType`, `Protocol`, `Url`, `QueryParams`, `ETag`, `HttpRange`, `RequestConditions`, paging primitives |
-| `http.context`                  | `CallContext` → `DispatchContext` → `RequestContext` → `ExchangeContext` chain, `ContextStore`           |
-| `http.auth`                     | `BearerTokenPolicy`, `BasicAuthPolicy`, `KeyCredentialPolicy`, `DigestChallengeHandler`, RFC 7235 challenge parser, `TokenCache` |
-| `http.sse`                      | `SseParser` for Server-Sent Events streams                                                               |
-| `pipeline`                      | `Pipeline`, `AsyncPipeline`, `Policy` ABC, `Stage` enum, `StagedPipelineBuilder`, `default_pipeline()`   |
-| `pipeline.policies`             | `RetryPolicy`, `RedirectPolicy`, `SetDatePolicy`, `LoggingPolicy`, `TracingPolicy` (+ async twins)       |
-| `client`                        | `HttpClient` and `AsyncHttpClient` Protocols                                                             |
-| `serde`                         | `Serde`, `Serializer`, `Deserializer` Protocols + `JsonSerde` reference impl                             |
-| `instrumentation`               | `ClientLogger`, `UrlRedactor`, `Tracer`, `Span`, `InstrumentationContext`, noop singletons               |
-| `errors`                        | `SdkError` hierarchy: `ServiceRequestError`, `ServiceResponseError`, `HttpResponseError[ModelT]`, …      |
-| `util`                          | `Clock`, `AsyncClock`, `ProxyOptions`                                                                    |
-| `config`                        | `Configuration` (layered env-var + override lookup) + `ConfigurationBuilder`                             |
-
 ## Quick start
 
-### Workspace setup (contributors)
-
-```bash
-git clone https://github.com/dexpace/python-sdk.git
-cd python-sdk
-uv sync
-```
-
-`uv sync` provisions a virtualenv with every workspace package installed in
-editable mode plus the dev toolchain (`pytest`, `mypy`, `ruff`). All
-commands below run via `uv run …`.
-
 ### A minimal request
 
 ```python
@@ -109,8 +79,8 @@ with UrllibHttpClient() as client, client.execute(request) as response:
 ### A configured pipeline
 
 `default_pipeline()` returns a `StagedPipelineBuilder` pre-wired with the
-canonical policy stack (redirect → retry → set-date → logging → tracing).
-Add authentication and customise as needed:
+canonical policy stack (redirect, retry, set-date, logging, tracing). Add
+authentication and adjust whatever the defaults get wrong for you:
 
 ```python
 from dexpace.sdk.core.http.auth import BearerTokenPolicy
@@ -128,10 +98,10 @@ with pipeline:
     response = pipeline.run(request, dispatch_context)
 ```
 
-`StagedPipelineBuilder` enforces stage-based ordering and pillar
-constraints (one redirect policy, one retry policy, one auth policy)
-through type-checked surgical edits — `replace`, `insert_after`,
-`insert_before`, `remove` operate by policy class.
+The builder enforces stage ordering and pillar constraints (one redirect
+policy, one retry policy, one auth policy) and supports surgical,
+type-checked edits: `replace`, `insert_after`, `insert_before`, and
+`remove` all operate by policy class.
 
 ### Streaming and replayable bodies
 
@@ -142,97 +112,126 @@ from dexpace.sdk.core.http.request import RequestBody
 RequestBody.from_stream(open("payload.bin", "rb"))
 RequestBody.from_iter([b"chunk-1", b"chunk-2"])
 
-# Replayable (transport may use zero-copy sendfile)
+# Replayable (transports may use zero-copy sendfile)
 RequestBody.from_file("upload.bin")
 
 # Convert any single-use body into a replayable one before retrying
 replayable = body.to_replayable()
 ```
 
-`RetryPolicy` automatically buffers single-use bodies before the first
-attempt when retries are configured.
+When retries are configured, `RetryPolicy` buffers single-use bodies
+before the first attempt so a retry never finds the stream already drained.
 
 ## Architecture
 
-The pipeline runs request flow through ordered `Policy` instances; each
-policy can mutate the request, invoke the downstream chain, and
-post-process the response. The terminal `Policy` is wired to an
-`HttpClient` transport.
+A request flows through ordered `Policy` instances. Each policy may rewrite
+the request, invoke the chain below it, and post-process the response on
+the way back up. The terminal policy hands the request to an `HttpClient`
+transport.
 
 ```
 caller → Pipeline → REDIRECT → RETRY → SET_DATE → AUTH → LOGGING → POST_LOGGING → HttpClient → wire
                      (pillar)  (pillar)            (pillar) (pillar)
 ```
 
-Stage ordering is enforced by `Stage`, an `IntEnum` with sparse 100-apart
-values that leave room for new stages without renumbering. Pillar stages
-admit at most one policy; non-pillar stages stack with deque semantics. The
-list-form `Pipeline(client, policies=[...])` constructor remains available
-for callers who want explicit ordering.
+Ordering is governed by `Stage`, an `IntEnum` whose values sit 100 apart so
+new stages can land without renumbering. Pillar stages admit a single
+policy; non-pillar stages stack with deque semantics. Callers who prefer
+explicit ordering can still use the list form,
+`Pipeline(client, policies=[...])`.
 
-Layered, bottom-up:
+Bottom-up, the layers are:
 
 1. **Bodies.** `RequestBody.iter_bytes(chunk)` produces bytes on demand;
-   `ResponseBody.iter_bytes` / `bytes()` / `string()` consume them.
+   `ResponseBody.iter_bytes`, `bytes()`, and `string()` consume them.
    Stream-backed variants are single-use; bytes-backed and file-backed
-   variants are replayable.
-2. **Models.** `Request`, `Response`, `Headers`, `Url`, etc. are
-   `@dataclass(frozen=True, slots=True)`. Mutate via `dataclasses.replace`
-   or `with_*` helpers.
-3. **Context.** `DispatchContext` → `RequestContext` → `ExchangeContext`
-   carry the `InstrumentationContext` (trace id, span id, flags) and are
-   registered in the thread-safe `ContextStore` keyed by trace id.
-4. **Pipeline.** `Policy` ABC + `Stage` enum. Policies declare
-   `STAGE: ClassVar[Stage]` (enforced at class-creation via
-   `__init_subclass__`) and slot into `StagedPipelineBuilder` accordingly.
+   variants replay freely.
+2. **Models.** `Request`, `Response`, `Headers`, `Url`, and their kin are
+   `@dataclass(frozen=True, slots=True)`. Mutation happens through
+   `dataclasses.replace` or the `with_*` helpers, never in place.
+3. **Context.** `DispatchContext` promotes to `RequestContext` and then
+   `ExchangeContext`, carrying an `InstrumentationContext` (trace id, span
+   id, flags) throughout. The thread-safe `ContextStore` indexes live
+   contexts by trace id.
+4. **Pipeline.** The `Policy` ABC pairs with the `Stage` enum. Each policy
+   declares `STAGE: ClassVar[Stage]`, checked at class creation via
+   `__init_subclass__`, and slots into the builder accordingly.
 5. **Client.** `HttpClient.execute(request) → Response` and its async twin
-   are the only transport contracts. Concrete transports live in separate
+   are the only transport contracts. Concrete transports live in their own
    distributions.
 
+## Inside the core
+
+| Subpackage          | Surface                                                                                                  |
+|---------------------|----------------------------------------------------------------------------------------------------------|
+| `http.request`      | `Request`, `RequestBody`, `FileRequestBody`, `LoggableRequestBody`, `MultipartRequestBody`, `Method`     |
+| `http.response`     | `Response`, `AsyncResponse`, `ResponseBody`, `AsyncResponseBody`, `LoggableResponseBody`, `Status`       |
+| `http.common`       | `Headers`, `HttpHeaderName`, `MediaType`, `Protocol`, `Url`, `QueryParams`, `ETag`, `HttpRange`, `RequestConditions`, paging primitives |
+| `http.context`      | `CallContext` → `DispatchContext` → `RequestContext` → `ExchangeContext` chain, `ContextStore`           |
+| `http.auth`         | `BearerTokenPolicy`, `BasicAuthPolicy`, `KeyCredentialPolicy`, `DigestChallengeHandler`, RFC 7235 challenge parser, `TokenCache` |
+| `http.sse`          | `SseParser` for Server-Sent Events streams                                                               |
+| `pipeline`          | `Pipeline`, `AsyncPipeline`, `Policy` ABC, `Stage` enum, `StagedPipelineBuilder`, `default_pipeline()`   |
+| `pipeline.policies` | `RetryPolicy`, `RedirectPolicy`, `SetDatePolicy`, `LoggingPolicy`, `TracingPolicy` (+ async twins)       |
+| `client`            | `HttpClient` and `AsyncHttpClient` Protocols                                                             |
+| `serde`             | `Serde`, `Serializer`, `Deserializer` Protocols + `JsonSerde` reference impl                             |
+| `instrumentation`   | `ClientLogger`, `UrlRedactor`, `Tracer`, `Span`, `InstrumentationContext`, noop singletons               |
+| `errors`            | `SdkError` hierarchy: `ServiceRequestError`, `ServiceResponseError`, `HttpResponseError[ModelT]`, …      |
+| `util`              | `Clock`, `AsyncClock`, `ProxyOptions`                                                                    |
+| `config`            | `Configuration` (layered env-var + override lookup) + `ConfigurationBuilder`                             |
+
 ## Highlights
 
-- **Strictly typed.** `mypy --strict` clean; no `Any` in public API; PEP
-  695 type parameters where they fit; `Literal[Stage.X]` to lock policy
-  stages at the type level.
-- **Immutable data with slots.** Frozen dataclasses with `__slots__` for
-  every model; non-destructive updates via `with_*` helpers.
-- **Pluggable everything.** `HttpClient` / `AsyncHttpClient` /
-  `ChallengeHandler` / `Serde` / `TokenCache` / `Clock` /
-  `Configuration` are all duck-typed Protocols.
-- **Real auth.** OAuth bearer with concurrent-refresh serialization,
+- **Strictly typed.** Clean under `mypy --strict`, with no `Any` in the
+  public API. PEP 695 type parameters appear where they fit, and
+  `Literal[Stage.X]` pins policy stages at the type level.
+- **Immutable data with slots.** Every model is a frozen dataclass with
+  `__slots__`; updates are non-destructive through `with_*` helpers.
+- **Pluggable everything.** `HttpClient`, `AsyncHttpClient`,
+  `ChallengeHandler`, `Serde`, `TokenCache`, `Clock`, and `Configuration`
+  are all duck-typed Protocols, so a conforming class is a valid
+  implementation with no registration step.
+- **Real auth.** OAuth bearer with serialized concurrent refresh, a
   `WWW-Authenticate` challenge parser per RFC 7235, RFC 7616 Digest
-  (MD5 / MD5-sess / SHA-256 / SHA-256-sess), basic, and key credential.
+  (MD5, MD5-sess, SHA-256, SHA-256-sess), basic, and key credential.
 - **Retry done right.** Exponential backoff with jitter, `Retry-After`
-  awareness, automatic single-use-body replay, deterministic via
-  injectable `Clock`.
-- **Redirects done right.** Loop detection, `Authorization` stripping on
+  awareness, automatic replay of single-use bodies, and deterministic
+  behaviour under test through an injectable `Clock`.
+- **Redirects done right.** Loop detection, `Authorization` stripped on
   reissue, userinfo dropped from `Location` URLs, configurable allowed
   methods and 303 handling.
-- **Observability.** Structured logging via `LoggingPolicy`, OpenTelemetry-
-  compatible spans via `TracingPolicy`, URL redaction with allowlisted
-  query parameters, body capture caps for diagnostic logging.
-- **Server-Sent Events.** WHATWG-compliant `SseParser` with bounded line
-  buffer.
-- **Zero core dependencies.** `dexpace-sdk-core` ships against the
-  standard library only; transport adapters bring exactly one third-party
-  HTTP library each.
+- **Observability.** Structured logging via `LoggingPolicy`,
+  OpenTelemetry-compatible spans via `TracingPolicy`, URL redaction with
+  allowlisted query parameters, and capped body capture for diagnostics.
+- **Server-Sent Events.** A WHATWG-compliant `SseParser` with a bounded
+  line buffer.
+- **A lean core.** `dexpace-sdk-core` carries a single runtime dependency
+  (`furl`, which backs `Url` parsing); each transport adapter adds exactly
+  one HTTP library.
 
 ## Development
 
+The workspace is managed with `uv`; one sync provisions every package in
+editable mode along with the dev toolchain (`pytest`, `mypy`, `ruff`).
+
+```bash
+git clone https://github.com/dexpace/python-sdk.git
+cd python-sdk
+uv sync
+```
+
 ```bash
-uv sync                          # provision workspace + dev tools
 uv run pytest -q                 # 646 tests across 5 packages
 uv run mypy --strict             # type-check (171 source files)
 uv run ruff check                # lint
 uv run ruff format --check       # formatting gate
 ```
 
 CI runs the same gates on Python 3.12, 3.13, and 3.14 for every push and
-pull request — see [`.github/workflows/ci.yml`](.github/workflows/ci.yml).
+pull request; see [`.github/workflows/ci.yml`](.github/workflows/ci.yml).
 
 ## Conventions
 
-Documented in [`CLAUDE.md`](CLAUDE.md). Highlights:
+Documented in [`CLAUDE.md`](CLAUDE.md). The short version:
 
 - Python 3.12+; modern syntax (`X | None`, `list[X]`, `Self`, PEP 695
   generics); `from __future__ import annotations` everywhere.
@@ -241,15 +240,14 @@ Documented in [`CLAUDE.md`](CLAUDE.md). Highlights:
 - Context managers for resources (`Response`, `ResponseBody`,
   `CallContext`).
 - `mypy --strict` and `ruff` clean on every commit; Google-style
-  docstrings on every public symbol; function-size cap of 50 lines.
+  docstrings on every public symbol; functions capped at 50 lines.
 
 ## Contributing
 
-External pull requests are welcome. Run the gates above (`pytest`, `mypy
---strict`, `ruff check`, `ruff format --check`) before opening one, and
-follow the conventions in [`CLAUDE.md`](CLAUDE.md).
+External pull requests are welcome. Run the gates above before opening
+one, and follow the conventions in [`CLAUDE.md`](CLAUDE.md).
 
 ## License
 
-Licensed under the [MIT License](LICENSE.md).
+Released under the [MIT License](LICENSE.md).
 Copyright © 2026 dexpace and Omar Aljarrah.
