@@ -8,7 +8,7 @@ Thank you for your interest in contributing. `httpware` is an open-source resili
 git clone https://github.com/modern-python/httpware.git
 cd httpware
 just install        # uv lock --upgrade && uv sync --all-extras --frozen --group lint
-just lint           # ruff format + ruff check + ty check
+just lint           # eof-fixer + ruff format + ruff check + ty check
 just test           # pytest with coverage
 ```
 
@@ -29,7 +29,9 @@ just test           # pytest with coverage
 
 ## Architecture invariants
 
-These are enforced by CI grep gates. Do not break them in pull requests:
+These are project invariants. The CI lint pass (`just lint-ci` — `ruff` + `ty`)
+catches what the linters can see (e.g. `print()` via ruff `T20`); the rest are
+enforced in code review. Do not break them in pull requests:
 
 - No `httpx2._*` (private API) usage anywhere in the library.
 - No `from __future__ import annotations`.
 
@@ -101,7 +101,7 @@ async def main() -> None:
         await client.get("/users/1")
 ```
 
-A note on logger names: the example logs under `myapp.request_id`, NOT under `httpware.*`. The `httpware.*` namespace is reserved for events emitted by the library itself (see [Observability](index.md#observability) — `httpware.retry` and `httpware.bulkhead` are stable contracts). Consumer middleware should use your application's own logger namespace.
+A note on logger names: the example logs under `myapp.request_id`, NOT under `httpware.*`. The `httpware.*` namespace is reserved for events emitted by the library itself (see [Observability](index.md#observability) — `httpware.retry`, `httpware.bulkhead`, `httpware.circuit_breaker`, and `httpware.timeout` are stable contracts). Consumer middleware should use your application's own logger namespace.
 
 The example pairs naturally with the 0.6.0 observability events: a `httpware.retry` `retry.giving_up` log record carries a `url` attribute, and your `RequestIdMiddleware` set an `X-Request-Id` for that same call. Correlate the two in your log aggregator and you have end-to-end visibility from "this user's request" to "we gave up after N retries."
 
 
@@ -20,17 +20,26 @@ class ServiceClients(Group):
 
 
 async def main() -> None:
-    async with Container(scope=Scope.APP, groups=[ServiceClients]) as container:
-        client = await container.resolve(AsyncClient)
+    container = Container(scope=Scope.APP, groups=[ServiceClients])
+    try:
+        client = container.resolve(AsyncClient)
         response = await client.get("/users/1")
         print(response.status_code)
+    finally:
+        await container.close_async()  # runs the AsyncClient.aclose finalizer
 ```
 
+> **modern-di 2.x.** Resolution is sync — `container.resolve(...)`, no `await`.
+> The root container is created plainly and torn down with `await
+> container.close_async()` (the `async with` form is for
+> `build_child_container(...)`, not the root). On modern-di 1.x, resolution was
+> awaited; pin accordingly if you are still on 1.x.
+
 Breaking that down:
 
 - **`Scope.APP`** ties the client to the application lifetime. One client per process; the connection pool is reused across all calls.
 - **`cache_settings=providers.CacheSettings(...)`** is what makes the provider a singleton. Without it, `Factory` returns a fresh `AsyncClient` on every resolve.
-- **`finalizer=AsyncClient.aclose`** is the unbound async method. `modern-di` detects it as a coroutine function (via `inspect.iscoroutinefunction`) and `await`s it on container teardown.
+- **`finalizer=AsyncClient.aclose`** is the unbound async method. `modern-di` detects the async finalizer and `await`s it on container teardown (here, on `close_async()`).
 
 A common first instinct here is `finalizer=lambda c: c.aclose()`. **That does not work** — the lambda itself is sync, so `modern-di` calls it synchronously and discards the returned coroutine unawaited. The underlying connection pool leaks. Pass the unbound async method directly, or wrap in `async def`.
 
@@ -96,10 +105,13 @@ class ServiceClients(Group):
 
 
 async def main() -> None:
-    async with Container(scope=Scope.APP, groups=[ServiceClients]) as container:
-        users = await container.resolve(UserApi)
-        billing = await container.resolve(BillingApi)
+    container = Container(scope=Scope.APP, groups=[ServiceClients])
+    try:
+        users = container.resolve(UserApi)
+        billing = container.resolve(BillingApi)
         # ... use them
+    finally:
+        await container.close_async()
 ```
 
 A couple of notes:
 
@@ -67,9 +67,13 @@ A Finagle-style token bucket bounding retry rate. Each request deposits a token;
 ### The token-bucket formula
 
 ```
-ceiling = int(len(deposits_in_window) * percent_can_retry) + int(min_retries_per_sec * ttl)
+ceiling = ceil(len(deposits_in_window) * percent_can_retry) + int(min_retries_per_sec * ttl)
 ```
 
+The percent term rounds **up** (`math.ceil`), so even a handful of recent
+deposits permits at least one retry above the floor; the floor term truncates
+(`int`).
+
 A withdrawal fails when `len(withdrawn_in_window) >= ceiling`.
 
 ### Why a floor matters
@@ -233,7 +237,7 @@ Bounds total wall-clock time across the entire inner pipeline. Place it outermos
 
 | Parameter | Default | Effect |
 |---|---|---|
-| `timeout` | **REQUIRED** | Overall deadline in seconds. Must be `> 0`; `≤0` raises `ValueError`. |
+| `timeout` | **REQUIRED** | Overall deadline in seconds. Must be a finite number `> 0`; a non-finite (`inf`/`nan`) or `≤0` value raises `ValueError`. |
 
 **This is not a per-call timeout.** httpx2's connect/read/write/pool timeouts are the right tool for bounding a single outbound call; `AsyncTimeout` doesn't duplicate them. What httpx2 cannot bound is the total wall-clock across a whole retry sequence — `AsyncTimeout` fills that gap.
 
 
@@ -70,7 +70,7 @@ carry **no** frontmatter — living prose, dated by git.
 
 ### Active
 
-_None._
+- **[docs-accuracy-fixes](changes/active/2026-06-13.04-docs-accuracy-fixes/change.md)** (draft, 2026-06-13) — Fix the 5 verified factual errors from the [docs audit](audits/2026-06-13-docs-audit.md): RetryBudget formula, modern-di 2.x recipe, contributing-doc CI/grep claim, `just lint` comment, middleware stable-contracts list (+ AsyncTimeout non-finite wording).
 
 ### Archived (shipped)
 
 
@@ -0,0 +1,194 @@
+# httpware documentation audit — 2026-06-13
+
+**Status:** complete
+**Scope:** the user-facing documentation surface — `README.md`, the published
+mkdocs site (`docs/index.md`, `docs/errors.md`, `docs/middleware.md`,
+`docs/resilience.md`, `docs/testing.md`, `docs/recipes/*`, `docs/dev/contributing.md`),
+and `mkdocs.yml`. The internal `architecture/` and `planning/` trees were used
+as the source-of-truth cross-reference, not themselves audited.
+**Method:** four parallel auditors over distinct slices (README+index accuracy,
+capability-page accuracy, recipe accuracy, and a cross-corpus readability/UX/navigation
+pass). Every concrete code/API claim was verified against the real source in
+`src/httpware/`; the modern-di recipe claim was verified against the official
+modern-di 2.x migration docs via Context7. The five headline accuracy findings
+were reproduced directly against the code before this report was written.
+
+## Summary
+
+- Bugs (false claim / broken copy-paste example): **2**
+- Inconsistencies (contradicts code or another doc): **3**
+- Readability: **3**
+- Onboarding / UX gaps: **6**
+
+**Verdict.** For a developer who already knows what they want, these docs are
+strong: the reference pages (`errors.md`, `resilience.md`) are thorough and —
+`errors.md` and `testing.md` entirely — accurate down to byte-for-byte hint
+strings and payload-field lists; example code is unusually well-commented;
+terminology discipline is excellent (always `httpx2`, `AsyncClient`/`Client`,
+consistent capability names). The weaknesses cluster in two places: **a
+newcomer's first ten minutes** (no "why httpware", a non-resolving first
+example, no base-client migration path) and **a maintenance surface that will
+silently drift** (README ↔ index.md duplicate ~70% of their prose, including the
+full observability contract). Of ~30 checkable claims on the landing pages,
+accuracy was near-perfect; the real bugs live in deeper reference prose and the
+dev/recipe docs.
+
+## Findings
+
+### Bugs
+
+**B1 — `docs/resilience.md:70` — RetryBudget token-bucket formula is wrong (rounding).**
+The doc gives `ceiling = int(len(deposits_in_window) * percent_can_retry) + int(min_retries_per_sec * ttl)`.
+The code (`src/httpware/middleware/resilience/budget.py:68`) is
+`math.ceil(len(self._deposits) * self._percent_can_retry) + floor`, where
+`floor = int(self._min_retries_per_sec * self._ttl)`. The percent term is
+`math.ceil`, not `int` — a material difference, not a rounding nitpick. With the
+default `percent_can_retry=0.2`: 3 deposits → doc says +0, code yields +1;
+11 deposits → doc says +2, code yields +3. Anyone sizing a budget against the
+documented formula under-counts permitted retries.
+*Fix:* change the percent term to `ceil(...)`; the floor term stays `int(...)`.
+
+**B2 — `docs/recipes/modern-di.md:24,33,99–101` — recipe is broken against current modern-di (2.x).**
+The recipe uses `await container.resolve(...)` and `async with Container(scope=…, groups=[…]) as container:`.
+Both are modern-di **1.x** shapes. Verified against the modern-di 2.x migration
+docs (Context7, `/modern-python/modern-di`): resolution in 2.x is **sync-only**
+— "the `await` keywords used for asynchronous resolution in 1.x are removed …
+use `container.resolve(SomeType)` directly." The root `Container` is constructed
+plainly and torn down with `await container.close_async()`; `async with` is shown
+only for `build_child_container(...)`, never the root container. The recipe links
+to the live (2.x) docs, so a user copy-pasting today hits `TypeError` on the
+`await`. The `inspect.iscoroutinefunction` claim at line 33 is an unverifiable
+internal-mechanism detail and should be softened to the observable behaviour.
+*Fix:* drop `await` on every `resolve(...)`; construct the root container plainly
+and close it in a `try/finally` via `await container.close_async()`; soften the
+finalizer-detection sentence.
+
+### Inconsistencies
+
+**I1 — `docs/dev/contributing.md:32` — "enforced by CI grep gates" is false.**
+No `grep` runs in any `.github/workflows/` file. CI runs only `just install
+lint-ci` (ruff + ty) and `just test`. The `httpx2._` grep described in
+`CLAUDE.md`/`architecture/overview.md` as CI-enforced is **not wired into any
+workflow** — it is enforced, if at all, by review. (Separately: `CLAUDE.md` and
+`architecture/overview.md` both assert these invariants are "CI-enforced / CI
+rejects PRs"; that is true for `print()` via ruff `T20` but overstated for the
+`httpx2._` and `from __future__` rules. Triage item, not fixed here — see below.)
+*Fix:* replace "CI grep gates" with the accurate enforcement (CI lint pass:
+ruff + ty; review for the rest).
+
+**I2 — `docs/dev/contributing.md:11` — `just lint` comment omits `eof-fixer`.**
+The inline comment reads `# ruff format + ruff check + ty check`; the real target
+(`justfile:7–11`) runs four steps — `eof-fixer .`, `ruff format`, `ruff check
+--fix`, `ty check`. `CLAUDE.md` lists all four correctly.
+*Fix:* add `eof-fixer` to the comment.
+
+**I3 — `docs/middleware.md:104` — stale "stable contracts" list (two of four).**
+Names only `httpware.retry` and `httpware.bulkhead` as stable observability
+contracts. Since the 0.10.0 circuit-breaker/timeout work, `httpware.circuit_breaker`
+and `httpware.timeout` are equally stable — `index.md:153–159` lists all four and
+`architecture/resilience.md:23` states their event names "join `retry.*` /
+`bulkhead.*` as the stable observability surface; renames are breaking changes."
+*Fix:* list all four.
+
+(Also reclassified during audit: **`docs/resilience.md:236`** — the `AsyncTimeout`
+parameter table says only "`≤0` raises `ValueError`", but the code
+(`timeout.py:47`) and `architecture/resilience.md:17` also reject non-finite
+values (`inf`/`nan`). Narrower than both code and the truth home. Fixed with the
+batch.)
+
+### Readability
+
+**R1 — dense stacked-qualifier sentences in the hottest spots.** `README.md:31`
+(decoder resolution) stacks two qualified clauses; the `respect_retry_after`
+cell in `docs/resilience.md:24` is a four-sentence paragraph inside a table cell.
+Correct, but hard on first read. *Suggest:* split the densest sentences/cells.
+
+**R2 — unglossed jargon on first use.** "Finagle-style" (`README.md:17`),
+"full-jitter", "bulkhead", "PEP 678 note", "token bucket" — most are defined
+later or never, but the README is first contact. *Suggest:* a one-clause gloss on
+first use.
+
+**R3 — `_LOGGER` used in `errors.md` examples (lines 77, 130, 154) without
+definition.** A literal copy-paste hits `NameError`. Minor/conventional.
+
+### Onboarding & UX gaps (the larger lane — not bugs)
+
+These are the high-leverage adoption improvements; they require design, not
+mechanical edits, and are recorded here for triage rather than fixed in the
+accompanying change.
+
+- **G1 — No "why httpware".** Both README and index lead with "thin wrapper over
+  httpx2" + a feature list. The actual selling points (typed errors without
+  `raise_for_status()`; typed bodies via `response_model=`) are buried mid-page.
+  *Suggest:* a 3-bullet "Why httpware" block up top.
+- **G2 — No base-client migration guide.** httpware explicitly supersedes
+  community-of-python/base-client, yet that inbound audience has zero signpost in
+  the user docs. *Suggest:* `docs/migration-from-base-client.md`.
+- **G3 — README ↔ index.md ~70% duplicated**, including the entire observability
+  contract table — guaranteed to drift on the next logger/event change. *Suggest:*
+  one canonical home (docs/); README becomes value-prop + install + one quickstart
+  + links.
+- **G4 — First quickstart hits `https://example.test`**, which resolves to
+  nothing — a newcomer's first paste yields `NetworkError`, not data. *Suggest:* a
+  real public test endpoint for the leading example.
+- **G5 — `STATUS_TO_EXCEPTION` is a public `__all__` export
+  (`src/httpware/__init__.py:54`) documented nowhere.** The lone undocumented
+  public symbol. *Suggest:* document it (it is the extensible status→exception
+  map) or reconsider its place in `__all__`.
+- **G6 — No custom-`ResponseDecoder` guide and no API reference.** The decoder
+  seam (Seam B) is a documented extension point but, unlike middleware, gets no
+  "write your own" guide; and there is no generated symbol reference
+  (mkdocstrings) for constructor/method signatures. *Suggest:* a short Decoders
+  guide + minimal mkdocstrings page.
+
+Navigation nits (LOW): mkdocs nav orders Resilience before Middleware though
+Resilience is built on it and forward-references it; several `architecture/*.md`
+references in published pages are bare paths, not links, so a site reader cannot
+follow them. No orphan pages and no broken nav targets — the nav is otherwise clean.
+
+### Verified correct (negative results)
+
+- `README.md` + `docs/index.md`: every import resolves against `__all__`; all
+  constructor signatures/params (`base_url`, `decoders`, `response_model`,
+  `httpx2_client`, `middleware`, `max_concurrent`), the exception tree, the extras
+  (`httpware[pydantic|msgspec|otel|all]` vs `pyproject.toml`), and the behavioural
+  claims (auto-raise on 4xx/5xx, `MissingDecoderError` before the HTTP call,
+  pydantic-first default, stream bypasses middleware + pre-reads body on error,
+  `_emit_event` OTel call) are literally true. Zero bugs.
+- `docs/errors.md`: exception tree, `STATUS_TO_EXCEPTION` mapping table, the
+  400≤status<600 fallback, the StatusError-single-positional / ClientError-keyword
+  `__init__` split, the doubly-inherited `TimeoutError`, every resilience-error
+  payload field, and both `MissingDecoderError` hint strings match `errors.py`
+  byte-for-byte.
+- `docs/resilience.md`: every constructor default verified against source
+  (`max_attempts=3`, `base_delay=0.1`, `max_delay=5.0`,
+  `retry_status_codes={408,429,502,503,504}`, `failure_threshold=5`,
+  `reset_timeout=30.0`, `success_threshold=1`, budget `ttl=10.0`,
+  `min_retries_per_sec=10.0`, `percent_can_retry=0.2`, bulkhead `acquire_timeout=1.0`,
+  …); 429-as-success, OPEN/HALF_OPEN/CLOSED behaviour, Retry-After parsing/clamping,
+  and composition ordering all correct.
+- `docs/middleware.md`: protocol definitions, `Next`/`AsyncNext` aliases, the three
+  phase-decorator signatures (incl. `on_error` catching `Exception` not
+  `BaseException`), and the compose-once-and-frozen claim all match.
+- `docs/testing.md`: the `httpx2.MockTransport`-via-`httpx2_client=` pattern matches
+  the real tests and `architecture/testing.md`; the "`RecordedTransport` removed"
+  reference is correct.
+- `docs/recipes/link-header-pagination.md` and `phase-decorator-patterns.md`: every
+  API call matches source; both are copy-paste-safe.
+
+## Spawned changes
+
+- **`2026-06-13.04-docs-accuracy-fixes`** (lightweight) — fixes B1, B2, I1, I2, I3,
+  and the `AsyncTimeout`-validation wording. All verified against code / official
+  upstream docs.
+
+## Deferred / triage
+
+- The onboarding & UX gaps (G1–G6) — a separate, larger docs-UX change (de-dup,
+  why-httpware, base-client migration, runnable quickstart, custom-decoder guide,
+  API reference). Not yet scheduled.
+- The `httpx2._` invariant is documented as CI-enforced (`CLAUDE.md`,
+  `architecture/overview.md`, and — fixed here — `contributing.md`) but no CI
+  workflow runs the grep. Either wire `grep -rE 'httpx2\._' src/httpware/` into the
+  lint workflow (tiny CI change) or downgrade the "CI-enforced" wording in the two
+  internal truth docs. Parked pending a decision on which.