From bbe2e53bbee14a8957cf09a22d41d0fe4e6ccf4f Mon Sep 17 00:00:00 2001
From: avivkeller <me@aviv.sh>
Date: Thu, 18 Jun 2026 11:21:53 -0600
Subject: [PATCH 1/2] feat(docs): migrate to doc-kit

---
 docs/.nojekyll                                |    0
 docs/CNAME                                    |    1 -
 docs/README.md                                |  115 +-
 docs/docs/api/Agent.md                        |  292 ++-
 docs/docs/api/BalancedPool.md                 |  294 ++-
 docs/docs/api/CacheStorage.md                 |  184 +-
 docs/docs/api/CacheStore.md                   |  392 +++-
 docs/docs/api/Client.md                       |  540 +++--
 docs/docs/api/ClientStats.md                  |   94 +-
 docs/docs/api/Connector.md                    |  154 +-
 docs/docs/api/ContentType.md                  |   90 +-
 docs/docs/api/Cookies.md                      |  193 +-
 docs/docs/api/Debug.md                        |   52 +-
 docs/docs/api/DiagnosticsChannel.md           |  528 +++--
 docs/docs/api/Dispatcher.md                   | 1745 +++++++----------
 docs/docs/api/EnvHttpProxyAgent.md            |  188 +-
 docs/docs/api/Errors.md                       |  544 ++++-
 docs/docs/api/EventSource.md                  |  326 ++-
 docs/docs/api/Fetch.md                        |  711 ++++++-
 docs/docs/api/GlobalInstallation.md           |  176 +-
 docs/docs/api/H2CClient.md                    |  474 +++--
 docs/docs/api/MockAgent.md                    |  636 +++---
 docs/docs/api/MockCallHistory.md              |  370 +++-
 docs/docs/api/MockCallHistoryLog.md           |  215 +-
 docs/docs/api/MockClient.md                   |  184 +-
 docs/docs/api/MockErrors.md                   |   61 +-
 docs/docs/api/MockPool.md                     |  562 +++---
 docs/docs/api/Pool.md                         |  278 ++-
 docs/docs/api/PoolStats.md                    |  132 +-
 docs/docs/api/ProxyAgent.md                   |  332 ++--
 docs/docs/api/RedirectHandler.md              |  301 ++-
 docs/docs/api/RetryAgent.md                   |  139 +-
 docs/docs/api/RetryHandler.md                 |  238 ++-
 docs/docs/api/RoundRobinPool.md               |  238 ++-
 docs/docs/api/SnapshotAgent.md                |  806 +++-----
 docs/docs/api/Socks5ProxyAgent.md             |  349 ++--
 docs/docs/api/Util.md                         |   79 +-
 docs/docs/api/WebSocket.md                    |  555 +++++-
 docs/docs/api/api-lifecycle.md                |  132 +-
 .../docs/best-practices/client-certificate.md |    2 +
 docs/docs/best-practices/crawling.md          |    4 +-
 .../best-practices/migrating-from-v7-to-v8.md |   10 +-
 docs/docs/best-practices/mocking-request.md   |   14 +-
 docs/docs/best-practices/proxy.md             |    4 +-
 .../best-practices/undici-vs-builtin-fetch.md |   18 +-
 docs/docs/best-practices/writing-tests.md     |    2 +
 .../{GettingStarted.md => getting-started.md} |   38 +-
 docs/docs/index.md                            |  778 ++++++++
 docs/docs/site.json                           |  119 ++
 docs/docs/type-map.json                       |   79 +
 docs/docsify/sidebar.md                       |   50 -
 docs/index.html                               |  126 --
 docs/package.json                             |   11 -
 scripts/release.js                            |   10 +
 54 files changed, 9458 insertions(+), 4507 deletions(-)
 delete mode 100644 docs/.nojekyll
 delete mode 100644 docs/CNAME
 mode change 120000 => 100644 docs/README.md
 rename docs/docs/{GettingStarted.md => getting-started.md} (84%)
 create mode 100644 docs/docs/index.md
 create mode 100644 docs/docs/site.json
 create mode 100644 docs/docs/type-map.json
 delete mode 100644 docs/docsify/sidebar.md
 delete mode 100644 docs/index.html
 delete mode 100644 docs/package.json

diff --git a/docs/.nojekyll b/docs/.nojekyll
deleted file mode 100644
index e69de29bb2d..00000000000
diff --git a/docs/CNAME b/docs/CNAME
deleted file mode 100644
index 27d813e57f9..00000000000
--- a/docs/CNAME
+++ /dev/null
@@ -1 +0,0 @@
-undici.nodejs.org
\ No newline at end of file
diff --git a/docs/README.md b/docs/README.md
deleted file mode 120000
index 32d46ee883b..00000000000
--- a/docs/README.md
+++ /dev/null
@@ -1 +0,0 @@
-../README.md
\ No newline at end of file
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 00000000000..8fc0bc486fa
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,114 @@
+# Documentation source
+
+This directory holds the source for undici's documentation site. The Markdown
+files here are built by [doc-kit][] (the same tooling Node.js core uses) into the
+published site.
+
+Most of the directory is plain Markdown (`index.md`, `getting-started.md`,
+`api/*.md`, `best-practices/*.md`). Two JSON files control how that Markdown is
+turned into a navigable, cross-linked site:
+
+- [`site.json`](./site.json) — the sidebar / navigation structure.
+- [`type-map.json`](./type-map.json) — resolves `{Type}` annotations into links.
+
+## `site.json`
+
+`site.json` defines the documentation sidebar. doc-kit reads it to render the
+left-hand navigation; pages are **not** auto-discovered, so a Markdown file only
+appears in the sidebar once it is listed here.
+
+The file has a single top-level `sidebar` array. Each entry is a group:
+
+```json
+{
+  "sidebar": [
+    {
+      "groupName": "Documentation",
+      "items": [
+        { "link": "/", "label": "Home" },
+        { "link": "/getting-started", "label": "Getting Started" }
+      ]
+    }
+  ]
+}
+```
+
+### Fields
+
+- `groupName` — the heading shown above a top-level section of the sidebar.
+- `items` — the entries within a group. An item is one of:
+  - **A link**: `{ "link": "/api/Client", "label": "Client" }`
+    - `link` — a site-relative path. It maps to the Markdown file of the same
+      name without the `.md` extension. `/` is `index.md`,
+      `/getting-started` is `getting-started.md`, and `/api/Client` is
+      `api/Client.md`.
+    - `label` — the text displayed in the sidebar.
+  - **A nested group**: `{ "label": "Core", "items": [ ... ] }`
+    - `label` — the collapsible sub-heading.
+    - `items` — a further list of links (or groups). This is how the `API`
+      group is split into `Core`, `Proxy & Agents`, `Web Standards`, and so on.
+
+### Adding a page to the sidebar
+
+1. Create the Markdown file (for example `api/MyFeature.md`).
+2. Add an item under the appropriate group in `site.json`:
+   ```json
+   { "link": "/api/MyFeature", "label": "My Feature" }
+   ```
+
+Order within a group is significant — items appear in the sidebar in the order
+they are listed.
+
+## `type-map.json`
+
+Throughout the API docs, types are written in curly braces — for example
+`{Dispatcher}`, `{AgentOptions}`, or `{Buffer}`:
+
+```markdown
+* `options` {AgentOptions} (optional) Extends {PoolOptions}.
+  * Returns: {Dispatcher}
+```
+
+This is the Node.js documentation convention for annotating the type of a
+parameter, option, or return value. `type-map.json` tells doc-kit what each of
+those type names should link to, so `{Dispatcher}` in any page becomes a link to
+the `Dispatcher` documentation.
+
+The file is a flat object mapping a **type name** to a **URL**:
+
+```json
+{
+  "Agent": "/api/Agent.md#class-agent",
+  "AgentOptions": "/api/Agent.md#new-agentoptions",
+  "Buffer": "https://nodejs.org/api/buffer.html#class-buffer"
+}
+```
+
+### Link targets
+
+Targets are either internal or external:
+
+- **Internal** — a site-relative path into our own docs, usually with an anchor
+  pointing at a specific heading: `/api/Agent.md#class-agent`. The anchor is the
+  GitHub-style slug of the heading text (lowercased, spaces and punctuation
+  replaced with hyphens). For example the heading `### new Agent([options])`
+  becomes the anchor `#new-agentoptions`.
+- **External** — a full URL to upstream documentation for types we don't define
+  ourselves, such as Node.js built-ins ([`Buffer`][], [`Readable`][]) or web
+  platform types on MDN (`HeadersInit`, `Iterable`).
+
+### Adding or updating a type
+
+When you document a new type, or reference an existing one in `{...}` form, add
+an entry so the annotation resolves to a link:
+
+1. Pick the type name exactly as it appears between the braces in the Markdown
+   (the key is matched verbatim — `MockInterceptor.Options` and `net.Socket`
+   are valid keys).
+2. Add `"TypeName": "<target>"` to `type-map.json`, pointing at the heading that
+   documents it (internal) or its upstream reference (external).
+
+If a `{Type}` annotation has no matching key, it renders as plain text instead
+of a link, so keep this file in sync when headings are renamed or pages move.
+
+[doc-kit]: https://github.com/nodejs/doc-kit
diff --git a/docs/docs/api/Agent.md b/docs/docs/api/Agent.md
index e4c73cb9a14..0c59b6eac56 100644
--- a/docs/docs/api/Agent.md
+++ b/docs/docs/api/Agent.md
@@ -1,87 +1,291 @@
 # Agent
 
-Extends: `undici.Dispatcher`
+<!--introduced_in=v3.2.0-->
+<!--type=module-->
+<!-- source_link=lib/dispatcher/agent.js -->
+
+> Stability: 2 - Stable
+
+An `Agent` dispatches requests against multiple different origins, creating and
+reusing a per-origin [`Pool`][] (or [`Client`][]) on demand. It is the default
+dispatcher used by [`request`][], [`stream`][], and [`fetch`][] when no explicit
+dispatcher is supplied.
+
+Requests are not guaranteed to be dispatched in their order of invocation.
+
+```mjs
+import { Agent, setGlobalDispatcher } from 'undici'
+
+const agent = new Agent({ connections: 10 })
+setGlobalDispatcher(agent)
+```
+
+## Class: `Agent`
+
+<!-- YAML
+added: v3.2.0
+-->
+
+* Extends: {Dispatcher}
+
+`Agent` keeps an internal map of origins to dispatchers. The first request to a
+given origin lazily creates a dispatcher through the configured `factory`, and
+subsequent requests to the same origin reuse it. Idle dispatchers are closed
+automatically once they have no open connections and are no longer busy.
+
+### `new Agent([options])`
+
+<!-- YAML
+added: v3.2.0
+changes:
+  - version: v7.16.0
+    pr-url: https://github.com/nodejs/undici/pull/4365
+    description: Added the `maxOrigins` option to cap the number of origins.
+-->
+
+* `options` {AgentOptions} (optional) Extends {PoolOptions}.
+  * `factory` {Function} Builds the dispatcher used for a given origin. When the
+    resolved options contain `connections: 1`, the default factory creates a
+    {Client}; otherwise it creates a {Pool}. **Default:** `(origin, opts) => new Pool(origin, opts)`.
+    * `origin` {URL|string} The origin to create a dispatcher for.
+    * `opts` {Object} The resolved options for the new dispatcher.
+    * Returns: {Dispatcher}
+  * `maxOrigins` {number} Limits the total number of distinct origins that may
+    receive requests at the same time. A {MaxOriginsReachedError} is thrown when
+    a request targets a new origin once the limit is reached. When set to
+    `Infinity`, no limit is enforced. Must be a number greater than `0`.
+    **Default:** `Infinity`.
+
+`Agent` inherits all {PoolOptions} (and therefore all {ClientOptions}). The
+per-origin {Pool} it creates uses the default unlimited `connections`, so
+concurrent requests to the same origin are spread across separate {Client}
+instances on separate sockets.
 
-Agent allows dispatching requests against multiple different origins.
+> [!NOTE]
+> Because each concurrent request to an origin may use a different {Client},
+> HTTP/2 multiplexing on a shared session does not apply unless `connections` is
+> set to a small value (for example `connections: 1`). See {PoolOptions} and
+> {ClientOptions} for the full set of inherited options such as `allowH2`
+> (default `true`) and `maxConcurrentStreams` (default `100`).
 
-Requests are not guaranteed to be dispatched in order of invocation.
+### `agent.closed`
 
-## `new undici.Agent([options])`
+<!-- YAML
+added: v3.2.0
+-->
 
-Arguments:
+* Type: {boolean}
 
-* **options** `AgentOptions` (optional)
+`true` after [`agent.close()`][] has been called.
 
-Returns: `Agent`
+### `agent.destroyed`
 
-### Parameter: `AgentOptions`
+<!-- YAML
+added: v3.2.0
+-->
 
-Extends: [`PoolOptions`](/docs/docs/api/Pool.md#parameter-pooloptions)
+* Type: {boolean}
 
-* **factory** `(origin: URL, opts: Object) => Dispatcher` - Default: `(origin, opts) => new Pool(origin, opts)`
-* **maxOrigins** `number` (optional) - Default: `Infinity` - Limits the total number of origins that can receive requests at a time, throwing an `MaxOriginsReachedError` error when attempting to dispatch when the max is reached. If `Infinity`, no limit is enforced.
+`true` after [`agent.destroy()`][] has been called, or after [`agent.close()`][]
+has been called and the shutdown has completed.
 
-> [!NOTE]
-> Like `Pool`, `Agent` inherits all [`ClientOptions`](/docs/docs/api/Client.md#parameter-clientoptions). `allowH2` defaults to `true` and `maxConcurrentStreams` to `100`. The per-origin `Pool` it creates uses the default unlimited `connections`, so concurrent requests to the same origin land on separate `Client` instances and separate TCP/TLS sockets — HTTP/2 multiplexing on a shared session does not apply unless `connections` is set to a small value. See [`PoolOptions`](/docs/docs/api/Pool.md#parameter-pooloptions).
+### `agent.stats`
+
+<!-- YAML
+added: v7.9.0
+-->
+
+* Type: {Record<string, ClientStats|PoolStats>}
+
+Aggregate statistics for the agent, keyed by origin. Each value is the
+[`ClientStats`][] or [`PoolStats`][] object reported by the dispatcher currently
+serving that origin. Origins whose dispatcher does not expose `stats` are
+omitted.
+
+```mjs
+import { Agent } from 'undici'
+
+const agent = new Agent()
+await agent.request({ origin: 'http://localhost:3000', path: '/', method: 'GET' })
+console.log(agent.stats)
+// { 'http://localhost:3000': PoolStats { ... } }
+```
+
+### `agent.dispatch(options, handler)`
+
+<!-- YAML
+added: v3.2.0
+-->
+
+* `options` {AgentDispatchOptions} Extends {DispatchOptions}.
+  * `origin` {string|URL} The origin to dispatch the request against. Required.
+* `handler` {DispatchHandler}
+* Returns: {boolean} `false` if the dispatcher is busy and the caller should
+  wait for the [`'drain'`][] event before dispatching again.
+
+Routes the request to the dispatcher for `options.origin`, creating one through
+the `factory` if needed. Throws an {InvalidArgumentError} when `options.origin`
+is not a non-empty string or {URL}, and a {MaxOriginsReachedError} when a new
+origin would exceed `maxOrigins`. Implements [`Dispatcher.dispatch()`][].
+
+### `agent.close([callback])`
+
+<!-- YAML
+added: v3.2.0
+-->
+
+* `callback` {Function} (optional) Invoked once every per-origin dispatcher has
+  closed. When omitted, a {Promise} is returned.
+* Returns: {Promise|void}
+
+Gracefully closes the agent and every dispatcher it owns, waiting for in-flight
+requests to complete. Implements [`Dispatcher.close()`][].
+
+### `agent.destroy([error[, callback]])`
+
+<!-- YAML
+added: v3.2.0
+-->
+
+* `error` {Error} (optional) The error to abort pending requests with.
+* `callback` {Function} (optional) Invoked once every per-origin dispatcher has
+  been destroyed. When omitted, a {Promise} is returned.
+* Returns: {Promise|void}
+
+Forcefully destroys the agent and every dispatcher it owns, aborting all pending
+requests. Implements [`Dispatcher.destroy()`][].
+
+### `agent.connect(options[, callback])`
+
+<!-- YAML
+added: v3.2.0
+-->
+
+See [`Dispatcher.connect()`][]. The request is routed to the dispatcher for
+`options.origin`.
+
+### `agent.pipeline(options, handler)`
 
-## Instance Properties
+<!-- YAML
+added: v3.2.0
+-->
 
-### `Agent.closed`
+See [`Dispatcher.pipeline()`][]. The request is routed to the dispatcher for
+`options.origin`.
 
-Implements [Client.closed](/docs/docs/api/Client.md#clientclosed)
+### `agent.request(options[, callback])`
 
-### `Agent.destroyed`
+<!-- YAML
+added: v3.2.0
+-->
 
-Implements [Client.destroyed](/docs/docs/api/Client.md#clientdestroyed)
+See [`Dispatcher.request()`][]. The request is routed to the dispatcher for
+`options.origin`.
 
-## Instance Methods
+```mjs
+import { Agent } from 'undici'
 
-### `Agent.close([callback])`
+const agent = new Agent()
+const { statusCode, body } = await agent.request({
+  origin: 'http://localhost:3000',
+  path: '/',
+  method: 'GET',
+})
 
-Implements [`Dispatcher.close([callback])`](/docs/docs/api/Dispatcher.md#dispatcherclosecallback-promise).
+console.log('response received', statusCode)
+console.log('data', await body.text())
+```
 
-### `Agent.destroy([error, callback])`
+### `agent.stream(options, factory[, callback])`
 
-Implements [`Dispatcher.destroy([error, callback])`](/docs/docs/api/Dispatcher.md#dispatcherdestroyerror-callback-promise).
+<!-- YAML
+added: v3.2.0
+-->
 
-### `Agent.dispatch(options, handler: AgentDispatchOptions)`
+See [`Dispatcher.stream()`][]. The request is routed to the dispatcher for
+`options.origin`.
 
-Implements [`Dispatcher.dispatch(options, handler)`](/docs/docs/api/Dispatcher.md#dispatcherdispatchoptions-handler).
+### `agent.upgrade(options[, callback])`
 
-#### Parameter: `AgentDispatchOptions`
+<!-- YAML
+added: v3.2.0
+-->
 
-Extends: [`DispatchOptions`](/docs/docs/api/Dispatcher.md#parameter-dispatchoptions)
+See [`Dispatcher.upgrade()`][]. The request is routed to the dispatcher for
+`options.origin`.
 
-* **origin** `string | URL`
+### Event: `'connect'`
 
-Implements [`Dispatcher.destroy([error, callback])`](/docs/docs/api/Dispatcher.md#dispatcherdestroyerror-callback-promise).
+<!-- YAML
+added: v6.6.0
+-->
 
-### `Agent.connect(options[, callback])`
+* `origin` {URL}
+* `targets` {Array<Dispatcher>} The dispatchers involved, starting with this
+  `Agent` followed by the per-origin dispatcher chain.
 
-See [`Dispatcher.connect(options[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherconnectoptions-callback).
+Emitted when a socket has been created for an origin and is ready to receive
+requests. Forwarded from the underlying dispatcher's [`'connect'`][] event.
 
-### `Agent.dispatch(options, handler)`
+### Event: `'disconnect'`
 
-Implements [`Dispatcher.dispatch(options, handler)`](/docs/docs/api/Dispatcher.md#dispatcherdispatchoptions-handler).
+<!-- YAML
+added: v6.6.0
+-->
 
-### `Agent.pipeline(options, handler)`
+* `origin` {URL}
+* `targets` {Array<Dispatcher>} The dispatchers involved, starting with this
+  `Agent`.
+* `error` {Error}
 
-See [`Dispatcher.pipeline(options, handler)`](/docs/docs/api/Dispatcher.md#dispatcherpipelineoptions-handler).
+Emitted when a socket for an origin has disconnected. Forwarded from the
+underlying dispatcher's [`'disconnect'`][] event.
 
-### `Agent.request(options[, callback])`
+### Event: `'connectionError'`
 
-See [`Dispatcher.request(options [, callback])`](/docs/docs/api/Dispatcher.md#dispatcherrequestoptions-callback).
+<!-- YAML
+added: v6.6.0
+-->
 
-### `Agent.stream(options, factory[, callback])`
+* `origin` {URL}
+* `targets` {Array<Dispatcher>} The dispatchers involved, starting with this
+  `Agent`.
+* `error` {Error}
 
-See [`Dispatcher.stream(options, factory[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherstreamoptions-factory-callback).
+Emitted when a connection attempt for an origin fails. Forwarded from the
+underlying dispatcher's [`'connectionError'`][] event.
 
-### `Agent.upgrade(options[, callback])`
+### Event: `'drain'`
 
-See [`Dispatcher.upgrade(options[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherupgradeoptions-callback).
+<!-- YAML
+added: v6.6.0
+-->
 
-### `Agent.stats()`
+* `origin` {URL}
+* `targets` {Array<Dispatcher>} The dispatchers involved, starting with this
+  `Agent`.
 
-Returns an object of stats by origin in the format of `Record<string, TClientStats | TPoolStats>`
+Emitted when an origin's dispatcher is no longer busy and can accept more
+requests. Forwarded from the underlying dispatcher's [`'drain'`][] event.
 
-See [`PoolStats`](/docs/docs/api/PoolStats.md) and [`ClientStats`](/docs/docs/api/ClientStats.md).
+[`'connect'`]: Dispatcher.md#event-connect
+[`'connectionError'`]: Dispatcher.md#event-connectionerror
+[`'disconnect'`]: Dispatcher.md#event-disconnect
+[`'drain'`]: Dispatcher.md#event-drain
+[`Client`]: Client.md#class-client
+[`ClientStats`]: ClientStats.md
+[`Dispatcher.close()`]: Dispatcher.md#dispatcherclosecallback-promise
+[`Dispatcher.connect()`]: Dispatcher.md#dispatcherconnectoptions-callback
+[`Dispatcher.destroy()`]: Dispatcher.md#dispatcherdestroyerror-callback-promise
+[`Dispatcher.dispatch()`]: Dispatcher.md#dispatcherdispatchoptions-handler
+[`Dispatcher.pipeline()`]: Dispatcher.md#dispatcherpipelineoptions-handler
+[`Dispatcher.request()`]: Dispatcher.md#dispatcherrequestoptions-callback
+[`Dispatcher.stream()`]: Dispatcher.md#dispatcherstreamoptions-factory-callback
+[`Dispatcher.upgrade()`]: Dispatcher.md#dispatcherupgradeoptions-callback
+[`Pool`]: Pool.md#class-pool
+[`PoolStats`]: PoolStats.md
+[`agent.close()`]: #agentclosecallback
+[`agent.destroy()`]: #agentdestroyerror-callback
+[`fetch`]: Fetch.md
+[`request`]: Dispatcher.md#dispatcherrequestoptions-callback
+[`stream`]: Dispatcher.md#dispatcherstreamoptions-factory-callback
diff --git a/docs/docs/api/BalancedPool.md b/docs/docs/api/BalancedPool.md
index 6d80317af78..77cd0a819b6 100644
--- a/docs/docs/api/BalancedPool.md
+++ b/docs/docs/api/BalancedPool.md
@@ -1,99 +1,297 @@
-# Class: BalancedPool
+# BalancedPool
 
-Extends: `undici.Dispatcher`
+<!--introduced_in=v4.8.0-->
+<!--type=module-->
+<!-- source_link=lib/dispatcher/balanced-pool.js -->
 
-A pool of [Pool](/docs/docs/api/Pool.md) instances connected to multiple upstreams.
+> Stability: 2 - Stable
 
-Requests are not guaranteed to be dispatched in order of invocation.
+A `BalancedPool` distributes requests across a set of {Pool} instances, each
+connected to a different upstream. It uses a weighted round-robin algorithm:
+every upstream starts with the same weight, and the weight is adjusted up on
+successful connections and down on connection errors, so that healthy upstreams
+receive a larger share of traffic.
 
-## `new BalancedPool(upstreams [, options])`
+Requests are not guaranteed to be dispatched in the order they are issued.
 
-Arguments:
+```mjs
+import { BalancedPool } from 'undici'
 
-* **upstreams** `URL | string | string[]` - It should only include the **protocol, hostname, and port**.
-* **options** `BalancedPoolOptions` (optional)
+const pool = new BalancedPool([
+  'http://localhost:3000',
+  'http://localhost:3001',
+  'http://localhost:3002',
+])
 
-### Parameter: `BalancedPoolOptions`
+const { statusCode, body } = await pool.request({
+  path: '/',
+  method: 'GET',
+})
+console.log('response received', statusCode)
+for await (const chunk of body) {
+  console.log('data', chunk.toString())
+}
+```
 
-Extends: [`PoolOptions`](/docs/docs/api/Pool.md#parameter-pooloptions)
+## Class: `BalancedPool`
 
-* **factory** `(origin: URL, opts: Object) => Dispatcher` - Default: `(origin, opts) => new Pool(origin, opts)`
+<!-- YAML
+added: v4.8.0
+changes:
+  - version: v4.10.4
+    pr-url: https://github.com/nodejs/undici/pull/1114
+    description: Introduced the `BalancedPool` class.
+-->
 
-The `PoolOptions` are passed to each of the `Pool` instances being created.
-## Instance Properties
+* Extends: {Dispatcher}
 
-### `BalancedPool.upstreams`
+A pool of {Pool} instances connected to multiple upstreams.
 
-Returns an array of upstreams that were previously added.
+### `new BalancedPool(upstreams[, options])`
 
-### `BalancedPool.closed`
+<!-- YAML
+added: v4.8.0
+changes:
+  - version: v4.15.0
+    pr-url: https://github.com/nodejs/undici/pull/1237
+    description: Added the `factory` option.
+-->
 
-Implements [Client.closed](/docs/docs/api/Client.md#clientclosed)
+* `upstreams` {URL|string|URL[]|string[]} One or more upstream origins. Each
+  value should only include the **protocol, hostname, and port**. **Default:**
+  `[]`.
+* `options` {BalancedPoolOptions} (optional)
 
-### `BalancedPool.destroyed`
+The options passed to the constructor are forwarded to every {Pool} instance
+that is created for an upstream.
 
-Implements [Client.destroyed](/docs/docs/api/Client.md#clientdestroyed)
+#### Parameter: `BalancedPoolOptions`
 
-### `BalancedPool.stats`
+Extends: {PoolOptions}
 
-Returns [`PoolStats`](/docs/docs/api/PoolStats.md) instance for this pool.
+In addition to all {PoolOptions}, the following options are supported:
 
-## Instance Methods
+* `factory` {Function} A function used to create the {Pool} instance for each
+  upstream. **Default:** `(origin, opts) => new Pool(origin, opts)`.
+  * `origin` {URL|string} The upstream origin.
+  * `opts` {Object} The options object derived from the constructor options.
+  * Returns: {Dispatcher}
+* `maxWeightPerServer` {number} The maximum weight any single upstream can
+  reach. Successful connections increase an upstream's weight up to this value.
+  **Default:** `100`.
+* `errorPenalty` {number} The amount by which an upstream's weight is decreased
+  on a connection error and increased on a successful connection. **Default:**
+  `15`.
 
-### `BalancedPool.addUpstream(upstream)`
+### `balancedPool.addUpstream(upstream)`
 
-Add an upstream.
+<!-- YAML
+added: v4.8.0
+-->
 
-Arguments:
+* `upstream` {URL|string} The upstream origin to add. It should only include the
+  **protocol, hostname, and port**.
+* Returns: {BalancedPool} The `BalancedPool` instance, for chaining.
 
-* **upstream** `string` - It should only include the **protocol, hostname, and port**.
+Adds an upstream. If an open, non-destroyed upstream with the same origin is
+already present, the call is a no-op.
 
-### `BalancedPool.removeUpstream(upstream)`
+### `balancedPool.removeUpstream(upstream)`
 
-Removes an upstream that was previously added.
+<!-- YAML
+added: v4.8.0
+-->
 
-### `BalancedPool.close([callback])`
+* `upstream` {URL|string} The upstream origin to remove. It should only include
+  the **protocol, hostname, and port**.
+* Returns: {BalancedPool} The `BalancedPool` instance, for chaining.
 
-Implements [`Dispatcher.close([callback])`](/docs/docs/api/Dispatcher.md#dispatcherclosecallback-promise).
+Removes an upstream that was previously added. If no matching upstream is found,
+the call is a no-op.
 
-### `BalancedPool.destroy([error, callback])`
+### `balancedPool.getUpstream(upstream)`
 
-Implements [`Dispatcher.destroy([error, callback])`](/docs/docs/api/Dispatcher.md#dispatcherdestroyerror-callback-promise).
+<!-- YAML
+added: v7.17.0
+-->
 
-### `BalancedPool.connect(options[, callback])`
+* `upstream` {URL|string} The upstream origin to look up. It should only include
+  the **protocol, hostname, and port**.
+* Returns: {Pool|undefined} The {Pool} instance managing the given upstream, or
+  `undefined` if it is not present.
 
-See [`Dispatcher.connect(options[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherconnectoptions-callback).
+Returns the {Pool} instance for the given upstream origin, if it is open and not
+destroyed.
 
-### `BalancedPool.dispatch(options, handlers)`
+### `balancedPool.upstreams`
 
-Implements [`Dispatcher.dispatch(options, handlers)`](/docs/docs/api/Dispatcher.md#dispatcherdispatchoptions-handler).
+<!-- YAML
+added: v4.8.0
+-->
 
-### `BalancedPool.pipeline(options, handler)`
+* Type: {string[]} The origins of the upstreams that are currently open and not
+  destroyed.
 
-See [`Dispatcher.pipeline(options, handler)`](/docs/docs/api/Dispatcher.md#dispatcherpipelineoptions-handler).
+### `balancedPool.closed`
 
-### `BalancedPool.request(options[, callback])`
+<!-- YAML
+added: v4.8.0
+changes:
+  - version: v4.10.4
+    pr-url: https://github.com/nodejs/undici/pull/1114
+    description: Introduced the `BalancedPool` class.
+-->
 
-See [`Dispatcher.request(options [, callback])`](/docs/docs/api/Dispatcher.md#dispatcherrequestoptions-callback).
+* Type: {boolean} `true` after `balancedPool.close()` has been called.
 
-### `BalancedPool.stream(options, factory[, callback])`
+Implements [`client.closed`][].
 
-See [`Dispatcher.stream(options, factory[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherstreamoptions-factory-callback).
+### `balancedPool.destroyed`
 
-### `BalancedPool.upgrade(options[, callback])`
+<!-- YAML
+added: v4.8.0
+changes:
+  - version: v4.10.4
+    pr-url: https://github.com/nodejs/undici/pull/1114
+    description: Introduced the `BalancedPool` class.
+-->
 
-See [`Dispatcher.upgrade(options[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherupgradeoptions-callback).
+* Type: {boolean} `true` after `balancedPool.destroy()` has been called, or after
+  `balancedPool.close()` has been called and the shutdown has completed.
 
-## Instance Events
+Implements [`client.destroyed`][].
+
+### `balancedPool.stats`
+
+<!-- YAML
+added: v4.8.0
+-->
+
+* Type: {PoolStats}
+
+Returns a {PoolStats} instance aggregating the statistics of the underlying
+pools.
+
+### `balancedPool.close([callback])`
+
+<!-- YAML
+added: v4.8.0
+-->
+
+Implements [`Dispatcher.close([callback])`][].
+
+### `balancedPool.destroy([error[, callback]])`
+
+<!-- YAML
+added: v4.8.0
+-->
+
+Implements [`Dispatcher.destroy([error, callback])`][].
+
+### `balancedPool.connect(options[, callback])`
+
+<!-- YAML
+added: v4.8.0
+-->
+
+See [`Dispatcher.connect(options[, callback])`][].
+
+### `balancedPool.dispatch(options, handlers)`
+
+<!-- YAML
+added: v4.8.0
+changes:
+  - version: v4.10.4
+    pr-url: https://github.com/nodejs/undici/pull/1114
+    description: Introduced the `BalancedPool` class.
+-->
+
+Implements [`Dispatcher.dispatch(options, handler)`][].
+
+### `balancedPool.pipeline(options, handler)`
+
+<!-- YAML
+added: v4.8.0
+-->
+
+See [`Dispatcher.pipeline(options, handler)`][].
+
+### `balancedPool.request(options[, callback])`
+
+<!-- YAML
+added: v4.8.0
+-->
+
+See [`Dispatcher.request(options[, callback])`][].
+
+### `balancedPool.stream(options, factory[, callback])`
+
+<!-- YAML
+added: v4.8.0
+-->
+
+See [`Dispatcher.stream(options, factory[, callback])`][].
+
+### `balancedPool.upgrade(options[, callback])`
+
+<!-- YAML
+added: v4.8.0
+-->
+
+See [`Dispatcher.upgrade(options[, callback])`][].
 
 ### Event: `'connect'`
 
-See [Dispatcher Event: `'connect'`](/docs/docs/api/Dispatcher.md#event-connect).
+<!-- YAML
+added: v4.8.0
+changes:
+  - version: v4.10.4
+    pr-url: https://github.com/nodejs/undici/pull/1114
+    description: Introduced the `BalancedPool` class.
+  - version: v5.8.0
+    pr-url: https://github.com/nodejs/undici/pull/1069
+    description: Adopted weighted round-robin selection across upstreams.
+-->
+
+See [Dispatcher Event: `'connect'`][].
 
 ### Event: `'disconnect'`
 
-See [Dispatcher Event: `'disconnect'`](/docs/docs/api/Dispatcher.md#event-disconnect).
+<!-- YAML
+added: v4.8.0
+changes:
+  - version: v4.10.4
+    pr-url: https://github.com/nodejs/undici/pull/1114
+    description: Introduced the `BalancedPool` class.
+  - version: v5.8.0
+    pr-url: https://github.com/nodejs/undici/pull/1069
+    description: Adopted weighted round-robin selection across upstreams.
+-->
+
+See [Dispatcher Event: `'disconnect'`][].
 
 ### Event: `'drain'`
 
-See [Dispatcher Event: `'drain'`](/docs/docs/api/Dispatcher.md#event-drain).
+<!-- YAML
+added: v4.8.0
+changes:
+  - version: v4.10.4
+    pr-url: https://github.com/nodejs/undici/pull/1114
+    description: Introduced the `BalancedPool` class.
+-->
+
+See [Dispatcher Event: `'drain'`][].
+
+[Dispatcher Event: `'connect'`]: Dispatcher.md#event-connect
+[Dispatcher Event: `'disconnect'`]: Dispatcher.md#event-disconnect
+[Dispatcher Event: `'drain'`]: Dispatcher.md#event-drain
+[`Dispatcher.close([callback])`]: Dispatcher.md#dispatcherclosecallback-promise
+[`Dispatcher.connect(options[, callback])`]: Dispatcher.md#dispatcherconnectoptions-callback
+[`Dispatcher.destroy([error, callback])`]: Dispatcher.md#dispatcherdestroyerror-callback-promise
+[`Dispatcher.dispatch(options, handler)`]: Dispatcher.md#dispatcherdispatchoptions-handler
+[`Dispatcher.pipeline(options, handler)`]: Dispatcher.md#dispatcherpipelineoptions-handler
+[`Dispatcher.request(options[, callback])`]: Dispatcher.md#dispatcherrequestoptions-callback
+[`Dispatcher.stream(options, factory[, callback])`]: Dispatcher.md#dispatcherstreamoptions-factory-callback
+[`Dispatcher.upgrade(options[, callback])`]: Dispatcher.md#dispatcherupgradeoptions-callback
+[`client.closed`]: Client.md#clientclosed
+[`client.destroyed`]: Client.md#clientdestroyed
diff --git a/docs/docs/api/CacheStorage.md b/docs/docs/api/CacheStorage.md
index 08ee99fab14..49d84bcd2de 100644
--- a/docs/docs/api/CacheStorage.md
+++ b/docs/docs/api/CacheStorage.md
@@ -1,30 +1,188 @@
 # CacheStorage
 
-Undici exposes a W3C spec-compliant implementation of [CacheStorage](https://developer.mozilla.org/en-US/docs/Web/API/CacheStorage) and [Cache](https://developer.mozilla.org/en-US/docs/Web/API/Cache).
+<!--introduced_in=v5.22.1-->
+<!--type=module-->
+<!-- source_link=lib/web/cache/cachestorage.js -->
 
-## Opening a Cache
+> Stability: 2 - Stable
 
-Undici exports a top-level CacheStorage instance. You can open a new Cache, or duplicate a Cache with an existing name, by using `CacheStorage.prototype.open`. If you open a Cache with the same name as an already-existing Cache, its list of cached Responses will be shared between both instances.
+undici provides a spec-compliant implementation of the [W3C Service Worker
+`CacheStorage`][] and [`Cache`][] interfaces. A `CacheStorage` is a named
+collection of [`Cache`][] objects, each of which stores `Request`/`Response`
+pairs.
+
+The class itself is not exported; instead, undici exposes a single shared
+`CacheStorage` instance named `caches`. Import it from `'undici'`:
+
+```mjs
+import { caches } from 'undici'
+
+const cache = await caches.open('v1')
+```
+
+```cjs
+const { caches } = require('undici')
+
+caches.open('v1').then((cache) => {
+  // ...
+})
+```
+
+## `caches`
+
+<!-- YAML
+added: v5.22.1
+-->
+
+* Type: {CacheStorage}
+
+The shared [`CacheStorage`](#class-cachestorage) instance exported by undici.
+All caches opened through `caches` live for the lifetime of the process.
+
+```mjs
+import { caches } from 'undici'
+
+await caches.open('v1')
+console.log(await caches.keys()) // ['v1']
+```
+
+## Class: `CacheStorage`
+
+<!-- YAML
+added: v5.22.1
+-->
+
+Represents the storage for [`Cache`][] objects. Each `CacheStorage` keeps a
+mapping of cache names to their backing list of cached responses.
+
+The constructor is not public: attempting to instantiate `CacheStorage`
+directly throws a `TypeError`. Use the exported [`caches`](#caches) instance
+instead.
+
+### `caches.match(request[, options])`
+
+<!-- YAML
+added: v5.22.1
+-->
+
+* `request` {Request|string} The request to match against. A string is treated
+  as a URL.
+* `options` {Object} (optional)
+  * `ignoreSearch` {boolean} When `true`, ignores the query string of the URL
+    when matching. **Default:** `false`.
+  * `ignoreMethod` {boolean} When `true`, prevents matching operations from
+    validating the `Request` `http` method. **Default:** `false`.
+  * `ignoreVary` {boolean} When `true`, ignores the `Vary` header when matching.
+    **Default:** `false`.
+  * `cacheName` {string} When set, restricts the search to the cache with this
+    name. **Default:** `undefined`.
+* Returns: {Promise} Fulfills with the first matching {Response}, or
+  `undefined` if no response matched.
+
+Searches the caches for a response matching `request`. When `options.cacheName`
+is provided, only that cache is searched; otherwise every cache is searched in
+insertion order and the first match is returned.
+
+```mjs
+import { caches } from 'undici'
+
+const response = await caches.match('https://example.com/data', {
+  cacheName: 'v1'
+})
+```
+
+### `caches.has(cacheName)`
+
+<!-- YAML
+added: v5.22.1
+-->
+
+* `cacheName` {string} The name of the cache to look up.
+* Returns: {Promise} Fulfills with `true` if a cache named `cacheName` exists,
+  otherwise `false`.
+
+Checks whether a cache with the given name exists in the storage.
+
+```mjs
+import { caches } from 'undici'
+
+await caches.open('v1')
+console.log(await caches.has('v1')) // true
+console.log(await caches.has('v2')) // false
+```
+
+### `caches.open(cacheName)`
+
+<!-- YAML
+added: v5.22.1
+-->
+
+* `cacheName` {string} The name of the cache to open.
+* Returns: {Promise} Fulfills with the {Cache} named `cacheName`.
+
+Opens the cache named `cacheName`, creating it if it does not already exist.
+
+Each call returns a new [`Cache`][] object, but caches opened with the same name
+share their underlying list of cached responses. As a result, a response stored
+through one instance is visible through another instance with the same name.
 
 ```mjs
 import { caches } from 'undici'
+import assert from 'node:assert'
 
-const cache_1 = await caches.open('v1')
-const cache_2 = await caches.open('v1')
+const cache1 = await caches.open('v1')
+const cache2 = await caches.open('v1')
 
-// Although .open() creates a new instance,
-assert(cache_1 !== cache_2)
-// The same Response is matched in both.
-assert.deepStrictEqual(await cache_1.match('/req'), await cache_2.match('/req'))
+// open() returns distinct objects,
+assert(cache1 !== cache2)
+// but they share the same cached responses.
+assert.deepStrictEqual(await cache1.match('/req'), await cache2.match('/req'))
 ```
 
-## Deleting a Cache
+### `caches.delete(cacheName)`
 
-If a Cache is deleted, the cached Responses/Requests can still be used.
+<!-- YAML
+added: v5.22.1
+-->
+
+* `cacheName` {string} The name of the cache to delete.
+* Returns: {Promise} Fulfills with `true` if the cache existed and was deleted,
+  otherwise `false`.
+
+Removes the cache named `cacheName` from the storage. Any [`Cache`][] objects
+already obtained for that name, along with the `Request`/`Response` pairs they
+returned, remain usable after deletion.
 
 ```mjs
-const response = await cache_1.match('/req')
+import { caches } from 'undici'
+
+const cache = await caches.open('v1')
+const response = await cache.match('/req')
+
 await caches.delete('v1')
 
-await response.text() // the Response's body
+// The already-retrieved response is still usable.
+await response.text()
 ```
+
+### `caches.keys()`
+
+<!-- YAML
+added: v5.22.1
+-->
+
+* Returns: {Promise} Fulfills with a {string[]} of cache names in insertion
+  order.
+
+Returns the names of all caches currently held by the storage.
+
+```mjs
+import { caches } from 'undici'
+
+await caches.open('v1')
+await caches.open('v2')
+console.log(await caches.keys()) // ['v1', 'v2']
+```
+
+[W3C Service Worker `CacheStorage`]: https://w3c.github.io/ServiceWorker/#cachestorage-interface
+[`Cache`]: https://w3c.github.io/ServiceWorker/#cache-interface
diff --git a/docs/docs/api/CacheStore.md b/docs/docs/api/CacheStore.md
index 15524748ad5..3e30abd5699 100644
--- a/docs/docs/api/CacheStore.md
+++ b/docs/docs/api/CacheStore.md
@@ -1,164 +1,360 @@
 # Cache Store
 
-A Cache Store is responsible for storing and retrieving cached responses.
-It is also responsible for deciding which specific response to use based off of
-a response's `Vary` header (if present). It is expected to be compliant with
-[RFC-9111](https://www.rfc-editor.org/rfc/rfc9111.html).
+<!--introduced_in=v7.0.0-->
+<!--type=module-->
+<!-- source_link=lib/cache/memory-cache-store.js -->
 
-## Pre-built Cache Stores
+> Stability: 2 - Stable
 
-### `MemoryCacheStore`
+A cache store is the storage backend used by the cache interceptor to persist
+and retrieve cached responses. A store decides which stored response to serve
+for a request by comparing the request against the response's `Vary` header, and
+is expected to be compliant with [RFC&nbsp;9111][].
 
-The `MemoryCacheStore` stores the responses in-memory.
+undici ships two stores. `MemoryCacheStore` keeps responses in memory, while
+`SqliteCacheStore` persists them to a SQLite database. Both are available under
+the `cacheStores` export:
 
-**Options**
+```mjs
+import { cacheStores } from 'undici'
 
-- `maxSize` - The maximum total size in bytes of all stored responses. Default `104857600` (100MB).
-- `maxCount` - The maximum amount of responses to store. Default `1024`.
-- `maxEntrySize` - The maximum size in bytes that a response's body can be. If a response's body is greater than or equal to this, the response will not be cached. Default `5242880` (5MB).
+const { MemoryCacheStore, SqliteCacheStore } = cacheStores
+```
+
+`SqliteCacheStore` requires the [`node:sqlite`][] API. The class is always
+exported, but constructing one throws if `node:sqlite` is not available in the
+running Node.js version.
 
-### Getters
+A cache store implements three methods — `get(key)`, `createWriteStream(key,
+value)`, and `delete(key)` — that operate on a [`CacheKey`](#cachekey) and a
+[`CacheValue`](#cachevalue). Any object implementing this contract can be passed
+to the cache interceptor, so custom stores (for example, backed by Redis or a
+remote service) are supported as well.
 
-#### `MemoryCacheStore.size`
+## Class: `MemoryCacheStore`
 
-Returns the current total size in bytes of all stored responses.
+<!-- YAML
+added: v7.0.0
+-->
 
-### Methods
+* Extends: {EventEmitter}
 
-#### `MemoryCacheStore.isFull()`
+Stores cached responses in memory. The store enforces upper bounds on the total
+number of responses, the total size of all responses, and the size of any single
+response. When a limit is exceeded, the store evicts approximately half of its
+entries and emits a [`'maxSizeExceeded'`](#event-maxsizeexceeded) event.
 
-Returns a boolean indicating whether the cache has reached its maximum size or count.
+```mjs
+import { interceptors, cacheStores, Agent, setGlobalDispatcher } from 'undici'
 
-### Events
+const store = new cacheStores.MemoryCacheStore({ maxSize: 50 * 1024 * 1024 })
+
+setGlobalDispatcher(
+  new Agent().compose(interceptors.cache({ store }))
+)
+```
 
-#### `'maxSizeExceeded'`
+### `new MemoryCacheStore([options])`
 
-Emitted when the cache exceeds its maximum size or count limits. The event payload contains `size`, `maxSize`, `count`, and `maxCount` properties.
+<!-- YAML
+added: v7.0.0
+-->
 
+* `options` {Object} (optional)
+  * `maxCount` {number} The maximum number of responses to store. **Default:**
+    `1024`.
+  * `maxSize` {number} The maximum total size, in bytes, of all stored
+    responses. **Default:** `104857600` (100 MiB).
+  * `maxEntrySize` {number} The maximum size, in bytes, of a single response
+    body. Responses whose body exceeds this value are not cached. **Default:**
+    `5242880` (5 MiB).
+  * `errorCallback` {Function} A callback invoked with any error raised by the
+    store. (optional)
+    * `err` {Error}
 
-### `SqliteCacheStore`
+Each of `maxCount`, `maxSize`, and `maxEntrySize` must be a non-negative
+integer; a `TypeError` is thrown otherwise.
 
-The `SqliteCacheStore` stores the responses in a SQLite database.
-Under the hood, it uses Node.js' [`node:sqlite`](https://nodejs.org/api/sqlite.html) api.
-The `SqliteCacheStore` is only exposed if the `node:sqlite` api is present.
+### `memoryCacheStore.size`
 
-**Options**
+<!-- YAML
+added: v7.0.0
+-->
 
-- `location` - The location of the SQLite database to use. Default `:memory:`.
-- `maxCount` - The maximum number of entries to store in the database. Default `Infinity`.
-- `maxEntrySize` - The maximum size in bytes that a response's body can be. If a response's body is greater than or equal to this, the response will not be cached. Default `Infinity`.
+* Type: {number}
 
-## Defining a Custom Cache Store
+The current total size, in bytes, of all stored response bodies.
 
-The store must implement the following functions:
+### `memoryCacheStore.isFull()`
 
-### Getter: `isFull`
+<!-- YAML
+added: v7.0.0
+-->
 
-Optional. This tells the cache interceptor if the store is full or not. If this is true,
-the cache interceptor will not attempt to cache the response.
+* Returns: {boolean} `true` when the store has reached its `maxSize` or
+  `maxCount` limit, `false` otherwise.
 
-### Function: `get`
+### `memoryCacheStore.get(key)`
 
-Parameters:
+<!-- YAML
+added: v7.0.0
+-->
 
-* **req** `Dispatcher.RequestOptions` - Incoming request
+* `key` {CacheKey} The request to look up. See [`CacheKey`](#cachekey).
+* Returns: {GetResult|undefined} The matching cached response, or `undefined`
+  when there is no fresh entry for `key`. See [`GetResult`](#getresult).
 
-Returns: `GetResult | Promise<GetResult | undefined> | undefined` - If the request is cached, the cached response is returned. If the request's method is anything other than HEAD, the response is also returned.
-If the request isn't cached, `undefined` is returned.
+Looks up a cached response for `key`. A stored entry matches only when its
+`method` equals `key.method`, its `deleteAt` time is in the future, and every
+header listed in its `vary` map matches the corresponding header in
+`key.headers`.
 
-The `get` method may return a `Promise` for async cache stores (e.g. Redis-backed or remote stores). The cache interceptor handles both synchronous and asynchronous return values, including in revalidation paths (304 Not Modified handling and stale-while-revalidate background revalidation).
+### `memoryCacheStore.createWriteStream(key, value)`
 
-Response properties:
+<!-- YAML
+added: v7.0.0
+-->
 
-* **response** `CacheValue` - The cached response data.
-* **body** `Readable | Iterable<Buffer> | undefined` - The response's body. This can be an array of `Buffer` chunks (with a `.values()` method) or a `Readable` stream. Both formats are supported in all code paths, including 304 revalidation.
+* `key` {CacheKey} The request the response is being cached for. See
+  [`CacheKey`](#cachekey).
+* `value` {CacheValue} The response metadata to store. See
+  [`CacheValue`](#cachevalue).
+* Returns: {Writable|undefined} A writable stream that the response body is
+  written to, or `undefined` when the response cannot be cached.
 
-### Function: `createWriteStream`
+Returns a {Writable} stream used to write the response body into the store. When
+the stream finishes, the entry is committed; if its accumulated size exceeds
+`maxEntrySize`, the stream is destroyed and nothing is stored. Writing a new
+entry whose `key` matches an existing one replaces that entry.
 
-Parameters:
+### `memoryCacheStore.delete(key)`
 
-* **req** `Dispatcher.RequestOptions` - Incoming request
-* **value** `CacheValue` - Response to store
+<!-- YAML
+added: v7.0.0
+-->
 
-Returns: `Writable | undefined` - If the store is full, return `undefined`. Otherwise, return a writable so that the cache interceptor can stream the body and trailers to the store.
+* `key` {CacheKey} The request whose cached responses should be removed. See
+  [`CacheKey`](#cachekey).
+* Returns: {undefined}
 
-## `CacheValue`
+Removes every cached response stored for `key.origin` and `key.path`. Throws a
+`TypeError` if `key` is not an object.
 
-This is an interface containing the majority of a response's data (minus the body).
+### Event: `'maxSizeExceeded'`
 
-### Property `statusCode`
+<!-- YAML
+added: v7.10.0
+-->
 
-`number` - The response's HTTP status code.
+* `data` {Object}
+  * `size` {number} The current total size, in bytes, of all stored responses.
+  * `maxSize` {number} The configured `maxSize` limit.
+  * `count` {number} The current number of stored responses.
+  * `maxCount` {number} The configured `maxCount` limit.
 
-### Property `statusMessage`
+Emitted when the store exceeds its `maxSize` or `maxCount` limit, immediately
+before entries are evicted. The event fires only once per overflow; it is not
+emitted again until the store drops back below both limits.
 
-`string` - The response's HTTP status message.
+## Class: `SqliteCacheStore`
 
-### Property `rawHeaders`
+<!-- YAML
+added: v7.0.0
+-->
 
-`Buffer[]` - The response's headers.
+Stores cached responses in a SQLite database using the [`node:sqlite`][] API.
+The constructor throws when [`node:sqlite`][] is not available.
 
-### Property `vary`
+```mjs
+import { interceptors, cacheStores, Agent, setGlobalDispatcher } from 'undici'
 
-`Record<string, string | string[] | null> | undefined` - The headers defined by the response's `Vary` header
-and their respective values for later comparison. Values are `null` when the
-header specified in `Vary` was not present in the original request. These `null`
-values are automatically filtered out during revalidation so they are not sent
-as request headers.
+const store = new cacheStores.SqliteCacheStore({ location: './cache.db' })
 
-For example, for a response like
+setGlobalDispatcher(
+  new Agent().compose(interceptors.cache({ store }))
+)
 ```
-Vary: content-encoding, accepts
+
+### `new SqliteCacheStore([options])`
+
+<!-- YAML
+added: v7.0.0
+-->
+
+* `options` {Object} (optional)
+  * `location` {string} The location of the SQLite database. Use `':memory:'`
+    for an in-memory database. **Default:** `':memory:'`.
+  * `maxCount` {number} The maximum number of responses to store. **Default:**
+    `Infinity`.
+  * `maxEntrySize` {number} The maximum size, in bytes, of a single response
+    body. Responses whose body exceeds this value are not cached. Must not
+    exceed `2000000000` (2 GB). **Default:** `2000000000` (2 GB).
+
+`maxCount` and `maxEntrySize` must be non-negative integers; a `TypeError` is
+thrown otherwise, or if `maxEntrySize` is greater than 2 GB.
+
+### `sqliteCacheStore.close()`
+
+<!-- YAML
+added: v7.0.0
+-->
+
+* Returns: {undefined}
+
+Closes the connection to the underlying SQLite database.
+
+### `sqliteCacheStore.size`
+
+<!-- YAML
+added: v7.0.0
+-->
+
+* Type: {number}
+
+The number of responses currently stored in the database.
+
+### `sqliteCacheStore.get(key)`
+
+<!-- YAML
+added: v7.0.0
+-->
+
+* `key` {CacheKey} The request to look up. See [`CacheKey`](#cachekey).
+* Returns: {GetResult|undefined} The matching cached response, or `undefined`
+  when there is no fresh entry for `key`. The returned `body` is a {Buffer}.
+  See [`GetResult`](#getresult).
+
+Looks up a cached response for `key`, comparing the request method and every
+header named in the stored `vary` map.
+
+### `sqliteCacheStore.set(key, value)`
+
+<!-- YAML
+added: v7.0.0
+-->
+
+* `key` {CacheKey} The request the response is being cached for. See
+  [`CacheKey`](#cachekey).
+* `value` {CacheValue} The response to store, with its `body` set to a {Buffer},
+  an {Array} of {Buffer}, or `null`. See [`CacheValue`](#cachevalue).
+* Returns: {undefined}
+
+Writes a response into the database directly, without going through a stream. If
+the body exceeds `maxEntrySize`, nothing is stored. When an entry already exists
+for `key` it is overwritten; otherwise a new row is inserted and old entries are
+pruned to honour `maxCount`. This method is used internally by
+[`sqliteCacheStore.createWriteStream()`](#sqlitecachestorecreatewritestreamkey-value).
+
+### `sqliteCacheStore.createWriteStream(key, value)`
+
+<!-- YAML
+added: v7.0.0
+-->
+
+* `key` {CacheKey} The request the response is being cached for. See
+  [`CacheKey`](#cachekey).
+* `value` {CacheValue} The response metadata to store. See
+  [`CacheValue`](#cachevalue).
+* Returns: {Writable|undefined} A writable stream that the response body is
+  written to, or `undefined` when the response cannot be cached.
+
+Returns a {Writable} stream used to write the response body into the store. When
+the stream finishes, the buffered body is committed via
+[`sqliteCacheStore.set()`](#sqlitecachestoresetkey-value). If the body exceeds
+`maxEntrySize`, the stream is destroyed and nothing is stored.
+
+### `sqliteCacheStore.delete(key)`
+
+<!-- YAML
+added: v7.0.0
+-->
+
+* `key` {CacheKey} The request whose cached responses should be removed. See
+  [`CacheKey`](#cachekey).
+* Returns: {undefined}
+
+Removes every cached response stored for the URL derived from `key.origin` and
+`key.path`. Throws a `TypeError` if `key` is not an object.
+
+## Implementing a custom cache store
+
+A cache store is any object that implements the `CacheStore` interface:
+
+* `get(key)` — Look up a response. Returns a [`GetResult`](#getresult),
+  `undefined`, or a {Promise} resolving to either.
+* `createWriteStream(key, value)` — Return a {Writable} to receive the response
+  body, or `undefined` if the response cannot be stored.
+* `delete(key)` — Remove all responses for `key`. May return a {Promise}.
+
+Returning a {Promise} from `get` or `delete` lets a store be backed by an
+asynchronous resource; the cache interceptor awaits these values, including on
+the revalidation and stale-while-revalidate paths.
+
+### `CacheKey`
+
+The request a response is being looked up or stored for.
+
+* `origin` {string} The request origin.
+* `method` {string} The request method.
+* `path` {string} The request path.
+* `headers` {Record<string, string|string[]>} The request headers, used to
+  satisfy `Vary`. (optional)
+
+### `CacheValue`
+
+The metadata of a cached response, excluding its body.
+
+* `statusCode` {number} The response's HTTP status code.
+* `statusMessage` {string} The response's HTTP status message.
+* `headers` {Record<string, string|string[]>} The response headers.
+* `vary` {Record<string, string|string[]|null>} The header names listed in the
+  response's `Vary` header mapped to the values they had in the original
+  request. A value is `null` when that header was absent from the original
+  request. (optional)
+* `etag` {string} The response's entity tag. (optional)
+* `cacheControlDirectives` {Object} The parsed `Cache-Control` directives of the
+  response. (optional)
+* `cachedAt` {number} The time, in milliseconds, at which the response was
+  cached.
+* `staleAt` {number} The time, in milliseconds, at which the response becomes
+  stale.
+* `deleteAt` {number} The time, in milliseconds, at which the response must be
+  evicted. A store must not return a response once this time has passed.
+
+The `vary` map drives response selection. For a response such as:
+
+```http
+Vary: content-encoding, accept
 content-encoding: utf8
-accepts: application/json
+accept: application/json
 ```
 
-This would be
+the recorded map is:
+
 ```js
 {
   'content-encoding': 'utf8',
-  accepts: 'application/json'
+  accept: 'application/json'
 }
 ```
 
-If the original request did not include the `accepts` header:
+If the original request did not include the `accept` header, its value is
+recorded as `null`:
+
 ```js
 {
   'content-encoding': 'utf8',
-  accepts: null
+  accept: null
 }
 ```
 
-### Property `cachedAt`
-
-`number` - Time in millis that this value was cached.
-
-### Property `staleAt`
-
-`number` - Time in millis that this value is considered stale.
-
-### Property `deleteAt`
-
-`number` - Time in millis that this value is to be deleted from the cache. This
-is either the same sa staleAt or the `max-stale` caching directive.
-
-The store must not return a response after the time defined in this property.
-
-## `CacheStoreReadable`
-
-This extends Node's [`Readable`](https://nodejs.org/api/stream.html#class-streamreadable)
-and defines extra properties relevant to the cache interceptor.
-
-### Getter: `value`
-
-The response's [`CacheStoreValue`](/docs/docs/api/CacheStore.md#cachestorevalue)
-
-## `CacheStoreWriteable`
+### `GetResult`
 
-This extends Node's [`Writable`](https://nodejs.org/api/stream.html#class-streamwritable)
-and defines extra properties relevant to the cache interceptor.
+The value returned by `get`. It contains every field of
+[`CacheValue`](#cachevalue) plus the response body.
 
-### Setter: `rawTrailers`
+* `body` {Readable|Iterable|AsyncIterable|Buffer|string} The cached response
+  body. (optional)
 
-If the response has trailers, the cache interceptor will pass them to the cache
-interceptor through this method.
+[RFC&nbsp;9111]: https://www.rfc-editor.org/rfc/rfc9111.html
+[`node:sqlite`]: https://nodejs.org/api/sqlite.html
diff --git a/docs/docs/api/Client.md b/docs/docs/api/Client.md
index 4e1a670eddc..2d1e2cf26b0 100644
--- a/docs/docs/api/Client.md
+++ b/docs/docs/api/Client.md
@@ -1,103 +1,167 @@
-# Class: Client
-
-Extends: `undici.Dispatcher`
-
-A basic HTTP/1.1 client, mapped on top a single TCP/TLS connection. Pipelining is disabled by default.
-
-Requests are not guaranteed to be dispatched in order of invocation.
-
-## `new Client(url[, options])`
-
-Arguments:
-
-* **url** `URL | string` - Should only include the **protocol, hostname, and port**.
-* **options** `ClientOptions` (optional)
-
-Returns: `Client`
-
-### Parameter: `ClientOptions`
-
-* **bodyTimeout** `number | null` (optional) - Default: `300e3` - The timeout after which a request will time out, in milliseconds. Monitors time between receiving body data. Use `0` to disable it entirely. Defaults to 300 seconds. Please note the `timeout` will be reset if you keep writing data to the socket everytime.
-* **headersTimeout** `number | null` (optional) - Default: `300e3` - The amount of time, in milliseconds, the parser will wait to receive the complete HTTP headers while not sending the request. Defaults to 300 seconds.
-* **keepAliveMaxTimeout** `number | null` (optional) - Default: `600e3` - The maximum allowed `keepAliveTimeout`, in milliseconds, when overridden by *keep-alive* hints from the server. Defaults to 10 minutes.
-* **keepAliveTimeout** `number | null` (optional) - Default: `4e3` - The timeout, in milliseconds, after which a socket without active requests will time out. Monitors time between activity on a connected socket. This value may be overridden by *keep-alive* hints from the server. See [MDN: HTTP - Headers - Keep-Alive directives](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Keep-Alive#directives) for more details. Defaults to 4 seconds.
-* **keepAliveTimeoutThreshold** `number | null` (optional) - Default: `2e3` - A number of milliseconds subtracted from server *keep-alive* hints when overriding `keepAliveTimeout` to account for timing inaccuracies caused by e.g. transport latency. Defaults to 2 seconds.
-* **maxHeaderSize** `number | null` (optional) - Default: `--max-http-header-size` or `16384` - The maximum length of request headers in bytes. Defaults to Node.js' --max-http-header-size or 16KiB.
-* **maxResponseSize** `number | null` (optional) - Default: `-1` - The maximum length of response body in bytes. Set to `-1` to disable.
-* **webSocket** `WebSocketOptions` (optional) - WebSocket-specific configuration options.
-  * **maxFragments** `number` (optional) - Default: `131072` - Maximum number of fragments in a message. Set to 0 to disable the limit.
-  * **maxPayloadSize** `number` (optional) - Default: `134217728` (128 MB) - Maximum allowed payload size in bytes for WebSocket messages. Applied to uncompressed messages, compressed frame payloads, and decompressed (permessage-deflate) messages. Set to 0 to disable the limit.
-* **pipelining** `number | null` (optional) - Default: `1` - The amount of concurrent requests to be sent over the single TCP/TLS connection according to [RFC7230](https://tools.ietf.org/html/rfc7230#section-6.3.2). Carefully consider your workload and environment before enabling concurrent requests as pipelining may reduce performance if used incorrectly. Pipelining is sensitive to network stack settings as well as head of line blocking caused by e.g. long running requests. Set to `0` to disable keep-alive connections. This option has no effect once HTTP/2 is negotiated — see `maxConcurrentStreams` for the h2 dispatch ceiling.
-* **connect** `ConnectOptions | Function | null` (optional) - Default: `null` - Configures how undici establishes TCP/TLS connections. Accepts two forms:
-  * **Object (`ConnectOptions`)**: Options passed directly to the internal [`buildConnector()`](/docs/docs/api/Connector.md). This is the simplest way to customize TLS or socket behavior (e.g., setting `rejectUnauthorized`, `ca`, `socketPath`). See [`ConnectOptions`](#parameter-connectoptions) for available fields.
-  * **Function**: A custom connector with the signature `(options, callback)`, where `options` contains `{ hostname, host, protocol, port, servername, localAddress, httpSocket }` and `callback` follows `(error, socket)`. Useful when you need full control over socket creation, such as adding custom validation or proxy logic. When a function is provided, undici wraps it to automatically inject `socketPath` and `allowH2` into the `options` argument if those values are set on the client.
-* **strictContentLength** `Boolean` (optional) - Default: `true` - Whether to treat request content length mismatches as errors. If true, an error is thrown when the request content-length header doesn't match the length of the request body. **Security Warning:** Disabling this option can expose your application to HTTP Request Smuggling attacks, where mismatched content-length headers cause servers and proxies to interpret request boundaries differently. This can lead to cache poisoning, credential hijacking, and bypassing security controls. Only disable this in controlled environments where you fully trust the request source.
-* **autoSelectFamily**: `boolean` (optional) - Default: depends on local Node version, on Node 18.13.0 and above is `false`. Enables a family autodetection algorithm that loosely implements section 5 of [RFC 8305](https://tools.ietf.org/html/rfc8305#section-5). See [here](https://nodejs.org/api/net.html#socketconnectoptions-connectlistener) for more details. This option is ignored if not supported by the current Node version.
-* **autoSelectFamilyAttemptTimeout**: `number` - Default: depends on local Node version, on Node 18.13.0 and above is `250`. The amount of time in milliseconds to wait for a connection attempt to finish before trying the next address when using the `autoSelectFamily` option. See [here](https://nodejs.org/api/net.html#socketconnectoptions-connectlistener) for more details.
-* **allowH2**: `boolean` - Default: `true`. Enables support for H2 if the server has assigned bigger priority to it through ALPN negotiation.
-* **useH2c**: `boolean` - Default: `false`. Enforces h2c for non-https connections.
-* **maxConcurrentStreams**: `number` - Default: `100`. The maximum number of concurrent HTTP/2 streams per session. When `allowH2` negotiates h2, this — not `pipelining` (which is HTTP/1.1 only, per [RFC7230](https://tools.ietf.org/html/rfc7230#section-6.3.2)) — is the ceiling the Client uses to dispatch in-flight requests on a shared session. The same value is advertised to the server as `peerMaxConcurrentStreams`, capping how many streams the server may push back. The initial value is replaced by the server's `SETTINGS_MAX_CONCURRENT_STREAMS` whenever the server sends one, so a user-supplied value acts as a pre-`SETTINGS` default rather than a hard cap.
-* **initialWindowSize**: `number` (optional) - Default: `262144` (256KB). Sets the HTTP/2 stream-level flow-control window size (SETTINGS_INITIAL_WINDOW_SIZE). Must be a positive integer greater than 0. This default is higher than Node.js core's default (65535 bytes) to improve throughput, Node's choice is very conservative for current high-bandwith networks. See [RFC 7540 Section 6.9.2](https://datatracker.ietf.org/doc/html/rfc7540#section-6.9.2) for more details.
-* **connectionWindowSize**: `number` (optional) - Default `524288` (512KB). Sets the HTTP/2 connection-level flow-control window size using `ClientHttp2Session.setLocalWindowSize()`. Must be a positive integer greater than 0. This provides better flow control for the entire connection across multiple streams. See [Node.js HTTP/2 documentation](https://nodejs.org/api/http2.html#clienthttp2sessionsetlocalwindowsize) for more details.
-* **pingInterval**: `number` - Default: `60e3`. The time interval in milliseconds between PING frames sent to the server. Set to `0` to disable PING frames. This is only applicable for HTTP/2 connections. This will emit a `ping` event on the client with the duration of the ping in milliseconds.
-
-> **Notes about HTTP/2**
-> - It only works under TLS connections. h2c is not supported.
-> - The server must support HTTP/2 and choose it as the protocol during the ALPN negotiation.
->   - The server must not have a bigger priority for HTTP/1.1 than HTTP/2.
-> - Pseudo headers are automatically attached to the request. If you try to set them, they will be overwritten.
->   - The `:path` header is automatically set to the request path.
->   - The `:method` header is automatically set to the request method.
->   - The `:scheme` header is automatically set to the request scheme.
->   - The `:authority` header is automatically set to the request `host[:port]`.
-> - `PUSH` frames are yet not supported.
-
-#### Parameter: `ConnectOptions`
-
-Every Tls option, see [here](https://nodejs.org/api/tls.html#tls_tls_connect_options_callback).
-Furthermore, the following options can be passed:
-
-* **socketPath** `string | null` (optional) - Default: `null` - An IPC endpoint, either Unix domain socket or Windows named pipe.
-* **maxCachedSessions** `number | null` (optional) - Default: `100` - Maximum number of TLS cached sessions. Use 0 to disable TLS session caching. Default: 100.
-* **timeout** `number | null` (optional) -  In milliseconds, Default `10e3`.
-* **servername** `string | null` (optional)
-* **keepAlive** `boolean | null` (optional) - Default: `true` - TCP keep-alive enabled
-* **keepAliveInitialDelay** `number | null` (optional) - Default: `60000` - TCP keep-alive interval for the socket in milliseconds
-
-### Example - Basic Client instantiation
-
-This will instantiate the undici Client, but it will not connect to the origin until something is queued. Consider using `client.connect` to prematurely connect to the origin, or just call `client.request`.
-
-```js
-'use strict'
+# Client
+
+<!--introduced_in=v1.0.0-->
+
+<!--type=module-->
+
+<!-- source_link=lib/dispatcher/client.js -->
+
+> Stability: 2 - Stable
+
+A basic HTTP/1.1 client mapped on top of a single TCP/TLS connection. When the
+server supports HTTP/2 and selects it during ALPN negotiation, the same
+connection is used for HTTP/2. Pipelining is disabled by default.
+
+`Client` extends [`Dispatcher`][] and is the lowest-level dispatcher in undici:
+it manages exactly one origin over one connection. For pooling across multiple
+connections use [`Pool`][], and for routing across multiple origins use
+[`Agent`][]. Requests are not guaranteed to be dispatched in the order in which
+they are invoked.
+
+```mjs
 import { Client } from 'undici'
 
 const client = new Client('http://localhost:3000')
+const { statusCode, body } = await client.request({ path: '/', method: 'GET' })
 ```
 
-### Example - Connect with TLS options (object form)
+## Class: `Client`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* Extends: {Dispatcher}
+
+### `new Client(url[, options])`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* `url` {URL|string} The origin to connect to. Only the protocol, hostname, and
+  port are used.
+* `options` {Object} (optional)
+  * `bodyTimeout` {number|null} The timeout, in milliseconds, after which a
+    request times out while receiving body data. Monitors the time between
+    consecutive body chunks. Use `0` to disable it entirely. **Default:**
+    `300e3`.
+  * `headersTimeout` {number|null} The timeout, in milliseconds, the parser
+    waits to receive the complete HTTP headers before the request times out. Use
+    `0` to disable it entirely. **Default:** `300e3`.
+  * `connectTimeout` {number|null} The timeout, in milliseconds, for
+    establishing a socket connection. Use `0` to disable it entirely.
+    **Default:** `10e3`.
+  * `keepAliveTimeout` {number|null} The timeout, in milliseconds, after which a
+    socket with no active requests times out. Monitors the time between activity
+    on a connected socket. This value may be overridden by *keep-alive* hints
+    from the server. **Default:** `4e3`.
+  * `keepAliveMaxTimeout` {number|null} The maximum allowed `keepAliveTimeout`,
+    in milliseconds, when overridden by *keep-alive* hints from the server.
+    **Default:** `600e3`.
+  * `keepAliveTimeoutThreshold` {number|null} A number of milliseconds
+    subtracted from server *keep-alive* hints when overriding `keepAliveTimeout`,
+    to account for timing inaccuracies caused by e.g. transport latency.
+    **Default:** `2e3`.
+  * `maxHeaderSize` {number|null} The maximum length of request headers, in
+    bytes. **Default:** the value of Node.js' `--max-http-header-size` or
+    `16384` (16 KiB).
+  * `maxResponseSize` {number|null} The maximum length of a response body, in
+    bytes. Set to `-1` to disable it. **Default:** `-1`.
+  * `maxRequestsPerClient` {number|null} The maximum number of requests to send
+    over a single connection before the socket is reset. Use `0` to disable this
+    limit. **Default:** `null`.
+  * `localAddress` {string|null} The local IP address the socket should connect
+    from. **Default:** `null`.
+  * `pipelining` {number|null} The number of concurrent requests sent over the
+    single connection, per [RFC 7230, section 6.3.2][]. Set to `0` to disable
+    keep-alive connections. Has no effect once HTTP/2 is negotiated; see
+    `maxConcurrentStreams` for the HTTP/2 dispatch ceiling. **Default:** `1`.
+  * `connect` {Object|Function|null} Configures how connections are established.
+    Either a `ConnectOptions` object passed to the built-in
+    [`buildConnector`][] (every [`tls.connect()`][] option is accepted, plus the
+    fields below), or a custom connector function with the signature
+    `(options, callback)`. **Default:** `null`.
+    * `socketPath` {string|null} An IPC endpoint, either a Unix domain socket or
+      a Windows named pipe. **Default:** `null`.
+    * `maxCachedSessions` {number|null} The maximum number of cached TLS
+      sessions. Use `0` to disable TLS session caching. **Default:** `100`.
+    * `timeout` {number|null} The connection timeout, in milliseconds.
+      **Default:** `10e3`.
+    * `servername` {string|null} The TLS server name used for SNI.
+    * `keepAlive` {boolean|null} Whether TCP keep-alive is enabled on the socket.
+      **Default:** `true`.
+    * `keepAliveInitialDelay` {number|null} The TCP keep-alive interval for the
+      socket, in milliseconds. **Default:** `60000`.
+  * `strictContentLength` {boolean} Whether to throw when the request
+    `content-length` header does not match the length of the request body.
+    Disabling this exposes the application to HTTP request smuggling; only do so
+    in controlled environments where the request source is fully trusted.
+    **Default:** `true`.
+  * `autoSelectFamily` {boolean} Enables a family autodetection algorithm that
+    loosely implements section 5 of [RFC 8305][]. Ignored if unsupported by the
+    current Node.js version. **Default:** `false`.
+  * `autoSelectFamilyAttemptTimeout` {number} The time, in milliseconds, to wait
+    for a connection attempt to finish before trying the next address when
+    `autoSelectFamily` is enabled. **Default:** `250`.
+  * `allowH2` {boolean} Enables HTTP/2 support when the server assigns it a
+    higher priority through ALPN negotiation. **Default:** `true`.
+  * `useH2c` {boolean} Enforces h2c (HTTP/2 cleartext) for non-HTTPS
+    connections. **Default:** `false`.
+  * `maxConcurrentStreams` {number} The maximum number of concurrent HTTP/2
+    streams for a single session. Once h2 is negotiated this — not `pipelining`,
+    which is HTTP/1.1 only — is the ceiling used to dispatch in-flight requests.
+    It may be overridden by the server's `SETTINGS_MAX_CONCURRENT_STREAMS`
+    frame. **Default:** `100`.
+  * `initialWindowSize` {number} The HTTP/2 stream-level flow-control window
+    size (`SETTINGS_INITIAL_WINDOW_SIZE`). Must be a positive integer.
+    **Default:** `262144`.
+  * `connectionWindowSize` {number} The HTTP/2 connection-level flow-control
+    window size set via `ClientHttp2Session.setLocalWindowSize()`. Must be a
+    positive integer. **Default:** `524288`.
+  * `pingInterval` {number} The time interval, in milliseconds, between HTTP/2
+    PING frames. Set to `0` to disable PING frames. Applies only to HTTP/2
+    connections and emits a `ping` event on the client. **Default:** `60e3`.
+  * `webSocket` {Object} (optional) WebSocket-specific configuration.
+    * `maxFragments` {number} The maximum number of fragments in a message. Set
+      to `0` to disable the limit. **Default:** `131072`.
+    * `maxPayloadSize` {number} The maximum allowed payload size, in bytes, for
+      WebSocket messages. Applied to uncompressed messages, compressed frame
+      payloads, and decompressed (`permessage-deflate`) messages. Set to `0` to
+      disable the limit. **Default:** `134217728`.
+* Returns: {Client}
+
+Instantiating a `Client` does not open a connection; the connection is
+established lazily once a request is queued. Call `client.connect()` to connect
+eagerly.
+
+> Notes about HTTP/2:
+>
+> * Pseudo headers (`:path`, `:method`, `:scheme`, `:authority`) are attached
+>   automatically and overwrite any user-provided values.
+> * The server must support HTTP/2 and select it during ALPN negotiation, and
+>   must not give HTTP/1.1 a higher priority than HTTP/2.
+> * `PUSH` frames are not supported.
+
+```mjs displayName="Basic instantiation"
+import { Client } from 'undici'
 
-Pass a `ConnectOptions` object to customize the TLS connection. The options are forwarded to the internal `buildConnector()`.
+const client = new Client('http://localhost:3000')
+```
 
-```js
-'use strict'
+```mjs displayName="TLS options (object connector)"
 import { Client } from 'undici'
-import fs from 'node:fs'
+import { readFileSync } from 'node:fs'
 
 const client = new Client('https://localhost:3000', {
   connect: {
     rejectUnauthorized: false,
-    ca: fs.readFileSync('./ca-cert.pem')
+    ca: readFileSync('./ca-cert.pem')
   }
 })
 ```
 
-### Example - Connect via Unix domain socket
-
-Use the `socketPath` option to connect through an IPC endpoint instead of a TCP connection.
-
-```js
-'use strict'
+```mjs displayName="Unix domain socket"
 import { Client } from 'undici'
 
 const client = new Client('http://localhost:3000', {
@@ -107,12 +171,7 @@ const client = new Client('http://localhost:3000', {
 })
 ```
 
-### Example - Custom DNS lookup
-
-Pass a `lookup` function in the object form when you need to control name resolution while still using Undici's built-in connector.
-
-```js
-'use strict'
+```mjs displayName="Custom DNS lookup"
 import { Client } from 'undici'
 import dns from 'node:dns'
 
@@ -125,14 +184,7 @@ const client = new Client('https://example.com', {
 })
 ```
 
-### Example - Custom connector (function form)
-
-Pass a function for full control over socket creation. This allows you to perform additional checks on the socket, use a proxy, or implement custom connection logic.
-
-> **Note:** When a function is provided, undici wraps it to automatically inject `socketPath` and `allowH2` into the first argument (`options`) when those values are set on the client.
-
-```js
-'use strict'
+```mjs displayName="Custom connector (function)"
 import { Client, buildConnector } from 'undici'
 
 const connector = buildConnector({ rejectUnauthorized: false })
@@ -141,9 +193,6 @@ const client = new Client('https://localhost:3000', {
     connector(opts, (err, socket) => {
       if (err) {
         cb(err)
-      } else if (/* assertion */) {
-        socket.destroy()
-        cb(new Error('kaboom'))
       } else {
         cb(null, socket)
       }
@@ -152,83 +201,179 @@ const client = new Client('https://localhost:3000', {
 })
 ```
 
-For more details on building custom connectors, see [Connector](/docs/docs/api/Connector.md).
+When a connector function is provided, undici wraps it to automatically inject
+`socketPath` and `allowH2` into the `options` argument when those values are set
+on the client. See [`Connector`][] for details on building custom connectors.
+
+### `client.close([callback])`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+Implements [`dispatcher.close([callback])`][]. Closes the client gracefully,
+waiting for enqueued requests to complete before resolving.
+
+### `client.destroy([error[, callback]])`
 
-## Instance Methods
+<!-- YAML
+added: v1.0.0
+-->
 
-### `Client.close([callback])`
+Implements [`dispatcher.destroy([error[, callback]])`][]. Destroys the client
+abruptly, aborting all pending and running requests, and waits until the socket
+is closed before invoking `callback` (or resolving the returned promise).
 
-Implements [`Dispatcher.close([callback])`](/docs/docs/api/Dispatcher.md#dispatcherclosecallback-promise).
+### `client.connect(options[, callback])`
 
-### `Client.destroy([error, callback])`
+<!-- YAML
+added: v1.0.0
+-->
 
-Implements [`Dispatcher.destroy([error, callback])`](/docs/docs/api/Dispatcher.md#dispatcherdestroyerror-callback-promise).
+* `options` {Object} The connect options, identical to
+  [`dispatcher.connect()`][] except that `origin` is omitted because the client
+  is bound to a single origin.
+* `callback` {Function} (optional)
+* Returns: {Promise|void} A promise when `callback` is not provided.
 
-Waits until socket is closed before invoking the callback (or returning a promise if no callback is provided).
+Starts a connection to the client's origin and tunnels a connection through it,
+as defined by [`dispatcher.connect()`][].
 
-### `Client.connect(options[, callback])`
+### `client.dispatch(options, handlers)`
 
-See [`Dispatcher.connect(options[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherconnectoptions-callback).
+<!-- YAML
+added: v1.0.0
+-->
 
-### `Client.dispatch(options, handlers)`
+Implements [`dispatcher.dispatch(options, handler)`][]. This is the lowest-level
+API used by all other request methods; prefer `client.request()` for most use
+cases.
 
-Implements [`Dispatcher.dispatch(options, handlers)`](/docs/docs/api/Dispatcher.md#dispatcherdispatchoptions-handler).
+### `client.pipeline(options, handler)`
 
-### `Client.pipeline(options, handler)`
+<!-- YAML
+added: v1.0.0
+-->
 
-See [`Dispatcher.pipeline(options, handler)`](/docs/docs/api/Dispatcher.md#dispatcherpipelineoptions-handler).
+See [`dispatcher.pipeline(options, handler)`][]. Sends a request and returns a
+{Duplex} stream that the request body is written to and the response body is
+read from.
 
-### `Client.request(options[, callback])`
+### `client.request(options[, callback])`
 
-See [`Dispatcher.request(options [, callback])`](/docs/docs/api/Dispatcher.md#dispatcherrequestoptions-callback).
+<!-- YAML
+added: v1.0.0
+-->
 
-### `Client.stream(options, factory[, callback])`
+* `options` {Object}
+* `callback` {Function} (optional)
+* Returns: {Promise|void} A promise resolving to the response data when
+  `callback` is not provided.
 
-See [`Dispatcher.stream(options, factory[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherstreamoptions-factory-callback).
+See [`dispatcher.request(options[, callback])`][]. Performs an HTTP request and
+returns its status code, headers, trailers, and a readable body stream.
 
-### `Client.upgrade(options[, callback])`
+```mjs
+import { Client } from 'undici'
+
+const client = new Client('http://localhost:3000')
+const { statusCode, headers, body } = await client.request({
+  path: '/',
+  method: 'GET'
+})
+
+console.log(statusCode)
+for await (const chunk of body) {
+  console.log(chunk.toString())
+}
+```
 
-See [`Dispatcher.upgrade(options[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherupgradeoptions-callback).
+### `client.stream(options, factory[, callback])`
 
-## Instance Properties
+<!-- YAML
+added: v1.0.0
+-->
 
-### `Client.closed`
+* `options` {Object}
+* `factory` {Function} Returns a {Writable} the response body is piped into.
+* `callback` {Function} (optional)
+* Returns: {Promise|void} A promise when `callback` is not provided.
 
-* `boolean`
+See [`dispatcher.stream(options, factory[, callback])`][]. A faster alternative
+to `client.request()` when the destination of the response body is known in
+advance.
+
+### `client.upgrade(options[, callback])`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* `options` {Object}
+* `callback` {Function} (optional)
+* Returns: {Promise|void} A promise when `callback` is not provided.
+
+See [`dispatcher.upgrade(options[, callback])`][]. Upgrades a connection to a
+different protocol, such as for WebSocket or HTTP `CONNECT`.
+
+### `client.closed`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* Type: {boolean}
 
 `true` after `client.close()` has been called.
 
-### `Client.destroyed`
+### `client.destroyed`
 
-* `boolean`
+<!-- YAML
+added: v1.0.0
+-->
 
-`true` after `client.destroyed()` has been called or `client.close()` has been called and the client shutdown has completed.
+* Type: {boolean}
 
-### `Client.pipelining`
+`true` after `client.destroy()` has been called, or after `client.close()` has
+been called and the client shutdown has completed.
 
-* `number`
+### `client.pipelining`
 
-Property to get and set the pipelining factor.
+<!-- YAML
+added: v1.0.0
+-->
 
-## Instance Events
+* Type: {number}
 
-### Event: `'connect'`
+The pipelining factor. This property can be read and written to adjust the
+number of concurrent requests sent over the connection.
+
+### `client.stats`
 
-See [Dispatcher Event: `'connect'`](/docs/docs/api/Dispatcher.md#event-connect).
+<!-- YAML
+added: v7.9.0
+-->
 
-Parameters:
+* Type: {ClientStats}
 
-* **origin** `URL`
-* **targets** `Array<Dispatcher>`
+Aggregate statistics for the client. See [`ClientStats`][].
+
+### Event: `'connect'`
 
-Emitted when a socket has been created and connected. The client will connect once `client.size > 0`.
+<!-- YAML
+added: v1.0.0
+-->
 
-#### Example - Client connect event
+* `origin` {URL}
+* `targets` {Array<Dispatcher>}
 
-```js
-import { createServer } from 'http'
+Emitted when a socket has been created and connected. The client connects once
+`client.size > 0`. See [`Dispatcher` Event: `'connect'`][].
+
+```mjs
+import { createServer } from 'node:http'
 import { Client } from 'undici'
-import { once } from 'events'
+import { once } from 'node:events'
 
 const server = createServer((request, response) => {
   response.end('Hello, World!')
@@ -239,43 +384,40 @@ await once(server, 'listening')
 const client = new Client(`http://localhost:${server.address().port}`)
 
 client.on('connect', (origin) => {
-  console.log(`Connected to ${origin}`) // should print before the request body statement
+  console.log(`Connected to ${origin}`)
 })
 
-try {
-  const { body } = await client.request({
-    path: '/',
-    method: 'GET'
-  })
-  body.setEncoding('utf-8')
-  body.on('data', console.log)
-  client.close()
-  server.close()
-} catch (error) {
-  console.error(error)
-  client.close()
-  server.close()
-}
+const { body } = await client.request({ path: '/', method: 'GET' })
+body.setEncoding('utf8')
+body.on('data', console.log)
+
+client.close()
+server.close()
 ```
 
 ### Event: `'disconnect'`
 
-See [Dispatcher Event: `'disconnect'`](/docs/docs/api/Dispatcher.md#event-disconnect).
-
-Parameters:
-
-* **origin** `URL`
-* **targets** `Array<Dispatcher>`
-* **error** `Error`
-
-Emitted when socket has disconnected. The error argument of the event is the error which caused the socket to disconnect. The client will reconnect if or once `client.size > 0`.
-
-#### Example - Client disconnect event
-
-```js
-import { createServer } from 'http'
+<!-- YAML
+added: v1.0.0
+changes:
+  - version: v4.0.0
+    pr-url: https://github.com/nodejs/undici/pull/771
+    description: The event is only emitted if the client had previously
+                 connected.
+-->
+
+* `origin` {URL}
+* `targets` {Array<Dispatcher>}
+* `error` {Error}
+
+Emitted when a socket has disconnected. The `error` argument is the error that
+caused the disconnection. The client reconnects if or once `client.size > 0`.
+See [`Dispatcher` Event: `'disconnect'`][].
+
+```mjs
+import { createServer } from 'node:http'
 import { Client } from 'undici'
-import { once } from 'events'
+import { once } from 'node:events'
 
 const server = createServer((request, response) => {
   response.destroy()
@@ -290,12 +432,10 @@ client.on('disconnect', (origin) => {
 })
 
 try {
-  await client.request({
-    path: '/',
-    method: 'GET'
-  })
+  await client.request({ path: '/', method: 'GET' })
 } catch (error) {
   console.error(error.message)
+} finally {
   client.close()
   server.close()
 }
@@ -303,16 +443,19 @@ try {
 
 ### Event: `'drain'`
 
-Emitted when pipeline is no longer busy.
+<!-- YAML
+added: v1.0.0
+-->
 
-See [Dispatcher Event: `'drain'`](/docs/docs/api/Dispatcher.md#event-drain).
+* `origin` {URL}
 
-#### Example - Client drain event
+Emitted when the pipeline is no longer busy. See
+[`Dispatcher` Event: `'drain'`][].
 
-```js
-import { createServer } from 'http'
+```mjs
+import { createServer } from 'node:http'
 import { Client } from 'undici'
-import { once } from 'events'
+import { once } from 'node:events'
 
 const server = createServer((request, response) => {
   response.end('Hello, World!')
@@ -328,17 +471,40 @@ client.on('drain', () => {
   server.close()
 })
 
-const requests = [
+await Promise.all([
   client.request({ path: '/', method: 'GET' }),
   client.request({ path: '/', method: 'GET' }),
   client.request({ path: '/', method: 'GET' })
-]
-
-await Promise.all(requests)
-
-console.log('requests completed')
+])
 ```
 
 ### Event: `'error'`
 
-Invoked for user errors such as throwing in the `onResponseError` handler.
+<!-- YAML
+added: v1.0.0
+-->
+
+* `error` {Error}
+
+Emitted for user errors, such as throwing inside an `onResponseError` handler.
+
+[RFC 7230, section 6.3.2]: https://tools.ietf.org/html/rfc7230#section-6.3.2
+[RFC 8305]: https://tools.ietf.org/html/rfc8305#section-5
+[`Agent`]: Agent.md#class-agent
+[`ClientStats`]: ClientStats.md
+[`Connector`]: Connector.md
+[`Dispatcher` Event: `'connect'`]: Dispatcher.md#event-connect
+[`Dispatcher` Event: `'disconnect'`]: Dispatcher.md#event-disconnect
+[`Dispatcher` Event: `'drain'`]: Dispatcher.md#event-drain
+[`Dispatcher`]: Dispatcher.md#class-dispatcher
+[`Pool`]: Pool.md#class-pool
+[`buildConnector`]: Connector.md
+[`dispatcher.close([callback])`]: Dispatcher.md#dispatcherclosecallback
+[`dispatcher.connect()`]: Dispatcher.md#dispatcherconnectoptions-callback
+[`dispatcher.destroy([error[, callback]])`]: Dispatcher.md#dispatcherdestroyerror-callback
+[`dispatcher.dispatch(options, handler)`]: Dispatcher.md#dispatcherdispatchoptions-handler
+[`dispatcher.pipeline(options, handler)`]: Dispatcher.md#dispatcherpipelineoptions-handler
+[`dispatcher.request(options[, callback])`]: Dispatcher.md#dispatcherrequestoptions-callback
+[`dispatcher.stream(options, factory[, callback])`]: Dispatcher.md#dispatcherstreamoptions-factory-callback
+[`dispatcher.upgrade(options[, callback])`]: Dispatcher.md#dispatcherupgradeoptions-callback
+[`tls.connect()`]: https://nodejs.org/api/tls.html#tlsconnectoptions-callback
diff --git a/docs/docs/api/ClientStats.md b/docs/docs/api/ClientStats.md
index fa899d482c8..0a6af86a1ff 100644
--- a/docs/docs/api/ClientStats.md
+++ b/docs/docs/api/ClientStats.md
@@ -1,27 +1,93 @@
-# Class: ClientStats
+# ClientStats
 
-Stats for a [Client](/docs/docs/api/Client.md).
+<!--introduced_in=v7.9.0-->
+<!--type=module-->
+<!-- source_link=lib/util/stats.js -->
 
-## `new ClientStats(client)`
+> Stability: 2 - Stable
 
-Arguments:
+A `ClientStats` is a point-in-time snapshot of the connection and request
+state of a single [`Client`][]. Instances are not created directly; a fresh
+snapshot is produced each time the [`client.stats`][] getter is read.
 
-* **client** `Client` - Client from which to return stats.
+```mjs
+import { Client } from 'undici'
 
-## Instance Properties
+const client = new Client('http://localhost:3000')
+const stats = client.stats
+console.log(stats.connected, stats.running)
+```
 
-### `ClientStats.connected`
+```cjs
+const { Client } = require('undici')
 
-Boolean if socket as open connection by this client.
+const client = new Client('http://localhost:3000')
+const stats = client.stats
+console.log(stats.connected, stats.running)
+```
 
-### `ClientStats.pending`
+## Class: `ClientStats`
 
-Number of pending requests of this client.
+<!-- YAML
+added: v7.9.0
+-->
 
-### `ClientStats.running`
+Captures the connection and request counters of a [`Client`][] at the moment
+the snapshot is taken. The values are read from the client at construction time
+and do not update afterwards; read [`client.stats`][] again for current values.
 
-Number of currently active requests across this client.
+### `new ClientStats(client)`
 
-### `ClientStats.size`
+<!-- YAML
+added: v7.9.0
+-->
 
-Number of active, pending, or queued requests of this clients.
+* `client` {Client} The client to read the statistics from.
+
+Creates a snapshot from the supplied `client`. This constructor is used
+internally by the [`client.stats`][] getter and is not normally invoked by
+application code.
+
+### `clientStats.connected`
+
+<!-- YAML
+added: v7.9.0
+-->
+
+* Type: {boolean}
+
+`true` when the client currently has an open socket connection.
+
+### `clientStats.pending`
+
+<!-- YAML
+added: v7.9.0
+-->
+
+* Type: {number}
+
+Number of open socket connections of this client that do not have an active
+request.
+
+### `clientStats.running`
+
+<!-- YAML
+added: v7.9.0
+-->
+
+* Type: {number}
+
+Number of currently active requests of this client.
+
+### `clientStats.size`
+
+<!-- YAML
+added: v7.9.0
+-->
+
+* Type: {number}
+
+Number of active, pending, or queued requests of this client.
+
+[`Client`]: Client.md#class-client
+[`client.stats`]: Client.md#clientstats
diff --git a/docs/docs/api/Connector.md b/docs/docs/api/Connector.md
index c30f69b5a6e..8e21f1713f0 100644
--- a/docs/docs/api/Connector.md
+++ b/docs/docs/api/Connector.md
@@ -1,49 +1,87 @@
 # Connector
 
-Undici creates the underlying socket via the connector builder.
-Normally, this happens automatically and you don't need to care about this,
-but if you need to perform some additional check over the currently used socket,
-this is the right place.
+<!--introduced_in=v4.3.0-->
+<!--type=module-->
+<!-- source_link=lib/core/connect.js -->
 
-If you want to create a custom connector, you must import the `buildConnector` utility.
+> Stability: 2 - Stable
 
-#### Parameter: `buildConnector.BuildOptions`
+undici opens the underlying socket for every request through a *connector*. By
+default this is handled internally, so most applications never interact with the
+connector directly. When a request needs additional control over the socket —
+for example to inspect a TLS certificate, pin a CA fingerprint, or tunnel the
+connection — a custom connector can be supplied through the `connect` option of
+a [`Dispatcher`][].
 
-Every Tls option, see [here](https://nodejs.org/api/tls.html#tls_tls_connect_options_callback).
-Furthermore, the following options can be passed:
+Use the `buildConnector` helper to construct a connector with sensible defaults
+and then wrap it:
 
-* **socketPath** `string | null` (optional) - Default: `null` - An IPC endpoint, either Unix domain socket or Windows named pipe.
-* **preferH2** `boolean` (optional) - Default: `false` - Only effective together with `allowH2`. When `true`, ALPN is offered as `['h2', 'http/1.1']` (HTTP/2 first) instead of the default `['http/1.1', 'h2']`. Use this when the server selects the ALPN protocol by *client* preference (e.g. some load balancers) so that HTTP/2 is negotiated whenever the server supports it. If the server does not support HTTP/2, ALPN transparently falls back to `http/1.1`.
-* **maxCachedSessions** `number | null` (optional) - Default: `100` - Maximum number of TLS cached sessions. Use 0 to disable TLS session caching. Default: `100`.
-* **timeout** `number | null` (optional) -  In milliseconds. Default `10e3`.
-* **servername** `string | null` (optional)
+```mjs
+import { buildConnector } from 'undici'
 
-Once you call `buildConnector`, it will return a connector function, which takes the following parameters.
-
-#### Parameter: `connector.Options`
-
-* **hostname** `string` (required)
-* **host** `string` (optional)
-* **protocol** `string` (required)
-* **port** `string` (required)
-* **servername** `string` (optional)
-* **localAddress** `string | null` (optional) Local address the socket should connect from.
-* **httpSocket** `Socket` (optional) Establish secure connection on a given socket rather than creating a new socket. It can only be sent on TLS update.
-
-### Basic example
-
-```js
-'use strict'
+const connector = buildConnector({ rejectUnauthorized: false })
+```
 
+`buildConnector` accepts the same TLS options as
+[`tls.connect()`][tls.connect] in addition to the undici-specific options listed
+below, and returns a [`connector`](#connectoroptions-callback) function that
+undici invokes for each new connection.
+
+## `buildConnector([options])`
+
+<!-- YAML
+added: v5.23.4
+-->
+
+* `options` {buildConnector.BuildOptions} (optional) Connection options. In
+  addition to every [`tls.connect()`][tls.connect] option, the following fields
+  are supported:
+  * `allowH2` {boolean} Whether to offer HTTP/2 (`h2`) during TLS ALPN
+    negotiation. **Default:** `true`.
+  * `preferH2` {boolean} Only effective together with `allowH2`. When `true`,
+    ALPN is offered as `['h2', 'http/1.1']` (HTTP/2 first) instead of the default
+    `['http/1.1', 'h2']`. Use this when the server selects the ALPN protocol by
+    *client* preference (for example, some load balancers) so that HTTP/2 is
+    negotiated whenever the server supports it. If the server does not support
+    HTTP/2, ALPN transparently falls back to `http/1.1`. **Default:** `false`.
+  * `maxCachedSessions` {number|null} Maximum number of TLS sessions to cache for
+    reuse. Use `0` to disable TLS session caching. Must be a non-negative
+    integer. **Default:** `100`.
+  * `socketPath` {string|null} An IPC endpoint, either a Unix domain socket or a
+    Windows named pipe. **Default:** `null`.
+  * `timeout` {number|null} The connection timeout in milliseconds. A
+    [`ConnectTimeoutError`][] is raised when the socket fails to connect within
+    this period. **Default:** `10e3`.
+  * `port` {number} The port to connect to when one is not provided to the
+    connector. Defaults to `443` for `https:` and `80` otherwise.
+  * `keepAlive` {boolean|null} Whether to enable TCP keep-alive on the socket.
+    **Default:** `true`.
+  * `keepAliveInitialDelay` {number|null} The delay in milliseconds before the
+    first TCP keep-alive probe is sent on an idle socket. **Default:** `60e3`.
+  * `typeOfService` {number|null} The IP Type of Service (ToS) value to set on
+    the socket. **Default:** `null`.
+* Returns: {buildConnector.connector} A
+  [`connector`](#connectoroptions-callback) function bound to the supplied
+  options.
+
+Builds a connector function. `maxCachedSessions` must be a non-negative integer
+or an [`InvalidArgumentError`][] is thrown.
+
+The returned function may be passed directly as the `connect` option of a
+[`Dispatcher`][], or wrapped to perform extra validation on each socket before it
+is handed back to undici.
+
+```mjs
 import { Client, buildConnector } from 'undici'
 
 const connector = buildConnector({ rejectUnauthorized: false })
+
 const client = new Client('https://localhost:3000', {
   connect (opts, cb) {
     connector(opts, (err, socket) => {
       if (err) {
         cb(err)
-      } else if (/* assertion */) {
+      } else if (/* assertion */ false) {
         socket.destroy()
         cb(new Error('kaboom'))
       } else {
@@ -54,15 +92,53 @@ const client = new Client('https://localhost:3000', {
 })
 ```
 
+## `connector(options, callback)`
+
+<!-- YAML
+added: v4.3.0
+-->
+
+* `options` {Object} Per-connection options provided by undici.
+  * `hostname` {string} The host to connect to.
+  * `host` {string} (optional) The value of the request `Host` header, used to
+    derive the TLS `servername` when one is not supplied.
+  * `protocol` {string} The request protocol, for example `'https:'` or
+    `'http:'`. A value of `'https:'` establishes a TLS connection.
+  * `port` {string} The port to connect to. Defaults to `443` for `https:` and
+    `80` otherwise.
+  * `servername` {string} (optional) The TLS Server Name Indication (SNI) value.
+    Derived from `host` when omitted.
+  * `localAddress` {string|null} (optional) The local address the socket should
+    connect from.
+  * `httpSocket` {Socket} (optional) An existing socket on which to establish the
+    secure connection rather than creating a new one. May only be supplied for a
+    TLS upgrade (`protocol` of `'https:'`).
+* `callback` {Function} Called once the socket has connected or failed.
+  * `err` {Error|null} The connection error, or `null` on success.
+  * `socket` {Socket|TLSSocket|null} The connected socket, or `null` on failure.
+* Returns: {Socket|TLSSocket} The socket being established.
+
+The function returned by [`buildConnector()`](#buildconnectoroptions). undici
+calls it for every new connection. It opens a [`net.Socket`][] for `http:`
+targets or a [`tls.TLSSocket`][] for `https:` targets, applies TCP keep-alive and
+the connect timeout, and invokes `callback` once the socket connects or errors.
+The socket is also returned synchronously.
+
+When connecting over TLS, established sessions are cached (subject to
+`maxCachedSessions`) and reused for subsequent connections to the same
+`servername` or `hostname`.
+
 ### Example: validate the CA fingerprint
 
-```js
-'use strict'
+A custom connector is a convenient place to verify the server certificate before
+any request is sent over the socket.
 
+```mjs
 import { Client, buildConnector } from 'undici'
 
 const caFingerprint = 'FO:OB:AR'
 const connector = buildConnector({ rejectUnauthorized: false })
+
 const client = new Client('https://localhost:3000', {
   connect (opts, cb) {
     connector(opts, (err, socket) => {
@@ -97,20 +173,26 @@ client.request({
 function getIssuerCertificate (socket) {
   let certificate = socket.getPeerCertificate(true)
   while (certificate && Object.keys(certificate).length > 0) {
-    // invalid certificate
+    // Invalid certificate.
     if (certificate.issuerCertificate == null) {
       return null
     }
 
-    // We have reached the root certificate.
-    // In case of self-signed certificates, `issuerCertificate` may be a circular reference.
+    // We have reached the root certificate. In case of self-signed
+    // certificates, `issuerCertificate` may be a circular reference.
     if (certificate.fingerprint256 === certificate.issuerCertificate.fingerprint256) {
       break
     }
 
-    // continue the loop
     certificate = certificate.issuerCertificate
   }
   return certificate
 }
 ```
+
+[`ConnectTimeoutError`]: Errors.md#class-connecttimeouterror
+[`Dispatcher`]: Dispatcher.md#class-dispatcher
+[`InvalidArgumentError`]: Errors.md#class-invalidargumenterror
+[`net.Socket`]: https://nodejs.org/api/net.html#class-netsocket
+[`tls.TLSSocket`]: https://nodejs.org/api/tls.html#class-tlstlssocket
+[tls.connect]: https://nodejs.org/api/tls.html#tlsconnectoptions-callback
diff --git a/docs/docs/api/ContentType.md b/docs/docs/api/ContentType.md
index 2bcc9f71ca3..3b94ba10bdb 100644
--- a/docs/docs/api/ContentType.md
+++ b/docs/docs/api/ContentType.md
@@ -1,19 +1,51 @@
 # MIME Type Parsing
 
-## `MIMEType` interface
+<!--introduced_in=v4.13.0-->
+<!--type=module-->
+<!-- source_link=lib/web/fetch/data-url.js -->
 
-* **type** `string`
-* **subtype** `string`
-* **parameters** `Map<string, string>`
-* **essence** `string`
+> Stability: 2 - Stable
 
-## `parseMIMEType(input)`
+undici exposes helpers for parsing and serializing MIME types according to the
+WHATWG [MIME Sniffing Standard][]. These are the same primitives undici uses
+internally to interpret `Content-Type` headers and `data:` URLs.
+
+Import the functions from `'undici'`:
+
+```mjs
+import { parseMIMEType, serializeAMimeType } from 'undici'
+```
+
+A parsed MIME type is represented as a plain object with the following shape:
 
-Implements [parse a MIME type](https://mimesniff.spec.whatwg.org/#parse-a-mime-type).
+* `type` {string} The lowercased type, for example `'text'`.
+* `subtype` {string} The lowercased subtype, for example `'html'`.
+* `parameters` {Map<string, string>} The parameters, keyed by lowercased
+  parameter name.
+* `essence` {string} The concatenation of `type`, `'/'`, and `subtype`, for
+  example `'text/html'`.
 
-Parses a MIME type, returning its type, subtype, and any associated parameters. If the parser can't parse an input it returns the string literal `'failure'`.
+## `parseMIMEType(input)`
 
-```js
+<!-- YAML
+added: v4.13.0
+-->
+
+* `input` {string} The MIME type string to parse.
+* Returns: {Object|string} A parsed MIME type record, or the string literal
+  `'failure'` when `input` cannot be parsed.
+  * `type` {string} The lowercased type.
+  * `subtype` {string} The lowercased subtype.
+  * `parameters` {Map<string, string>} The parsed parameters, keyed by
+    lowercased parameter name.
+  * `essence` {string} The MIME type essence, `` `${type}/${subtype}` ``.
+
+Implements the WHATWG [parse a MIME type][] algorithm. The `type` and `subtype`
+are lowercased, and only the first occurrence of a duplicate parameter name is
+retained. When `input` is empty, lacks a `/`, or otherwise violates the grammar,
+the string literal `'failure'` is returned instead of a record.
+
+```mjs
 import { parseMIMEType } from 'undici'
 
 parseMIMEType('text/html; charset=gbk')
@@ -23,21 +55,31 @@ parseMIMEType('text/html; charset=gbk')
 //   parameters: Map(1) { 'charset' => 'gbk' },
 //   essence: 'text/html'
 // }
-```
-
-Arguments:
 
-* **input** `string`
+parseMIMEType('not a mime type')
+// 'failure'
+```
 
-Returns: `MIMEType|'failure'`
+## `serializeAMimeType(mimeType)`
 
-## `serializeAMimeType(input)`
+<!-- YAML
+added: v5.11.0
+-->
 
-Implements [serialize a MIME type](https://mimesniff.spec.whatwg.org/#serialize-a-mime-type).
+* `mimeType` {Object} A MIME type record, as returned by [`parseMIMEType()`][].
+  * `type` {string} The type.
+  * `subtype` {string} The subtype.
+  * `parameters` {Map<string, string>} The parameters to serialize, in
+    insertion order.
+  * `essence` {string} The MIME type essence, `` `${type}/${subtype}` ``.
+* Returns: {string} The serialized MIME type.
 
-Serializes a MIMEType object.
+Implements the WHATWG [serialize a MIME type][] algorithm. The essence is
+emitted followed by each parameter as `;name=value`. A parameter value that
+contains characters outside the HTTP token set is quoted, and any `"` or `\`
+characters within it are escaped.
 
-```js
+```mjs
 import { serializeAMimeType } from 'undici'
 
 serializeAMimeType({
@@ -46,12 +88,10 @@ serializeAMimeType({
   parameters: new Map([['charset', 'gbk']]),
   essence: 'text/html'
 })
-// text/html;charset=gbk
-
+// 'text/html;charset=gbk'
 ```
 
-Arguments:
-
-* **mimeType** `MIMEType`
-
-Returns: `string`
+[MIME Sniffing Standard]: https://mimesniff.spec.whatwg.org/
+[`parseMIMEType()`]: #parsemimetypeinput
+[parse a MIME type]: https://mimesniff.spec.whatwg.org/#parse-a-mime-type
+[serialize a MIME type]: https://mimesniff.spec.whatwg.org/#serialize-a-mime-type
diff --git a/docs/docs/api/Cookies.md b/docs/docs/api/Cookies.md
index bd2b63f6d97..55aa2e1563a 100644
--- a/docs/docs/api/Cookies.md
+++ b/docs/docs/api/Cookies.md
@@ -1,44 +1,58 @@
-# Cookie Handling
+# Cookies
 
-## `Cookie` interface
+<!--introduced_in=v5.15.0-->
+<!--type=module-->
+<!-- source_link=lib/web/cookies/index.js -->
 
-* **name** `string`
-* **value** `string`
-* **expires** `Date|number` (optional)
-* **maxAge** `number` (optional)
-* **domain** `string` (optional)
-* **path** `string` (optional)
-* **secure** `boolean` (optional)
-* **httpOnly** `boolean` (optional)
-* **sameSite** `'Strict'|'Lax'|'None'` (optional)
-* **unparsed** `string[]` (optional) Left over attributes that weren't parsed.
+> Stability: 2 - Stable
 
-## `deleteCookie(headers, name[, attributes])`
-
-Sets the expiry time of the cookie to the unix epoch, causing browsers to delete it when received.
-
-```js
-import { deleteCookie, Headers } from 'undici'
-
-const headers = new Headers()
-deleteCookie(headers, 'name')
+A set of helpers for reading and writing HTTP cookies on a [`Headers`][]
+instance, following the [RFC 6265bis][] cookie parsing and serialization
+algorithm. They operate on the `Cookie` request header and the `Set-Cookie`
+response header.
 
-console.log(headers.get('set-cookie')) // name=; Expires=Thu, 01 Jan 1970 00:00:00 GMT
+```mjs
+import { getCookies, setCookie, deleteCookie, getSetCookies, parseCookie } from 'undici'
 ```
 
-Arguments:
+These functions do not manage a cookie jar or perform any network activity; they
+only read from and mutate the supplied `Headers` object.
+
+## `Cookie`
+
+The `Cookie` object describes a single cookie and its attributes. It is the
+return shape of [`parseCookie()`][] and [`getSetCookies()`][], and the input
+shape accepted by [`setCookie()`][].
+
+* `name` {string} The cookie name.
+* `value` {string} The cookie value.
+* `expires` {Date|number} The cookie expiry time, as a `Date` or a Unix
+  timestamp in seconds. (optional)
+* `maxAge` {number} The number of seconds until the cookie expires. (optional)
+* `domain` {string} The hosts the cookie is sent to. (optional)
+* `path` {string} The URL path that must exist for the cookie to be sent.
+  (optional)
+* `secure` {boolean} Whether the cookie is only sent over HTTPS. (optional)
+* `httpOnly` {boolean} Whether the cookie is inaccessible to client-side
+  JavaScript. (optional)
+* `sameSite` {string} Controls whether the cookie is sent with cross-site
+  requests. One of `'Strict'`, `'Lax'`, or `'None'`. (optional)
+* `unparsed` {string[]} Any attributes that were present in the `Set-Cookie`
+  header but not recognized, each formatted as `` `name=value` ``. (optional)
 
-* **headers** `Headers`
-* **name** `string`
-* **attributes** `{ path?: string, domain?: string }` (optional)
+## `getCookies(headers)`
 
-Returns: `void`
+<!-- YAML
+added: v5.15.0
+-->
 
-## `getCookies(headers)`
+* `headers` {Headers} The `Headers` to read the `Cookie` header from.
+* Returns: {Record<string, string>} A map of cookie names to values.
 
-Parses the `Cookie` header and returns a list of attributes and values.
+Parses the `Cookie` header of `headers` and returns its name/value pairs as a
+plain object. An empty object is returned when no `Cookie` header is present.
 
-```js
+```mjs
 import { getCookies, Headers } from 'undici'
 
 const headers = new Headers({
@@ -48,17 +62,48 @@ const headers = new Headers({
 console.log(getCookies(headers)) // { get: 'cookies', and: 'attributes' }
 ```
 
-Arguments:
+## `deleteCookie(headers, name[, attributes])`
 
-* **headers** `Headers`
+<!-- YAML
+added: v5.15.0
+-->
 
-Returns: `Record<string, string>`
+* `headers` {Headers} The `Headers` to append the expiring cookie to.
+* `name` {string} The name of the cookie to delete.
+* `attributes` {Object} (optional)
+  * `path` {string} The path the cookie was scoped to. **Default:** `null`.
+  * `domain` {string} The domain the cookie was scoped to. **Default:** `null`.
+* Returns: {undefined}
+
+Appends a `Set-Cookie` header to `headers` that expires the named cookie by
+setting its expiry time to the Unix epoch, causing a client to delete it on
+receipt. The optional `path` and `domain` must match those of the cookie being
+removed.
+
+```mjs
+import { deleteCookie, Headers } from 'undici'
+
+const headers = new Headers()
+deleteCookie(headers, 'name')
+
+console.log(headers.get('set-cookie')) // name=; Expires=Thu, 01 Jan 1970 00:00:00 GMT
+```
 
 ## `getSetCookies(headers)`
 
-Parses all `Set-Cookie` headers.
+<!-- YAML
+added: v5.15.0
+-->
+
+* `headers` {Headers} The `Headers` to read the `Set-Cookie` headers from.
+* Returns: {Cookie[]} The parsed cookies, or an empty array when none are
+  present.
 
-```js
+Parses every `Set-Cookie` header of `headers` and returns the resulting
+[`Cookie`][] objects. A header that fails to parse yields a `null` entry at its
+position in the returned array.
+
+```mjs
 import { getSetCookies, Headers } from 'undici'
 
 const headers = new Headers({ 'set-cookie': 'undici=getSetCookies; Secure' })
@@ -71,20 +116,45 @@ console.log(getSetCookies(headers))
 //     secure: true
 //   }
 // ]
-
 ```
 
-Arguments:
+## `setCookie(headers, cookie)`
+
+<!-- YAML
+added: v5.15.0
+-->
+
+* `headers` {Headers} The `Headers` to append the `Set-Cookie` header to.
+* `cookie` {Cookie} The cookie to serialize. See [`Cookie`][].
+* Returns: {undefined}
 
-* **headers** `Headers`
+Serializes `cookie` and appends it to the `Set-Cookie` header of `headers`. When
+the cookie name is empty, serialization yields no value and no header is
+appended.
 
-Returns: `Cookie[]`
+```mjs
+import { setCookie, Headers } from 'undici'
+
+const headers = new Headers()
+setCookie(headers, { name: 'undici', value: 'setCookie' })
+
+console.log(headers.get('Set-Cookie')) // undici=setCookie
+```
 
 ## `parseCookie(cookie)`
 
-Parses a single `Set-Cookie` header value into a `Cookie` object.
+<!-- YAML
+added: v7.0.0
+-->
+
+* `cookie` {string} A `Set-Cookie` header value.
+* Returns: {Cookie|null} The parsed cookie, or `null` if `cookie` is invalid.
 
-```js
+Parses a single `Set-Cookie` header value into a [`Cookie`][] object. `null` is
+returned when the value contains control characters or otherwise cannot be
+parsed.
+
+```mjs
 import { parseCookie } from 'undici'
 
 console.log(parseCookie('undici=getSetCookies; Secure; SameSite=Lax'))
@@ -96,33 +166,14 @@ console.log(parseCookie('undici=getSetCookies; Secure; SameSite=Lax'))
 // }
 ```
 
-Notes:
-
-* The cookie value is returned as it appears in the header. Percent-encoded sequences such as `%20` or `%0D%0A` are **not** decoded.
-* `sameSite` is only set for exact case-insensitive matches of `Strict`, `Lax`, or `None`.
-
-Arguments:
-
-* **cookie** `string`
-
-Returns: `Cookie | null`
-
-## `setCookie(headers, cookie)`
-
-Appends a cookie to the `Set-Cookie` header.
-
-```js
-import { setCookie, Headers } from 'undici'
-
-const headers = new Headers()
-setCookie(headers, { name: 'undici', value: 'setCookie' })
-
-console.log(headers.get('Set-Cookie')) // undici=setCookie
-```
-
-Arguments:
-
-* **headers** `Headers`
-* **cookie** `Cookie`
-
-Returns: `void`
+The cookie value is returned exactly as it appears in the header; percent-encoded
+sequences such as `%20` or `%0D%0A` are not decoded. The `sameSite` attribute is
+only set when the value is a case-insensitive match for `Strict`, `Lax`, or
+`None`.
+
+[RFC 6265bis]: https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis
+[`Cookie`]: #cookie
+[`Headers`]: https://developer.mozilla.org/en-US/docs/Web/API/Headers
+[`getSetCookies()`]: #getsetcookiesheaders
+[`parseCookie()`]: #parsecookiecookie
+[`setCookie()`]: #setcookieheaders-cookie
diff --git a/docs/docs/api/Debug.md b/docs/docs/api/Debug.md
index 69c7d7b4fee..da511b29cf5 100644
--- a/docs/docs/api/Debug.md
+++ b/docs/docs/api/Debug.md
@@ -1,16 +1,29 @@
 # Debug
 
-Undici (and subsenquently `fetch` and `websocket`) exposes a debug statement that can be enabled by setting `NODE_DEBUG` within the environment.
+<!--type=misc-->
 
-The flags available are:
+Undici emits human-readable debug logs through Node.js' built-in
+[`util.debuglog()`][]. The logs are disabled by default and are turned on by
+listing one or more namespaces in the `NODE_DEBUG` environment variable. Because
+`util.debuglog()` reads `NODE_DEBUG` once, when the namespace is first used, the
+variable must be set before the process starts.
 
-## `undici`
+Each log line is prefixed with the namespace (uppercased) and the process id,
+for example `UNDICI 16241: connecting to nodejs.org using https:h1`. Multiple
+namespaces can be enabled at once by separating them with commas, for example
+`NODE_DEBUG=undici,websocket`.
+
+The following sections describe the namespaces exposed by undici.
 
-This flag enables debug statements for the core undici library.
+## `undici`
 
-```sh
-NODE_DEBUG=undici node script.js
+Enables debug logs for the core undici library, covering connection setup,
+request dispatch, responses, and trailers. The `fetch` and `websocket` APIs are
+built on top of this core, so enabling `undici` also surfaces activity that
+originates from them.
 
+```console
+$ NODE_DEBUG=undici node script.js
 UNDICI 16241: connecting to nodejs.org using https:h1
 UNDICI 16241: connecting to nodejs.org using https:h1
 UNDICI 16241: connected to nodejs.org using https:h1
@@ -26,13 +39,12 @@ UNDICI 16241: trailers received from GET https://nodejs.org/en
 
 ## `fetch`
 
-This flag enables debug statements for the `fetch` API.
-
-> **Note**: statements are pretty similar to the ones in the `undici` flag, but scoped to `fetch`
-
-```sh
-NODE_DEBUG=fetch node script.js
+Enables debug logs scoped to the `fetch` API. The output mirrors the `undici`
+namespace but is emitted only for requests made through [`fetch()`][], which
+makes it useful for isolating `fetch` traffic from other undici activity.
 
+```console
+$ NODE_DEBUG=fetch node script.js
 FETCH 16241: connecting to nodejs.org using https:h1
 FETCH 16241: connecting to nodejs.org using https:h1
 FETCH 16241: connected to nodejs.org using https:h1
@@ -48,15 +60,19 @@ FETCH 16241: trailers received from GET https://nodejs.org/en
 
 ## `websocket`
 
-This flag enables debug statements for the `Websocket` API.
-
-> **Note**: statements can overlap with `UNDICI` ones if `undici` or `fetch` flag has been enabled as well.
-
-```sh
-NODE_DEBUG=websocket node script.js
+Enables debug logs scoped to the [`WebSocket`][] API, covering the opening
+handshake and connection lifecycle. When the `undici` or `fetch` namespace is
+also enabled, some lines may appear under both namespaces because the handshake
+is performed through the core library.
 
+```console
+$ NODE_DEBUG=websocket node script.js
 WEBSOCKET 18309: connecting to echo.websocket.org using https:h1
 WEBSOCKET 18309: connected to echo.websocket.org using https:h1
 WEBSOCKET 18309: sending request to GET https://echo.websocket.org/
 WEBSOCKET 18309: connection opened <ip_address>
 ```
+
+[`WebSocket`]: WebSocket.md#class-websocket
+[`fetch()`]: Fetch.md
+[`util.debuglog()`]: https://nodejs.org/api/util.html#utildebuglogsection-callback
diff --git a/docs/docs/api/DiagnosticsChannel.md b/docs/docs/api/DiagnosticsChannel.md
index cff8546f6f0..aee300302fc 100644
--- a/docs/docs/api/DiagnosticsChannel.md
+++ b/docs/docs/api/DiagnosticsChannel.md
@@ -1,306 +1,497 @@
 # Diagnostics Channel Support
 
-Stability: Experimental.
+<!--introduced_in=v6.3.0-->
+<!--type=misc-->
 
-Undici supports the [`diagnostics_channel`](https://nodejs.org/api/diagnostics_channel.html) (currently available only on Node.js v16+).
-It is the preferred way to instrument Undici and retrieve internal information.
+> Stability: 1 - Experimental
 
-The channels available are the following.
+Undici is instrumented with Node.js' built-in [`diagnostics_channel`][] module.
+It is the preferred way to observe undici's internal behaviour without patching
+the library, and it backs the human-readable [debug logs][Debug].
 
-## `undici:request:create`
+Each integration point is exposed as a named channel. To observe an event,
+obtain the channel by name and subscribe to it:
 
-This message is published when a new outgoing request is created.
+```mjs
+import diagnosticsChannel from 'node:diagnostics_channel'
 
-```js
-import diagnosticsChannel from 'diagnostics_channel'
+diagnosticsChannel.channel('undici:request:create').subscribe(({ request }) => {
+  console.log(request.method, request.origin, request.path)
+})
+```
+
+```cjs
+const diagnosticsChannel = require('node:diagnostics_channel')
+
+diagnosticsChannel.channel('undici:request:create').subscribe(({ request }) => {
+  console.log(request.method, request.origin, request.path)
+})
+```
+
+The message published to a channel is always a single object whose shape depends
+on the channel. The sections below describe every channel and the object it
+publishes. Subscriber callbacks run synchronously inside undici, so they should
+be fast and must not throw.
+
+The same `request` object is shared across all `undici:request:*` channels for a
+given request, so a subscriber may correlate the lifecycle of one request by
+identity.
+
+## Event: `'undici:request:create'`
+
+<!-- YAML
+added: v6.3.0
+-->
+
+Published when a new outgoing request is created, before it is dispatched.
+
+* `message` {Object}
+  * `request` {Object} The request being created.
+    * `origin` {string|URL} The origin the request is sent to.
+    * `completed` {boolean} Whether the request has completed. `false` at this
+      point.
+    * `method` {string} The HTTP method, e.g. `'GET'`.
+    * `path` {string} The request path, including any query string.
+    * `headers` {string[]} The request headers as a flat array of strings,
+      alternating between header name and value.
+
+The `request` object also exposes an `addHeader(name, value)` method that
+appends a header before the request is sent.
+
+```mjs
+import diagnosticsChannel from 'node:diagnostics_channel'
 
 diagnosticsChannel.channel('undici:request:create').subscribe(({ request }) => {
   console.log('origin', request.origin)
   console.log('completed', request.completed)
   console.log('method', request.method)
   console.log('path', request.path)
-  console.log('headers', request.headers) // array of strings, e.g: ['foo', 'bar']
+  console.log('headers', request.headers)
   request.addHeader('hello', 'world')
-  console.log('headers', request.headers) // e.g. ['foo', 'bar', 'hello', 'world']
 })
 ```
 
-Note: a request is only loosely completed to a given socket.
+A request is only loosely bound to a given socket at this stage.
+
+## Event: `'undici:request:bodyChunkSent'`
+
+<!-- YAML
+added: v7.11.0
+-->
 
-## `undici:request:bodyChunkSent`
+Published each time a chunk of the request body is written to the socket.
 
-This message is published when a chunk of the request body is being sent.
+* `message` {Object}
+  * `request` {Object} The same object published by
+    [`'undici:request:create'`][].
+  * `chunk` {Uint8Array|string} The body chunk being sent.
 
-```js
-import diagnosticsChannel from 'diagnostics_channel'
+```mjs
+import diagnosticsChannel from 'node:diagnostics_channel'
 
 diagnosticsChannel.channel('undici:request:bodyChunkSent').subscribe(({ request, chunk }) => {
-  // request is the same object undici:request:create
+  console.log('sent', chunk.length, 'bytes')
 })
 ```
 
-## `undici:request:bodySent`
+## Event: `'undici:request:bodySent'`
 
-This message is published after the request body has been fully sent.
+<!-- YAML
+added: v6.3.0
+-->
 
-```js
-import diagnosticsChannel from 'diagnostics_channel'
+Published after the request body has been fully sent.
+
+* `message` {Object}
+  * `request` {Object} The same object published by
+    [`'undici:request:create'`][].
+
+```mjs
+import diagnosticsChannel from 'node:diagnostics_channel'
 
 diagnosticsChannel.channel('undici:request:bodySent').subscribe(({ request }) => {
-  // request is the same object undici:request:create
+  // request is the same object as in 'undici:request:create'
 })
 ```
 
-## `undici:request:headers`
+## Event: `'undici:request:headers'`
+
+<!-- YAML
+added: v6.3.0
+-->
 
-This message is published after the response headers have been received.
+Published after the response headers have been received.
 
-```js
-import diagnosticsChannel from 'diagnostics_channel'
+* `message` {Object}
+  * `request` {Object} The same object published by
+    [`'undici:request:create'`][].
+  * `response` {Object} The response being received.
+    * `statusCode` {number} The HTTP status code.
+    * `statusText` {string} The HTTP status message.
+    * `headers` {Buffer[]} The raw response headers as an array of buffers,
+      alternating between header name and value.
+
+```mjs
+import diagnosticsChannel from 'node:diagnostics_channel'
 
 diagnosticsChannel.channel('undici:request:headers').subscribe(({ request, response }) => {
-  // request is the same object undici:request:create
   console.log('statusCode', response.statusCode)
   console.log(response.statusText)
-  // response.headers are buffers.
   console.log(response.headers.map((x) => x.toString()))
 })
 ```
 
-## `undici:request:bodyChunkReceived`
+## Event: `'undici:request:bodyChunkReceived'`
+
+<!-- YAML
+added: v7.11.0
+-->
 
-This message is published after a chunk of the response body has been received.
+Published each time a chunk of the response body is received.
 
-```js
-import diagnosticsChannel from 'diagnostics_channel'
+* `message` {Object}
+  * `request` {Object} The same object published by
+    [`'undici:request:create'`][].
+  * `chunk` {Buffer} The body chunk that was received.
+
+```mjs
+import diagnosticsChannel from 'node:diagnostics_channel'
 
 diagnosticsChannel.channel('undici:request:bodyChunkReceived').subscribe(({ request, chunk }) => {
-  // request is the same object undici:request:create
+  console.log('received', chunk.length, 'bytes')
 })
 ```
 
-## `undici:request:trailers`
+## Event: `'undici:request:trailers'`
+
+<!-- YAML
+added: v6.3.0
+-->
 
-This message is published after the response body and trailers have been received, i.e. the response has been completed.
+Published after the response body and trailers have been received, that is, once
+the response has fully completed.
 
-```js
-import diagnosticsChannel from 'diagnostics_channel'
+* `message` {Object}
+  * `request` {Object} The same object published by
+    [`'undici:request:create'`][]. `request.completed` is now `true`.
+  * `trailers` {Buffer[]} The raw response trailers as an array of buffers,
+    alternating between header name and value.
+
+```mjs
+import diagnosticsChannel from 'node:diagnostics_channel'
 
 diagnosticsChannel.channel('undici:request:trailers').subscribe(({ request, trailers }) => {
-  // request is the same object undici:request:create
   console.log('completed', request.completed)
-  // trailers are buffers.
   console.log(trailers.map((x) => x.toString()))
 })
 ```
 
-## `undici:request:error`
+## Event: `'undici:request:error'`
+
+<!-- YAML
+added: v6.3.0
+-->
+
+Published when the request is about to error, before the error is surfaced to
+the caller.
 
-This message is published if the request is going to error, but it has not errored yet.
+* `message` {Object}
+  * `request` {Object} The same object published by
+    [`'undici:request:create'`][].
+  * `error` {Error} The error the request is about to fail with.
 
-```js
-import diagnosticsChannel from 'diagnostics_channel'
+```mjs
+import diagnosticsChannel from 'node:diagnostics_channel'
 
 diagnosticsChannel.channel('undici:request:error').subscribe(({ request, error }) => {
-  // request is the same object undici:request:create
+  console.error(error)
 })
 ```
 
-## `undici:client:sendHeaders`
+## Event: `'undici:client:sendHeaders'`
 
-This message is published right before the first byte of the request is written to the socket.
+<!-- YAML
+added: v6.3.0
+changes:
+  - version: v7.0.0
+    pr-url: https://github.com/nodejs/undici/pull/3585
+    description: Refactor the diagnostics channel internals.
+-->
 
-*Note*: It will publish the exact headers that will be sent to the server in raw format.
+Published immediately before the first byte of the request is written to the
+socket. The headers are published exactly as they will be sent to the server, in
+raw form.
 
-```js
-import diagnosticsChannel from 'diagnostics_channel'
+* `message` {Object}
+  * `request` {Object} The same object published by
+    [`'undici:request:create'`][].
+  * `headers` {string} The request headers as a single raw string, with lines
+    separated by `\r\n`.
+  * `socket` {net.Socket} The socket the request is written to.
+
+```mjs
+import diagnosticsChannel from 'node:diagnostics_channel'
 
 diagnosticsChannel.channel('undici:client:sendHeaders').subscribe(({ request, headers, socket }) => {
-  // request is the same object undici:request:create
-  console.log(`Full headers list ${headers.split('\r\n')}`);
+  console.log(`Full headers list: ${headers.split('\r\n')}`)
 })
 ```
 
-## `undici:client:beforeConnect`
+## Event: `'undici:client:beforeConnect'`
+
+<!-- YAML
+added: v6.3.0
+changes:
+  - version: v7.0.0
+    pr-url: https://github.com/nodejs/undici/pull/3585
+    description: Refactor the diagnostics channel internals.
+-->
 
-This message is published before creating a new connection for **any** request.
-You can not assume that this event is related to any specific request.
+Published before a new connection is opened for any request. This event cannot be
+attributed to a specific request, because connections are pooled and shared.
 
-```js
-import diagnosticsChannel from 'diagnostics_channel'
+* `message` {Object}
+  * `connectParams` {Object} The parameters used to open the connection.
+    * `host` {string} The connection host, including the port if present.
+    * `hostname` {string} The connection hostname.
+    * `protocol` {string} The protocol, e.g. `'https:'`.
+    * `port` {string} The connection port.
+    * `servername` {string|null} The TLS server name, or `null`.
+  * `connector` {Function} The function that creates the socket.
+
+```mjs
+import diagnosticsChannel from 'node:diagnostics_channel'
 
 diagnosticsChannel.channel('undici:client:beforeConnect').subscribe(({ connectParams, connector }) => {
-  // const { host, hostname, protocol, port, servername, version } = connectParams
-  // connector is a function that creates the socket
+  const { host, hostname, protocol, port, servername } = connectParams
+  // connector is the function that creates the socket
 })
 ```
 
-## `undici:client:connected`
+## Event: `'undici:client:connected'`
+
+<!-- YAML
+added: v6.3.0
+changes:
+  - version: v7.0.0
+    pr-url: https://github.com/nodejs/undici/pull/3585
+    description: Refactor the diagnostics channel internals.
+-->
 
-This message is published after a connection is established.
+Published after a connection has been successfully established.
 
-```js
-import diagnosticsChannel from 'diagnostics_channel'
+* `message` {Object}
+  * `socket` {net.Socket} The newly connected socket.
+  * `connectParams` {Object} The parameters used to open the connection. See
+    [`'undici:client:beforeConnect'`][] for the field descriptions.
+  * `connector` {Function} The function that created the socket.
+
+```mjs
+import diagnosticsChannel from 'node:diagnostics_channel'
 
 diagnosticsChannel.channel('undici:client:connected').subscribe(({ socket, connectParams, connector }) => {
-  // const { host, hostname, protocol, port, servername, version } = connectParams
- // connector is a function that creates the socket
+  const { host, hostname, protocol, port, servername } = connectParams
 })
 ```
 
-## `undici:client:connectError`
+## Event: `'undici:client:connectError'`
+
+<!-- YAML
+added: v6.3.0
+changes:
+  - version: v7.0.0
+    pr-url: https://github.com/nodejs/undici/pull/3585
+    description: Refactor the diagnostics channel internals.
+-->
+
+Published when a connection could not be established.
 
-This message is published if it did not succeed to create new connection
+* `message` {Object}
+  * `error` {Error} The error that prevented the connection.
+  * `socket` {net.Socket} The socket associated with the failed attempt.
+  * `connectParams` {Object} The parameters used to open the connection. See
+    [`'undici:client:beforeConnect'`][] for the field descriptions.
+  * `connector` {Function} The function that created the socket.
 
-```js
-import diagnosticsChannel from 'diagnostics_channel'
+```mjs
+import diagnosticsChannel from 'node:diagnostics_channel'
 
 diagnosticsChannel.channel('undici:client:connectError').subscribe(({ error, socket, connectParams, connector }) => {
-  // const { host, hostname, protocol, port, servername, version } = connectParams
-  // connector is a function that creates the socket
-  console.log(`Connect failed with ${error.message}`)
+  console.error(`Connect failed with ${error.message}`)
 })
 ```
 
-## `undici:websocket:open`
-
-This message is published after the client has successfully connected to a server.
-
-```js
-import diagnosticsChannel from 'diagnostics_channel'
-
-diagnosticsChannel.channel('undici:websocket:open').subscribe(({ 
-  address,           // { address: string, family: string, port: number }
-  protocol,          // string - negotiated subprotocol
-  extensions,        // string - negotiated extensions
-  websocket,         // WebSocket - the WebSocket instance
-  handshakeResponse  // object - HTTP response that upgraded the connection
+## Event: `'undici:websocket:open'`
+
+<!-- YAML
+added: v6.3.0
+-->
+
+Published after a [`WebSocket`][] has successfully connected to a server.
+
+* `message` {Object}
+  * `address` {Object|null} The remote socket address, as returned by
+    [`socket.address()`][], or `null` if it cannot be determined. When present,
+    it contains `address`, `family`, and `port`.
+  * `protocol` {string} The negotiated subprotocol.
+  * `extensions` {string} The negotiated extensions.
+  * `websocket` {WebSocket} The `WebSocket` instance.
+  * `handshakeResponse` {Object} The HTTP response that upgraded the connection.
+    * `status` {number} The HTTP status code: `101` for an HTTP/1.1 upgrade, or
+      `200` for an HTTP/2 extended `CONNECT`.
+    * `statusText` {string} The HTTP status message: `'Switching Protocols'` for
+      HTTP/1.1, and commonly `'OK'` for HTTP/2.
+    * `headers` {Object} The response headers from the server. The `upgrade` and
+      `connection` headers are only present for HTTP/1.1 handshakes.
+
+```mjs
+import diagnosticsChannel from 'node:diagnostics_channel'
+
+diagnosticsChannel.channel('undici:websocket:open').subscribe(({
+  address,
+  protocol,
+  extensions,
+  websocket,
+  handshakeResponse
 }) => {
-  console.log(address) // address, family, and port
-  console.log(protocol) // negotiated subprotocols
-  console.log(extensions) // negotiated extensions
-  console.log(websocket) // the WebSocket instance
-  
-  // Handshake response details
-  console.log(handshakeResponse.status) // 101 for HTTP/1.1, 200 for HTTP/2 extended CONNECT
-  console.log(handshakeResponse.statusText) // 'Switching Protocols' for HTTP/1.1, commonly 'OK' for HTTP/2 in Node.js
-  console.log(handshakeResponse.headers) // Object containing response headers
+  console.log(address)
+  console.log(protocol)
+  console.log(extensions)
+  console.log(handshakeResponse.status)
+  console.log(handshakeResponse.headers)
 })
 ```
 
-### Handshake Response Object
-
-The `handshakeResponse` object contains the HTTP response that established the WebSocket connection:
+## Event: `'undici:websocket:close'`
 
-- `status` (number): The HTTP status code (`101` for HTTP/1.1 upgrade, `200` for HTTP/2 extended CONNECT)
-- `statusText` (string): The HTTP status message (`'Switching Protocols'` for HTTP/1.1, commonly `'OK'` for HTTP/2 in Node.js)
-- `headers` (object): The HTTP response headers from the server, including:
-  - `sec-websocket-accept` and other WebSocket-related headers
-  - `upgrade: 'websocket'`
-  - `connection: 'upgrade'`
+<!-- YAML
+added: v6.3.0
+-->
 
-  The `upgrade` and `connection` headers are only present for HTTP/1.1 handshakes.
+Published after the [`WebSocket`][] connection has closed.
 
-This information is particularly useful for debugging and monitoring WebSocket connections, as it provides access to the initial HTTP handshake response that established the WebSocket connection.
+* `message` {Object}
+  * `websocket` {WebSocket} The `WebSocket` instance.
+  * `code` {number} The closing status code.
+  * `reason` {string} The closing reason.
 
-## `undici:websocket:close`
-
-This message is published after the connection has closed.
-
-```js
-import diagnosticsChannel from 'diagnostics_channel'
+```mjs
+import diagnosticsChannel from 'node:diagnostics_channel'
 
 diagnosticsChannel.channel('undici:websocket:close').subscribe(({ websocket, code, reason }) => {
-  console.log(websocket) // the WebSocket instance
-  console.log(code) // the closing status code
-  console.log(reason) // the closing reason
+  console.log(code, reason)
 })
 ```
 
-## `undici:websocket:socket_error`
+## Event: `'undici:websocket:socket_error'`
+
+<!-- YAML
+added: v6.3.0
+-->
 
-This message is published if the socket experiences an error.
+Published when the underlying WebSocket socket experiences an error. Unlike the
+other WebSocket channels, the published message is the error itself.
 
-```js
-import diagnosticsChannel from 'diagnostics_channel'
+* `error` {Error} The socket error.
+
+```mjs
+import diagnosticsChannel from 'node:diagnostics_channel'
 
 diagnosticsChannel.channel('undici:websocket:socket_error').subscribe((error) => {
-  console.log(error)
+  console.error(error)
 })
 ```
 
-## `undici:websocket:ping`
+## Event: `'undici:websocket:ping'`
+
+<!-- YAML
+added: v6.3.0
+-->
 
-This message is published after the client receives a ping frame, if the connection is not closing.
+Published after the client receives a ping frame.
 
-```js
-import diagnosticsChannel from 'diagnostics_channel'
+* `message` {Object}
+  * `payload` {Buffer|undefined} The optional application data carried by the
+    frame.
+  * `websocket` {WebSocket} The `WebSocket` instance.
+
+```mjs
+import diagnosticsChannel from 'node:diagnostics_channel'
 
 diagnosticsChannel.channel('undici:websocket:ping').subscribe(({ payload, websocket }) => {
-  // a Buffer or undefined, containing the optional application data of the frame
   console.log(payload)
-  console.log(websocket) // the WebSocket instance
 })
 ```
 
-## `undici:websocket:pong`
+## Event: `'undici:websocket:pong'`
+
+<!-- YAML
+added: v6.3.0
+-->
 
-This message is published after the client receives a pong frame.
+Published after the client receives a pong frame.
 
-```js
-import diagnosticsChannel from 'diagnostics_channel'
+* `message` {Object}
+  * `payload` {Buffer|undefined} The optional application data carried by the
+    frame.
+  * `websocket` {WebSocket} The `WebSocket` instance.
+
+```mjs
+import diagnosticsChannel from 'node:diagnostics_channel'
 
 diagnosticsChannel.channel('undici:websocket:pong').subscribe(({ payload, websocket }) => {
-  // a Buffer or undefined, containing the optional application data of the frame
   console.log(payload)
-  console.log(websocket) // the WebSocket instance
 })
 ```
 
-## `undici:proxy:connected`
-
-This message is published after the `ProxyAgent` establishes a connection to the proxy server.
-
-```js
-import diagnosticsChannel from 'diagnostics_channel'
+## Event: `'undici:proxy:connected'`
 
-diagnosticsChannel.channel('undici:proxy:connected').subscribe(({ socket, connectParams }) => {
-  console.log(socket)
-  console.log(connectParams)
-  // const { origin, port, path, signal, headers, servername } = connectParams
-})
-```
-
-## `undici:request:pending-requests`
+<!-- YAML
+added: v7.17.0
+-->
 
-This message is published when the deduplicate interceptor's pending request map changes. This is useful for monitoring and debugging request deduplication behavior.
+Published after a [`ProxyAgent`][] has established a tunnel to the proxy server.
 
-The deduplicate interceptor automatically deduplicates concurrent requests for the same resource. When multiple identical requests are made while one is already in-flight, only one request is sent to the origin server, and all waiting handlers receive the same response.
+* `message` {Object}
+  * `socket` {net.Socket} The socket connected to the proxy.
+  * `connectParams` {Object} The parameters used to establish the tunnel.
+    * `origin` {string|URL} The proxy origin.
+    * `port` {string} The proxy port.
+    * `path` {string} The requested tunnel target, e.g. `'example.com:443'`.
+    * `signal` {AbortSignal|undefined} The signal associated with the request.
+    * `headers` {Object} The headers sent in the `CONNECT` request.
+    * `servername` {string|undefined} The TLS server name used for the proxy.
 
-```js
-import diagnosticsChannel from 'diagnostics_channel'
+```mjs
+import diagnosticsChannel from 'node:diagnostics_channel'
 
-diagnosticsChannel.channel('undici:request:pending-requests').subscribe(({ type, size, key }) => {
-  console.log(type)  // 'added' or 'removed'
-  console.log(size)  // current number of pending requests
-  console.log(key)   // the deduplication key for this request
+diagnosticsChannel.channel('undici:proxy:connected').subscribe(({ socket, connectParams }) => {
+  const { origin, port, path, signal, headers, servername } = connectParams
 })
 ```
 
-### Event Properties
+## Event: `'undici:request:pending-requests'`
 
-- `type` (`string`): Either `'added'` when a new pending request is registered, or `'removed'` when a pending request completes (successfully or with an error).
-- `size` (`number`): The current number of pending requests after the change.
-- `key` (`string`): The deduplication key for the request, composed of the origin, method, path, and request headers.
+<!-- YAML
+added: v6.3.0
+-->
 
-### Example: Monitoring Request Deduplication
+Published when the [`dedupe`][] interceptor's set of pending requests changes.
+The interceptor coalesces concurrent identical requests so that only one reaches
+the origin; this channel exposes that bookkeeping for monitoring and debugging.
 
-```js
-import diagnosticsChannel from 'diagnostics_channel'
+* `message` {Object}
+  * `type` {string} Either `'added'` when a new pending request is registered, or
+    `'removed'` when a pending request completes, whether successfully or with an
+    error.
+  * `size` {number} The number of pending requests after the change.
+  * `key` {string} The deduplication key for the request, composed of the origin,
+    method, path, and request headers.
 
-const channel = diagnosticsChannel.channel('undici:request:pending-requests')
+```mjs
+import diagnosticsChannel from 'node:diagnostics_channel'
 
-channel.subscribe(({ type, size, key }) => {
+diagnosticsChannel.channel('undici:request:pending-requests').subscribe(({ type, size, key }) => {
   if (type === 'added') {
     console.log(`New pending request: ${key} (${size} total pending)`)
   } else {
@@ -309,7 +500,16 @@ channel.subscribe(({ type, size, key }) => {
 })
 ```
 
-This can be useful for:
-- Verifying that request deduplication is working as expected
-- Monitoring the number of concurrent in-flight requests
-- Debugging deduplication behavior in production environments
+This is useful for verifying that deduplication is working, monitoring the number
+of concurrent in-flight requests, and debugging deduplication behaviour in
+production.
+
+[`'undici:client:beforeConnect'`]: #event-undiciclientbeforeconnect
+[`'undici:request:create'`]: #event-undicirequestcreate
+[`'undici:request:headers'`]: #event-undicirequestheaders
+[`ProxyAgent`]: ProxyAgent.md#class-proxyagent
+[`WebSocket`]: WebSocket.md#class-websocket
+[`dedupe`]: Dispatcher.md#dedupe
+[`diagnostics_channel`]: https://nodejs.org/api/diagnostics_channel.html
+[`socket.address()`]: https://nodejs.org/api/net.html#socketaddress
+[Debug]: Debug.md
diff --git a/docs/docs/api/Dispatcher.md b/docs/docs/api/Dispatcher.md
index eab6fa58dfa..853c718c3ee 100644
--- a/docs/docs/api/Dispatcher.md
+++ b/docs/docs/api/Dispatcher.md
@@ -1,34 +1,61 @@
 # Dispatcher
 
-Extends: `events.EventEmitter`
+<!--introduced_in=v4.0.0-->
 
-Dispatcher is the core API used to dispatch requests.
+<!--type=module-->
 
-Requests are not guaranteed to be dispatched in order of invocation.
+<!-- source_link=lib/dispatcher/dispatcher.js -->
 
-## Instance Methods
+> Stability: 2 - Stable
 
-### `Dispatcher.close([callback]): Promise`
+`Dispatcher` is the core abstraction used to dispatch HTTP requests in undici.
+It extends [`EventEmitter`][] and defines the low-level [`dispatch()`][] contract
+along with the higher-level [`request()`][], [`stream()`][], [`pipeline()`][],
+[`connect()`][], and [`upgrade()`][] methods that every concrete dispatcher
+provides.
 
-Closes the dispatcher and gracefully waits for enqueued requests to complete before resolving.
+`Dispatcher` itself is abstract: its [`dispatch()`][], [`close()`][], and
+[`destroy()`][] methods throw `Error: not implemented`. Concrete dispatchers such
+as [`Client`][], [`Pool`][], [`BalancedPool`][], and [`Agent`][] implement the
+contract and are what application code instantiates. Requests are not guaranteed
+to be dispatched in the order in which they are invoked.
 
-Arguments:
+```mjs
+import { Dispatcher, Agent } from 'undici'
 
-* **callback** `(error: Error | null, data: null) => void` (optional)
+const dispatcher = new Agent()
+console.log(dispatcher instanceof Dispatcher) // true
+```
 
-Returns: `void | Promise<null>` - Only returns a `Promise` if no `callback` argument was passed
+## Class: `Dispatcher`
 
-```js
-dispatcher.close() // -> Promise
-dispatcher.close(() => {}) // -> void
-```
+<!-- YAML
+added: v4.0.0
+-->
+
+* Extends: {EventEmitter}
+
+Base dispatcher class. Concrete dispatchers extend it and implement the
+[`dispatch()`][] method on which the other request helpers are built.
+
+### `dispatcher.close([callback])`
+
+<!-- YAML
+added: v4.0.0
+-->
 
-#### Example - Request resolves before Client closes
+* `callback` {Function} (optional) Invoked once the dispatcher is closed.
+  * `error` {Error|null}
+* Returns: {Promise} A `Promise` is returned only when `callback` is omitted. It
+  resolves with `void` once the dispatcher is closed.
 
-```js
-import { createServer } from 'http'
+Closes the dispatcher and gracefully waits for enqueued requests to complete
+before resolving or invoking `callback`.
+
+```mjs
+import { createServer } from 'node:http'
 import { Client } from 'undici'
-import { once } from 'events'
+import { once } from 'node:events'
 
 const server = createServer((request, response) => {
   response.end('undici')
@@ -39,10 +66,7 @@ await once(server, 'listening')
 const client = new Client(`http://localhost:${server.address().port}`)
 
 try {
-  const { body } = await client.request({
-      path: '/',
-      method: 'GET'
-  })
+  const { body } = await client.request({ path: '/', method: 'GET' })
   body.setEncoding('utf8')
   body.on('data', console.log)
 } catch (error) {}
@@ -53,40 +77,41 @@ console.log('Client closed')
 server.close()
 ```
 
-### `Dispatcher.connect(options[, callback])`
-
-Starts two-way communications with the requested resource using [HTTP CONNECT](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/CONNECT).
-
-Arguments:
-
-* **options** `ConnectOptions`
-* **callback** `(err: Error | null, data: ConnectData | null) => void` (optional)
-
-Returns: `void | Promise<ConnectData>` - Only returns a `Promise` if no `callback` argument was passed
-
-#### Parameter: `ConnectOptions`
-
-* **path** `string`
-* **headers** `UndiciHeaders` (optional) - Default: `null`
-* **signal** `AbortSignal | events.EventEmitter | null` (optional) - Default: `null`
-* **opaque** `unknown` (optional) - This argument parameter is passed through to `ConnectData`
-
-#### Parameter: `ConnectData`
-
-* **statusCode** `number`
-* **headers** `Record<string, string | string[] | undefined>`
-* **socket** `stream.Duplex`
-* **opaque** `unknown`
-
-#### Example - Connect request with echo
-
-```js
-import { createServer } from 'http'
+### `dispatcher.connect(options[, callback])`
+
+<!-- YAML
+added: v4.0.0
+-->
+
+* `options` {Object}
+  * `origin` {string|URL} The origin to connect to.
+  * `path` {string} The request path.
+  * `headers` {UndiciHeaders} Request headers. **Default:** `null`.
+  * `signal` {AbortSignal|EventEmitter|null} A signal used to abort the request.
+    **Default:** `null`.
+  * `opaque` {any} An opaque value passed through to the returned `ConnectData`.
+  * `responseHeaders` {string|null} Set to `'raw'` to return the response headers
+    as a raw array instead of an object. **Default:** `null`.
+* `callback` {Function} (optional) Invoked when the connection is established.
+  * `error` {Error|null}
+  * `data` {Object}
+    * `statusCode` {number}
+    * `headers` {Object} The response headers.
+    * `socket` {Duplex} The established socket.
+    * `opaque` {any} The `opaque` value passed in `options`.
+* Returns: {Promise} A `Promise` is returned only when `callback` is omitted. It
+  resolves with the `data` object described above.
+
+Starts two-way communications with the requested resource using the
+[HTTP `CONNECT`][] method.
+
+```mjs
+import { createServer } from 'node:http'
 import { Client } from 'undici'
-import { once } from 'events'
+import { once } from 'node:events'
 
 const server = createServer((request, response) => {
-  throw Error('should never get here')
+  throw new Error('should never get here')
 }).listen()
 
 server.on('connect', (req, socket, head) => {
@@ -107,9 +132,7 @@ await once(server, 'listening')
 const client = new Client(`http://localhost:${server.address().port}`)
 
 try {
-  const { socket } = await client.connect({
-    path: '/'
-  })
+  const { socket } = await client.connect({ path: '/' })
   const wanted = 'Body'
   let data = ''
   socket.on('data', d => { data += d })
@@ -120,35 +143,39 @@ try {
   })
   socket.write(wanted)
   socket.end()
-} catch (error) { }
+} catch (error) {}
 ```
 
-### `Dispatcher.destroy([error, callback]): Promise`
-
-Destroy the dispatcher abruptly with the given error. All the pending and running requests will be asynchronously aborted and error. Since this operation is asynchronously dispatched there might still be some progress on dispatched requests.
+### `dispatcher.destroy([error[, callback]])`
 
-Both arguments are optional; the method can be called in four different ways:
+<!-- YAML
+added: v4.0.0
+-->
 
-Arguments:
+* `error` {Error|null} (optional) The error with which pending requests are
+  rejected. **Default:** `null`.
+* `callback` {Function} (optional) Invoked once the socket is closed.
+* Returns: {Promise} A `Promise` is returned only when `callback` is omitted. It
+  resolves with `void` once the dispatcher is destroyed.
 
-* **error** `Error | null` (optional)
-* **callback** `(error: Error | null, data: null) => void` (optional)
+Destroys the dispatcher abruptly with the given `error`. All pending and running
+requests are asynchronously aborted and rejected. Because the operation is
+dispatched asynchronously, dispatched requests may still make some progress
+before being aborted.
 
-Returns: `void | Promise<void>` - Only returns a `Promise` if no `callback` argument was passed
+Both arguments are optional, so the method can be called in four ways:
 
-```js
+```mjs
 dispatcher.destroy() // -> Promise
 dispatcher.destroy(new Error()) // -> Promise
 dispatcher.destroy(() => {}) // -> void
 dispatcher.destroy(new Error(), () => {}) // -> void
 ```
 
-#### Example - Request is aborted when Client is destroyed
-
-```js
-import { createServer } from 'http'
+```mjs
+import { createServer } from 'node:http'
 import { Client } from 'undici'
-import { once } from 'events'
+import { once } from 'node:events'
 
 const server = createServer((request, response) => {
   response.end()
@@ -159,10 +186,7 @@ await once(server, 'listening')
 const client = new Client(`http://localhost:${server.address().port}`)
 
 try {
-  const request = client.request({
-    path: '/',
-    method: 'GET'
-  })
+  const request = client.request({ path: '/', method: 'GET' })
   client.destroy()
     .then(() => {
       console.log('Client destroyed')
@@ -174,86 +198,107 @@ try {
 }
 ```
 
-### `Dispatcher.dispatch(options, handler)`
-
-This is the low level API which all the preceding APIs are implemented on top of.
-This API is expected to evolve through semver-major versions and is less stable than the preceding higher level APIs.
-It is primarily intended for library developers who implement higher level APIs on top of this.
-
-Arguments:
-
-* **options** `DispatchOptions`
-* **handler** `DispatchHandler`
-
-Returns: `Boolean` - `false` if dispatcher is busy and further dispatch calls won't make any progress until the `'drain'` event has been emitted.
-
-#### Parameter: `DispatchOptions`
-
-* **origin** `string | URL`
-* **path** `string`
-* **method** `string`
-* **reset** `boolean` (optional) - Default: `false` - If `false`, the request will attempt to create a long-living connection by sending the `connection: keep-alive` header,otherwise will attempt to close it immediately after response by sending `connection: close` within the request and closing the socket afterwards.
-* **body** `string | Buffer | Uint8Array | stream.Readable | Iterable | AsyncIterable | null` (optional) - Default: `null`
-* **headers** `UndiciHeaders` (optional) - Default: `null`.
-* **query** `Record<string, any> | null` (optional) - Default: `null` - Query string params to be embedded in the request URL. Note that both keys and values of query are encoded using `encodeURIComponent`. If for some reason you need to send them unencoded, embed query params into path directly instead.
-* **idempotent** `boolean` (optional) - Default: `true` if `method` is `'HEAD'` or `'GET'` - Whether the requests can be safely retried or not. If `false` the request won't be sent until all preceding requests in the pipeline has completed.
-* **blocking** `boolean` (optional) - Default: `method !== 'HEAD'` - Whether the response is expected to take a long time and would end up blocking the pipeline. When this is set to `true` further pipelining will be avoided on the same connection until headers have been received.
-* **upgrade** `string | null` (optional) - Default: `null` - Upgrade the request. Should be used to specify the kind of upgrade i.e. `'Websocket'`.
-* **bodyTimeout** `number | null` (optional) - The timeout after which a request will time out, in milliseconds. Monitors time between receiving body data. Use `0` to disable it entirely. Defaults to 300 seconds.
-* **headersTimeout** `number | null` (optional) - The amount of time, in milliseconds, the parser will wait to receive the complete HTTP headers while not sending the request. Defaults to 300 seconds.
-* **expectContinue** `boolean` (optional) - Default: `false` - For H2, it appends the expect: 100-continue header, and halts the request body until a 100-continue is received from the remote server
-
-#### Parameter: `DispatchHandler`
-
-* **onRequestStart** `(controller: DispatchController, context: object) => void` - Invoked before request is dispatched on socket. May be invoked multiple times when a request is retried when the request at the head of the pipeline fails.
-* **onRequestUpgrade** `(controller: DispatchController, statusCode: number, headers: Record<string, string | string[]>, socket: Duplex) => void` (optional) - Invoked when request is upgraded. Required if `DispatchOptions.upgrade` is defined or `DispatchOptions.method === 'CONNECT'`.
-* **onResponseStart** `(controller: DispatchController, statusCode: number, headers: Record<string, string | string []>, statusMessage?: string) => void` - Invoked when statusCode and headers have been received. May be invoked multiple times due to 1xx informational headers. Not required for `upgrade` requests. Any return value is ignored.
-* **onResponseData** `(controller: DispatchController, chunk: Buffer) => void` - Invoked when response payload data is received. Not required for `upgrade` requests.
-* **onResponseEnd** `(controller: DispatchController, trailers: Record<string, string | string[]>) => void` - Invoked when response payload and trailers have been received and the request has completed. Not required for `upgrade` requests.
-* **onResponseError** `(controller: DispatchController, error: Error) => void` - Invoked when an error has occurred. May not throw.
-* **onBodySent** `(chunk: Buffer) => void` (optional) - Invoked when a chunk of the request body is sent.
-
-#### Migration from legacy handler API
-
-If you were previously using `onConnect/onHeaders/onData/onComplete/onError`, switch to the new callbacks:
-
-- `onConnect(abort)` → `onRequestStart(controller)` and call `controller.abort(reason)`
-- `onHeaders(status, rawHeaders, resume, statusText)` → `onResponseStart(controller, status, headers, statusText)`
-- `onData(chunk)` → `onResponseData(controller, chunk)`
-- `onComplete(trailers)` → `onResponseEnd(controller, trailers)`
-- `onError(err)` → `onResponseError(controller, err)`
-- `onUpgrade(status, rawHeaders, socket)` → `onRequestUpgrade(controller, status, headers, socket)`
-
-To access raw header arrays (for preserving duplicates/casing), read them from the controller:
-
-- `controller.rawHeaders` for response headers
-- `controller.rawTrailers` for trailers
-
-Pause/resume now uses the controller:
-
-- Call `controller.pause()` and `controller.resume()` instead of returning `false` from handlers.
-
-#### Compatibility notes
-
-Undici now stores the global dispatcher under `Symbol.for('undici.globalDispatcher.2')`.
-This avoids conflicts with runtimes (such as Node.js built-in `fetch`) that still rely on the legacy dispatcher handler interface.
-
-`setGlobalDispatcher()` also mirrors the configured dispatcher to `Symbol.for('undici.globalDispatcher.1')` using a `Dispatcher1Wrapper`, so Node's built-in `fetch` can keep using the legacy handler contract.
-
-If you need to expose a new dispatcher/agent to legacy v1 handler consumers (`onConnect/onHeaders/onData/onComplete/onError/onUpgrade`), use `Dispatcher1Wrapper`:
-
-```js
-import { Agent, Dispatcher1Wrapper } from 'undici'
-
-const legacyCompatibleDispatcher = new Dispatcher1Wrapper(new Agent())
-```
-
-#### Example 1 - Dispatch GET request
-
-```js
-import { createServer } from 'http'
+### `dispatcher.dispatch(options, handler)`
+
+<!-- YAML
+added: v4.0.0
+-->
+
+* `options` {Object}
+  * `origin` {string|URL} (optional) The origin to dispatch the request to.
+  * `path` {string} The request path.
+  * `method` {string} The HTTP method, e.g. `'GET'` or `'POST'`.
+  * `body` {string|Buffer|Uint8Array|Readable|FormData|null} The request body.
+    **Default:** `null`.
+  * `headers` {UndiciHeaders} Request headers. **Default:** `null`.
+  * `query` {Object} Query string parameters embedded into the request URL. Both
+    keys and values are encoded with `encodeURIComponent`. **Default:** `null`.
+  * `idempotent` {boolean} Whether the request can be safely retried. If `false`,
+    the request is not sent until all preceding requests in the pipeline have
+    completed. **Default:** `true` when `method` is `'HEAD'` or `'GET'`.
+  * `blocking` {boolean} Whether the response is expected to block the pipeline.
+    When `true`, further pipelining on the same connection is avoided until
+    headers have been received. **Default:** `method !== 'HEAD'`.
+  * `typeOfService` {number|null} The IP Type of Service (ToS) value for the
+    request socket. Must be an integer between `0` and `255`. **Default:** `0`.
+  * `upgrade` {boolean|string|null} Upgrades the request, e.g. to `'Websocket'`.
+    **Default:** `null`, or the request method when it is `'CONNECT'`.
+  * `headersTimeout` {number|null} The time, in milliseconds, the parser waits to
+    receive the complete HTTP headers. Defaults to 300 seconds.
+  * `bodyTimeout` {number|null} The time, in milliseconds, after which the request
+    times out while receiving body data. Monitors the time between body chunks.
+    Use `0` to disable it entirely. Defaults to 300 seconds.
+  * `reset` {boolean} Whether the request should establish a keep-alive
+    connection. **Default:** `false`.
+  * `expectContinue` {boolean} For HTTP/2, appends the `expect: 100-continue`
+    header and halts the request body until a `100 Continue` is received from the
+    remote server. **Default:** `false`.
+* `handler` {Object} A set of callbacks invoked over the request lifecycle.
+  * `onRequestStart` {Function} Invoked before the request is dispatched on the
+    socket. May be invoked multiple times when the request is retried.
+    * `controller` {DispatchController}
+    * `context` {any}
+  * `onRequestUpgrade` {Function} (optional) Invoked when the request is upgraded.
+    Required when `options.upgrade` is set or `options.method` is `'CONNECT'`.
+    * `controller` {DispatchController}
+    * `statusCode` {number}
+    * `headers` {Object}
+    * `socket` {Duplex}
+  * `onResponseStart` {Function} (optional) Invoked when the status code and
+    headers have been received. May be invoked multiple times for 1xx
+    informational responses. Not used for `upgrade` requests.
+    * `controller` {DispatchController}
+    * `statusCode` {number}
+    * `headers` {Object}
+    * `statusMessage` {string} (optional)
+  * `onResponseData` {Function} (optional) Invoked when response payload data is
+    received. Not used for `upgrade` requests.
+    * `controller` {DispatchController}
+    * `chunk` {Buffer}
+  * `onResponseEnd` {Function} (optional) Invoked when the response payload and
+    trailers have been received and the request has completed. Not used for
+    `upgrade` requests.
+    * `controller` {DispatchController}
+    * `trailers` {Object}
+  * `onResponseError` {Function} (optional) Invoked when an error occurs. Must not
+    throw.
+    * `controller` {DispatchController}
+    * `error` {Error}
+  * `onResponseStarted` {Function} (optional) Invoked when the response is
+    received, before headers have been read.
+  * `onBodySent` {Function} (optional) Invoked when a chunk of the request body is
+    sent. May be invoked multiple times for chunked requests.
+    * `chunk` {Buffer}
+  * `onRequestSent` {Function} (optional) Invoked after the request body is fully
+    sent.
+* Returns: {boolean} `false` when the dispatcher is busy and further `dispatch()`
+  calls will make no progress until the [`'drain'`][] event is emitted.
+
+This is the low-level API on which all the higher-level methods are built. This
+API is expected to evolve through semver-major versions and is less stable than
+the higher-level methods. It is primarily intended for library developers who
+implement higher-level APIs on top of it.
+
+The `controller` passed to each handler is a `DispatchController` with the
+following shape:
+
+* `aborted` {boolean} Whether the request has been aborted.
+* `paused` {boolean} Whether the request is paused.
+* `reason` {Error|null} The reason the request was aborted, if any.
+* `rawHeaders` {Buffer[]|string[]|Object|null} The raw response headers,
+  preserving duplicates and casing.
+* `rawTrailers` {Buffer[]|string[]|Object|null} The raw response trailers.
+* `abort(reason)` Aborts the request with the given `reason`.
+* `pause()` Pauses the response stream.
+* `resume()` Resumes the response stream.
+
+Call `controller.pause()` and `controller.resume()` to apply backpressure rather
+than returning `false` from a handler.
+
+```mjs
+import { createServer } from 'node:http'
 import { Client } from 'undici'
-import { once } from 'events'
+import { once } from 'node:events'
 
 const server = createServer((request, response) => {
   response.end('Hello, World!')
@@ -268,112 +313,7 @@ const data = []
 client.dispatch({
   path: '/',
   method: 'GET',
-  headers: {
-    'x-foo': 'bar'
-  }
-}, {
-  onRequestStart: () => {
-    console.log('Connected!')
-  },
-  onResponseError: (_controller, error) => {
-    console.error(error)
-  },
-  onResponseStart: (_controller, statusCode, headers) => {
-    console.log(`onResponseStart | statusCode: ${statusCode} | headers: ${JSON.stringify(headers)}`)
-  },
-  onResponseData: (_controller, chunk) => {
-    console.log('onResponseData: chunk received')
-    data.push(chunk)
-  },
-  onResponseEnd: (_controller, trailers) => {
-    console.log(`onResponseEnd | trailers: ${JSON.stringify(trailers)}`)
-    const res = Buffer.concat(data).toString('utf8')
-    console.log(`Data: ${res}`)
-    client.close()
-    server.close()
-  }
-})
-```
-
-#### Example 2 - Dispatch Upgrade Request
-
-```js
-import { createServer } from 'http'
-import { Client } from 'undici'
-import { once } from 'events'
-
-const server = createServer((request, response) => {
-  response.end()
-}).listen()
-
-await once(server, 'listening')
-
-server.on('upgrade', (request, socket, head) => {
-  console.log('Node.js Server - upgrade event')
-  socket.write('HTTP/1.1 101 Web Socket Protocol Handshake\r\n')
-  socket.write('Upgrade: WebSocket\r\n')
-  socket.write('Connection: Upgrade\r\n')
-  socket.write('\r\n')
-  socket.end()
-})
-
-const client = new Client(`http://localhost:${server.address().port}`)
-
-client.dispatch({
-  path: '/',
-  method: 'GET',
-  upgrade: 'websocket'
-}, {
-  onRequestStart: () => {
-    console.log('Undici Client - onRequestStart')
-  },
-  onResponseError: () => {
-    console.log('onResponseError') // shouldn't print
-  },
-  onRequestUpgrade: (_controller, statusCode, headers, socket) => {
-    console.log('Undici Client - onRequestUpgrade')
-    console.log(`onRequestUpgrade Headers: ${JSON.stringify(headers)}`)
-    socket.on('data', buffer => {
-      console.log(buffer.toString('utf8'))
-    })
-    socket.on('end', () => {
-      client.close()
-      server.close()
-    })
-    socket.end()
-  }
-})
-```
-
-#### Example 3 - Dispatch POST request
-
-```js
-import { createServer } from 'http'
-import { Client } from 'undici'
-import { once } from 'events'
-
-const server = createServer((request, response) => {
-  request.on('data', (data) => {
-    console.log(`Request Data: ${data.toString('utf8')}`)
-    const body = JSON.parse(data)
-    body.message = 'World'
-    response.end(JSON.stringify(body))
-  })
-}).listen()
-
-await once(server, 'listening')
-
-const client = new Client(`http://localhost:${server.address().port}`)
-
-const data = []
-
-client.dispatch({
-  path: '/',
-  method: 'POST',
-  headers: {
-    'content-type': 'application/json'
-  },
-  body: JSON.stringify({ message: 'Hello' })
+  headers: { 'x-foo': 'bar' }
 }, {
   onRequestStart: () => {
     console.log('Connected!')
@@ -382,55 +322,52 @@ client.dispatch({
     console.error(error)
   },
   onResponseStart: (_controller, statusCode, headers) => {
-    console.log(`onResponseStart | statusCode: ${statusCode} | headers: ${JSON.stringify(headers)}`)
+    console.log(`statusCode: ${statusCode} | headers: ${JSON.stringify(headers)}`)
   },
   onResponseData: (_controller, chunk) => {
-    console.log('onResponseData: chunk received')
     data.push(chunk)
   },
   onResponseEnd: (_controller, trailers) => {
-    console.log(`onResponseEnd | trailers: ${JSON.stringify(trailers)}`)
-    const res = Buffer.concat(data).toString('utf8')
-    console.log(`Response Data: ${res}`)
+    console.log(`trailers: ${JSON.stringify(trailers)}`)
+    console.log(`Data: ${Buffer.concat(data).toString('utf8')}`)
     client.close()
     server.close()
   }
 })
 ```
 
-### `Dispatcher.pipeline(options, handler)`
-
-For easy use with [stream.pipeline](https://nodejs.org/api/stream.html#streampipelinesource-transforms-destination-options). The `handler` argument should return a `Readable` from which the result will be read. Usually it should just return the `body` argument unless some kind of transformation needs to be performed based on e.g. `headers` or `statusCode`. The `handler` should validate the response and save any required state. If there is an error, it should be thrown. The function returns a `Duplex` which writes to the request and reads from the response.
-
-Arguments:
-
-* **options** `PipelineOptions`
-* **handler** `(data: PipelineHandlerData) => stream.Readable`
-
-Returns: `stream.Duplex`
-
-#### Parameter: PipelineOptions
-
-Extends: [`RequestOptions`](/docs/docs/api/Dispatcher.md#parameter-requestoptions)
-
-* **objectMode** `boolean` (optional) - Default: `false` - Set to `true` if the `handler` will return an object stream.
-
-#### Parameter: PipelineHandlerData
-
-* **statusCode** `number`
-* **headers** `Record<string, string | string[] | undefined>`
-* **opaque** `unknown`
-* **body** `stream.Readable`
-* **context** `object`
-* **onInfo** `({statusCode: number, headers: Record<string, string | string[]>}) => void | null` (optional) - Default: `null` - Callback collecting all the info headers (HTTP 100-199) received.
-
-#### Example 1 - Pipeline Echo
-
-```js
-import { Readable, Writable, PassThrough, pipeline } from 'stream'
-import { createServer } from 'http'
+### `dispatcher.pipeline(options, handler)`
+
+<!-- YAML
+added: v4.0.0
+-->
+
+* `options` {Object} Accepts every field of [`dispatcher.request()`][]'s
+  `options`, plus:
+  * `objectMode` {boolean} Set to `true` when `handler` returns an object stream.
+    **Default:** `false`.
+* `handler` {Function} Returns a `Readable` from which the result is read.
+  * `data` {Object}
+    * `statusCode` {number}
+    * `headers` {Object} The response headers.
+    * `opaque` {any} The `opaque` value passed in `options`.
+    * `body` {Readable} The response body.
+    * `context` {Object}
+  * Returns: {Readable}
+* Returns: {Duplex} A duplex stream that writes to the request and reads from the
+  response.
+
+For easy use with [`stream.pipeline()`][]. The `handler` should return a
+`Readable` from which the result is read. Usually it returns the `body` directly,
+unless a transformation is needed based on, for example, `headers` or
+`statusCode`. The `handler` should validate the response and save any required
+state; if there is an error, it should be thrown.
+
+```mjs
+import { Readable, Writable, PassThrough, pipeline } from 'node:stream'
+import { createServer } from 'node:http'
 import { Client } from 'undici'
-import { once } from 'events'
+import { once } from 'node:events'
 
 const server = createServer((request, response) => {
   request.pipe(response)
@@ -449,10 +386,7 @@ pipeline(
       this.push(null)
     }
   }),
-  client.pipeline({
-    path: '/',
-    method: 'GET'
-  }, ({ statusCode, headers, body }) => {
+  client.pipeline({ path: '/', method: 'GET' }, ({ statusCode, headers, body }) => {
     console.log(`response received ${statusCode}`)
     console.log('headers', headers)
     return pipeline(body, new PassThrough(), () => {})
@@ -471,79 +405,72 @@ pipeline(
     if (error) {
       console.error(error)
     }
-
     client.close()
     server.close()
   }
 )
 ```
 
-### `Dispatcher.request(options[, callback])`
-
-Performs a HTTP request.
-
-Non-idempotent requests will not be pipelined in order
-to avoid indirect failures.
-
-Idempotent requests will be automatically retried if
-they fail due to indirect failure from the request
-at the head of the pipeline. This does not apply to
-idempotent requests with a stream request body.
-
-All response bodies must always be fully consumed or destroyed.
-
-Arguments:
-
-* **options** `RequestOptions`
-* **callback** `(error: Error | null, data: ResponseData) => void` (optional)
-
-Returns: `void | Promise<ResponseData>` - Only returns a `Promise` if no `callback` argument was passed.
-
-#### Parameter: `RequestOptions`
-
-Extends: [`DispatchOptions`](/docs/docs/api/Dispatcher.md#parameter-dispatchoptions)
-
-* **opaque** `unknown` (optional) - Default: `null` - Used for passing through context to `ResponseData`.
-* **signal** `AbortSignal | events.EventEmitter | null` (optional) - Default: `null`.
-* **onInfo** `({statusCode: number, headers: Record<string, string | string[]>}) => void | null` (optional) - Default: `null` - Callback collecting all the info headers (HTTP 100-199) received.
-
-The `RequestOptions.method` property should not be value `'CONNECT'`.
-
-#### Parameter: `ResponseData`
-
-* **statusCode** `number`
-* **statusText** `string` - The status message from the response (e.g., "OK", "Not Found").
-* **headers** `Record<string, string | string[]>` - Note that all header keys are lower-cased, e.g. `content-type`.
-* **body** `stream.Readable` which also implements [the body mixin from the Fetch Standard](https://fetch.spec.whatwg.org/#body-mixin).
-* **trailers** `Record<string, string>` - This object starts out
-  as empty and will be mutated to contain trailers after `body` has emitted `'end'`.
-* **opaque** `unknown`
-* **context** `object`
-
-`body` contains the following additional [body mixin](https://fetch.spec.whatwg.org/#body-mixin) methods and properties:
-
-* [`.arrayBuffer()`](https://fetch.spec.whatwg.org/#dom-body-arraybuffer)
-* [`.blob()`](https://fetch.spec.whatwg.org/#dom-body-blob)
-* [`.bytes()`](https://fetch.spec.whatwg.org/#dom-body-bytes)
-* [`.json()`](https://fetch.spec.whatwg.org/#dom-body-json)
-* [`.text()`](https://fetch.spec.whatwg.org/#dom-body-text)
-* `body`
-* `bodyUsed`
-
-`body` can not be consumed twice. For example, calling `text()` after `json()` throws `TypeError`.
-
-`body` contains the following additional extensions:
-
-- `dump({ limit: Integer })`, dump the response by reading up to `limit` bytes without killing the socket (optional) - Default: 131072.
-
-Note that body will still be a `Readable` even if it is empty, but attempting to deserialize it with `json()` will result in an exception. Recommended way to ensure there is a body to deserialize is to check if status code is not 204, and `content-type` header starts with `application/json`.
-
-#### Example 1 - Basic GET Request
-
-```js
-import { createServer } from 'http'
+### `dispatcher.request(options[, callback])`
+
+<!-- YAML
+added: v4.0.0
+-->
+
+* `options` {Object} Accepts every field of [`dispatcher.dispatch()`][]'s
+  `options`, plus:
+  * `opaque` {any} A value passed through to the returned response data.
+    **Default:** `null`.
+  * `signal` {AbortSignal|EventEmitter|null} A signal used to abort the request.
+    **Default:** `null`.
+  * `onInfo` {Function|null} Invoked for each informational (1xx) response
+    received. **Default:** `null`.
+    * `info` {Object}
+      * `statusCode` {number}
+      * `headers` {Object}
+  * `responseHeaders` {string|null} Set to `'raw'` to return the response headers
+    as a raw array. **Default:** `null`.
+  * `highWaterMark` {number} The high water mark of the response body stream.
+    **Default:** `65536` (64 KiB).
+* `callback` {Function} (optional) Invoked when the response is received.
+  * `error` {Error|null}
+  * `data` {Object}
+    * `statusCode` {number}
+    * `statusText` {string} The status message, e.g. `'OK'` or `'Not Found'`.
+    * `headers` {Object} The response headers. All keys are lower-cased.
+    * `body` {Readable} The response body, which also implements the
+      [body mixin][] from the Fetch Standard.
+    * `trailers` {Object} Starts out empty and is mutated to contain the trailers
+      after `body` emits `'end'`.
+    * `opaque` {any} The `opaque` value passed in `options`.
+    * `context` {Object}
+* Returns: {Promise} A `Promise` is returned only when `callback` is omitted. It
+  resolves with the `data` object described above.
+
+Performs an HTTP request. `options.method` must not be `'CONNECT'`.
+
+Non-idempotent requests are not pipelined, to avoid indirect failures. Idempotent
+requests are automatically retried if they fail due to an indirect failure from
+the request at the head of the pipeline; this does not apply to idempotent
+requests with a stream request body. All response bodies must always be fully
+consumed or destroyed.
+
+The `body` exposes the following [body mixin][] methods and properties:
+[`.arrayBuffer()`][], [`.blob()`][], [`.bytes()`][], [`.json()`][],
+[`.text()`][], `body`, and `bodyUsed`. A body cannot be consumed twice; for
+example, calling `text()` after `json()` throws a `TypeError`. The body also
+provides `dump({ limit })`, which discards up to `limit` bytes (default
+`131072`) without destroying the socket.
+
+The body is always a `Readable`, even when empty. Deserializing an empty body
+with `json()` throws. To guard against this, verify the status code is not `204`
+and the `content-type` header starts with `application/json` before calling
+`json()`.
+
+```mjs
+import { createServer } from 'node:http'
 import { Client } from 'undici'
-import { once } from 'events'
+import { once } from 'node:events'
 
 const server = createServer((request, response) => {
   response.end('Hello, World!')
@@ -574,107 +501,28 @@ try {
 }
 ```
 
-#### Example 2 - Aborting a request
-
-> Node.js v15+ is required to run this example
+A request can be aborted with an `AbortSignal`, with any `EventEmitter` that
+emits an `'abort'` event, or by destroying the response body:
 
-```js
-import { createServer } from 'http'
+```mjs
 import { Client } from 'undici'
-import { once } from 'events'
-
-const server = createServer((request, response) => {
-  response.end('Hello, World!')
-}).listen()
-
-await once(server, 'listening')
 
-const client = new Client(`http://localhost:${server.address().port}`)
+const client = new Client('http://localhost:3000')
 const abortController = new AbortController()
 
 try {
-  client.request({
-    path: '/',
-    method: 'GET',
-    signal: abortController.signal
-  })
+  client.request({ path: '/', method: 'GET', signal: abortController.signal })
 } catch (error) {
-  console.error(error) // should print an RequestAbortedError
-  client.close()
-  server.close()
+  console.error(error) // RequestAbortedError
 }
 
 abortController.abort()
 ```
 
-Alternatively, any `EventEmitter` that emits an `'abort'` event may be used as an abort controller:
-
-```js
-import { createServer } from 'http'
-import { Client } from 'undici'
-import EventEmitter, { once } from 'events'
-
-const server = createServer((request, response) => {
-  response.end('Hello, World!')
-}).listen()
-
-await once(server, 'listening')
-
-const client = new Client(`http://localhost:${server.address().port}`)
-const ee = new EventEmitter()
-
-try {
-  client.request({
-    path: '/',
-    method: 'GET',
-    signal: ee
-  })
-} catch (error) {
-  console.error(error) // should print an RequestAbortedError
-  client.close()
-  server.close()
-}
-
-ee.emit('abort')
-```
-
-Destroying the request or response body will have the same effect.
-
-```js
-import { createServer } from 'http'
-import { Client } from 'undici'
-import { once } from 'events'
-
-const server = createServer((request, response) => {
-  response.end('Hello, World!')
-}).listen()
-
-await once(server, 'listening')
-
-const client = new Client(`http://localhost:${server.address().port}`)
-
-try {
-  const { body } = await client.request({
-    path: '/',
-    method: 'GET'
-  })
-  body.destroy()
-} catch (error) {
-  console.error(error) // should print an RequestAbortedError
-  client.close()
-  server.close()
-}
-```
-
-#### Example 3 - Conditionally reading the body
+When the response body is conditionally read, always fully consume it otherwise:
 
-Remember to fully consume the body even in the case when it is not read.
-
-```js
-const { body, statusCode } = await client.request({
-  path: '/',
-  method: 'GET'
-})
+```mjs
+const { body, statusCode } = await client.request({ path: '/', method: 'GET' })
 
 if (statusCode === 200) {
   return await body.arrayBuffer()
@@ -685,40 +533,42 @@ await body.dump()
 return null
 ```
 
-### `Dispatcher.stream(options, factory[, callback])`
-
-A faster version of `Dispatcher.request`. This method expects the second argument `factory` to return a [`stream.Writable`](https://nodejs.org/api/stream.html#stream_class_stream_writable) stream which the response will be written to. This improves performance by avoiding creating an intermediate [`stream.Readable`](https://nodejs.org/api/stream.html#stream_readable_streams) stream when the user expects to directly pipe the response body to a [`stream.Writable`](https://nodejs.org/api/stream.html#stream_class_stream_writable) stream.
-
-As demonstrated in [Example 1 - Basic GET stream request](/docs/docs/api/Dispatcher.md#example-1-basic-get-stream-request), it is recommended to use the `option.opaque` property to avoid creating a closure for the `factory` method. This pattern works well with Node.js Web Frameworks such as [Fastify](https://fastify.io). See [Example 2 - Stream to Fastify Response](/docs/docs/api/Dispatcher.md#example-2-stream-to-fastify-response) for more details.
-
-Arguments:
-
-* **options** `RequestOptions`
-* **factory** `(data: StreamFactoryData) => stream.Writable`
-* **callback** `(error: Error | null, data: StreamData) => void` (optional)
-
-Returns: `void | Promise<StreamData>` - Only returns a `Promise` if no `callback` argument was passed
-
-#### Parameter: `StreamFactoryData`
-
-* **statusCode** `number`
-* **headers** `Record<string, string | string[] | undefined>`
-* **opaque** `unknown`
-* **onInfo** `({statusCode: number, headers: Record<string, string | string[]>}) => void | null` (optional) - Default: `null` - Callback collecting all the info headers (HTTP 100-199) received.
-
-#### Parameter: `StreamData`
-
-* **opaque** `unknown`
-* **trailers** `Record<string, string>`
-* **context** `object`
-
-#### Example 1 - Basic GET stream request
-
-```js
-import { createServer } from 'http'
+### `dispatcher.stream(options, factory[, callback])`
+
+<!-- YAML
+added: v4.0.0
+-->
+
+* `options` {Object} Accepts the same fields as [`dispatcher.request()`][]'s
+  `options`.
+* `factory` {Function} Returns the `Writable` to which the response is written.
+  * `data` {Object}
+    * `statusCode` {number}
+    * `headers` {Object} The response headers.
+    * `opaque` {any} The `opaque` value passed in `options`.
+    * `context` {Object}
+  * Returns: {Writable}
+* `callback` {Function} (optional) Invoked when the request has completed.
+  * `error` {Error|null}
+  * `data` {Object}
+    * `opaque` {any} The `opaque` value passed in `options`.
+    * `trailers` {Object}
+* Returns: {Promise} A `Promise` is returned only when `callback` is omitted. It
+  resolves with the `data` object described above.
+
+A faster version of [`dispatcher.request()`][]. The `factory` returns a
+[`Writable`][] to which the response is written, which avoids creating an
+intermediate [`Readable`][] when the caller intends to pipe the response body
+directly to a `Writable`.
+
+Use `options.opaque` to avoid creating a closure for the `factory` method. This
+pattern works well with Node.js web frameworks such as [Fastify][].
+
+```mjs
+import { createServer } from 'node:http'
 import { Client } from 'undici'
-import { once } from 'events'
-import { Writable } from 'stream'
+import { once } from 'node:events'
+import { Writable } from 'node:stream'
 
 const server = createServer((request, response) => {
   response.end('Hello, World!')
@@ -755,95 +605,38 @@ try {
 }
 ```
 
-#### Example 2 - Stream to Fastify Response
-
-In this example, a (fake) request is made to the fastify server using `fastify.inject()`. This request then executes the fastify route handler which makes a subsequent request to the raw Node.js http server using `undici.dispatcher.stream()`. The fastify response is passed to the `opaque` option so that undici can tap into the underlying writable stream using `response.raw`. This methodology demonstrates how one could use undici and fastify together to create fast-as-possible requests from one backend server to another.
-
-```js
-import { createServer } from 'http'
+### `dispatcher.upgrade(options[, callback])`
+
+<!-- YAML
+added: v4.0.0
+-->
+
+* `options` {Object}
+  * `path` {string} The request path.
+  * `method` {string} The HTTP method. **Default:** `'GET'`.
+  * `headers` {UndiciHeaders} Request headers. **Default:** `null`.
+  * `protocol` {string} A comma-separated list of protocols, in descending
+    preference order. **Default:** `'Websocket'`.
+  * `signal` {AbortSignal|EventEmitter|null} A signal used to abort the request.
+    **Default:** `null`.
+  * `responseHeaders` {string|null} Set to `'raw'` to return the response headers
+    as a raw array. **Default:** `null`.
+* `callback` {Function} (optional) Invoked when the upgrade completes.
+  * `error` {Error|null}
+  * `data` {Object}
+    * `headers` {Object} The response headers.
+    * `socket` {Duplex} The upgraded socket.
+    * `opaque` {any}
+* Returns: {Promise} A `Promise` is returned only when `callback` is omitted. It
+  resolves with the `data` object described above.
+
+Upgrades to a different protocol. See
+[MDN: Protocol upgrade mechanism][] for more details.
+
+```mjs
+import { createServer } from 'node:http'
 import { Client } from 'undici'
-import { once } from 'events'
-import fastify from 'fastify'
-
-const nodeServer = createServer((request, response) => {
-  response.end('Hello, World! From Node.js HTTP Server')
-}).listen()
-
-await once(nodeServer, 'listening')
-
-console.log('Node Server listening')
-
-const nodeServerUndiciClient = new Client(`http://localhost:${nodeServer.address().port}`)
-
-const fastifyServer = fastify()
-
-fastifyServer.route({
-  url: '/',
-  method: 'GET',
-  handler: (request, response) => {
-    nodeServerUndiciClient.stream({
-      path: '/',
-      method: 'GET',
-      opaque: response
-    }, ({ opaque }) => opaque.raw)
-  }
-})
-
-await fastifyServer.listen()
-
-console.log('Fastify Server listening')
-
-const fastifyServerUndiciClient = new Client(`http://localhost:${fastifyServer.server.address().port}`)
-
-try {
-  const { statusCode, body } = await fastifyServerUndiciClient.request({
-    path: '/',
-    method: 'GET'
-  })
-
-  console.log(`response received ${statusCode}`)
-  body.setEncoding('utf8')
-  body.on('data', console.log)
-
-  nodeServerUndiciClient.close()
-  fastifyServerUndiciClient.close()
-  fastifyServer.close()
-  nodeServer.close()
-} catch (error) { }
-```
-
-### `Dispatcher.upgrade(options[, callback])`
-
-Upgrade to a different protocol. Visit [MDN - HTTP - Protocol upgrade mechanism](https://developer.mozilla.org/en-US/docs/Web/HTTP/Protocol_upgrade_mechanism) for more details.
-
-Arguments:
-
-* **options** `UpgradeOptions`
-
-* **callback** `(error: Error | null, data: UpgradeData) => void` (optional)
-
-Returns: `void | Promise<UpgradeData>` - Only returns a `Promise` if no `callback` argument was passed
-
-#### Parameter: `UpgradeOptions`
-
-* **path** `string`
-* **method** `string` (optional) - Default: `'GET'`
-* **headers** `UndiciHeaders` (optional) - Default: `null`
-* **protocol** `string` (optional) - Default: `'Websocket'` - A string of comma separated protocols, in descending preference order.
-* **signal** `AbortSignal | EventEmitter | null` (optional) - Default: `null`
-
-#### Parameter: `UpgradeData`
-
-* **headers** `http.IncomingHeaders`
-* **socket** `stream.Duplex`
-* **opaque** `unknown`
-
-#### Example 1 - Basic Upgrade Request
-
-```js
-import { createServer } from 'http'
-import { Client } from 'undici'
-import { once } from 'events'
+import { once } from 'node:events'
 
 const server = createServer((request, response) => {
   response.statusCode = 101
@@ -857,9 +650,7 @@ await once(server, 'listening')
 const client = new Client(`http://localhost:${server.address().port}`)
 
 try {
-  const { headers, socket } = await client.upgrade({
-    path: '/',
-  })
+  const { headers, socket } = await client.upgrade({ path: '/' })
   socket.on('end', () => {
     console.log(`upgrade: ${headers.upgrade}`) // upgrade: Websocket
     client.close()
@@ -873,109 +664,62 @@ try {
 }
 ```
 
-### `Dispatcher.compose(interceptors[, interceptor])`
-
-Compose a new dispatcher from the current dispatcher and the given interceptors.
-
-> _Notes_:
-> - The order of the interceptors matters. The last interceptor will be the first to be called.
-> - It is important to note that the `interceptor` function should return a function that follows the `Dispatcher.dispatch` signature.
-> - Any fork of the chain of `interceptors` can lead to unexpected results.
->
-> **Interceptor Stack Visualization:**
-> ```
-> compose([interceptor1, interceptor2, interceptor3])
->
-> Request Flow:
-> ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
-> │   Request   │───▶│interceptor3 │───▶│interceptor2 │───▶│interceptor1 │───▶│  dispatcher │
-> └─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘    │   .dispatch │
->                           ▲                   ▲                   ▲         └─────────────┘
->                           │                   │                   │                ▲
->                    (called first)      (called second)     (called last)           │
->                                                                                    │
-> ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐          │
-> │  Response   │◀───│interceptor3 │◀───│interceptor2 │◀───│interceptor1 │◀─────────┘
-> └─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
->
-> The interceptors are composed in reverse order due to function composition.
-> ```
+### `dispatcher.compose(interceptors[, interceptor])`
 
-Arguments:
+<!-- YAML
+added: v6.9.0
+-->
 
-* **interceptors** `Interceptor[interceptor[]]`: It is an array of `Interceptor` functions passed as only argument, or several interceptors passed as separate arguments.
+* `interceptors` {Array|Function} An array of interceptor functions, or the first
+  of several interceptors passed as separate arguments.
+* `...interceptor` {Function} Additional interceptors when passed as separate
+  arguments.
+* Returns: {Dispatcher} A new dispatcher that applies the interceptors over the
+  current dispatcher's [`dispatch()`][] method.
 
-Returns: `Dispatcher`.
+Composes a new dispatcher from the current dispatcher and the given
+interceptors. Each interceptor is a function that takes a `dispatch` method and
+returns a `dispatch`-like function with the same signature
+(`(options, handler)`).
 
-#### Parameter: `Interceptor`
+The order of the interceptors matters: the last interceptor in the chain is the
+first to be called. Forking the chain of interceptors can lead to unexpected
+results.
 
-A function that takes a `dispatch` method and returns a `dispatch`-like function.
+```text
+compose([interceptor1, interceptor2, interceptor3])
 
-#### Example 1 - Basic Compose
+Request flow:
+Request -> interceptor3 -> interceptor2 -> interceptor1 -> dispatcher.dispatch
+           (called first)  (called second) (called last)
+```
 
-```js
-const { Client, RedirectHandler } = require('undici')
+```mjs
+import { Client, RedirectHandler } from 'undici'
 
 const redirectInterceptor = dispatch => {
-    return (opts, handler) => {
-      const { maxRedirections } = opts
-
-      if (!maxRedirections) {
-        return dispatch(opts, handler)
-      }
+  return (opts, handler) => {
+    const { maxRedirections } = opts
 
-      const redirectHandler = new RedirectHandler(
-        dispatch,
-        maxRedirections,
-        opts,
-        handler
-      )
-      opts = { ...opts, maxRedirections: 0 } // Stop sub dispatcher from also redirecting.
-      return dispatch(opts, redirectHandler)
+    if (!maxRedirections) {
+      return dispatch(opts, handler)
     }
+
+    const redirectHandler = new RedirectHandler(dispatch, maxRedirections, opts, handler)
+    opts = { ...opts, maxRedirections: 0 } // Stop the sub-dispatcher from also redirecting.
+    return dispatch(opts, redirectHandler)
+  }
 }
 
-const client = new Client('http://localhost:3000')
-  .compose(redirectInterceptor)
+const client = new Client('http://localhost:3000').compose(redirectInterceptor)
 
 await client.request({ path: '/', method: 'GET' })
 ```
 
-#### Example 2 - Chained Compose
-
-```js
-const { Client, RedirectHandler, RetryHandler } = require('undici')
-
-const redirectInterceptor = dispatch => {
-    return (opts, handler) => {
-      const { maxRedirections } = opts
-
-      if (!maxRedirections) {
-        return dispatch(opts, handler)
-      }
+Interceptors can be chained by calling `compose()` repeatedly:
 
-      const redirectHandler = new RedirectHandler(
-        dispatch,
-        maxRedirections,
-        opts,
-        handler
-      )
-      opts = { ...opts, maxRedirections: 0 }
-      return dispatch(opts, redirectHandler)
-    }
-}
-
-const retryInterceptor = dispatch => {
-  return function retryInterceptor (opts, handler) {
-    return dispatch(
-      opts,
-      new RetryHandler(opts, {
-        handler,
-        dispatch
-      })
-    )
-  }
-}
+```mjs
+import { Client } from 'undici'
 
 const client = new Client('http://localhost:3000')
   .compose(redirectInterceptor)
@@ -984,461 +728,374 @@ const client = new Client('http://localhost:3000')
 await client.request({ path: '/', method: 'GET' })
 ```
 
-#### Pre-built interceptors
-
-##### `redirect`
+### Event: `'connect'`
 
-The `redirect` interceptor allows you to customize the way your dispatcher handles redirects.
+<!-- YAML
+added: v4.0.0
+-->
 
-It accepts the same arguments as the [`RedirectHandler` constructor](/docs/docs/api/RedirectHandler.md).
+* `origin` {URL}
+* `targets` {Array<Dispatcher>}
 
-Options:
+Emitted when the dispatcher has connected to the origin.
 
-- **maxRedirections** `number` - Maximum number of redirections allowed.
-- **throwOnMaxRedirect** `boolean` - Throw when the maximum number of redirections is reached.
-- **stripHeadersOnRedirect** `string[]` - Header names to remove from all redirected requests.
-- **stripHeadersOnCrossOriginRedirect** `string[]` - Header names to remove from cross-origin redirected requests.
+### Event: `'disconnect'`
 
-**Example - Basic Redirect Interceptor**
+<!-- YAML
+added: v4.0.0
+-->
 
-```js
-const { Client, interceptors } = require("undici");
-const { redirect } = interceptors;
+* `origin` {URL}
+* `targets` {Array<Dispatcher>}
+* `error` {Error}
 
-const client = new Client("http://service.example").compose(
-  redirect({ maxRedirections: 3, throwOnMaxRedirect: true })
-);
-client.request({ path: "/" })
-```
+Emitted when the dispatcher has been disconnected from the origin.
 
-##### `retry`
+For HTTP/2, this event is also emitted when the dispatcher receives a
+[GOAWAY frame][], with an error whose message is `HTTP/2: "GOAWAY" frame received`
+and whose code is `UND_ERR_INFO`. Because of the binary-framing nature of the
+protocol, a request may hang if a frame is received between the `HEADER` and
+`DATA` frames. It is recommended to handle this event and close the dispatcher to
+create a new HTTP/2 session.
 
-The `retry` interceptor allows you to customize the way your dispatcher handles retries.
+### Event: `'connectionError'`
 
-It accepts the same arguments as the [`RetryHandler` constructor](/docs/docs/api/RetryHandler.md).
+<!-- YAML
+added: v4.0.0
+-->
 
-**Example - Basic Retry Interceptor**
+* `origin` {URL}
+* `targets` {Array<Dispatcher>}
+* `error` {Error}
 
-```js
-const { Client, interceptors } = require("undici");
-const { retry } = interceptors;
+Emitted when the dispatcher fails to connect to the origin.
 
-const client = new Client("http://service.example").compose(
-  retry({
-    maxRetries: 3,
-    minTimeout: 1000,
-    maxTimeout: 10000,
-    timeoutFactor: 2,
-    retryAfter: true,
-  })
-);
-```
+### Event: `'drain'`
 
-##### `dump`
+<!-- YAML
+added: v4.0.0
+-->
 
-The `dump` interceptor enables you to dump the response body from a request upon a given limit.
+* `origin` {URL}
 
-**Options**
-- `maxSize` - The maximum size (in bytes) of the response body to dump. If the size of the response's body exceeds this value then the connection will be closed. Default: `1048576`.
+Emitted when the dispatcher is no longer busy and further [`dispatch()`][] calls
+can make progress.
 
-> The `Dispatcher#options` also gets extended with the options `dumpMaxSize`, `abortOnDumped`, and `waitForTrailers` which can be used to configure the interceptor at a request-per-request basis.
+## Pre-built interceptors
 
-**Example - Basic Dump Interceptor**
+undici ships a set of pre-built interceptors under the top-level `interceptors`
+namespace. Each is a factory that returns an interceptor suitable for
+[`dispatcher.compose()`][].
 
-```js
-const { Client, interceptors } = require("undici");
-const { dump } = interceptors;
+```mjs
+import { interceptors } from 'undici'
 
-const client = new Client("http://service.example").compose(
-  dump({
-    maxSize: 1024,
-  })
-);
-
-// or
-client.dispatch(
-  {
-    path: "/",
-    method: "GET",
-    dumpMaxSize: 1024,
-  },
-  handler
-);
+const { redirect, retry, dump, dns, responseError, decompress, cache, deduplicate } = interceptors
 ```
 
-##### `dns`
-
-The `dns` interceptor enables you to cache DNS lookups for a given duration, per origin.
-
->It is well suited for scenarios where you want to cache DNS lookups to avoid the overhead of resolving the same domain multiple times
-
-**Options**
-- `maxTTL` - The maximum time-to-live (in milliseconds) of the DNS cache. It should be a positive integer. Default: `10000`.
-  - Set `0` to disable TTL.
-- `maxItems` - The maximum number of items to cache. It should be a positive integer. Default: `Infinity`.
-- `dualStack` - Whether to resolve both IPv4 and IPv6 addresses. Default: `true`.
-  - It will also attempt a happy-eyeballs-like approach to connect to the available addresses in case of a connection failure.
-- `affinity` - Whether to use IPv4 or IPv6 addresses. Default: `4`.
-  - It can be either `4` or `6`.
-  - It will only take effect if `dualStack` is `false`.
-- `lookup: (hostname: string, options: LookupOptions, callback: (err: NodeJS.ErrnoException | null, addresses: DNSInterceptorRecord[]) => void) => void` - Custom lookup function. Default: `dns.lookup`.
-  - For more info see [dns.lookup](https://nodejs.org/api/dns.html#dnslookuphostname-options-callback).
-- `pick: (origin: URL, records: DNSInterceptorRecords, affinity: 4 | 6) => DNSInterceptorRecord` - Custom pick function. Default: `RoundRobin`.
-  - The function should return a single record from the records array.
-  - By default a simplified version of Round Robin is used.
-  - The `records` property can be mutated to store the state of the balancing algorithm.
-- `storage: DNSStorage` - Custom storage for resolved DNS records
-
-> The `Dispatcher#options` also gets extended with the options `dns.affinity`, `dns.dualStack`, `dns.lookup` and `dns.pick` which can be used to configure the interceptor at a request-per-request basis.
-
-
-**DNSInterceptorRecord**
-It represents a DNS record.
-- `family` - (`number`) The IP family of the address. It can be either `4` or `6`.
-- `address` - (`string`) The IP address.
-
-**DNSInterceptorOriginRecords**
-It represents a map of DNS IP addresses records for a single origin.
-- `4.ips` - (`DNSInterceptorRecord[] | null`) The IPv4 addresses.
-- `6.ips` - (`DNSInterceptorRecord[] | null`) The IPv6 addresses.
-
-**DNSStorage**
-It represents a storage object for resolved DNS records.
-- `size` - (`number`) current size of the storage.
-- `get` - (`(origin: string) => DNSInterceptorOriginRecords | null`) method to get the records for a given origin.
-- `set` - (`(origin: string, records: DNSInterceptorOriginRecords | null, options: { ttl: number }) => void`) method to set the records for a given origin.
-- `delete` - (`(origin: string) => void`) method to delete records for a given origin.
-- `full` - (`() => boolean`) method to check if the storage is full, if returns `true`, DNS lookup will be skipped in this interceptor and new records will not be stored.
-
-**Example - Basic DNS Interceptor**
-
-```js
-const { Agent, interceptors } = require("undici");
-const { dns } = interceptors;
-
-const client = new Agent().compose([
-  dns({ ...opts })
-])
-
-const response = await client.request({
-  origin: `http://localhost:3030`,
-  ...requestOpts
-})
-```
+### `interceptors.redirect(options)`
 
-**Example - DNS Interceptor and LRU cache as a storage**
+<!-- YAML
+added: v4.0.0
+-->
 
-```js
-const { Agent, interceptors } = require("undici");
-const QuickLRU = require("quick-lru");
-const { dns } = interceptors;
+* `options` {Object}
+  * `maxRedirections` {number} The maximum number of redirections allowed.
+  * `throwOnMaxRedirect` {boolean} Whether to throw when the maximum number of
+    redirections is reached.
+  * `stripHeadersOnRedirect` {string[]} Header names to remove from all
+    redirected requests.
+  * `stripHeadersOnCrossOriginRedirect` {string[]} Header names to remove from
+    cross-origin redirected requests.
+* Returns: {Function} An interceptor for [`dispatcher.compose()`][].
 
-const lru = new QuickLRU({ maxSize: 100 });
+Customizes how the dispatcher handles redirects. The options match the
+[`RedirectHandler`][] constructor.
 
-const lruAdapter = {
-  get size() {
-    return lru.size;
-  },
-  get(origin) {
-    return lru.get(origin);
-  },
-  set(origin, records, { ttl }) {
-    lru.set(origin, records, { maxAge: ttl });
-  },
-  delete(origin) {
-    lru.delete(origin);
-  },
-  full() {
-    // For LRU cache, we can always store new records,
-    // old records will be evicted automatically
-    return false;
-  }
-}
+```mjs
+import { Client, interceptors } from 'undici'
 
-const client = new Agent().compose([
-  dns({ storage: lruAdapter })
-])
+const client = new Client('http://service.example').compose(
+  interceptors.redirect({ maxRedirections: 3, throwOnMaxRedirect: true })
+)
 
-const response = await client.request({
-  origin: `http://localhost:3030`,
-  ...requestOpts
-})
+await client.request({ path: '/' })
 ```
 
-##### `responseError`
+### `interceptors.retry(options)`
 
-The `responseError` interceptor throws an error for responses with status code errors (>= 400).
+<!-- YAML
+added: v4.0.0
+-->
 
-**Example**
+* `options` {Object} Retry options. The options match the [`RetryHandler`][]
+  constructor.
+* Returns: {Function} An interceptor for [`dispatcher.compose()`][].
 
-```js
-const { Client, interceptors } = require("undici");
-const { responseError } = interceptors;
+Customizes how the dispatcher handles retries. The options match the
+[`RetryHandler`][] constructor and are also configurable per request through
+`options.retryOptions`.
 
-const client = new Client("http://service.example").compose(
-  responseError()
-);
+```mjs
+import { Client, interceptors } from 'undici'
 
-// Will throw a ResponseError for status codes >= 400
-await client.request({
-  method: "GET",
-  path: "/"
-});
+const client = new Client('http://service.example').compose(
+  interceptors.retry({
+    maxRetries: 3,
+    minTimeout: 1000,
+    maxTimeout: 10000,
+    timeoutFactor: 2,
+    retryAfter: true
+  })
+)
 ```
 
-##### `decompress`
-
-⚠️ The decompress interceptor is experimental and subject to change.
+### `interceptors.dump(options)`
 
-The `decompress` interceptor automatically decompresses response bodies that are compressed with gzip, deflate, brotli, or zstd compression. It removes the `content-encoding` and `content-length` headers from decompressed responses and supports RFC-9110 compliant multiple encodings.
+<!-- YAML
+added: v4.0.0
+-->
 
-**Options**
+* `options` {Object}
+  * `maxSize` {number} The maximum size, in bytes, of a response body to dump. If
+    the response body exceeds this value, the connection is closed.
+    **Default:** `1048576`.
+* Returns: {Function} An interceptor for [`dispatcher.compose()`][].
 
-- `skipErrorResponses` - Whether to skip decompression for error responses (status codes >= 400). Default: `true`.
-- `skipStatusCodes` - Array of status codes to skip decompression for. Default: `[204, 304]`.
+Dumps the response body of a request up to a given limit. The per-request option
+`dumpMaxSize` can be passed to [`dispatcher.dispatch()`][] to configure the
+interceptor on a per-request basis.
 
-**Example - Basic Decompress Interceptor**
+```mjs
+import { Client, interceptors } from 'undici'
 
-```js
-const { Client, interceptors } = require("undici");
-const { decompress } = interceptors;
-
-const client = new Client("http://service.example").compose(
-  decompress()
-);
-
-// Automatically decompresses gzip/deflate/brotli/zstd responses
-const response = await client.request({
-  method: "GET",
-  path: "/"
-});
+const client = new Client('http://service.example').compose(
+  interceptors.dump({ maxSize: 1024 })
+)
 ```
 
-**Example - Custom Options**
-
-```js
-const { Client, interceptors } = require("undici");
-const { decompress } = interceptors;
+### `interceptors.dns(options)`
+
+<!-- YAML
+added: v4.0.0
+-->
+
+* `options` {Object}
+  * `maxTTL` {number} The maximum time-to-live, in milliseconds, of the DNS
+    cache. Must be a positive integer. Set to `0` to disable TTL.
+    **Default:** `10000`.
+  * `maxItems` {number} The maximum number of items to cache. Must be a positive
+    integer. **Default:** `Infinity`.
+  * `dualStack` {boolean} Whether to resolve both IPv4 and IPv6 addresses. When
+    enabled, a happy-eyeballs-like approach is used to connect to available
+    addresses on connection failure. **Default:** `true`.
+  * `affinity` {number} Whether to use IPv4 (`4`) or IPv6 (`6`) addresses. Only
+    takes effect when `dualStack` is `false`. **Default:** `4`.
+  * `lookup` {Function} A custom lookup function. **Default:** [`dns.lookup()`][].
+  * `pick` {Function} A custom function that returns a single record from the
+    resolved records. **Default:** a simplified round-robin.
+  * `storage` {Object} A custom storage for resolved DNS records.
+* Returns: {Function} An interceptor for [`dispatcher.compose()`][].
+
+Caches DNS lookups for a given duration, per origin. It is well suited to
+scenarios where the same domain is resolved many times.
+
+The per-request options `dns.affinity`, `dns.dualStack`, `dns.lookup`, and
+`dns.pick` can be passed to [`dispatcher.dispatch()`][] to configure the
+interceptor on a per-request basis.
+
+A custom `storage` object must implement `size` (getter), `get(origin)`,
+`set(origin, records, { ttl })`, `delete(origin)`, and `full()`. When `full()`
+returns `true`, DNS lookups are skipped and new records are not stored.
+
+```mjs
+import { Agent, interceptors } from 'undici'
+
+const client = new Agent().compose(
+  interceptors.dns({ maxTTL: 10000, maxItems: 100 })
+)
 
-const client = new Client("http://service.example").compose(
-  decompress({
-    skipErrorResponses: false, // Decompress 5xx responses
-    skipStatusCodes: [204, 304, 201] // Skip these status codes
-  })
-);
+const response = await client.request({ origin: 'http://localhost:3030', path: '/', method: 'GET' })
 ```
 
-**Supported Encodings**
-
-- `gzip` / `x-gzip` - GZIP compression
-- `deflate` / `x-compress` - DEFLATE compression  
-- `br` - Brotli compression
-- `zstd` - Zstandard compression
-- Multiple encodings (e.g., `gzip, deflate`) are supported per RFC-9110
-
-**Behavior**
-
-- Skips decompression for status codes < 200 or >= 400 (configurable)
-- Skips decompression for 204 No Content and 304 Not Modified by default
-- Removes `content-encoding` and `content-length` headers when decompressing
-- Passes through unsupported encodings unchanged
-- Handles case-insensitive encoding names
-- Supports streaming decompression without buffering
+### `interceptors.responseError()`
 
-##### `Cache Interceptor`
+<!-- YAML
+added: v4.0.0
+-->
 
-The `cache` interceptor implements client-side response caching as described in
-[RFC9111](https://www.rfc-editor.org/rfc/rfc9111.html).
+* Returns: {Function} An interceptor for [`dispatcher.compose()`][].
 
-**Options**
+Throws a [`ResponseError`][] for responses with a status code of `400` or
+greater.
 
-- `store` - The [`CacheStore`](/docs/docs/api/CacheStore.md) to store and retrieve responses from. Default is [`MemoryCacheStore`](/docs/docs/api/CacheStore.md#memorycachestore).
-- `methods` - The [**safe** HTTP methods](https://www.rfc-editor.org/rfc/rfc9110#section-9.2.1) to cache the response of.
-- `cacheByDefault` - The default expiration time to cache responses by if they don't have an explicit expiration and cannot have an heuristic expiry computed. If this isn't present, responses neither with an explicit expiration nor heuristically cacheable will not be cached. Default `undefined`.
-- `type` - The [type of cache](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Caching#types_of_caches) for Undici to act as. Can be `shared` or `private`. Default `shared`. `private` implies privately cacheable responses will be cached and potentially shared with other users of your application.
+```mjs
+import { Client, interceptors } from 'undici'
 
-**Usage with `fetch`**
-
-```js
-const { Agent, cacheStores, interceptors, setGlobalDispatcher } = require('undici')
-
-const client = new Agent().compose(interceptors.cache({
-  store: new cacheStores.MemoryCacheStore({
-    maxSize: 100 * 1024 * 1024, // 100MB
-    maxCount: 1000,
-    maxEntrySize: 5 * 1024 * 1024 // 5MB
-  })
-}))
-
-setGlobalDispatcher(client)
-
-// First request goes to the network and is cached when cache headers allow it.
-const first = await fetch('https://example.com/data')
+const client = new Client('http://service.example').compose(
+  interceptors.responseError()
+)
 
-// Second request can be served from cache according to RFC9111 rules.
-const second = await fetch('https://example.com/data')
+// Throws a ResponseError for status codes >= 400.
+await client.request({ method: 'GET', path: '/' })
 ```
 
-##### `Deduplicate Interceptor`
+### `interceptors.decompress(options)`
 
-The `deduplicate` interceptor deduplicates concurrent identical requests. When multiple identical requests are made while one is already in-flight, only one request is sent to the origin server, and all waiting handlers receive the same response. This reduces server load and improves performance.
+<!-- YAML
+added: v4.0.0
+-->
 
-**Options**
+> Stability: 1 - Experimental
 
-- `methods` - The [**safe** HTTP methods](https://www.rfc-editor.org/rfc/rfc9110#section-9.2.1) to deduplicate. Default `['GET']`.
-- `skipHeaderNames` - Header names that, if present in a request, will cause the request to skip deduplication entirely. Useful for headers like `idempotency-key` where presence indicates unique processing. Header name matching is case-insensitive. Default `[]`.
-- `excludeHeaderNames` - Header names to exclude from the deduplication key. Requests with different values for these headers will still be deduplicated together. Useful for headers like `x-request-id` that vary per request but shouldn't affect deduplication. Header name matching is case-insensitive. Default `[]`.
-- `maxBufferSize` - Maximum bytes buffered per paused waiting deduplicated handler. If a waiting handler remains paused and exceeds this threshold, it is failed with an abort error to prevent unbounded memory growth. Default `5 * 1024 * 1024`.
+* `options` {Object}
+  * `skipErrorResponses` {boolean} Whether to skip decompression for error
+    responses (status codes `>= 400`). **Default:** `true`.
+  * `skipStatusCodes` {number[]} Status codes for which decompression is skipped.
+    **Default:** `[204, 304]`.
+* Returns: {Function} An interceptor for [`dispatcher.compose()`][].
 
-**Usage**
+Automatically decompresses response bodies compressed with gzip, deflate,
+Brotli, or Zstandard. It removes the `content-encoding` and `content-length`
+headers from decompressed responses and supports RFC 9110-compliant multiple
+encodings. The supported encodings are `gzip`/`x-gzip`, `deflate`/`x-compress`,
+`br`, and `zstd`; unsupported encodings are passed through unchanged. Encoding
+names are matched case-insensitively, and decompression is streamed without
+buffering.
 
-```js
-const { Client, interceptors } = require("undici");
-const { deduplicate, cache } = interceptors;
+```mjs
+import { Client, interceptors } from 'undici'
 
-// Deduplicate only
-const client = new Client("http://service.example").compose(
-  deduplicate()
-);
+const client = new Client('http://service.example').compose(
+  interceptors.decompress()
+)
 
-// Deduplicate with caching
-const clientWithCache = new Client("http://service.example").compose(
-  deduplicate(),
-  cache()
-);
+// Automatically decompresses gzip/deflate/brotli/zstd responses.
+const response = await client.request({ method: 'GET', path: '/' })
 ```
 
-Requests are considered identical if they have the same:
-- Origin
-- HTTP method
-- Path
-- Request headers (excluding any headers specified in `excludeHeaderNames`)
-
-All deduplicated requests receive the complete response including status code, headers, and body.
-
-For observability, request deduplication events are published to the `undici:request:pending-requests` [diagnostic channel](/docs/docs/api/DiagnosticsChannel.md#undicirequestpending-requests).
-
-## Instance Events
-
-### Event: `'connect'`
-
-Parameters:
-
-* **origin** `URL`
-* **targets** `Array<Dispatcher>`
-
-### Event: `'disconnect'`
-
-Parameters:
-
-* **origin** `URL`
-* **targets** `Array<Dispatcher>`
-* **error** `Error`
-
-Emitted when the dispatcher has been disconnected from the origin.
-
-> **Note**: For HTTP/2, this event is also emitted when the dispatcher has received the [GOAWAY Frame](https://webconcepts.info/concepts/http2-frame-type/0x7) with an Error with the message `HTTP/2: "GOAWAY" frame received` and the code `UND_ERR_INFO`.
-> Due to nature of the protocol of using binary frames, it is possible that requests gets hanging as a frame can be received between the `HEADER` and `DATA` frames.
-> It is recommended to handle this event and close the dispatcher to create a new HTTP/2 session.
-
-### Event: `'connectionError'`
-
-Parameters:
-
-* **origin** `URL`
-* **targets** `Array<Dispatcher>`
-* **error** `Error`
-
-Emitted when dispatcher fails to connect to
-origin.
-
-### Event: `'drain'`
-
-Parameters:
+### `interceptors.cache(options)`
 
-* **origin** `URL`
+<!-- YAML
+added: v4.0.0
+-->
 
-Emitted when dispatcher is no longer busy.
+* `options` {Object}
+  * `store` {CacheStore} The store used to retrieve and persist responses.
+    **Default:** a new [`MemoryCacheStore`][].
+  * `methods` {string[]} The [safe HTTP methods][] whose responses are cached.
+    **Default:** `['GET']`.
+  * `cacheByDefault` {number} The default expiration time, in seconds, for
+    responses without an explicit expiration that cannot have a heuristic expiry
+    computed. When omitted, such responses are not cached. **Default:**
+    `undefined`.
+  * `type` {string} The [type of cache][] to act as, either `'shared'` or
+    `'private'`. **Default:** `'shared'`.
+  * `origins` {Array} An array of strings or `RegExp` instances restricting which
+    origins are cached. **Default:** `undefined`.
+* Returns: {Function} An interceptor for [`dispatcher.compose()`][].
 
-## Parameter: `UndiciHeaders`
+Implements client-side response caching as described in [RFC 9111][].
 
-* `Record<string, number | string | string[] | undefined> | string[] | Iterable<[string, string | string[] | undefined]> | null`
+```mjs
+import { Agent, cacheStores, interceptors, setGlobalDispatcher } from 'undici'
 
-Header arguments such as `options.headers` in [`Client.dispatch`](/docs/docs/api/Client.md#clientdispatchoptions-handlers) can be specified in three forms:
-* As an object specified by the `Record<string, number | string | string[] | undefined>` (`OutgoingHttpHeaders`) type.
-* As an array of strings. An array representation of a header list must have an even length, or an `InvalidArgumentError` will be thrown.
-* As an iterable that can encompass `Headers`, `Map`, or a custom iterator returning key-value pairs.
-Keys are lowercase and values are not modified.
-
-Undici validates header syntax at the protocol level (for example, invalid header names and invalid control characters in string values), but it does not sanitize untrusted application input. Validate and sanitize any user-provided header names and values before passing them to Undici to prevent header/body injection vulnerabilities.
-
-When using the array header format (`string[]`), Undici processes only indexed elements. Additional properties assigned to the array object are ignored.
-
-Response headers will derive a `host` from the `url` of the [Client](/docs/docs/api/Client.md#class-client) instance if no `host` header was previously specified.
-
-### Request header validation
-
-Request headers that are managed by the HTTP connection are handled differently from ordinary headers:
+const client = new Agent().compose(interceptors.cache({
+  store: new cacheStores.MemoryCacheStore({
+    maxSize: 100 * 1024 * 1024, // 100 MB
+    maxCount: 1000,
+    maxEntrySize: 5 * 1024 * 1024 // 5 MB
+  })
+}))
 
-* `transfer-encoding`, `keep-alive`, and `upgrade` cannot be set through `options.headers`; Undici throws an `InvalidArgumentError`.
-* `expect` is not supported; Undici throws a `NotSupportedError`.
-* `connection` must be a string containing comma-separated valid HTTP tokens. Undici rejects malformed tokens with `InvalidArgumentError: invalid connection header` and uses the `close` token to request connection reset behavior.
-* `host` and `content-length` are tracked separately from the raw header list. Duplicate `host` or `content-length` values are rejected, and `content-length` must contain only decimal digits.
+setGlobalDispatcher(client)
 
-### Example 1 - Object
+// The first request goes to the network and is cached when cache headers allow it.
+const first = await fetch('https://example.com/data')
 
-```js
-{
-  'content-length': '123',
-  'content-type': 'text/plain',
-  host: 'mysite.com',
-  'accept-language': 'en',
-  accept: '*/*'
-}
+// The second request can be served from the cache per RFC 9111 rules.
+const second = await fetch('https://example.com/data')
 ```
 
-### Example 2 - Array
+### `interceptors.deduplicate(options)`
+
+<!-- YAML
+added: v4.0.0
+-->
+
+* `options` {Object}
+  * `methods` {string[]} The [safe HTTP methods][] to deduplicate.
+    **Default:** `['GET']`.
+  * `skipHeaderNames` {string[]} Header names that, when present in a request,
+    cause that request to skip deduplication entirely. Matching is
+    case-insensitive. **Default:** `[]`.
+  * `excludeHeaderNames` {string[]} Header names excluded from the deduplication
+    key, so requests that differ only in these headers are still deduplicated
+    together. Matching is case-insensitive. **Default:** `[]`.
+  * `maxBufferSize` {number} The maximum number of bytes buffered per paused
+    waiting handler. A waiting handler that exceeds this threshold is failed with
+    an abort error to prevent unbounded memory growth. **Default:** `5242880`.
+* Returns: {Function} An interceptor for [`dispatcher.compose()`][].
+
+Deduplicates concurrent identical requests. When multiple identical requests are
+made while one is already in-flight, only one request is sent to the origin and
+all waiting handlers receive the same response. Requests are considered identical
+when they share the same origin, HTTP method, path, and request headers
+(excluding any headers in `excludeHeaderNames`).
+
+Deduplication events are published to the `undici:request:pending-requests`
+[diagnostics channel][].
+
+```mjs
+import { Client, interceptors } from 'undici'
+
+const client = new Client('http://service.example').compose(
+  interceptors.deduplicate()
+)
 
-```js
-[
-  'content-length', '123',
-  'content-type', 'text/plain',
-  'connection', 'keep-alive',
-  'host', 'mysite.com',
-  'accept', '*/*'
-]
+// Deduplicate together with caching.
+const clientWithCache = new Client('http://service.example').compose(
+  interceptors.deduplicate(),
+  interceptors.cache()
+)
 ```
 
-### Example 3 - Iterable
-
-```js
-new Headers({
-  'content-length': '123',
-  'content-type': 'text/plain',
-  connection: 'keep-alive',
-  host: 'mysite.com',
-  accept: '*/*'
-})
-```
-or
-```js
-new Map([
-  ['content-length', '123'],
-  ['content-type', 'text/plain'],
-  ['connection', 'keep-alive'],
-  ['host', 'mysite.com'],
-  ['accept', '*/*']
-])
-```
-or
-```js
-{
-  *[Symbol.iterator] () {
-    yield ['content-length', '123']
-    yield ['content-type', 'text/plain']
-    yield ['connection', 'keep-alive']
-    yield ['host', 'mysite.com']
-    yield ['accept', '*/*']
-  }
-}
-```
+[Fastify]: https://fastify.dev
+[GOAWAY frame]: https://webconcepts.info/concepts/http2-frame-type/0x7
+[HTTP `CONNECT`]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/CONNECT
+[MDN: Protocol upgrade mechanism]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Protocol_upgrade_mechanism
+[RFC 9111]: https://www.rfc-editor.org/rfc/rfc9111.html
+[`.arrayBuffer()`]: https://fetch.spec.whatwg.org/#dom-body-arraybuffer
+[`.blob()`]: https://fetch.spec.whatwg.org/#dom-body-blob
+[`.bytes()`]: https://fetch.spec.whatwg.org/#dom-body-bytes
+[`.json()`]: https://fetch.spec.whatwg.org/#dom-body-json
+[`.text()`]: https://fetch.spec.whatwg.org/#dom-body-text
+[`'drain'`]: #event-drain
+[`Agent`]: Agent.md#class-agent
+[`BalancedPool`]: BalancedPool.md#class-balancedpool
+[`Client`]: Client.md#class-client
+[`EventEmitter`]: https://nodejs.org/api/events.html#class-eventemitter
+[`MemoryCacheStore`]: CacheStore.md#class-memorycachestore
+[`Pool`]: Pool.md#class-pool
+[`Readable`]: https://nodejs.org/api/stream.html#class-streamreadable
+[`RedirectHandler`]: RedirectHandler.md
+[`ResponseError`]: Errors.md#class-responseerror
+[`RetryHandler`]: RetryHandler.md
+[`Writable`]: https://nodejs.org/api/stream.html#class-streamwritable
+[`close()`]: #dispatcherclosecallback
+[`connect()`]: #dispatcherconnectoptions-callback
+[`destroy()`]: #dispatcherdestroyerror-callback
+[`dispatch()`]: #dispatcherdispatchoptions-handler
+[`dispatcher.compose()`]: #dispatchercomposeinterceptors-interceptor
+[`dispatcher.dispatch()`]: #dispatcherdispatchoptions-handler
+[`dispatcher.request()`]: #dispatcherrequestoptions-callback
+[`dns.lookup()`]: https://nodejs.org/api/dns.html#dnslookuphostname-options-callback
+[`pipeline()`]: #dispatcherpipelineoptions-handler
+[`request()`]: #dispatcherrequestoptions-callback
+[`stream()`]: #dispatcherstreamoptions-factory-callback
+[`stream.pipeline()`]: https://nodejs.org/api/stream.html#streampipelinesource-transforms-destination-options
+[`upgrade()`]: #dispatcherupgradeoptions-callback
+[body mixin]: https://fetch.spec.whatwg.org/#body-mixin
+[diagnostics channel]: DiagnosticsChannel.md#undicirequestpending-requests
+[safe HTTP methods]: https://www.rfc-editor.org/rfc/rfc9110#section-9.2.1
+[type of cache]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Caching#types_of_caches
diff --git a/docs/docs/api/EnvHttpProxyAgent.md b/docs/docs/api/EnvHttpProxyAgent.md
index ccc16e819a2..8a6b75a3d67 100644
--- a/docs/docs/api/EnvHttpProxyAgent.md
+++ b/docs/docs/api/EnvHttpProxyAgent.md
@@ -1,52 +1,85 @@
-# Class: EnvHttpProxyAgent
+# EnvHttpProxyAgent
 
-Extends: `undici.Dispatcher`
+<!--introduced_in=v6.14.0-->
 
-EnvHttpProxyAgent automatically reads the proxy configuration from the environment variables `http_proxy`, `https_proxy`, and `no_proxy` and sets up the proxy agents accordingly. When `http_proxy` and `https_proxy` are set, `http_proxy` is used for HTTP requests and `https_proxy` is used for HTTPS requests. If only `http_proxy` is set, `http_proxy` is used for both HTTP and HTTPS requests. If only `https_proxy` is set, it is only used for HTTPS requests.
+<!--type=module-->
 
-`no_proxy` is a comma or space-separated list of hostnames that should not be proxied. The list may contain leading wildcard characters (`*`). If `no_proxy` is set, the EnvHttpProxyAgent will bypass the proxy for requests to hosts that match the list. If `no_proxy` is set to `"*"`, the EnvHttpProxyAgent will bypass the proxy for all requests.
+<!-- source_link=lib/dispatcher/env-http-proxy-agent.js -->
 
-Uppercase environment variables are also supported: `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY`. However, if both the lowercase and uppercase environment variables are set, the uppercase environment variables will be ignored.
+> Stability: 2 - Stable
 
-## `new EnvHttpProxyAgent([options])`
+`EnvHttpProxyAgent` is a [`Dispatcher`][] that reads its proxy configuration from
+the `http_proxy`, `https_proxy`, and `no_proxy` environment variables and routes
+requests through the appropriate proxy automatically. Import it from `undici`:
 
-Arguments:
-
-* **options** `EnvHttpProxyAgentOptions` (optional) - extends the `Agent` options.
-
-Returns: `EnvHttpProxyAgent`
-
-### Parameter: `EnvHttpProxyAgentOptions`
-
-Extends: [`AgentOptions`](/docs/docs/api/Agent.md#parameter-agentoptions)
-
-* **httpProxy** `string` (optional) - When set, it will override the `HTTP_PROXY` environment variable.
-* **httpsProxy** `string` (optional) - When set, it will override the `HTTPS_PROXY` environment variable.
-* **noProxy** `string` (optional) - When set, it will override the `NO_PROXY` environment variable.
-
-Examples:
-
-```js
+```mjs
 import { EnvHttpProxyAgent } from 'undici'
-
-const envHttpProxyAgent = new EnvHttpProxyAgent()
-// or
-const envHttpProxyAgent = new EnvHttpProxyAgent({ httpProxy: 'my.proxy.server:8080', httpsProxy: 'my.proxy.server:8443', noProxy: 'localhost' })
 ```
 
-#### Example - EnvHttpProxyAgent instantiation
-
-This will instantiate the EnvHttpProxyAgent. It will not do anything until registered as the agent to use with requests.
-
-```js
+When `http_proxy` and `https_proxy` are both set, `http_proxy` is used for HTTP
+requests and `https_proxy` is used for HTTPS requests. If only `http_proxy` is
+set, it is used for both HTTP and HTTPS requests. If only `https_proxy` is set,
+it is used only for HTTPS requests.
+
+`no_proxy` is a comma- or space-separated list of hosts that must not be
+proxied. Each entry may include a leading dot or `*.` wildcard (for example
+`.example.com`) to match subdomains, and an optional `:port` suffix to restrict
+the match to a specific port. A request bypasses the proxy when its host equals
+an entry or is a subdomain of one. Setting `no_proxy` to `*` bypasses the proxy
+for every request.
+
+The uppercase variants `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` are also
+honored. When both the lowercase and uppercase forms of a variable are set, the
+lowercase form takes precedence and the uppercase form is ignored. The `no_proxy`
+value is re-read from the environment on demand, so changes to it after the agent
+is created take effect on subsequent requests; this does not apply when `noProxy`
+is passed as an option.
+
+## Class: `EnvHttpProxyAgent`
+
+<!-- YAML
+added: v6.14.0
+-->
+
+* Extends: {Dispatcher}
+
+### `new EnvHttpProxyAgent([options])`
+
+<!-- YAML
+added: v6.14.0
+-->
+
+* `options` {EnvHttpProxyAgentOptions} Extends the [`ProxyAgent`][] options
+  (except `uri`). (optional)
+  * `httpProxy` {string} When set, overrides the `http_proxy` and `HTTP_PROXY`
+    environment variables. (optional)
+  * `httpsProxy` {string} When set, overrides the `https_proxy` and
+    `HTTPS_PROXY` environment variables. (optional)
+  * `noProxy` {string} When set, overrides the `no_proxy` and `NO_PROXY`
+    environment variables. (optional)
+* Returns: {EnvHttpProxyAgent}
+
+Creates a new `EnvHttpProxyAgent`. Any options other than `httpProxy`,
+`httpsProxy`, and `noProxy` are forwarded to the underlying [`Agent`][] and
+[`ProxyAgent`][] instances. Constructing the agent only configures it; it does
+not affect any request until it is registered as a dispatcher, either globally
+with `setGlobalDispatcher()` or per-request through the `dispatcher` option.
+
+```mjs
 import { EnvHttpProxyAgent } from 'undici'
 
 const envHttpProxyAgent = new EnvHttpProxyAgent()
+// or, overriding the environment variables explicitly:
+const envHttpProxyAgentWithOpts = new EnvHttpProxyAgent({
+  httpProxy: 'my.proxy.server:8080',
+  httpsProxy: 'my.proxy.server:8443',
+  noProxy: 'localhost'
+})
 ```
 
-#### Example - Basic Proxy Fetch with global agent dispatcher
+#### Example - Proxied `fetch()` with the global dispatcher
 
-```js
+```mjs
 import { setGlobalDispatcher, fetch, EnvHttpProxyAgent } from 'undici'
 
 const envHttpProxyAgent = new EnvHttpProxyAgent()
@@ -56,12 +89,12 @@ const response = await fetch('http://localhost:3000/foo')
 
 console.log('response received', response.status) // response received 200
 
-const data = await response.json() // data { foo: "bar" }
+const data = await response.json() // data { foo: 'bar' }
 ```
 
-#### Example - Basic Proxy Request with global agent dispatcher
+#### Example - Proxied `request()` with the global dispatcher
 
-```js
+```mjs
 import { setGlobalDispatcher, request, EnvHttpProxyAgent } from 'undici'
 
 const envHttpProxyAgent = new EnvHttpProxyAgent()
@@ -76,17 +109,16 @@ for await (const data of body) {
 }
 ```
 
-#### Example - Basic Proxy Request with local agent dispatcher
+#### Example - Proxied `request()` with a local dispatcher
 
-```js
+```mjs
 import { EnvHttpProxyAgent, request } from 'undici'
 
 const envHttpProxyAgent = new EnvHttpProxyAgent()
 
-const {
-  statusCode,
-  body
-} = await request('http://localhost:3000/foo', { dispatcher: envHttpProxyAgent })
+const { statusCode, body } = await request('http://localhost:3000/foo', {
+  dispatcher: envHttpProxyAgent
+})
 
 console.log('response received', statusCode) // response received 200
 
@@ -95,62 +127,44 @@ for await (const data of body) {
 }
 ```
 
-#### Example - Basic Proxy Fetch with local agent dispatcher
+#### Example - Proxied `fetch()` with a local dispatcher
 
-```js
+```mjs
 import { EnvHttpProxyAgent, fetch } from 'undici'
 
 const envHttpProxyAgent = new EnvHttpProxyAgent()
 
-const response = await fetch('http://localhost:3000/foo', { dispatcher: envHttpProxyAgent })
+const response = await fetch('http://localhost:3000/foo', {
+  dispatcher: envHttpProxyAgent
+})
 
 console.log('response received', response.status) // response received 200
 
-const data = await response.json() // data { foo: "bar" }
+const data = await response.json() // data { foo: 'bar' }
 ```
 
-## Instance Methods
-
-### `EnvHttpProxyAgent.close([callback])`
-
-Implements [`Dispatcher.close([callback])`](/docs/docs/api/Dispatcher.md#dispatcherclosecallback-promise).
-
-### `EnvHttpProxyAgent.destroy([error, callback])`
-
-Implements [`Dispatcher.destroy([error, callback])`](/docs/docs/api/Dispatcher.md#dispatcherdestroyerror-callback-promise).
-
-### `EnvHttpProxyAgent.dispatch(options, handler: AgentDispatchOptions)`
-
-Implements [`Dispatcher.dispatch(options, handler)`](/docs/docs/api/Dispatcher.md#dispatcherdispatchoptions-handler).
-
-#### Parameter: `AgentDispatchOptions`
-
-Extends: [`DispatchOptions`](/docs/docs/api/Dispatcher.md#parameter-dispatchoptions)
-
-* **origin** `string | URL`
-
-Implements [`Dispatcher.destroy([error, callback])`](/docs/docs/api/Dispatcher.md#dispatcherdestroyerror-callback-promise).
-
-### `EnvHttpProxyAgent.connect(options[, callback])`
-
-See [`Dispatcher.connect(options[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherconnectoptions-callback).
-
-### `EnvHttpProxyAgent.dispatch(options, handler)`
-
-Implements [`Dispatcher.dispatch(options, handler)`](/docs/docs/api/Dispatcher.md#dispatcherdispatchoptions-handler).
-
-### `EnvHttpProxyAgent.pipeline(options, handler)`
-
-See [`Dispatcher.pipeline(options, handler)`](/docs/docs/api/Dispatcher.md#dispatcherpipelineoptions-handler).
-
-### `EnvHttpProxyAgent.request(options[, callback])`
+### `envHttpProxyAgent.dispatch(options, handler)`
 
-See [`Dispatcher.request(options [, callback])`](/docs/docs/api/Dispatcher.md#dispatcherrequestoptions-callback).
+<!-- YAML
+added: v6.14.0
+-->
 
-### `EnvHttpProxyAgent.stream(options, factory[, callback])`
+* `options` {AgentDispatchOptions}
+  * `origin` {string|URL}
+* `handler` {DispatchHandler}
+* Returns: {boolean}
 
-See [`Dispatcher.stream(options, factory[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherstreamoptions-factory-callback).
+Dispatches a request through the proxy selected for `options.origin`. The origin's
+protocol, host, and port are compared against the `no_proxy` configuration: when
+the host should be proxied, the request is routed to the HTTPS proxy agent for
+`https:` origins or the HTTP proxy agent otherwise; when the host is excluded by
+`no_proxy`, the request is sent directly through a non-proxying [`Agent`][].
 
-### `EnvHttpProxyAgent.upgrade(options[, callback])`
+This method is not normally called directly. Use the higher-level
+[`Dispatcher`][] methods such as [`dispatcher.request()`][] or the top-level
+`request()` and `fetch()` helpers instead.
 
-See [`Dispatcher.upgrade(options[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherupgradeoptions-callback).
+[`Agent`]: Agent.md#class-agent
+[`Dispatcher`]: Dispatcher.md#class-dispatcher
+[`ProxyAgent`]: ProxyAgent.md#class-proxyagent
+[`dispatcher.request()`]: Dispatcher.md#dispatcherrequestoptions-callback
diff --git a/docs/docs/api/Errors.md b/docs/docs/api/Errors.md
index 14c88cabf38..713537395b2 100644
--- a/docs/docs/api/Errors.md
+++ b/docs/docs/api/Errors.md
@@ -1,50 +1,309 @@
 # Errors
 
-Undici exposes a variety of error objects that you can use to enhance your error handling.
-You can find all the error objects inside the `errors` key.
+<!--introduced_in=v1.0.0-->
+<!--type=module-->
+<!-- source_link=lib/core/errors.js -->
+
+> Stability: 2 - Stable
+
+undici raises typed error objects so that failures can be distinguished
+programmatically. Every error class is exposed through the `errors` namespace of
+the package:
 
 ```js
 import { errors } from 'undici'
+
+if (err instanceof errors.ConnectTimeoutError) {
+  // handle connect timeout
+}
+```
+
+All errors, except [`HTTPParserError`][], extend [`UndiciError`][]. Each error
+carries a stable `code` string (for example `UND_ERR_CONNECT_TIMEOUT`) and a
+`name`.
+
+Because the bundled (global) dispatcher may come from a different undici version
+than the one you import directly, prefer matching on `error.code` rather than
+`instanceof errors.UndiciError`:
+
+```js
+if (err.code === 'UND_ERR_CONNECT_TIMEOUT') {
+  // handle connect timeout
+}
 ```
 
-| Error                                | Error Codes                           | Description                                                               |
-| ------------------------------------ | ------------------------------------- | ------------------------------------------------------------------------- |
-| `UndiciError`                        | `UND_ERR`                             | all errors below are extended from `UndiciError`.                         |
-| `ConnectTimeoutError`                | `UND_ERR_CONNECT_TIMEOUT`             | socket is destroyed due to connect timeout.                               |
-| `HeadersTimeoutError`                | `UND_ERR_HEADERS_TIMEOUT`             | socket is destroyed due to headers timeout.                               |
-| `HeadersOverflowError`               | `UND_ERR_HEADERS_OVERFLOW`            | socket is destroyed due to headers' max size being exceeded.              |
-| `BodyTimeoutError`                   | `UND_ERR_BODY_TIMEOUT`                | socket is destroyed due to body timeout.                                  |
-| `InvalidArgumentError`               | `UND_ERR_INVALID_ARG`                 | passed an invalid argument.                                               |
-| `InvalidReturnValueError`            | `UND_ERR_INVALID_RETURN_VALUE`        | returned an invalid value.                                                |
-| `RequestAbortedError`                | `UND_ERR_ABORTED`                     | the request has been aborted by the user                                  |
-| `ClientDestroyedError`               | `UND_ERR_DESTROYED`                   | trying to use a destroyed client.                                         |
-| `ClientClosedError`                  | `UND_ERR_CLOSED`                      | trying to use a closed client.                                            |
-| `SocketError`                        | `UND_ERR_SOCKET`                      | there is an error with the socket.                                        |
-| `NotSupportedError`                  | `UND_ERR_NOT_SUPPORTED`               | encountered unsupported functionality.                                    |
-| `RequestContentLengthMismatchError`  | `UND_ERR_REQ_CONTENT_LENGTH_MISMATCH` | request body does not match content-length header                         |
-| `ResponseContentLengthMismatchError` | `UND_ERR_RES_CONTENT_LENGTH_MISMATCH` | response body does not match content-length header                        |
-| `InformationalError`                 | `UND_ERR_INFO`                        | expected error with reason                                                |
-| `ResponseExceededMaxSizeError`       | `UND_ERR_RES_EXCEEDED_MAX_SIZE`       | response body exceed the max size allowed                                 |
-| `SecureProxyConnectionError`         | `UND_ERR_PRX_TLS`                     | tls connection to a proxy failed                                          |
-| `ProxyConnectionError`               | `UND_ERR_PRX_CONN`                    | establishing the proxy `CONNECT` tunnel failed                            |
-| `MessageSizeExceededError`           | `UND_ERR_WS_MESSAGE_SIZE_EXCEEDED`    | WebSocket decompressed message exceeded the maximum allowed size          |
-| `AbortError`                         | `UND_ERR_ABORT`                       | the operation was aborted (base class of `RequestAbortedError`).          |
-| `RequestRetryError`                  | `UND_ERR_REQ_RETRY`                   | request failed and could not be retried; carries `statusCode`, `headers` and `data`. |
-| `ResponseError`                      | `UND_ERR_RESPONSE`                    | response returned an error status code; carries `statusCode`, `headers` and `body`.  |
-| `MaxOriginsReachedError`             | `UND_ERR_MAX_ORIGINS_REACHED`         | the maximum number of allowed origins has been reached.                   |
-| `BalancedPoolMissingUpstreamError`   | `UND_ERR_BPL_MISSING_UPSTREAM`        | no upstream has been added to the `BalancedPool`.                         |
-| `Socks5ProxyError`                   | `UND_ERR_SOCKS5`                      | an error occurred during SOCKS5 proxy negotiation.                        |
-| `HTTPParserError`                    | `HPE_*`                               | an error occurred while parsing the HTTP response (extends `Error`, not `UndiciError`). |
-
-Be aware of the possible difference between the global dispatcher version and the actual undici version you might be using. We recommend to avoid the check `instanceof errors.UndiciError` and seek for the `error.code === '<error_code>'` instead to avoid inconsistencies.
-
-### `ConnectTimeoutError`
-
-When `autoSelectFamily` is enabled and every attempted address fails with a timeout, Node raises an `AggregateError`. Undici surfaces these multi-address timeouts as `ConnectTimeoutError` (so the error shape is the same regardless of whether Node's family-attempt timer or undici's `connectTimeout` wins the race); the original `AggregateError` is preserved on `error.cause`.
-
-### `SocketError`
-
-The `SocketError` has a `.socket` property which holds socket metadata:
+## Class: `UndiciError`
+
+<!-- YAML
+added: v1.0.0
+changes:
+  - version: v7.16.0
+    pr-url: https://github.com/nodejs/undici/pull/4472
+    description: Made `UndiciError` and its subclasses reliable with `instanceof`
+                 across realms and undici versions.
+-->
+
+* Extends: {Error}
+
+The base class for all undici errors. It is reliable with `instanceof` even when
+the error originates from a different undici version, because the check is based
+on a well-known symbol rather than the prototype chain.
+
+* `name` {string} Always `'UndiciError'`.
+* `code` {string} Always `'UND_ERR'`.
+
+## Class: `ConnectTimeoutError`
+
+<!-- YAML
+added: v1.0.0
+changes:
+  - version: v7.16.0
+    pr-url: https://github.com/nodejs/undici/pull/4472
+    description: Made the error reliable with `instanceof`.
+-->
+
+* Extends: {UndiciError}
+
+The socket was destroyed because establishing the connection exceeded the
+`connectTimeout` option.
+
+* `name` {string} Always `'ConnectTimeoutError'`.
+* `code` {string} Always `'UND_ERR_CONNECT_TIMEOUT'`.
+
+When `autoSelectFamily` is enabled and every attempted address times out, Node.js
+raises an `AggregateError`. undici normalizes these multi-address timeouts into a
+`ConnectTimeoutError` so that the error shape is the same regardless of whether
+Node.js's per-address timer or undici's `connectTimeout` wins the race. The
+original `AggregateError` is preserved on `error.cause`.
+
+## Class: `HeadersTimeoutError`
+
+<!-- YAML
+added: v1.0.0
+changes:
+  - version: v7.16.0
+    pr-url: https://github.com/nodejs/undici/pull/4472
+    description: Made the error reliable with `instanceof`.
+-->
+
+* Extends: {UndiciError}
+
+The socket was destroyed because receiving the response headers exceeded the
+`headersTimeout` option.
+
+* `name` {string} Always `'HeadersTimeoutError'`.
+* `code` {string} Always `'UND_ERR_HEADERS_TIMEOUT'`.
+
+## Class: `HeadersOverflowError`
+
+<!-- YAML
+added: v1.0.0
+changes:
+  - version: v7.16.0
+    pr-url: https://github.com/nodejs/undici/pull/4472
+    description: Made the error reliable with `instanceof`.
+-->
+
+* Extends: {UndiciError}
+
+The socket was destroyed because the response headers exceeded the maximum
+allowed size.
+
+* `name` {string} Always `'HeadersOverflowError'`.
+* `code` {string} Always `'UND_ERR_HEADERS_OVERFLOW'`.
+
+## Class: `BodyTimeoutError`
+
+<!-- YAML
+added: v1.0.0
+changes:
+  - version: v7.16.0
+    pr-url: https://github.com/nodejs/undici/pull/4472
+    description: Made the error reliable with `instanceof`.
+-->
+
+* Extends: {UndiciError}
+
+The socket was destroyed because reading the response body exceeded the
+`bodyTimeout` option.
+
+* `name` {string} Always `'BodyTimeoutError'`.
+* `code` {string} Always `'UND_ERR_BODY_TIMEOUT'`.
+
+## Class: `InvalidArgumentError`
+
+<!-- YAML
+added: v1.0.0
+changes:
+  - version: v7.16.0
+    pr-url: https://github.com/nodejs/undici/pull/4472
+    description: Made the error reliable with `instanceof`.
+-->
+
+* Extends: {UndiciError}
+
+An invalid argument was passed to an undici API.
+
+* `name` {string} Always `'InvalidArgumentError'`.
+* `code` {string} Always `'UND_ERR_INVALID_ARG'`.
+
+## Class: `InvalidReturnValueError`
+
+<!-- YAML
+added: v1.0.0
+changes:
+  - version: v7.16.0
+    pr-url: https://github.com/nodejs/undici/pull/4472
+    description: Made the error reliable with `instanceof`.
+-->
+
+* Extends: {UndiciError}
+
+A user-supplied callback or interceptor returned an invalid value.
+
+* `name` {string} Always `'InvalidReturnValueError'`.
+* `code` {string} Always `'UND_ERR_INVALID_RETURN_VALUE'`.
+
+## Class: `AbortError`
+
+<!-- YAML
+added: v1.0.0
+changes:
+  - version: v7.16.0
+    pr-url: https://github.com/nodejs/undici/pull/4472
+    description: Made the error reliable with `instanceof`.
+-->
+
+* Extends: {UndiciError}
+
+The operation was aborted. This is the base class of [`RequestAbortedError`][].
+
+* `name` {string} Always `'AbortError'`.
+* `code` {string} Always `'UND_ERR_ABORT'`.
+
+## Class: `RequestAbortedError`
+
+<!-- YAML
+added: v1.0.0
+changes:
+  - version: v7.16.0
+    pr-url: https://github.com/nodejs/undici/pull/4472
+    description: Made the error reliable with `instanceof`.
+-->
+
+* Extends: {AbortError}
+
+The request was aborted by the user, typically through an `AbortSignal`.
+
+* `name` {string} Always `'AbortError'`.
+* `code` {string} Always `'UND_ERR_ABORTED'`.
+
+## Class: `InformationalError`
+
+<!-- YAML
+added: v1.0.0
+changes:
+  - version: v7.16.0
+    pr-url: https://github.com/nodejs/undici/pull/4472
+    description: Made the error reliable with `instanceof`.
+-->
+
+* Extends: {UndiciError}
+
+An expected error carrying a reason, used internally to surface a cause for a
+failed or retried request (for example as the `cause` of another error).
+
+* `name` {string} Always `'InformationalError'`.
+* `code` {string} Always `'UND_ERR_INFO'`.
+
+## Class: `RequestContentLengthMismatchError`
+
+<!-- YAML
+added: v1.0.0
+changes:
+  - version: v7.16.0
+    pr-url: https://github.com/nodejs/undici/pull/4472
+    description: Made the error reliable with `instanceof`.
+-->
+
+* Extends: {UndiciError}
+
+The length of the request body did not match the `content-length` header.
+
+* `name` {string} Always `'RequestContentLengthMismatchError'`.
+* `code` {string} Always `'UND_ERR_REQ_CONTENT_LENGTH_MISMATCH'`.
+
+## Class: `ResponseContentLengthMismatchError`
+
+<!-- YAML
+added: v1.0.0
+changes:
+  - version: v7.16.0
+    pr-url: https://github.com/nodejs/undici/pull/4472
+    description: Made the error reliable with `instanceof`.
+-->
+
+* Extends: {UndiciError}
+
+The length of the response body did not match the `content-length` header.
+
+* `name` {string} Always `'ResponseContentLengthMismatchError'`.
+* `code` {string} Always `'UND_ERR_RES_CONTENT_LENGTH_MISMATCH'`.
+
+## Class: `ClientDestroyedError`
+
+<!-- YAML
+added: v1.0.0
+changes:
+  - version: v7.16.0
+    pr-url: https://github.com/nodejs/undici/pull/4472
+    description: Made the error reliable with `instanceof`.
+-->
+
+* Extends: {UndiciError}
+
+An operation was attempted on a client that has already been destroyed.
+
+* `name` {string} Always `'ClientDestroyedError'`.
+* `code` {string} Always `'UND_ERR_DESTROYED'`.
+
+## Class: `ClientClosedError`
+
+<!-- YAML
+added: v1.0.0
+changes:
+  - version: v7.16.0
+    pr-url: https://github.com/nodejs/undici/pull/4472
+    description: Made the error reliable with `instanceof`.
+-->
+
+* Extends: {UndiciError}
+
+An operation was attempted on a client that has already been closed.
+
+* `name` {string} Always `'ClientClosedError'`.
+* `code` {string} Always `'UND_ERR_CLOSED'`.
+
+## Class: `SocketError`
+
+<!-- YAML
+added: v1.0.0
+changes:
+  - version: v7.16.0
+    pr-url: https://github.com/nodejs/undici/pull/4472
+    description: Made the error reliable with `instanceof`.
+-->
+
+* Extends: {UndiciError}
+
+An error occurred on the underlying socket.
+
+* `name` {string} Always `'SocketError'`.
+* `code` {string} Always `'UND_ERR_SOCKET'`.
+* `socket` {SocketInfo|null} Metadata about the socket at the time of the error,
+  or `null` when no socket information is available.
+
+The `socket` property, when present, holds the following fields:
 
 ```ts
 interface SocketInfo {
@@ -59,4 +318,207 @@ interface SocketInfo {
 }
 ```
 
-Be aware that in some cases the `.socket` property can be `null`.
+## Class: `NotSupportedError`
+
+<!-- YAML
+added: v1.0.0
+changes:
+  - version: v7.16.0
+    pr-url: https://github.com/nodejs/undici/pull/4472
+    description: Made the error reliable with `instanceof`.
+-->
+
+* Extends: {UndiciError}
+
+Unsupported functionality was requested.
+
+* `name` {string} Always `'NotSupportedError'`.
+* `code` {string} Always `'UND_ERR_NOT_SUPPORTED'`.
+
+## Class: `BalancedPoolMissingUpstreamError`
+
+<!-- YAML
+added: v1.0.0
+changes:
+  - version: v7.16.0
+    pr-url: https://github.com/nodejs/undici/pull/4472
+    description: Made the error reliable with `instanceof`.
+-->
+
+* Extends: {UndiciError}
+
+No upstream has been added to the [`BalancedPool`][].
+
+* `name` {string} Always `'MissingUpstreamError'`.
+* `code` {string} Always `'UND_ERR_BPL_MISSING_UPSTREAM'`.
+
+## Class: `HTTPParserError`
+
+<!-- YAML
+added: v4.0.0
+-->
+
+* Extends: {Error}
+
+An error occurred while parsing the HTTP response. Unlike the other error
+classes, `HTTPParserError` extends {Error} directly rather than
+[`UndiciError`][].
+
+* `name` {string} Always `'HTTPParserError'`.
+* `code` {string} An `HPE_`-prefixed parser error code, or `undefined` when no
+  code was provided.
+* `data` {string} The raw data associated with the parser failure, or
+  `undefined` when none was provided.
+
+## Class: `ResponseExceededMaxSizeError`
+
+<!-- YAML
+added: v1.0.0
+changes:
+  - version: v7.16.0
+    pr-url: https://github.com/nodejs/undici/pull/4472
+    description: Made the error reliable with `instanceof`.
+-->
+
+* Extends: {UndiciError}
+
+The response body exceeded the maximum allowed size.
+
+* `name` {string} Always `'ResponseExceededMaxSizeError'`.
+* `code` {string} Always `'UND_ERR_RES_EXCEEDED_MAX_SIZE'`.
+
+## Class: `RequestRetryError`
+
+<!-- YAML
+added: v1.0.0
+changes:
+  - version: v7.16.0
+    pr-url: https://github.com/nodejs/undici/pull/4472
+    description: Made the error reliable with `instanceof`.
+-->
+
+* Extends: {UndiciError}
+
+A request failed and could not be retried, for example because the body is
+stateful (a stream or `AsyncIterable`) and cannot be replayed.
+
+* `name` {string} Always `'RequestRetryError'`.
+* `code` {string} Always `'UND_ERR_REQ_RETRY'`.
+* `statusCode` {number} The HTTP status code of the failed response.
+* `data` {Object} Retry metadata.
+  * `count` {number} The number of retry attempts that were made.
+* `headers` {Record<string, string|string[]>} The response headers.
+
+### `new RequestRetryError(message, code, options)`
+
+* `message` {string} The error message.
+* `code` {number} The HTTP status code of the failed response.
+* `options` {Object}
+  * `headers` {Object|string[]|null} The response headers. (optional)
+  * `data` {Object|string|null} Retry metadata. (optional)
+
+## Class: `ResponseError`
+
+<!-- YAML
+added: v1.0.0
+changes:
+  - version: v7.16.0
+    pr-url: https://github.com/nodejs/undici/pull/4472
+    description: Made the error reliable with `instanceof`.
+-->
+
+* Extends: {UndiciError}
+
+The response returned an error status code. This is raised, for example, when the
+`throwOnError` option is enabled.
+
+* `name` {string} Always `'ResponseError'`.
+* `code` {string} Always `'UND_ERR_RESPONSE'`.
+* `statusCode` {number} The HTTP status code of the response.
+* `body` {Object|string|null} The response body.
+* `headers` {Object|string[]|null} The response headers.
+
+### `new ResponseError(message, code, options)`
+
+* `message` {string} The error message.
+* `code` {number} The HTTP status code of the response.
+* `options` {Object}
+  * `headers` {Object|string[]|null} The response headers. (optional)
+  * `body` {Object|string|null} The response body. (optional)
+
+## Class: `SecureProxyConnectionError`
+
+<!-- YAML
+added: v1.0.0
+changes:
+  - version: v7.16.0
+    pr-url: https://github.com/nodejs/undici/pull/4472
+    description: Made the error reliable with `instanceof`.
+-->
+
+* Extends: {UndiciError}
+
+A TLS connection to a proxy failed.
+
+* `name` {string} Always `'SecureProxyConnectionError'`.
+* `code` {string} Always `'UND_ERR_PRX_TLS'`.
+* `cause` {Error} The underlying error that caused the proxy connection to fail.
+
+### `new SecureProxyConnectionError(cause[, message[, options]])`
+
+* `cause` {Error} The underlying error. (optional)
+* `message` {string} The error message. (optional)
+* `options` {Object} Additional `Error` options merged with `cause`. (optional)
+
+## Class: `MaxOriginsReachedError`
+
+<!-- YAML
+added: v1.0.0
+changes:
+  - version: v7.16.0
+    pr-url: https://github.com/nodejs/undici/pull/4365
+    description: Added to support capping the number of origins in `Agent`.
+-->
+
+* Extends: {UndiciError}
+
+The maximum number of allowed origins has been reached.
+
+* `name` {string} Always `'MaxOriginsReachedError'`.
+* `code` {string} Always `'UND_ERR_MAX_ORIGINS_REACHED'`.
+
+## Class: `Socks5ProxyError`
+
+<!-- YAML
+added: v7.23.0
+-->
+
+* Extends: {UndiciError}
+
+An error occurred during SOCKS5 proxy negotiation.
+
+* `name` {string} Always `'Socks5ProxyError'`.
+* `code` {string} The error code. **Default:** `'UND_ERR_SOCKS5'`.
+
+### `new Socks5ProxyError([message[, code]])`
+
+* `message` {string} The error message. (optional)
+* `code` {string} The error code. **Default:** `'UND_ERR_SOCKS5'`. (optional)
+
+## Class: `MessageSizeExceededError`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* Extends: {UndiciError}
+
+A decompressed WebSocket message exceeded the maximum allowed size.
+
+* `name` {string} Always `'MessageSizeExceededError'`.
+* `code` {string} Always `'UND_ERR_WS_MESSAGE_SIZE_EXCEEDED'`.
+
+[`BalancedPool`]: BalancedPool.md#class-balancedpool
+[`HTTPParserError`]: #class-httpparsererror
+[`RequestAbortedError`]: #class-requestabortederror
+[`UndiciError`]: #class-undicierror
diff --git a/docs/docs/api/EventSource.md b/docs/docs/api/EventSource.md
index e774bc0f29a..938a7a8c6f2 100644
--- a/docs/docs/api/EventSource.md
+++ b/docs/docs/api/EventSource.md
@@ -1,14 +1,15 @@
 # EventSource
 
-> ⚠️ Warning: the EventSource API is experimental.
+<!--introduced_in=v6.5.0-->
+<!--type=module-->
+<!-- source_link=lib/web/eventsource/eventsource.js -->
 
-Undici exposes a WHATWG spec-compliant implementation of [EventSource](https://developer.mozilla.org/en-US/docs/Web/API/EventSource)
-for [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events).
+> Stability: 1 - Experimental
 
-## Instantiating EventSource
-
-Undici exports an EventSource class. You can instantiate the EventSource as
-follows:
+`EventSource` is a [WHATWG-conformant][] implementation of the
+[server-sent events][] interface. It opens a persistent HTTP connection to a
+server that responds with the `text/event-stream` content type and dispatches
+the events it receives without closing the connection.
 
 ```mjs
 import { EventSource } from 'undici'
@@ -19,11 +20,266 @@ eventSource.onmessage = (event) => {
 }
 ```
 
-## Receiving events from a server
+Constructing an `EventSource` for the first time emits a one-time
+`ExperimentalWarning` with the code `'UNDICI-ES'`. The interface is also
+installed onto `globalThis` as `globalThis.EventSource`.
+
+## Class: `EventSource`
+
+<!-- YAML
+added: v6.5.0
+-->
+
+> Stability: 1 - Experimental
+
+* Extends: {EventTarget}
+
+The `EventSource` interface receives server-sent events over an HTTP
+connection. Instances are created with the [`new EventSource()`](#new-eventsourceurl-eventsourceinitdict)
+constructor and emit [`'open'`](#event-open), [`'message'`](#event-message), and
+[`'error'`](#event-error) events.
+
+### `new EventSource(url[, eventSourceInitDict])`
+
+<!-- YAML
+added: v6.5.0
+-->
 
-EventSource connects to an HTTP endpoint that responds with a `text/event-stream`
-content type. The connection stays open and receives events as the server writes
-them.
+> Stability: 1 - Experimental
+
+* `url` {string|URL} The URL of the event stream. Relative URLs are resolved
+  against the environment's base URL.
+* `eventSourceInitDict` {Object} (optional)
+  * `withCredentials` {boolean} When `true`, the request is made with the
+    credentials mode set to `include` and CORS attribute state set to
+    `use-credentials`; otherwise the credentials mode is `same-origin`.
+    **Default:** `false`.
+  * `dispatcher` {Dispatcher} The dispatcher used for the underlying request.
+    **Default:** the global dispatcher.
+
+    > Stability: 0 - Deprecated. Use `node.dispatcher` instead.
+  * `node` {Object} undici-specific extensions to the standard
+    `EventSourceInit` dictionary.
+    * `dispatcher` {Dispatcher} The dispatcher used for the underlying request.
+      **Default:** the global dispatcher.
+    * `reconnectionTime` {number} The reconnection time, in milliseconds, to
+      wait before re-establishing a dropped connection. The server may override
+      this value with a `retry` field. **Default:** `3000`.
+
+Creates a new `EventSource` and immediately begins connecting to `url`. The
+request is sent with the `Accept: text/event-stream` header, a cache mode of
+`no-store`, and an initiator type of `other`.
+
+If `url` cannot be parsed, a `SyntaxError` `DOMException` is thrown.
+
+```mjs
+import { EventSource } from 'undici'
+
+const eventSource = new EventSource('http://localhost:3000', {
+  withCredentials: true
+})
+```
+
+A custom [`Dispatcher`][] can be supplied to control the underlying request, for
+example to add request headers:
+
+```mjs
+import { EventSource, Agent } from 'undici'
+
+class CustomHeaderAgent extends Agent {
+  dispatch (opts) {
+    opts.headers['x-custom-header'] = 'hello world'
+    return super.dispatch(...arguments)
+  }
+}
+
+const eventSource = new EventSource('http://localhost:3000', {
+  node: {
+    dispatcher: new CustomHeaderAgent()
+  }
+})
+```
+
+### `eventSource.close()`
+
+<!-- YAML
+added: v6.5.0
+-->
+
+> Stability: 1 - Experimental
+
+* Returns: {undefined}
+
+Closes the connection, if any, aborts the underlying request, and sets
+[`eventSource.readyState`](#eventsourcereadystate) to `CLOSED`. Once closed, the
+`EventSource` does not attempt to reconnect. Calling `close()` on an already
+closed `EventSource` has no effect.
+
+### `eventSource.readyState`
+
+<!-- YAML
+added: v6.5.0
+-->
+
+> Stability: 1 - Experimental
+
+* Type: {number}
+
+A read-only number representing the state of the connection. It is one of the
+following constants:
+
+* [`EventSource.CONNECTING`](#eventsourceconnecting) (`0`) — the connection has
+  not yet been established, or it was closed and is being re-established.
+* [`EventSource.OPEN`](#eventsourceopen) (`1`) — the connection is open and
+  events are being dispatched as they are received.
+* [`EventSource.CLOSED`](#eventsourceclosed) (`2`) — the connection is not open
+  and is not being re-established.
+
+### `eventSource.url`
+
+<!-- YAML
+added: v6.5.0
+-->
+
+> Stability: 1 - Experimental
+
+* Type: {string}
+
+A read-only string providing the URL of the event stream, after resolution
+against the environment's base URL.
+
+### `eventSource.withCredentials`
+
+<!-- YAML
+added: v6.5.0
+-->
+
+> Stability: 1 - Experimental
+
+* Type: {boolean}
+
+A read-only boolean indicating whether the `EventSource` was instantiated with
+CORS credentials (`true`), or not (`false`, the default). It reflects the
+`withCredentials` option passed to the constructor.
+
+### `eventSource.onopen`
+
+<!-- YAML
+added: v6.5.0
+-->
+
+> Stability: 1 - Experimental
+
+* Type: {Function|null} **Default:** `null`.
+
+An event handler that is invoked when an [`'open'`](#event-open) event is
+dispatched. Assigning a function registers it as the handler; assigning `null`
+removes the current handler.
+
+### `eventSource.onmessage`
+
+<!-- YAML
+added: v6.5.0
+-->
+
+> Stability: 1 - Experimental
+
+* Type: {Function|null} **Default:** `null`.
+
+An event handler that is invoked when a [`'message'`](#event-message) event is
+dispatched. Assigning a function registers it as the handler; assigning `null`
+removes the current handler.
+
+### `eventSource.onerror`
+
+<!-- YAML
+added: v6.5.0
+-->
+
+> Stability: 1 - Experimental
+
+* Type: {Function|null} **Default:** `null`.
+
+An event handler that is invoked when an [`'error'`](#event-error) event is
+dispatched. Assigning a function registers it as the handler; assigning `null`
+removes the current handler.
+
+### `EventSource.CONNECTING`
+
+<!-- YAML
+added: v6.5.0
+-->
+
+> Stability: 1 - Experimental
+
+* Type: {number}
+
+The numeric constant `0`, representing the `CONNECTING`
+[`readyState`](#eventsourcereadystate). It is defined as a read-only,
+non-writable property on both the `EventSource` constructor and instances.
+
+### `EventSource.OPEN`
+
+<!-- YAML
+added: v6.5.0
+-->
+
+> Stability: 1 - Experimental
+
+* Type: {number}
+
+The numeric constant `1`, representing the `OPEN`
+[`readyState`](#eventsourcereadystate). It is defined as a read-only,
+non-writable property on both the `EventSource` constructor and instances.
+
+### `EventSource.CLOSED`
+
+<!-- YAML
+added: v6.5.0
+-->
+
+> Stability: 1 - Experimental
+
+* Type: {number}
+
+The numeric constant `2`, representing the `CLOSED`
+[`readyState`](#eventsourcereadystate). It is defined as a read-only,
+non-writable property on both the `EventSource` constructor and instances.
+
+### Event: `'open'`
+
+<!-- YAML
+added: v6.5.0
+-->
+
+> Stability: 1 - Experimental
+
+Emitted when the connection is established and the
+[`readyState`](#eventsourcereadystate) becomes `OPEN`. The listener receives an
+{Event}.
+
+```mjs
+import { EventSource } from 'undici'
+
+const eventSource = new EventSource('http://localhost:3000')
+eventSource.addEventListener('open', () => {
+  console.log('connection opened')
+})
+```
+
+### Event: `'message'`
+
+<!-- YAML
+added: v6.15.0
+-->
+
+> Stability: 1 - Experimental
+
+Emitted when a message that has no explicit `event` field is received. The
+listener receives a {MessageEvent} whose `data`, `lastEventId`, and `origin`
+properties are populated from the server-sent event. Named events (those with an
+`event` field) are dispatched under their own type and must be subscribed to with
+[`addEventListener()`][].
 
 ```mjs
 import { createServer } from 'node:http'
@@ -49,44 +305,50 @@ const server = createServer((request, response) => {
 server.listen(3000, () => {
   const eventSource = new EventSource('http://localhost:3000')
 
+  // Named event, delivered under its own type.
   eventSource.addEventListener('ping', (event) => {
     console.log('ping:', event.data)
   })
 
+  // Unnamed event, delivered as 'message'.
   eventSource.onmessage = (event) => {
     console.log('message:', event.data)
   }
-
-  eventSource.onerror = () => {
-    eventSource.close()
-    server.close()
-  }
 })
 ```
 
-The `message` event receives events without an explicit `event:` field. Use
-`addEventListener()` to subscribe to named events.
+### Event: `'error'`
 
-## Using a custom Dispatcher
+<!-- YAML
+added: v6.5.0
+changes:
+  - version: v7.11.0
+    pr-url: https://github.com/nodejs/undici/pull/4247
+    description: The connection is no longer re-established after a network
+                 error; the `EventSource` is closed instead.
+-->
 
-Undici allows you to set your own Dispatcher in the EventSource constructor.
+> Stability: 1 - Experimental
 
-An example which allows you to modify the request headers is:
+Emitted when the connection fails or is interrupted. The listener receives an
+{Event}. When the failure is recoverable, the `EventSource` transitions back to
+`CONNECTING` and retries after the reconnection time; when it is not, the
+`EventSource` transitions to `CLOSED` and does not reconnect.
 
 ```mjs
-import { EventSource, Agent } from 'undici'
+import { EventSource } from 'undici'
 
-class CustomHeaderAgent extends Agent {
-  dispatch (opts) {
-    opts.headers['x-custom-header'] = 'hello world'
-    return super.dispatch(...arguments)
+const eventSource = new EventSource('http://localhost:3000')
+eventSource.onerror = () => {
+  if (eventSource.readyState === EventSource.CLOSED) {
+    console.log('connection closed')
+  } else {
+    console.log('reconnecting')
   }
 }
-
-const eventSource = new EventSource('http://localhost:3000', {
-  dispatcher: new CustomHeaderAgent()
-})
 ```
 
-More information about the EventSource API can be found on
-[MDN](https://developer.mozilla.org/en-US/docs/Web/API/EventSource).
+[WHATWG-conformant]: https://html.spec.whatwg.org/multipage/server-sent-events.html#server-sent-events
+[`Dispatcher`]: Dispatcher.md#class-dispatcher
+[`addEventListener()`]: https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener
+[server-sent events]: https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events
diff --git a/docs/docs/api/Fetch.md b/docs/docs/api/Fetch.md
index 1e0c962fbc3..af352742232 100644
--- a/docs/docs/api/Fetch.md
+++ b/docs/docs/api/Fetch.md
@@ -1,51 +1,643 @@
 # Fetch
 
-Undici exposes a fetch() method starts the process of fetching a resource from the network.
+<!--introduced_in=v1.0.0-->
+<!--type=module-->
+<!-- source_link=lib/web/fetch/index.js -->
 
-Documentation and examples can be found on [MDN](https://developer.mozilla.org/en-US/docs/Web/API/fetch).
+> Stability: 2 - Stable
 
-## FormData
+undici implements the [WHATWG Fetch Standard][], providing `fetch()` together
+with the `Request`, `Response`, `Headers`, and `FormData` classes that mirror
+the browser APIs. The implementation follows the standard, so the
+[MDN Fetch documentation][] applies as well.
 
-This API is implemented as per the standard, you can find documentation on [MDN](https://developer.mozilla.org/en-US/docs/Web/API/FormData).
+```mjs
+import { fetch, Request, Response, Headers, FormData } from 'undici'
+
+const response = await fetch('https://example.com')
+const text = await response.text()
+```
+
+When mixing these classes, keep them from the same implementation: use the
+global `fetch()` with the global `FormData`, `Request`, `Response`, and
+`Headers`, and use undici's `fetch()` with undici's classes. Passing a value
+created by one implementation to the other can throw.
+
+## `fetch(input[, init])`
+
+<!-- YAML
+added: v5.6.0
+changes:
+  - version: v5.6.1
+    pr-url: https://github.com/nodejs/undici/pull/1529
+    description: No default value is assigned to `init.method`.
+-->
+
+* `input` {string|URL|Request} The resource to fetch. A string or {URL} is
+  treated as the URL to request; a {Request} is used as the request template.
+* `init` {RequestInit} (optional) An options object that customizes the
+  request.
+  * `body` {string|Buffer|Uint8Array|Blob|FormData|URLSearchParams|ReadableStream|null}
+    The request body. **Default:** `null`.
+  * `cache` {string} The cache mode. One of `'default'`, `'force-cache'`,
+    `'no-cache'`, `'no-store'`, `'only-if-cached'`, or `'reload'`.
+  * `credentials` {string} How credentials are sent. One of `'omit'`,
+    `'include'`, or `'same-origin'`.
+  * `dispatcher` {Dispatcher} The {Dispatcher} used to perform the request.
+    **Default:** the global dispatcher.
+  * `duplex` {string} The duplex mode of the request. Must be `'half'` when a
+    streaming `body` is provided.
+  * `headers` {Headers|Object|Array} The request headers, as a {Headers}
+    instance, a plain object, or an array of `[name, value]` pairs.
+  * `integrity` {string} The subresource integrity metadata of the request.
+  * `keepalive` {boolean} Whether the connection may outlive the page.
+    **Default:** `false`.
+  * `method` {string} The request method, for example `'GET'` or `'POST'`.
+  * `mode` {string} The request mode. One of `'cors'`, `'navigate'`,
+    `'no-cors'`, or `'same-origin'`.
+  * `redirect` {string} How redirects are handled. One of `'error'`,
+    `'follow'`, or `'manual'`.
+  * `referrer` {string} The request referrer.
+  * `referrerPolicy` {string} The referrer policy. One of `''`,
+    `'no-referrer'`, `'no-referrer-when-downgrade'`, `'origin'`,
+    `'origin-when-cross-origin'`, `'same-origin'`, `'strict-origin'`,
+    `'strict-origin-when-cross-origin'`, or `'unsafe-url'`.
+  * `signal` {AbortSignal|null} An {AbortSignal} used to abort the request.
+    **Default:** `null`.
+  * `window` {null} Can only be `null`; reserved by the standard.
+* Returns: {Promise} Fulfills with a {Response} once the response headers have
+  been received.
+
+Starts the process of fetching a resource from the network and returns a
+promise that fulfills with a {Response}. The promise rejects only on network
+failures; an HTTP error status such as `404` still fulfills the promise, so
+inspect [`response.ok`](#responseok) to detect failures.
+
+```mjs
+import { fetch } from 'undici'
+
+const response = await fetch('https://example.com', {
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify({ hello: 'world' }),
+})
+
+console.log(response.status)
+console.log(await response.json())
+```
+
+To route the request through a custom {Dispatcher} (for example a `ProxyAgent`
+or `Agent` with specific options), pass it as `init.dispatcher`.
+
+```mjs
+import { fetch, Agent } from 'undici'
+
+const response = await fetch('https://example.com', {
+  dispatcher: new Agent({ connect: { rejectUnauthorized: false } }),
+})
+```
+
+## Class: `FormData`
+
+<!-- YAML
+added: v4.4.4
+-->
+
+A set of key/value pairs representing form fields and their values, suitable
+for use as a `fetch()` request `body`. The implementation follows the
+[WHATWG Fetch Standard][]; see the [MDN `FormData` documentation][].
+
+When using `FormData` as a request body, keep `fetch` and `FormData` from the
+same implementation: use the global `FormData` with the global `fetch()`, and
+undici's `FormData` with undici's `fetch()`.
+
+### `new FormData()`
+
+<!-- YAML
+added: v4.4.4
+-->
 
-If any parameters are passed to the FormData constructor other than `undefined`, an error will be thrown. Other parameters are ignored.
+Creates a new, empty `FormData` instance. Passing any argument other than
+`undefined` throws; in particular, an `HTMLFormElement` argument is not
+supported in this environment.
 
-When you use `FormData` as a request body, keep `fetch` and `FormData` from the
-same implementation. Use the built-in global `FormData` with the built-in
-global `fetch()`, and use `undici`'s `FormData` with `undici.fetch()`.
+### `formData.append(name, value[, filename])`
 
-If you want the installed `undici` package to provide the globals, call
-[`install()`](/docs/docs/api/GlobalInstallation.md) so `fetch`, `Headers`,
-`Response`, `Request`, and `FormData` are installed together as a matching set.
+<!-- YAML
+added: v1.0.0
+-->
 
-## Response
+* `name` {string} The name of the field.
+* `value` {string|Blob} The value of the field.
+* `filename` {string} The filename reported to the server when `value` is a
+  {Blob}. (optional)
 
-This API is implemented as per the standard, you can find documentation on [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Response)
+Appends a new value to an existing key, or adds the key if it does not exist.
+Unlike [`formData.set()`](#formdatasetname-value-filename), `append()` keeps
+any existing values for `name`.
 
-## Request
+### `formData.delete(name)`
 
-This API is implemented as per the standard, you can find documentation on [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Request)
+<!-- YAML
+added: v1.0.0
+-->
 
-## Headers
+* `name` {string} The name of the field to remove.
 
-This API is implemented as per the standard, you can find documentation on [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Headers)
+Deletes all values associated with `name`.
 
-# Body Mixins
+### `formData.get(name)`
 
-`Response` and `Request` body inherit body mixin methods. These methods include:
+<!-- YAML
+added: v1.0.0
+-->
 
-- [`.arrayBuffer()`](https://fetch.spec.whatwg.org/#dom-body-arraybuffer)
-- [`.blob()`](https://fetch.spec.whatwg.org/#dom-body-blob)
-- [`.bytes()`](https://fetch.spec.whatwg.org/#dom-body-bytes)
-- [`.formData()`](https://fetch.spec.whatwg.org/#dom-body-formdata)
-- [`.json()`](https://fetch.spec.whatwg.org/#dom-body-json)
-- [`.text()`](https://fetch.spec.whatwg.org/#dom-body-text)
+* `name` {string} The name of the field to read.
+* Returns: {string|File|null} The first value associated with `name`, or
+  `null` if there is none.
 
-There is an ongoing discussion regarding `body.formData()` and its usefulness, performance, and security in server environments. Calling `body.formData()` causes undici to buffer and parse the entire body. Because multipart parsing has inherent security risks, `body.formData()` must only be called on responses from trusted servers.
+### `formData.getAll(name)`
 
-For responses from untrusted or user-controlled servers, use a dedicated streaming library for parsing `multipart/form-data` bodies, such as [Busboy](https://www.npmjs.com/package/busboy) or [@fastify/busboy](https://www.npmjs.com/package/@fastify/busboy), and apply application-specific limits.
+<!-- YAML
+added: v1.0.0
+-->
 
-These libraries can be interfaced with fetch with the following example code:
+* `name` {string} The name of the field to read.
+* Returns: {Array} All values associated with `name`, as an array of
+  {string} and {File} entries.
+
+### `formData.has(name)`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* `name` {string} The name of the field to look up.
+* Returns: {boolean} `true` if at least one value is associated with `name`.
+
+### `formData.set(name, value[, filename])`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* `name` {string} The name of the field.
+* `value` {string|Blob} The value of the field.
+* `filename` {string} The filename reported to the server when `value` is a
+  {Blob}. (optional)
+
+Sets a new value for an existing key, or adds the key if it does not exist,
+replacing any values previously associated with `name`.
+
+## Class: `Response`
+
+<!-- YAML
+added: v4.4.0
+-->
+
+* Extends: {BodyMixin}
+
+Represents the response to a request. Instances are typically obtained by
+awaiting `fetch()`, but can also be constructed directly. The implementation
+follows the [WHATWG Fetch Standard][]; see the
+[MDN `Response` documentation][]. `Response` inherits the body-reading methods
+described in [Body mixin](#body-mixin).
+
+### `new Response([body[, init]])`
+
+<!-- YAML
+added: v4.4.0
+-->
+
+* `body` {string|Buffer|Uint8Array|Blob|FormData|URLSearchParams|ReadableStream|null}
+  The response body. **Default:** `null`.
+* `init` {ResponseInit} (optional)
+  * `status` {number} The response status code. **Default:** `200`.
+  * `statusText` {string} The response status message. **Default:** `''`.
+  * `headers` {Headers|Object|Array} The response headers.
+
+Creates a new `Response`.
+
+### Static method: `Response.error()`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* Returns: {Response} A network-error response.
+
+Returns a new `Response` representing a network error, with its
+[`type`](#responsetype) set to `'error'`.
+
+### Static method: `Response.json(data[, init])`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* `data` {any} The value to serialize as JSON.
+* `init` {ResponseInit} (optional)
+  * `status` {number} The response status code. **Default:** `200`.
+  * `statusText` {string} The response status message. **Default:** `''`.
+  * `headers` {Headers|Object|Array} The response headers.
+* Returns: {Response} A response whose body is the JSON serialization of
+  `data` and whose `Content-Type` is `application/json`.
+
+```mjs
+import { Response } from 'undici'
+
+const response = Response.json({ ok: true }, { status: 201 })
+```
+
+### Static method: `Response.redirect(url[, status])`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* `url` {string|URL} The URL to redirect to.
+* `status` {number} The redirect status code. One of `301`, `302`, `303`,
+  `307`, or `308`. **Default:** `302`.
+* Returns: {Response} A redirect response with the `Location` header set to
+  `url`.
+
+### `response.clone()`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* Returns: {Response} A copy of the response.
+
+Creates a clone of the response. Throws a `TypeError` if the body has already
+been read or is locked.
+
+### `response.type`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* Type: {string} The response type. One of `'basic'`, `'cors'`, `'default'`,
+  `'error'`, `'opaque'`, or `'opaqueredirect'`.
+
+### `response.url`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* Type: {string} The final URL of the response after any redirects, or the
+  empty string if not available.
+
+### `response.redirected`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* Type: {boolean} `true` if the response is the result of one or more
+  redirects.
+
+### `response.status`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* Type: {number} The HTTP status code of the response.
+
+### `response.ok`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* Type: {boolean} `true` when [`status`](#responsestatus) is in the range
+  `200`–`299`.
+
+### `response.statusText`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* Type: {string} The status message corresponding to the status code.
+
+### `response.headers`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* Type: {Headers} The {Headers} object associated with the response.
+
+## Class: `Request`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* Extends: {BodyMixin}
+
+Represents a resource request. Instances can be passed to `fetch()` in place
+of a URL string. The implementation follows the [WHATWG Fetch Standard][]; see
+the [MDN `Request` documentation][]. `Request` inherits the body-reading
+methods described in [Body mixin](#body-mixin).
+
+### `new Request(input[, init])`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* `input` {string|URL|Request} The resource to request, as a URL string,
+  {URL}, or another {Request} to copy.
+* `init` {RequestInit} (optional) An options object with the same fields as
+  the `init` argument of [`fetch()`](#fetchinput-init).
+* Returns: {Request}
+
+Creates a new `Request`.
+
+### `request.clone()`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* Returns: {Request} A copy of the request.
+
+Creates a clone of the request. Throws a `TypeError` if the body has already
+been read or is locked.
+
+### `request.method`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* Type: {string} The request method, for example `'GET'`.
+
+### `request.url`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* Type: {string} The serialized URL of the request.
+
+### `request.headers`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* Type: {Headers} The {Headers} object associated with the request.
+
+### `request.destination`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* Type: {string} The request destination, indicating the type of content being
+  requested, for example `''`, `'image'`, or `'script'`.
+
+### `request.referrer`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* Type: {string} The referrer of the request. May be `'about:client'` or a URL
+  string.
+
+### `request.referrerPolicy`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* Type: {string} The referrer policy of the request.
+
+### `request.mode`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* Type: {string} The mode of the request. One of `'cors'`, `'navigate'`,
+  `'no-cors'`, or `'same-origin'`.
+
+### `request.credentials`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* Type: {string} The credentials mode of the request. One of `'omit'`,
+  `'include'`, or `'same-origin'`.
+
+### `request.cache`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* Type: {string} The cache mode of the request.
+
+### `request.redirect`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* Type: {string} The redirect mode of the request. One of `'error'`,
+  `'follow'`, or `'manual'`.
+
+### `request.integrity`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* Type: {string} The subresource integrity metadata of the request.
+
+### `request.keepalive`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* Type: {boolean} Whether the request may outlive the environment that created
+  it.
+
+### `request.isReloadNavigation`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* Type: {boolean} `true` if the request is a reload navigation.
+
+### `request.isHistoryNavigation`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* Type: {boolean} `true` if the request is a history navigation.
+
+### `request.signal`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* Type: {AbortSignal} The {AbortSignal} associated with the request.
+
+### `request.duplex`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* Type: {string} The duplex mode of the request. Always `'half'`.
+
+## Class: `Headers`
+
+<!-- YAML
+added: v4.4.0
+-->
+
+Represents the header list of a request or response and provides methods to
+read and modify it. The implementation follows the [WHATWG Fetch Standard][];
+see the [MDN `Headers` documentation][]. `Headers` is iterable, yielding
+`[name, value]` pairs sorted by name.
+
+### `new Headers([init])`
+
+<!-- YAML
+added: v4.4.0
+-->
+
+* `init` {Headers|Object|Array} (optional) Initial headers, as a {Headers}
+  instance, a plain object of name/value pairs, or an array of `[name, value]`
+  pairs.
+
+Creates a new `Headers` object.
+
+### `headers.append(name, value)`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* `name` {string} The name of the header.
+* `value` {string} The value of the header.
+
+Appends a value to a header, or adds the header if it does not exist. Existing
+values for `name` are preserved.
+
+### `headers.delete(name)`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* `name` {string} The name of the header to remove.
+
+Removes the header named `name`.
+
+### `headers.get(name)`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* `name` {string} The name of the header to read.
+* Returns: {string|null} The combined values of the header, or `null` if it is
+  not present.
+
+### `headers.has(name)`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* `name` {string} The name of the header to look up.
+* Returns: {boolean} `true` if the header is present.
+
+### `headers.set(name, value)`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* `name` {string} The name of the header.
+* `value` {string} The value of the header.
+
+Sets a header to a single value, replacing any existing values for `name`.
+
+### `headers.getSetCookie()`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* Returns: {string[]} An array of the values of all `Set-Cookie` headers.
+
+Returns each `Set-Cookie` header as a separate string, without combining them.
+
+## Body mixin
+
+`Request` and `Response` both extend {BodyMixin}, which provides methods and
+properties for reading a body. Each consuming method reads the body once; after
+the body has been consumed, [`bodyUsed`](#bodybodyused) becomes `true` and
+calling another consuming method throws a `TypeError`.
+
+### `body.arrayBuffer()`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* Returns: {Promise} Fulfills with an {ArrayBuffer} containing the body bytes.
+
+### `body.blob()`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* Returns: {Promise} Fulfills with a {Blob} containing the body.
+
+### `body.bytes()`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* Returns: {Promise} Fulfills with a {Uint8Array} containing the body bytes.
+
+### `body.formData()`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+> Stability: 0 - Deprecated
+
+* Returns: {Promise} Fulfills with a {FormData} parsed from the body.
+
+Buffers and parses the entire body as `multipart/form-data` or
+`application/x-www-form-urlencoded`. Because multipart parsing has inherent
+security risks and the whole body is buffered, this method must only be called
+on responses from trusted servers.
+
+For responses from untrusted or user-controlled servers, use a dedicated
+streaming parser such as [@fastify/busboy][] and apply application-specific
+limits:
 
 ```mjs
 import { Busboy } from '@fastify/busboy'
@@ -53,10 +645,67 @@ import { Readable } from 'node:stream'
 
 const response = await fetch('...')
 const busboy = new Busboy({
-  headers: {
-    'content-type': response.headers.get('content-type')
-  }
+  headers: { 'content-type': response.headers.get('content-type') },
 })
 
+// Handle the events emitted by `busboy`.
+
 Readable.fromWeb(response.body).pipe(busboy)
 ```
+
+### `body.json()`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* Returns: {Promise} Fulfills with the result of parsing the body as JSON.
+
+### `body.text()`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* Returns: {Promise} Fulfills with a {string} containing the body decoded as
+  UTF-8.
+
+### `body.textStream()`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+> Stability: 1 - Experimental
+
+* Returns: {ReadableStream} A {ReadableStream} of {string} chunks produced by
+  decoding the body as UTF-8.
+
+An undici-specific extension that exposes the body as a stream of decoded text
+chunks rather than buffering it. It is not part of the [WHATWG Fetch
+Standard][].
+
+### `body.body`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* Type: {ReadableStream|null} The body as a {ReadableStream}, or `null` if the
+  message has no body.
+
+### `body.bodyUsed`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* Type: {boolean} `true` once the body has been read.
+
+[@fastify/busboy]: https://www.npmjs.com/package/@fastify/busboy
+[MDN Fetch documentation]: https://developer.mozilla.org/en-US/docs/Web/API/fetch
+[MDN `FormData` documentation]: https://developer.mozilla.org/en-US/docs/Web/API/FormData
+[MDN `Headers` documentation]: https://developer.mozilla.org/en-US/docs/Web/API/Headers
+[MDN `Request` documentation]: https://developer.mozilla.org/en-US/docs/Web/API/Request
+[MDN `Response` documentation]: https://developer.mozilla.org/en-US/docs/Web/API/Response
+[WHATWG Fetch Standard]: https://fetch.spec.whatwg.org/
diff --git a/docs/docs/api/GlobalInstallation.md b/docs/docs/api/GlobalInstallation.md
index d2f8f77e7b8..f50504a375d 100644
--- a/docs/docs/api/GlobalInstallation.md
+++ b/docs/docs/api/GlobalInstallation.md
@@ -1,24 +1,70 @@
 # Global Installation
 
-Undici provides an `install()` function to add fetch-related and other web API classes to `globalThis`, making them available globally without requiring imports.
+<!--introduced_in=v7.11.0-->
+<!--type=module-->
+<!-- source_link=index.js -->
 
-## `install()`
-
-Install undici's global web APIs on `globalThis`.
+> Stability: 2 - Stable
 
-**Example:**
+undici ships its own implementations of several WHATWG web APIs. The `install()`
+function assigns those implementations onto `globalThis`, so they can be used
+without importing them from `'undici'` first. This is useful for polyfilling
+environments, guaranteeing consistent behavior across Node.js versions, and
+satisfying third-party libraries that expect the relevant classes to be global.
 
-```js
+```mjs
 import { install } from 'undici'
 
-// Install undici's global web APIs
 install()
 
-// Now you can use fetch classes globally without importing
-const response = await fetch('https://api.example.com/data')
-const data = await response.json()
+// `fetch`, `Headers`, `Response`, `Request`, etc. now resolve to undici's
+// implementations.
+const response = await fetch('https://example.com')
+```
+
+```cjs
+const { install } = require('undici')
+
+install()
+```
+
+## `install()`
+
+<!-- YAML
+added: v7.11.0
+-->
+
+* Returns: {undefined}
+
+Overwrites the following properties of `globalThis` with undici's
+implementations:
+
+* `globalThis.fetch`
+* `globalThis.Headers`
+* `globalThis.Response`
+* `globalThis.Request`
+* `globalThis.FormData`
+* `globalThis.WebSocket`
+* `globalThis.CloseEvent`
+* `globalThis.ErrorEvent`
+* `globalThis.MessageEvent`
+* `globalThis.EventSource`
+
+Each installed value is the same object exported by `'undici'` under the
+matching name, so the global identifiers form a single, self-consistent set.
+The assignment is unconditional: any pre-existing global of the same name,
+including the Node.js built-in, is replaced. The change persists for the
+lifetime of the process. Calling `install()` more than once is safe and simply
+re-assigns the same values.
+
+Documentation for each installed class lives on its own page: see
+[`fetch`][], [`WebSocket`][], and [`EventSource`][].
+
+```mjs
+import { install } from 'undici'
+
+install()
 
-// All classes are available globally:
 const headers = new Headers([['content-type', 'application/json']])
 const request = new Request('https://example.com')
 const formData = new FormData()
@@ -26,116 +72,50 @@ const ws = new WebSocket('wss://example.com')
 const eventSource = new EventSource('https://example.com/events')
 ```
 
-## Installed Classes
-
-The `install()` function adds the following classes to `globalThis`:
-
-| Class | Description |
-|-------|-------------|
-| `fetch` | The fetch function for making HTTP requests |
-| `Headers` | HTTP headers management |
-| `Response` | HTTP response representation |
-| `Request` | HTTP request representation |
-| `FormData` | Form data handling |
-| `WebSocket` | WebSocket client |
-| `CloseEvent` | WebSocket close event |
-| `ErrorEvent` | WebSocket error event |
-| `MessageEvent` | WebSocket message event |
-| `EventSource` | Server-sent events client |
-
-## Using `FormData` with `fetch`
+### Pairing `fetch` and `FormData`
 
-If you send a `FormData` body, use matching implementations for `fetch` and
-`FormData`.
+When a request body is a `FormData` instance, the `fetch` and `FormData`
+implementations must come from the same source. After `install()`, both globals
+resolve to undici, so they always match:
 
-These two patterns are safe:
-
-```js
-// Built-in globals from Node.js
-const body = new FormData()
-await fetch('https://example.com', {
-  method: 'POST',
-  body
-})
-```
-
-```js
-// Globals installed from the undici package
+```mjs
 import { install } from 'undici'
 
 install()
 
 const body = new FormData()
-await fetch('https://example.com', {
-  method: 'POST',
-  body
-})
+await fetch('https://example.com', { method: 'POST', body })
 ```
 
-After `install()`, `fetch`, `Headers`, `Response`, `Request`, and `FormData`
-all come from the installed `undici` package, so they work as a matching set.
-`WebSocket`, `CloseEvent`, `ErrorEvent`, `MessageEvent`, and `EventSource`
-also come from the installed `undici` package.
+If global installation is not desired, import the matching pair directly from
+`'undici'` instead:
 
-If you do not want to install globals, import both from `undici` instead:
-
-```js
+```mjs
 import { fetch, FormData } from 'undici'
 
 const body = new FormData()
-await fetch('https://example.com', {
-  method: 'POST',
-  body
-})
+await fetch('https://example.com', { method: 'POST', body })
 ```
 
-Avoid mixing a global `FormData` with `undici.fetch()`, or `undici.FormData`
-with the built-in global `fetch()`. Keeping them paired avoids surprising
-multipart behavior across Node.js and undici versions.
-
-## Use Cases
+Mixing a global `FormData` with `undici.fetch()`, or `undici.FormData` with the
+built-in global `fetch()`, can produce surprising multipart behavior across
+Node.js and undici versions. Keep the two paired.
 
-Global installation is useful for:
+### Conditional installation
 
-- **Polyfilling environments** that don't have native fetch support
-- **Ensuring consistent behavior** across different Node.js versions
-- **Library compatibility** when third-party libraries expect global fetch
-- **Migration scenarios** where you want to replace built-in implementations
-- **Testing environments** where you need predictable fetch behavior
+`install()` can be guarded so undici's `fetch` is only installed when no global
+`fetch` already exists:
 
-## Example: Polyfilling an Environment
-
-```js
+```mjs
 import { install } from 'undici'
 
-// Check if fetch is available and install if needed
 if (typeof globalThis.fetch === 'undefined') {
   install()
-  console.log('Undici fetch installed globally')
 }
 
-// Now fetch is guaranteed to be available
-const response = await fetch('https://api.example.com')
+const response = await fetch('https://example.com')
 ```
 
-## Example: Testing Environment
-
-```js
-import { install } from 'undici'
-
-// In test setup, ensure consistent fetch behavior
-install()
-
-// Now all tests use undici's implementations
-test('fetch API test', async () => {
-  const response = await fetch('https://example.com')
-  expect(response).toBeInstanceOf(Response)
-})
-```
-
-## Notes
-
-- The `install()` function overwrites any existing global implementations
-- Classes installed are undici's implementations, not Node.js built-ins
-- This provides access to undici's latest fetch, WebSocket, and EventSource features and performance improvements
-- The global installation persists for the lifetime of the process
+[`EventSource`]: EventSource.md#class-eventsource
+[`WebSocket`]: WebSocket.md#class-websocket
+[`fetch`]: Fetch.md
diff --git a/docs/docs/api/H2CClient.md b/docs/docs/api/H2CClient.md
index 2c96ae921f5..298a7d4c688 100644
--- a/docs/docs/api/H2CClient.md
+++ b/docs/docs/api/H2CClient.md
@@ -1,263 +1,385 @@
-# Class: H2CClient
+# H2CClient
 
-Extends: `undici.Dispatcher`
+<!--introduced_in=v7.7.0-->
+<!--type=module-->
+<!-- source_link=lib/dispatcher/h2c-client.js -->
 
-A basic H2C client.
+> Stability: 2 - Stable
 
-**Example**
+An `H2CClient` is a [`Dispatcher`][] that speaks HTTP/2 in cleartext (h2c) over a
+single TCP connection to an `http:` origin, without the protocol upgrade or prior
+knowledge negotiation that a regular [`Client`][] performs. It is a thin
+specialization of [`Client`][] that forces `allowH2` and `useH2c` on and aliases
+`pipelining` to `maxConcurrentStreams`, so multiple requests are multiplexed as
+HTTP/2 streams rather than pipelined HTTP/1.x requests.
 
-```js
-const { createServer } = require('node:http2')
-const { once } = require('node:events')
-const { H2CClient } = require('undici')
+Use an `H2CClient` when the server is known to accept cleartext HTTP/2 directly,
+for example a service behind a trusted proxy or in a test environment. Only the
+`http:` protocol is supported; passing any other protocol throws
+`InvalidArgumentError`.
 
-const server = createServer((req, res) => {
-  res.writeHead(200)
-  res.end('Hello, world!')
-})
+```mjs
+import { H2CClient } from 'undici'
 
-server.listen()
-once(server, 'listening').then(async () => {
-  const client = new H2CClient(`http://localhost:${server.address().port}/`)
+const client = new H2CClient('http://localhost:3000')
 
-  const response = await client.request({ path: '/', method: 'GET' })
-  console.log(response.statusCode) // 200
-  response.body.text.then((text) => {
-    console.log(text) // Hello, world!
-  })
-})
+const { statusCode, body } = await client.request({ path: '/', method: 'GET' })
+console.log(statusCode)
+console.log(await body.text())
 ```
 
-## `new H2CClient(url[, options])`
+## Class: `H2CClient`
+
+<!-- YAML
+added: v7.7.0
+changes:
+  - version: v7.17.0
+    pr-url: https://github.com/nodejs/undici/pull/4690
+    description: Added support for h2c over Unix domain sockets.
+-->
+
+* Extends: {Client}
+
+`H2CClient` inherits the full instance API of [`Client`][] (and therefore of
+[`Dispatcher`][]). The sections below cover the surface that is meaningful for an
+h2c client; refer to [`Dispatcher`][] for the complete semantics of each method
+and event.
+
+### `new H2CClient(url[, options])`
+
+<!-- YAML
+added: v7.7.0
+-->
+
+* `url` {URL|string} The origin to connect to. Should include only the protocol,
+  hostname, and port. Only the `http:` protocol is supported.
+* `options` {H2CClientOptions} (optional)
+  * `maxConcurrentStreams` {number} The maximum number of concurrent HTTP/2
+    streams for the session. It is advertised to the server and may be overridden
+    by a remote `SETTINGS` frame. Must be a positive integer. **Default:** `100`.
+  * `pipelining` {number} The number of concurrent requests multiplexed over the
+    single connection. For an `H2CClient` this is aliased to
+    `maxConcurrentStreams` and may not exceed it. Must be a positive integer.
+    **Default:** `100`.
+  * `maxHeaderSize` {number} The maximum length of request headers in bytes.
+    **Default:** Node.js' `--max-http-header-size` or `16384` (16 KiB).
+  * `headersTimeout` {number} The amount of time, in milliseconds, the parser
+    waits to receive the complete HTTP headers. **Default:** `300e3`.
+  * `connectTimeout` {number} The timeout for establishing a socket connection,
+    in milliseconds. Use `0` to disable it entirely. **Default:** `10e3`.
+  * `bodyTimeout` {number} The timeout, in milliseconds, after which a request
+    times out. Monitors the time between received body data. Use `0` to disable
+    it entirely. **Default:** `300e3`.
+  * `keepAliveTimeout` {number} The timeout, in milliseconds, after which a
+    socket without active requests times out. May be overridden by _keep-alive_
+    hints from the server. **Default:** `4e3`.
+  * `keepAliveMaxTimeout` {number} The maximum allowed `keepAliveTimeout`, in
+    milliseconds, when overridden by _keep-alive_ hints from the server.
+    **Default:** `600e3`.
+  * `keepAliveTimeoutThreshold` {number} A number of milliseconds subtracted from
+    server _keep-alive_ hints when overriding `keepAliveTimeout`, to account for
+    timing inaccuracies such as transport latency. **Default:** `1e3`.
+  * `socketPath` {string} An IPC endpoint, either a Unix domain socket or a
+    Windows named pipe. **Default:** `null`.
+  * `strictContentLength` {boolean} If `true`, an error is thrown when the
+    request `content-length` header does not match the length of the request
+    body. **Default:** `true`.
+  * `maxCachedSessions` {number} The maximum number of TLS sessions cached by the
+    built-in connector. Use `0` to disable TLS session caching. **Default:** `100`.
+  * `connect` {Object|Function} Connector options passed to `buildConnector`, or
+    a custom connector function. The `allowH2` option may not be set here.
+    **Default:** `null`.
+  * `maxRequestsPerClient` {number} The maximum number of requests to send over
+    a single connection before it is reset. Use `0` to disable this limit.
+    **Default:** `null`.
+  * `localAddress` {string} The local IP address the socket should connect from.
+  * `maxResponseSize` {number} The maximum allowed response body size in bytes.
+    Use `-1` to disable. **Default:** `-1`.
+  * `autoSelectFamily` {boolean} Enables a family autodetection algorithm that
+    loosely implements section 5 of [RFC 8305][]. Ignored if not supported by the
+    current Node.js version.
+  * `autoSelectFamilyAttemptTimeout` {number} The amount of time, in
+    milliseconds, to wait for a connection attempt to finish before trying the
+    next address when `autoSelectFamily` is enabled.
+
+Creates a new `H2CClient` for the given origin. The client does not connect until
+a request is queued; call [`h2cClient.connect()`](#h2cclientconnectoptions-callback)
+to connect eagerly.
+
+```mjs
+import { H2CClient } from 'undici'
+
+const client = new H2CClient('http://localhost:3000')
+```
 
-Arguments:
+### `h2cClient.close([callback])`
 
-- **url** `URL | string` - Should only include the **protocol, hostname, and port**. It only supports `http` protocol.
-- **options** `H2CClientOptions` (optional)
+<!-- YAML
+added: v7.7.0
+-->
 
-Returns: `H2CClient`
+* `callback` {Function} (optional) Invoked once all queued requests have settled
+  and the client is closed.
+* Returns: {Promise|undefined} A `Promise` that resolves once the client is
+  closed, when `callback` is not provided.
 
-### Parameter: `H2CClientOptions`
+Closes the client and gracefully waits for enqueued requests to complete before
+resolving. See [`dispatcher.close([callback])`][].
 
-- **bodyTimeout** `number | null` (optional) - Default: `300e3` - The timeout after which a request will time out, in milliseconds. Monitors time between receiving body data. Use `0` to disable it entirely. Defaults to 300 seconds. Please note the `timeout` will be reset if you keep writing data to the socket everytime.
-- **headersTimeout** `number | null` (optional) - Default: `300e3` - The amount of time, in milliseconds, the parser will wait to receive the complete HTTP headers while not sending the request. Defaults to 300 seconds.
-- **keepAliveMaxTimeout** `number | null` (optional) - Default: `600e3` - The maximum allowed `keepAliveTimeout`, in milliseconds, when overridden by _keep-alive_ hints from the server. Defaults to 10 minutes.
-- **keepAliveTimeout** `number | null` (optional) - Default: `4e3` - The timeout, in milliseconds, after which a socket without active requests will time out. Monitors time between activity on a connected socket. This value may be overridden by _keep-alive_ hints from the server. See [MDN: HTTP - Headers - Keep-Alive directives](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Keep-Alive#directives) for more details. Defaults to 4 seconds.
-- **keepAliveTimeoutThreshold** `number | null` (optional) - Default: `2e3` - A number of milliseconds subtracted from server _keep-alive_ hints when overriding `keepAliveTimeout` to account for timing inaccuracies caused by e.g. transport latency. Defaults to 2 seconds.
-- **maxHeaderSize** `number | null` (optional) - Default: `--max-http-header-size` or `16384` - The maximum length of request headers in bytes. Defaults to Node.js' --max-http-header-size or 16KiB.
-- **maxResponseSize** `number | null` (optional) - Default: `-1` - The maximum length of response body in bytes. Set to `-1` to disable.
-- **maxConcurrentStreams**: `number` - Default: `100`. The maximum number of concurrent HTTP/2 streams per session — also advertised to the server as `peerMaxConcurrentStreams` (the cap on streams the server may push back). The initial value is replaced by the server's `SETTINGS_MAX_CONCURRENT_STREAMS` whenever the server sends one, so a user-supplied value acts as a pre-`SETTINGS` default rather than a hard cap.
-- **pipelining** `number | null` (optional) - Default to `maxConcurrentStreams` - The amount of concurrent requests sent over a single HTTP/2 session in accordance with [RFC-7540](https://httpwg.org/specs/rfc7540.html#StreamsLayer) Stream specification. Streams can be closed up by remote server at any time. Unlike on a regular [`Client`](/docs/docs/api/Client.md), `H2CClient` aliases `pipelining` to `maxConcurrentStreams` at construction time, so the two move together.
-- **pingInterval**: `number` - Default: `60e3`. The time interval in milliseconds between PING frames sent to the server. Set to `0` to disable PING frames. This is only applicable for HTTP/2 connections.
-- **connect** `ConnectOptions | null` (optional) - Default: `null`.
-- **strictContentLength** `Boolean` (optional) - Default: `true` - Whether to treat request content length mismatches as errors. If true, an error is thrown when the request content-length header doesn't match the length of the request body. **Security Warning:** Disabling this option can expose your application to HTTP Request Smuggling attacks, where mismatched content-length headers cause servers and proxies to interpret request boundaries differently. This can lead to cache poisoning, credential hijacking, and bypassing security controls. Only disable this in controlled environments where you fully trust the request source.
-- **autoSelectFamily**: `boolean` (optional) - Default: depends on local Node version, on Node 18.13.0 and above is `false`. Enables a family autodetection algorithm that loosely implements section 5 of [RFC 8305](https://tools.ietf.org/html/rfc8305#section-5). See [here](https://nodejs.org/api/net.html#socketconnectoptions-connectlistener) for more details. This option is ignored if not supported by the current Node version.
-- **autoSelectFamilyAttemptTimeout**: `number` - Default: depends on local Node version, on Node 18.13.0 and above is `250`. The amount of time in milliseconds to wait for a connection attempt to finish before trying the next address when using the `autoSelectFamily` option. See [here](https://nodejs.org/api/net.html#socketconnectoptions-connectlistener) for more details.
+### `h2cClient.destroy([error[, callback]])`
 
-#### Parameter: `H2CConnectOptions`
+<!-- YAML
+added: v7.7.0
+-->
 
-- **socketPath** `string | null` (optional) - Default: `null` - An IPC endpoint, either Unix domain socket or Windows named pipe.
-- **timeout** `number | null` (optional) - In milliseconds, Default `10e3`.
-- **servername** `string | null` (optional)
-- **keepAlive** `boolean | null` (optional) - Default: `true` - TCP keep-alive enabled
-- **keepAliveInitialDelay** `number | null` (optional) - Default: `60000` - TCP keep-alive interval for the socket in milliseconds
+* `error` {Error} (optional) The error with which to reject pending requests.
+  **Default:** `null`.
+* `callback` {Function} (optional) Invoked once the client is destroyed.
+* Returns: {Promise|undefined} A `Promise` that resolves once the client is
+  destroyed, when `callback` is not provided.
 
-### Example - Basic Client instantiation
+Destroys the client abruptly, aborting any pending requests. Waits until the
+socket is closed before invoking `callback` (or resolving the returned `Promise`).
+See [`dispatcher.destroy([error[, callback]])`][].
 
-This will instantiate the undici H2CClient, but it will not connect to the origin until something is queued. Consider using `client.connect` to prematurely connect to the origin, or just call `client.request`.
+### `h2cClient.connect(options[, callback])`
 
-```js
-"use strict";
-import { H2CClient } from "undici";
+<!-- YAML
+added: v7.7.0
+-->
 
-const client = new H2CClient("http://localhost:3000");
-```
+* `options` {Object}
+  * `path` {string}
+  * `headers` {Object} (optional) **Default:** `null`.
+  * `signal` {AbortSignal|EventEmitter|null} (optional) **Default:** `null`.
+  * `opaque` {any} (optional) An opaque value passed through to the returned
+    connect data.
+  * `responseHeaders` {string|null} (optional) Set to `'raw'` to return the
+    response headers as a raw array instead of an object. **Default:** `null`.
+* `callback` {Function} (optional) Invoked with `(err, data)` once the connection
+  is established. If omitted, a `Promise` is returned instead.
+* Returns: {Promise|undefined} A `Promise` resolving to the connect data, when
+  `callback` is not provided.
 
-## Instance Methods
+Starts an HTTP `CONNECT` request. See [`dispatcher.connect(options[, callback])`][].
 
-### `H2CClient.close([callback])`
+### `h2cClient.dispatch(options, handlers)`
 
-Implements [`Dispatcher.close([callback])`](/docs/docs/api/Dispatcher.md#dispatcherclosecallback-promise).
+<!-- YAML
+added: v7.7.0
+-->
 
-### `H2CClient.destroy([error, callback])`
+* `options` {Object} The request options.
+* `handlers` {Object} The dispatch handler callbacks.
+* Returns: {boolean} `false` if the dispatcher is busy and the caller should wait
+  for the [`'drain'`](#event-drain) event before dispatching again.
 
-Implements [`Dispatcher.destroy([error, callback])`](/docs/docs/api/Dispatcher.md#dispatcherdestroyerror-callback-promise).
+The lowest-level request API. All other request methods are implemented on top of
+it. See [`dispatcher.dispatch(options, handler)`][].
 
-Waits until socket is closed before invoking the callback (or returning a promise if no callback is provided).
+### `h2cClient.pipeline(options, handler)`
 
-### `H2CClient.connect(options[, callback])`
+<!-- YAML
+added: v7.7.0
+-->
 
-See [`Dispatcher.connect(options[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherconnectoptions-callback).
+* `options` {Object} The request options.
+* `handler` {Function} A handler that receives the response data and returns a
+  {Readable} body.
+* Returns: {Duplex} A duplex stream for the request body and response body.
 
-### `H2CClient.dispatch(options, handlers)`
+Sends a request and returns a duplex stream, suitable for piping. See
+[`dispatcher.pipeline(options, handler)`][].
 
-Implements [`Dispatcher.dispatch(options, handlers)`](/docs/docs/api/Dispatcher.md#dispatcherdispatchoptions-handler).
+### `h2cClient.request(options[, callback])`
 
-### `H2CClient.pipeline(options, handler)`
+<!-- YAML
+added: v7.7.0
+-->
 
-See [`Dispatcher.pipeline(options, handler)`](/docs/docs/api/Dispatcher.md#dispatcherpipelineoptions-handler).
+* `options` {Object} The request options.
+* `callback` {Function} (optional) Invoked with `(err, data)` once the response
+  is received. If omitted, a `Promise` is returned instead.
+* Returns: {Promise|undefined} A `Promise` resolving to the response data, when
+  `callback` is not provided.
 
-### `H2CClient.request(options[, callback])`
+Performs an HTTP request. See [`dispatcher.request(options[, callback])`][].
 
-See [`Dispatcher.request(options [, callback])`](/docs/docs/api/Dispatcher.md#dispatcherrequestoptions-callback).
+### `h2cClient.stream(options, factory[, callback])`
 
-### `H2CClient.stream(options, factory[, callback])`
+<!-- YAML
+added: v7.7.0
+-->
 
-See [`Dispatcher.stream(options, factory[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherstreamoptions-factory-callback).
+* `options` {Object} The request options.
+* `factory` {Function} A factory that returns a {Writable} to which the response
+  body is written.
+* `callback` {Function} (optional) Invoked once the request completes. If
+  omitted, a `Promise` is returned instead.
+* Returns: {Promise|undefined} A `Promise` that resolves once the request
+  completes, when `callback` is not provided.
 
-### `H2CClient.upgrade(options[, callback])`
+Sends a request and writes the response body to the stream returned by `factory`.
+See [`dispatcher.stream(options, factory[, callback])`][].
 
-See [`Dispatcher.upgrade(options[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherupgradeoptions-callback).
+### `h2cClient.upgrade(options[, callback])`
 
-## Instance Properties
+<!-- YAML
+added: v7.7.0
+-->
 
-### `H2CClient.closed`
+* `options` {Object} The request options.
+* `callback` {Function} (optional) Invoked with `(err, data)` once the upgrade
+  completes. If omitted, a `Promise` is returned instead.
+* Returns: {Promise|undefined} A `Promise` resolving to the upgrade data, when
+  `callback` is not provided.
 
-- `boolean`
+Upgrades a connection to a different protocol. See
+[`dispatcher.upgrade(options[, callback])`][].
 
-`true` after `H2CClient.close()` has been called.
+### `h2cClient.closed`
 
-### `H2CClient.destroyed`
+<!-- YAML
+added: v7.7.0
+-->
 
-- `boolean`
+* Type: {boolean}
 
-`true` after `client.destroyed()` has been called or `client.close()` has been called and the client shutdown has completed.
+`true` after [`h2cClient.close()`](#h2cclientclosecallback) has been called.
 
-### `H2CClient.pipelining`
+### `h2cClient.destroyed`
 
-- `number`
+<!-- YAML
+added: v7.7.0
+-->
 
-Property to get and set the pipelining factor.
+* Type: {boolean}
 
-## Instance Events
+`true` after [`h2cClient.destroy()`](#h2cclientdestroyerror-callback) has been
+called, or after [`h2cClient.close()`](#h2cclientclosecallback) has been called
+and the client shutdown has completed.
 
-### Event: `'connect'`
+### `h2cClient.pipelining`
+
+<!-- YAML
+added: v7.7.0
+-->
 
-See [Dispatcher Event: `'connect'`](/docs/docs/api/Dispatcher.md#event-connect).
+* Type: {number}
 
-Parameters:
+Gets and sets the pipelining factor, i.e. the number of requests multiplexed over
+the connection.
 
-- **origin** `URL`
-- **targets** `Array<Dispatcher>`
+### Event: `'connect'`
 
-Emitted when a socket has been created and connected. The client will connect once `client.size > 0`.
+<!-- YAML
+added: v7.7.0
+-->
 
-#### Example - Client connect event
+* `origin` {URL}
+* `targets` {Array<Dispatcher>}
 
-```js
-import { createServer } from "node:http2";
-import { H2CClient } from "undici";
-import { once } from "events";
+Emitted when the socket has been created and connected. The client connects once
+`client.size > 0`. See [Dispatcher Event: `'connect'`][].
+
+```mjs
+import { createServer } from 'node:http2'
+import { once } from 'node:events'
+import { H2CClient } from 'undici'
 
 const server = createServer((request, response) => {
-  response.end("Hello, World!");
-}).listen();
+  response.end('Hello, World!')
+}).listen()
 
-await once(server, "listening");
+await once(server, 'listening')
 
-const client = new H2CClient(`http://localhost:${server.address().port}`);
+const client = new H2CClient(`http://localhost:${server.address().port}`)
 
-client.on("connect", (origin) => {
-  console.log(`Connected to ${origin}`); // should print before the request body statement
-});
+client.on('connect', (origin) => {
+  console.log(`Connected to ${origin}`)
+})
 
-try {
-  const { body } = await client.request({
-    path: "/",
-    method: "GET",
-  });
-  body.setEncoding("utf-8");
-  body.on("data", console.log);
-  client.close();
-  server.close();
-} catch (error) {
-  console.error(error);
-  client.close();
-  server.close();
-}
+const { body } = await client.request({ path: '/', method: 'GET' })
+console.log(await body.text())
+
+client.close()
+server.close()
 ```
 
 ### Event: `'disconnect'`
 
-See [Dispatcher Event: `'disconnect'`](/docs/docs/api/Dispatcher.md#event-disconnect).
+<!-- YAML
+added: v7.7.0
+-->
 
-Parameters:
+* `origin` {URL}
+* `targets` {Array<Dispatcher>}
+* `error` {Error}
 
-- **origin** `URL`
-- **targets** `Array<Dispatcher>`
-- **error** `Error`
+Emitted when the socket has disconnected. The `error` argument is the error that
+caused the socket to disconnect. The client reconnects if (or once)
+`client.size > 0`. See [Dispatcher Event: `'disconnect'`][].
 
-Emitted when socket has disconnected. The error argument of the event is the error which caused the socket to disconnect. The client will reconnect if or once `client.size > 0`.
-
-#### Example - Client disconnect event
-
-```js
-import { createServer } from "node:http2";
-import { H2CClient } from "undici";
-import { once } from "events";
+```mjs
+import { createServer } from 'node:http2'
+import { once } from 'node:events'
+import { H2CClient } from 'undici'
 
 const server = createServer((request, response) => {
-  response.destroy();
-}).listen();
+  response.destroy()
+}).listen()
 
-await once(server, "listening");
+await once(server, 'listening')
 
-const client = new H2CClient(`http://localhost:${server.address().port}`);
+const client = new H2CClient(`http://localhost:${server.address().port}`)
 
-client.on("disconnect", (origin) => {
-  console.log(`Disconnected from ${origin}`);
-});
+client.on('disconnect', (origin) => {
+  console.log(`Disconnected from ${origin}`)
+})
 
 try {
-  await client.request({
-    path: "/",
-    method: "GET",
-  });
+  await client.request({ path: '/', method: 'GET' })
 } catch (error) {
-  console.error(error.message);
-  client.close();
-  server.close();
+  console.error(error.message)
+} finally {
+  client.close()
+  server.close()
 }
 ```
 
 ### Event: `'drain'`
 
-Emitted when pipeline is no longer busy.
-
-See [Dispatcher Event: `'drain'`](/docs/docs/api/Dispatcher.md#event-drain).
+<!-- YAML
+added: v7.7.0
+-->
 
-#### Example - Client drain event
-
-```js
-import { createServer } from "node:http2";
-import { H2CClient } from "undici";
-import { once } from "events";
-
-const server = createServer((request, response) => {
-  response.end("Hello, World!");
-}).listen();
+* `origin` {URL}
 
-await once(server, "listening");
-
-const client = new H2CClient(`http://localhost:${server.address().port}`);
-
-client.on("drain", () => {
-  console.log("drain event");
-  client.close();
-  server.close();
-});
-
-const requests = [
-  client.request({ path: "/", method: "GET" }),
-  client.request({ path: "/", method: "GET" }),
-  client.request({ path: "/", method: "GET" }),
-];
-
-await Promise.all(requests);
-
-console.log("requests completed");
-```
+Emitted when the client is no longer busy and can accept more requests. See
+[Dispatcher Event: `'drain'`][].
 
 ### Event: `'error'`
 
-Invoked for user errors such as throwing in the `onResponseError` handler.
+<!-- YAML
+added: v7.7.0
+-->
+
+* `error` {Error}
+
+Emitted for user errors, such as an error thrown from an `onResponseError`
+handler.
+
+[RFC 8305]: https://tools.ietf.org/html/rfc8305#section-5
+[Dispatcher Event: `'connect'`]: Dispatcher.md#event-connect
+[Dispatcher Event: `'disconnect'`]: Dispatcher.md#event-disconnect
+[Dispatcher Event: `'drain'`]: Dispatcher.md#event-drain
+[`Client`]: Client.md#class-client
+[`Dispatcher`]: Dispatcher.md#class-dispatcher
+[`dispatcher.close([callback])`]: Dispatcher.md#dispatcherclosecallback
+[`dispatcher.connect(options[, callback])`]: Dispatcher.md#dispatcherconnectoptions-callback
+[`dispatcher.destroy([error[, callback]])`]: Dispatcher.md#dispatcherdestroyerror-callback
+[`dispatcher.dispatch(options, handler)`]: Dispatcher.md#dispatcherdispatchoptions-handler
+[`dispatcher.pipeline(options, handler)`]: Dispatcher.md#dispatcherpipelineoptions-handler
+[`dispatcher.request(options[, callback])`]: Dispatcher.md#dispatcherrequestoptions-callback
+[`dispatcher.stream(options, factory[, callback])`]: Dispatcher.md#dispatcherstreamoptions-factory-callback
+[`dispatcher.upgrade(options[, callback])`]: Dispatcher.md#dispatcherupgradeoptions-callback
diff --git a/docs/docs/api/MockAgent.md b/docs/docs/api/MockAgent.md
index d46f1b95a21..f0a147d7ce5 100644
--- a/docs/docs/api/MockAgent.md
+++ b/docs/docs/api/MockAgent.md
@@ -1,40 +1,77 @@
-# Class: MockAgent
+# MockAgent
 
-Extends: `undici.Dispatcher`
+<!--introduced_in=v4.0.0-->
+<!--type=module-->
+<!-- source_link=lib/mock/mock-agent.js -->
 
-A mocked Agent class that implements the Agent API. It allows one to intercept HTTP requests made through undici and return mocked responses instead.
+> Stability: 2 - Stable
 
-## `new MockAgent([options])`
+A `MockAgent` is a {Dispatcher} that intercepts HTTP requests made through
+undici and replies with programmed mock responses instead of contacting the
+network. It is useful for testing code that performs HTTP requests without
+relying on a live server.
 
-Arguments:
+A `MockAgent` does not intercept requests on its own. Mock responses are
+registered on the {MockClient} or {MockPool} instances returned by
+[`mockAgent.get(origin)`][], and requests are routed through them once the
+`MockAgent` is set as the dispatcher (for example through
+[`setGlobalDispatcher()`][] or a per-request `dispatcher` option).
 
-* **options** `MockAgentOptions` (optional) - It extends the `Agent` options.
+```mjs
+import { MockAgent } from 'undici'
+
+const mockAgent = new MockAgent()
+```
 
-Returns: `MockAgent`
+## Class: `MockAgent`
 
-### Parameter: `MockAgentOptions`
+<!-- YAML
+added: v4.0.0
+-->
 
-Extends: [`AgentOptions`](/docs/docs/api/Agent.md#parameter-agentoptions)
+* Extends: {Dispatcher}
 
-* **agent** `Agent` (optional) - Default: `new Agent([options])` - a custom agent encapsulated by the MockAgent.
+Intercepts HTTP requests made through undici and returns mocked responses.
 
-* **ignoreTrailingSlash** `boolean` (optional) - Default: `false` - set the default value for `ignoreTrailingSlash` for interceptors.
+### `new MockAgent([options])`
 
-* **acceptNonStandardSearchParameters** `boolean` (optional) - Default: `false` - set to `true` if the matcher should also accept non standard search parameters such as multi-value items specified with `[]` (e.g. `param[]=1&param[]=2&param[]=3`) and multi-value items which values are comma separated (e.g. `param=1,2,3`).
+<!-- YAML
+added: v4.0.0
+changes:
+  - version: v7.16.0
+    pr-url: https://github.com/nodejs/undici/pull/4479
+    description: Mock options are always normalized to an object internally.
+-->
 
-### Example - Basic MockAgent instantiation
+* `options` {MockAgentOptions} (optional)
+* Returns: {MockAgent}
 
-This will instantiate the MockAgent. It will not do anything until registered as the agent to use with requests and mock interceptions are added.
+When instantiated, a `MockAgent` is automatically activated. It does not
+intercept any request until mock interceptors are registered on the dispatchers
+returned by [`mockAgent.get(origin)`][].
 
-```js
+#### Parameter: `MockAgentOptions`
+
+* Extends: {AgentOptions}
+* `agent` {Dispatcher} (optional) A custom agent to be encapsulated by the
+  `MockAgent`. It must implement the `Agent` API (that is, expose a `dispatch`
+  function). **Default:** a new {Agent} constructed from `options`.
+* `ignoreTrailingSlash` {boolean} (optional) Whether trailing slashes in the
+  request path are ignored when matching interceptors. **Default:** `false`.
+* `acceptNonStandardSearchParameters` {boolean} (optional) Whether the matcher
+  also accepts URLs using non-standard search-parameter syntaxes, such as
+  multi-value items written with `[]` (for example `param[]=1&param[]=2`) or
+  comma-separated values (for example `param=1,2,3`). **Default:** `false`.
+* `enableCallHistory` {boolean} (optional) Whether call history recording is
+  enabled. See [`mockAgent.getCallHistory()`][]. **Default:** `false`.
+
+```mjs displayName="Basic instantiation"
 import { MockAgent } from 'undici'
 
 const mockAgent = new MockAgent()
 ```
 
-### Example - Basic MockAgent instantiation with custom agent
-
-```js
+```mjs displayName="Instantiation with a custom agent"
 import { Agent, MockAgent } from 'undici'
 
 const agent = new Agent()
@@ -42,34 +79,30 @@ const agent = new Agent()
 const mockAgent = new MockAgent({ agent })
 ```
 
-## Instance Methods
+### `mockAgent.get(origin)`
 
-### `MockAgent.get(origin)`
+<!-- YAML
+added: v4.0.0
+-->
 
-This method creates and retrieves MockPool or MockClient instances which can then be used to intercept HTTP requests. If the number of connections on the mock agent is set to 1, a MockClient instance is returned. Otherwise a MockPool instance is returned.
+* `origin` {string|RegExp|Function} A matcher for the origin to retrieve. The
+  function form has the signature `(origin) => boolean`.
+* Returns: {MockClient|MockPool}
 
-For subsequent `MockAgent.get` calls on the same origin, the same mock instance will be returned.
+Creates and retrieves the mock dispatcher used to intercept requests for the
+given origin. When the `connections` option of the `MockAgent` is `1`, a
+{MockClient} is returned; otherwise a {MockPool} is returned. Subsequent calls
+with the same origin return the same instance.
 
-Arguments:
+The way `origin` is matched against incoming requests depends on its type:
 
-* **origin** `string | RegExp | (value) => boolean` - a matcher for the pool origin to be retrieved from the MockAgent.
+| Matcher type | Condition to pass            |
+| :----------: | ---------------------------- |
+| `string`     | Exact match against the value |
+| `RegExp`     | The regular expression matches |
+| `Function`   | The function returns `true`  |
 
-| Matcher type | Condition to pass          |
-|:------------:| -------------------------- |
-| `string`     | Exact match against string |
-| `RegExp`     | Regex must pass            |
-| `Function`   | Function must return true  |
-
-Returns: `MockClient | MockPool`.
-
-| `MockAgentOptions`   | Mock instance returned |
-| -------------------- | ---------------------- |
-| `connections === 1`  | `MockClient`           |
-| `connections` > `1`  | `MockPool`             |
-
-#### Example - Basic Mocked Request
-
-```js
+```mjs displayName="Basic mocked request"
 import { MockAgent, setGlobalDispatcher, request } from 'undici'
 
 const mockAgent = new MockAgent()
@@ -87,9 +120,7 @@ for await (const data of body) {
 }
 ```
 
-#### Example - Basic Mocked Request with local mock agent dispatcher
-
-```js
+```mjs displayName="Mocked request using a local dispatcher"
 import { MockAgent, request } from 'undici'
 
 const mockAgent = new MockAgent()
@@ -97,32 +128,9 @@ const mockAgent = new MockAgent()
 const mockPool = mockAgent.get('http://localhost:3000')
 mockPool.intercept({ path: '/foo' }).reply(200, 'foo')
 
-const {
-  statusCode,
-  body
-} = await request('http://localhost:3000/foo', { dispatcher: mockAgent })
-
-console.log('response received', statusCode) // response received 200
-
-for await (const data of body) {
-  console.log('data', data.toString('utf8')) // data foo
-}
-```
-
-#### Example - Basic Mocked Request with local mock pool dispatcher
-
-```js
-import { MockAgent, request } from 'undici'
-
-const mockAgent = new MockAgent()
-
-const mockPool = mockAgent.get('http://localhost:3000')
-mockPool.intercept({ path: '/foo' }).reply(200, 'foo')
-
-const {
-  statusCode,
-  body
-} = await request('http://localhost:3000/foo', { dispatcher: mockPool })
+const { statusCode, body } = await request('http://localhost:3000/foo', {
+  dispatcher: mockAgent
+})
 
 console.log('response received', statusCode) // response received 200
 
@@ -131,9 +139,7 @@ for await (const data of body) {
 }
 ```
 
-#### Example - Basic Mocked Request with local mock client dispatcher
-
-```js
+```mjs displayName="Returning a MockClient"
 import { MockAgent, request } from 'undici'
 
 const mockAgent = new MockAgent({ connections: 1 })
@@ -141,10 +147,9 @@ const mockAgent = new MockAgent({ connections: 1 })
 const mockClient = mockAgent.get('http://localhost:3000')
 mockClient.intercept({ path: '/foo' }).reply(200, 'foo')
 
-const {
-  statusCode,
-  body
-} = await request('http://localhost:3000/foo', { dispatcher: mockClient })
+const { statusCode, body } = await request('http://localhost:3000/foo', {
+  dispatcher: mockClient
+})
 
 console.log('response received', statusCode) // response received 200
 
@@ -153,131 +158,64 @@ for await (const data of body) {
 }
 ```
 
-#### Example - Basic Mocked requests with multiple intercepts
-
-```js
+```mjs displayName="Matching the origin with a regular expression"
 import { MockAgent, setGlobalDispatcher, request } from 'undici'
 
 const mockAgent = new MockAgent()
 setGlobalDispatcher(mockAgent)
 
-const mockPool = mockAgent.get('http://localhost:3000')
+const mockPool = mockAgent.get(new RegExp('http://localhost:3000'))
 mockPool.intercept({ path: '/foo' }).reply(200, 'foo')
-mockPool.intercept({ path: '/hello'}).reply(200, 'hello')
-
-const result1 = await request('http://localhost:3000/foo')
-
-console.log('response received', result1.statusCode) // response received 200
-
-for await (const data of result1.body) {
-  console.log('data', data.toString('utf8')) // data foo
-}
 
-const result2 = await request('http://localhost:3000/hello')
+const { statusCode } = await request('http://localhost:3000/foo')
 
-console.log('response received', result2.statusCode) // response received 200
-
-for await (const data of result2.body) {
-  console.log('data', data.toString('utf8')) // data hello
-}
-```
-
-#### Example - Mock different requests within the same file
-
-```js
-const { MockAgent, setGlobalDispatcher } = require('undici');
-const agent = new MockAgent();
-agent.disableNetConnect();
-setGlobalDispatcher(agent);
-describe('Test', () => {
-  it('200', async () => {
-    const mockAgent = agent.get('http://test.com');
-    // your test
-  });
-  it('200', async () => {
-    const mockAgent = agent.get('http://testing.com');
-    // your test
-  });
-});
+console.log('response received', statusCode) // response received 200
 ```
 
-#### Example - Mocked request with query body, headers and trailers
-
-```js
+```mjs displayName="Matching the origin with a function"
 import { MockAgent, setGlobalDispatcher, request } from 'undici'
 
 const mockAgent = new MockAgent()
 setGlobalDispatcher(mockAgent)
 
-const mockPool = mockAgent.get('http://localhost:3000')
-
-mockPool.intercept({
-  path: '/foo?hello=there&see=ya',
-  method: 'POST',
-  body: 'form1=data1&form2=data2'
-}).reply(200, { foo: 'bar' }, {
-  headers: { 'content-type': 'application/json' },
-  trailers: { 'Content-MD5': 'test' }
-})
+const mockPool = mockAgent.get((origin) => origin === 'http://localhost:3000')
+mockPool.intercept({ path: '/foo' }).reply(200, 'foo')
 
-const {
-  statusCode,
-  headers,
-  trailers,
-  body
-} = await request('http://localhost:3000/foo?hello=there&see=ya', {
-  method: 'POST',
-  body: 'form1=data1&form2=data2'
-})
+const { statusCode } = await request('http://localhost:3000/foo')
 
 console.log('response received', statusCode) // response received 200
-console.log('headers', headers) // { 'content-type': 'application/json' }
-
-for await (const data of body) {
-  console.log('data', data.toString('utf8')) // '{"foo":"bar"}'
-}
-
-console.log('trailers', trailers) // { 'content-md5': 'test' }
 ```
 
-#### Example - Mocked request with origin regex
-
-```js
-import { MockAgent, setGlobalDispatcher, request } from 'undici'
-
-const mockAgent = new MockAgent()
-setGlobalDispatcher(mockAgent)
-
-const mockPool = mockAgent.get(new RegExp('http://localhost:3000'))
-mockPool.intercept({ path: '/foo' }).reply(200, 'foo')
-
-const {
-  statusCode,
-  body
-} = await request('http://localhost:3000/foo')
+### `mockAgent.dispatch(options, handler)`
 
-console.log('response received', statusCode) // response received 200
+<!-- YAML
+added: v4.0.0
+-->
 
-for await (const data of body) {
-  console.log('data', data.toString('utf8')) // data foo
-}
-```
+* `options` {AgentDispatchOptions}
+* `handler` {DispatchHandler}
+* Returns: {boolean}
 
-#### Example - Mocked request with origin function
+Dispatches a mocked request. This implements
+[`Dispatcher.dispatch()`][] for the encapsulated agent: it ensures the mock
+dispatcher for `options.origin` exists, records the call in the call history
+when enabled, and forwards the request to the underlying agent. It is normally
+invoked indirectly through higher-level methods such as
+[`mockAgent.request()`][].
 
-```js
-import { MockAgent, setGlobalDispatcher, request } from 'undici'
+```mjs displayName="Using mockAgent.request()"
+import { MockAgent } from 'undici'
 
 const mockAgent = new MockAgent()
-setGlobalDispatcher(mockAgent)
 
-const mockPool = mockAgent.get((origin) => origin === 'http://localhost:3000')
+const mockPool = mockAgent.get('http://localhost:3000')
 mockPool.intercept({ path: '/foo' }).reply(200, 'foo')
 
-const {
-  statusCode,
-  body
-} = await request('http://localhost:3000/foo')
+const { statusCode, body } = await mockAgent.request({
+  origin: 'http://localhost:3000',
+  path: '/foo',
+  method: 'GET'
+})
 
 console.log('response received', statusCode) // response received 200
 
@@ -286,15 +224,19 @@ for await (const data of body) {
 }
 ```
 
-### `MockAgent.close()`
+### `mockAgent.close()`
 
-Closes the mock agent and waits for registered mock pools and clients to also close before resolving.
+<!-- YAML
+added: v4.0.0
+-->
 
-Returns: `Promise<void>`
+* Returns: {Promise<void>} Resolves once the agent and its registered mock pools
+  and clients have closed.
 
-#### Example - clean up after tests are complete
+Clears the call history, closes the encapsulated agent, and waits for all
+registered mock pools and clients to close.
 
-```js
+```mjs displayName="Clean up after tests"
 import { MockAgent, setGlobalDispatcher } from 'undici'
 
 const mockAgent = new MockAgent()
@@ -303,49 +245,18 @@ setGlobalDispatcher(mockAgent)
 await mockAgent.close()
 ```
 
-### `MockAgent.dispatch(options, handlers)`
-
-Implements [`Agent.dispatch(options, handlers)`](/docs/docs/api/Agent.md#parameter-agentdispatchoptions).
-
-### `MockAgent.request(options[, callback])`
-
-See [`Dispatcher.request(options [, callback])`](/docs/docs/api/Dispatcher.md#dispatcherrequestoptions-callback).
-
-#### Example - MockAgent request
-
-```js
-import { MockAgent } from 'undici'
-
-const mockAgent = new MockAgent()
-
-const mockPool = mockAgent.get('http://localhost:3000')
-mockPool.intercept({ path: '/foo' }).reply(200, 'foo')
-
-const {
-  statusCode,
-  body
-} = await mockAgent.request({
-  origin: 'http://localhost:3000',
-  path: '/foo',
-  method: 'GET'
-})
-
-console.log('response received', statusCode) // response received 200
-
-for await (const data of body) {
-  console.log('data', data.toString('utf8')) // data foo
-}
-```
-
-### `MockAgent.deactivate()`
+### `mockAgent.deactivate()`
 
-This method disables mocking in MockAgent.
+<!-- YAML
+added: v4.0.0
+-->
 
-Returns: `void`
+* Returns: {undefined}
 
-#### Example - Deactivate Mocking
+Disables mocking on the `MockAgent`. While deactivated, requests are no longer
+intercepted.
 
-```js
+```mjs displayName="Deactivate mocking"
 import { MockAgent, setGlobalDispatcher } from 'undici'
 
 const mockAgent = new MockAgent()
@@ -354,15 +265,19 @@ setGlobalDispatcher(mockAgent)
 mockAgent.deactivate()
 ```
 
-### `MockAgent.activate()`
+### `mockAgent.activate()`
 
-This method enables mocking in a MockAgent instance. When instantiated, a MockAgent is automatically activated. Therefore, this method is only effective after `MockAgent.deactivate` has been called.
+<!-- YAML
+added: v4.0.0
+-->
 
-Returns: `void`
+* Returns: {undefined}
 
-#### Example - Activate Mocking
+Enables mocking on the `MockAgent`. A `MockAgent` is activated automatically
+when instantiated, so this method is only required after
+[`mockAgent.deactivate()`][] has been called.
 
-```js
+```mjs displayName="Re-activate mocking"
 import { MockAgent, setGlobalDispatcher } from 'undici'
 
 const mockAgent = new MockAgent()
@@ -375,21 +290,23 @@ mockAgent.deactivate()
 mockAgent.activate()
 ```
 
-### `MockAgent.enableNetConnect([host])`
+### `mockAgent.enableNetConnect([matcher])`
 
-When requests are not matched in a MockAgent intercept, a real HTTP request is attempted. We can control this further through the use of `enableNetConnect`. This is achieved by defining host matchers so only matching requests will be attempted.
+<!-- YAML
+added: v4.0.0
+-->
 
-When using a string, it should only include the **hostname and optionally, the port**. In addition, calling this method multiple times with a string will allow all HTTP requests that match these values.
+* `matcher` {string|RegExp|Function} (optional) A host matcher. When a string is
+  used it should only contain the hostname and, optionally, the port. The
+  function form has the signature `(host) => boolean`. When omitted, all
+  non-matching requests are allowed to perform a real request.
+* Returns: {undefined}
 
-Arguments:
+Defines host matchers so that requests that are not intercepted by a mock
+dispatcher are allowed to perform a real HTTP request. Calling this method
+multiple times with a string appends each value to the list of allowed hosts.
 
-* **host** `string | RegExp | (value) => boolean` - (optional)
-
-Returns: `void`
-
-#### Example - Allow all non-matching urls to be dispatched in a real HTTP request
-
-```js
+```mjs displayName="Allow all non-matching requests"
 import { MockAgent, setGlobalDispatcher, request } from 'undici'
 
 const mockAgent = new MockAgent()
@@ -401,9 +318,7 @@ await request('http://example.com')
 // A real request is made
 ```
 
-#### Example - Allow requests matching a host string to make real requests
-
-```js
+```mjs displayName="Allow requests matching specific hosts"
 import { MockAgent, setGlobalDispatcher, request } from 'undici'
 
 const mockAgent = new MockAgent()
@@ -422,75 +337,167 @@ await request('http://example-3.com')
 // Will throw
 ```
 
-#### Example - Allow requests matching a host regex to make real requests
-
-```js
+```mjs displayName="Allow requests matching a regular expression or function"
 import { MockAgent, setGlobalDispatcher, request } from 'undici'
 
 const mockAgent = new MockAgent()
 setGlobalDispatcher(mockAgent)
 
 mockAgent.enableNetConnect(new RegExp('example.com'))
+mockAgent.enableNetConnect((host) => host === 'example.org')
 
 await request('http://example.com')
 // A real request is made
 ```
 
-#### Example - Allow requests matching a host function to make real requests
+### `mockAgent.disableNetConnect()`
 
-```js
-import { MockAgent, setGlobalDispatcher, request } from 'undici'
+<!-- YAML
+added: v4.0.0
+-->
+
+* Returns: {undefined}
+
+Causes every request that is not matched by a mock interceptor to throw,
+disallowing real HTTP requests.
+
+```mjs displayName="Throw on every non-matching request"
+import { MockAgent, request } from 'undici'
 
 const mockAgent = new MockAgent()
-setGlobalDispatcher(mockAgent)
 
-mockAgent.enableNetConnect((value) => value === 'example.com')
+mockAgent.disableNetConnect()
 
 await request('http://example.com')
-// A real request is made
+// Will throw
 ```
 
-### `MockAgent.disableNetConnect()`
+### `mockAgent.enableCallHistory()`
 
-This method causes all requests to throw when requests are not matched in a MockAgent intercept.
+<!-- YAML
+added: v7.5.0
+-->
 
-Returns: `void`
+* Returns: {MockAgent} The same `MockAgent` instance, for chaining.
 
-#### Example - Disable all non-matching requests by throwing an error for each
+Enables call history recording. Once enabled, subsequent calls are registered
+and can be retrieved through [`mockAgent.getCallHistory()`][]. Call history can
+also be enabled at construction time with the `enableCallHistory` option.
 
-```js
-import { MockAgent, request } from 'undici'
+```mjs
+import { MockAgent } from 'undici'
 
 const mockAgent = new MockAgent()
 
-mockAgent.disableNetConnect()
+mockAgent.enableCallHistory()
+```
 
-await request('http://example.com')
-// Will throw
+### `mockAgent.disableCallHistory()`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+* Returns: {MockAgent} The same `MockAgent` instance, for chaining.
+
+Disables call history recording. Subsequent calls are no longer registered.
+
+```mjs
+import { MockAgent } from 'undici'
+
+const mockAgent = new MockAgent({ enableCallHistory: true })
+
+mockAgent.disableCallHistory()
 ```
 
-### `MockAgent.pendingInterceptors()`
+### `mockAgent.getCallHistory()`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+* Returns: {MockCallHistory|undefined} The {MockCallHistory} instance, or
+  `undefined` when call history is not enabled.
 
-This method returns any pending interceptors registered on a mock agent. A pending interceptor meets one of the following criteria:
+Returns the call history instance, which records every request made through the
+`MockAgent` (whether intercepted or not). Call history is not enabled by
+default; enable it with the `enableCallHistory` option or
+[`mockAgent.enableCallHistory()`][].
 
-- Is registered with neither `.times(<number>)` nor `.persist()`, and has not been invoked;
-- Is persistent (i.e., registered with `.persist()`) and has not been invoked;
-- Is registered with `.times(<number>)` and has not been invoked `<number>` of times.
+```mjs displayName="Inspect recorded calls"
+import { MockAgent, setGlobalDispatcher, request } from 'undici'
+
+const mockAgent = new MockAgent({ enableCallHistory: true })
+setGlobalDispatcher(mockAgent)
+
+await request('http://example.com', { query: { item: 1 } })
+
+mockAgent.getCallHistory()?.firstCall()
+// Returns
+// MockCallHistoryLog {
+//   body: undefined,
+//   headers: undefined,
+//   method: 'GET',
+//   origin: 'http://example.com',
+//   fullUrl: 'http://example.com/?item=1',
+//   path: '/',
+//   searchParams: { item: '1' },
+//   protocol: 'http:',
+//   host: 'example.com',
+//   port: ''
+// }
+```
 
-Returns: `PendingInterceptor[]` (where `PendingInterceptor` is a `MockDispatch` with an additional `origin: string`)
+### `mockAgent.clearCallHistory()`
 
-#### Example - List all pending interceptors
+<!-- YAML
+added: v7.5.0
+-->
 
-```js
-const agent = new MockAgent()
-agent.disableNetConnect()
+* Returns: {undefined}
 
-agent
+Clears the call history, deleting every recorded {MockCallHistoryLog} on the
+{MockCallHistory} instance. It is a no-op when call history has never been
+enabled.
+
+```mjs
+import { MockAgent } from 'undici'
+
+const mockAgent = new MockAgent({ enableCallHistory: true })
+
+mockAgent.clearCallHistory()
+```
+
+### `mockAgent.pendingInterceptors()`
+
+<!-- YAML
+added: v5.1.0
+-->
+
+* Returns: {PendingInterceptor[]} A `PendingInterceptor` is a `MockDispatch`
+  with an additional `origin` {string} property.
+
+Returns the interceptors registered on the `MockAgent` that are still pending.
+An interceptor is pending when it meets one of the following criteria:
+
+* It is registered with neither `.times(<number>)` nor `.persist()` and has not
+  been invoked.
+* It is persistent (registered with `.persist()`) and has not been invoked.
+* It is registered with `.times(<number>)` and has not been invoked `<number>`
+  times.
+
+```mjs displayName="List pending interceptors"
+import { MockAgent } from 'undici'
+
+const mockAgent = new MockAgent()
+mockAgent.disableNetConnect()
+
+mockAgent
   .get('https://example.com')
   .intercept({ method: 'GET', path: '/' })
   .reply(200)
 
-const pendingInterceptors = agent.pendingInterceptors()
+const pendingInterceptors = mockAgent.pendingInterceptors()
 // Returns [
 //   {
 //     timesInvoked: 0,
@@ -514,26 +521,35 @@ const pendingInterceptors = agent.pendingInterceptors()
 // ]
 ```
 
-### `MockAgent.assertNoPendingInterceptors([options])`
+### `mockAgent.assertNoPendingInterceptors([options])`
+
+<!-- YAML
+added: v5.1.0
+-->
 
-This method throws if the mock agent has any pending interceptors. A pending interceptor meets one of the following criteria:
+* `options` {Object} (optional)
+  * `pendingInterceptorsFormatter` {Object} An object exposing a
+    `format(pendingInterceptors)` method used to render the pending interceptors
+    in the thrown error message. **Default:** a built-in formatter that prints a
+    table.
+* Returns: {undefined}
 
-- Is registered with neither `.times(<number>)` nor `.persist()`, and has not been invoked;
-- Is persistent (i.e., registered with `.persist()`) and has not been invoked;
-- Is registered with `.times(<number>)` and has not been invoked `<number>` of times.
+Throws an {UndiciError} when the `MockAgent` has any pending interceptors. The
+criteria for an interceptor being pending are the same as for
+[`mockAgent.pendingInterceptors()`][].
 
-#### Example - Check that there are no pending interceptors
+```mjs displayName="Assert there are no pending interceptors"
+import { MockAgent } from 'undici'
 
-```js
-const agent = new MockAgent()
-agent.disableNetConnect()
+const mockAgent = new MockAgent()
+mockAgent.disableNetConnect()
 
-agent
+mockAgent
   .get('https://example.com')
   .intercept({ method: 'GET', path: '/' })
   .reply(200)
 
-agent.assertNoPendingInterceptors()
+mockAgent.assertNoPendingInterceptors()
 // Throws an UndiciError with the following message:
 //
 // 1 interceptor is pending:
@@ -545,59 +561,35 @@ agent.assertNoPendingInterceptors()
 // └─────────┴────────┴───────────────────────┴──────┴─────────────┴────────────┴─────────────┴───────────┘
 ```
 
-#### Example - access call history on MockAgent
-
-You can register every call made within a MockAgent to be able to retrieve the body, headers and so on.
-
-This is not enabled by default.
-
-```js
-import { MockAgent, setGlobalDispatcher, request } from 'undici'
+### `mockAgent.isMockActive`
 
-const mockAgent = new MockAgent({ enableCallHistory: true })
-setGlobalDispatcher(mockAgent)
+<!-- YAML
+added: v5.3.0
+-->
 
-await request('http://example.com', { query: { item: 1 }})
+* Type: {boolean} `true` while mocking is active, `false` after
+  [`mockAgent.deactivate()`][] has been called.
 
-mockAgent.getCallHistory()?.firstCall()
-// Returns
-// MockCallHistoryLog {
-//   body: undefined,
-//   headers: undefined,
-//   method: 'GET',
-//   origin: 'http://example.com',
-//   fullUrl: 'http://example.com/?item=1',
-//   path: '/',
-//   searchParams: { item: '1' },
-//   protocol: 'http:',
-//   host: 'example.com',
-//   port: ''
-// }
-```
+A read-only property indicating whether mocking is currently active on the
+`MockAgent`.
 
-#### Example - clear call history
+```mjs
+import { MockAgent } from 'undici'
 
-```js
 const mockAgent = new MockAgent()
 
-mockAgent.clearCallHistory()
-```
-
-#### Example - call history instance class method
+console.log(mockAgent.isMockActive) // true
 
-```js
-const mockAgent = new MockAgent()
+mockAgent.deactivate()
 
-const mockAgentHistory = mockAgent.getCallHistory()
-
-mockAgentHistory?.calls() // returns an array of MockCallHistoryLogs
-mockAgentHistory?.firstCall() // returns the first MockCallHistoryLogs or undefined
-mockAgentHistory?.lastCall() // returns the last MockCallHistoryLogs or undefined
-mockAgentHistory?.nthCall(3) // returns the third MockCallHistoryLogs or undefined
-mockAgentHistory?.filterCalls({ path: '/endpoint', hash: '#hash-value' }) // returns an Array of MockCallHistoryLogs WHERE path === /endpoint OR hash === #hash-value
-mockAgentHistory?.filterCalls({ path: '/endpoint', hash: '#hash-value' }, { operator: 'AND' }) // returns an Array of MockCallHistoryLogs WHERE path === /endpoint AND hash === #hash-value
-mockAgentHistory?.filterCalls(/"data": "{}"/) // returns an Array of MockCallHistoryLogs where any value match regexp
-mockAgentHistory?.filterCalls('application/json') // returns an Array of MockCallHistoryLogs where any value === 'application/json'
-mockAgentHistory?.filterCalls((log) => log.path === '/endpoint') // returns an Array of MockCallHistoryLogs when given function returns true
-mockAgentHistory?.clear() // clear the history
+console.log(mockAgent.isMockActive) // false
 ```
+
+[`Dispatcher.dispatch()`]: Dispatcher.md#dispatcherdispatchoptions-handler
+[`mockAgent.deactivate()`]: #mockagentdeactivate
+[`mockAgent.enableCallHistory()`]: #mockagentenablecallhistory
+[`mockAgent.get(origin)`]: #mockagentgetorigin
+[`mockAgent.getCallHistory()`]: #mockagentgetcallhistory
+[`mockAgent.pendingInterceptors()`]: #mockagentpendinginterceptors
+[`mockAgent.request()`]: Dispatcher.md#dispatcherrequestoptions-callback
+[`setGlobalDispatcher()`]: Dispatcher.md#setglobaldispatcherdispatcher
diff --git a/docs/docs/api/MockCallHistory.md b/docs/docs/api/MockCallHistory.md
index 4fd393b941e..27c7a2aaf6b 100644
--- a/docs/docs/api/MockCallHistory.md
+++ b/docs/docs/api/MockCallHistory.md
@@ -1,197 +1,371 @@
-# Class: MockCallHistory
+# MockCallHistory
 
-Access to an instance with :
+<!--introduced_in=v7.5.0-->
+<!--type=module-->
+<!-- source_link=lib/mock/mock-call-history.js -->
 
-```js
-const mockAgent = new MockAgent({ enableCallHistory: true })
-mockAgent.getCallHistory()
+> Stability: 2 - Stable
 
-// or
-const mockAgent = new MockAgent()
-mockAgent.enableMockHistory()
-mockAgent.getCallHistory()
+A `MockCallHistory` records the configuration of every request intercepted by a
+[`MockAgent`][] for which call history is enabled. Each recorded request is
+stored as a [`MockCallHistoryLog`][], and the `MockCallHistory` exposes helpers
+to read and filter those logs in tests.
+
+Instances are not created directly. Enable call history on a [`MockAgent`][] and
+retrieve the history with `mockAgent.getCallHistory()`:
 
+```mjs
+import { MockAgent } from 'undici'
+
+const mockAgent = new MockAgent({ enableCallHistory: true })
+const callHistory = mockAgent.getCallHistory()
 ```
 
-a MockCallHistory instance implements a **Symbol.iterator** letting you iterate on registered logs :
+Call history can also be enabled after construction:
 
-```ts
-for (const log of mockAgent.getCallHistory()) {
-  //...
-}
+```mjs
+import { MockAgent } from 'undici'
 
-const array: Array<MockCallHistoryLog> = [...mockAgent.getCallHistory()]
-const set: Set<MockCallHistoryLog> = new Set(mockAgent.getCallHistory())
+const mockAgent = new MockAgent()
+mockAgent.enableCallHistory()
+const callHistory = mockAgent.getCallHistory()
 ```
 
-## class methods
+## Class: `MockCallHistory`
 
-### clear
+<!-- YAML
+added: v7.5.0
+-->
 
-Clear all MockCallHistoryLog registered. This is automatically done when calling `mockAgent.close()`
+Tracks the configuration of intercepted requests as an ordered collection of
+[`MockCallHistoryLog`][] entries.
 
-```js
-mockAgent.clearCallHistory()
-// same as
-mockAgent.getCallHistory()?.clear()
+A `MockCallHistory` is iterable. Use it with a `for...of` loop, the spread
+operator, or any constructor that accepts an iterable:
+
+```mjs
+for (const log of mockAgent.getCallHistory()) {
+  // ...
+}
+
+const logs = [...mockAgent.getCallHistory()]
+const logSet = new Set(mockAgent.getCallHistory())
 ```
 
-### calls
+### `mockCallHistory.calls()`
 
-Get all MockCallHistoryLog registered as an array
+<!-- YAML
+added: v7.5.0
+-->
 
-```js
+* Returns: {MockCallHistoryLog[]} All recorded logs, in the order the requests
+  were intercepted.
+
+Returns every recorded [`MockCallHistoryLog`][] as an array.
+
+```mjs
 mockAgent.getCallHistory()?.calls()
 ```
 
-### firstCall
+### `mockCallHistory.firstCall()`
+
+<!-- YAML
+added: v7.5.0
+-->
 
-Get the first MockCallHistoryLog registered or undefined
+* Returns: {MockCallHistoryLog|undefined} The first recorded log, or `undefined`
+  when no request has been recorded.
 
-```js
+Returns the first recorded [`MockCallHistoryLog`][].
+
+```mjs
 mockAgent.getCallHistory()?.firstCall()
 ```
 
-### lastCall
+### `mockCallHistory.lastCall()`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+* Returns: {MockCallHistoryLog|undefined} The last recorded log, or `undefined`
+  when no request has been recorded.
 
-Get the last MockCallHistoryLog registered or undefined
+Returns the last recorded [`MockCallHistoryLog`][].
 
-```js
+```mjs
 mockAgent.getCallHistory()?.lastCall()
 ```
 
-### nthCall
+### `mockCallHistory.nthCall(position)`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+* `position` {number} The 1-based position of the log to return. Must be a
+  positive integer.
+* Returns: {MockCallHistoryLog|undefined} The log at `position`, or `undefined`
+  when no log exists at that position.
 
-Get the nth MockCallHistoryLog registered or undefined
+Returns the [`MockCallHistoryLog`][] at the given 1-based `position`. The index
+is 1-based for readability, so `nthCall(1)` is equivalent to `firstCall()`.
 
-```js
-mockAgent.getCallHistory()?.nthCall(3) // the third MockCallHistoryLog registered
+Throws an [`InvalidArgumentError`][] when `position` is not a number, not an
+integer, or not positive. Use `firstCall()` or `lastCall()` instead of passing a
+non-positive value.
+
+```mjs
+mockAgent.getCallHistory()?.nthCall(3) // the third recorded log
+```
+
+### `mockCallHistory.filterCalls(criteria[, options])`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+* `criteria` {Function|RegExp|Object} The filter to apply.
+  * When a {Function} is given, it is used as the predicate of
+    `Array.prototype.filter` and receives each [`MockCallHistoryLog`][]; logs for
+    which it returns a truthy value are kept.
+  * When a {RegExp} is given, a log is kept when the expression matches its
+    [`mockCallHistoryLog.toString()`][] representation.
+  * When an {Object} is given, each property is a request field to filter on and
+    each value is a [filter parameter](#filter-parameter). An empty object
+    returns every log.
+    * `protocol` {string|RegExp|null|undefined} Filters by request protocol.
+    * `host` {string|RegExp|null|undefined} Filters by request host.
+    * `port` {string|RegExp|null|undefined} Filters by request port.
+    * `origin` {string|RegExp|null|undefined} Filters by request origin.
+    * `path` {string|RegExp|null|undefined} Filters by request path.
+    * `hash` {string|RegExp|null|undefined} Filters by request hash.
+    * `fullUrl` {string|RegExp|null|undefined} Filters by request full URL.
+    * `method` {string|RegExp|null|undefined} Filters by request method.
+* `options` {Object} Adjusts the filtering behavior. Only applied when `criteria`
+  is an object. (optional)
+  * `operator` {string} How to combine multiple object properties. `'OR'` keeps
+    a log matching any criterion; `'AND'` keeps a log matching every criterion.
+    The value is case-insensitive. **Default:** `'OR'`.
+* Returns: {MockCallHistoryLog[]} The matching logs. Duplicates produced by an
+  `'OR'` combination are removed.
+
+A convenience method for applying one or several filters at once. It is a more
+expressive alternative to the per-field helpers below.
+
+Throws an [`InvalidArgumentError`][] when `criteria` is not a function, regular
+expression, or object, or when `options.operator` is neither `'OR'` nor `'AND'`.
+
+```mjs
+const callHistory = mockAgent.getCallHistory()
+
+callHistory?.filterCalls((log) =>
+  log.hash === '#hash' && log.headers?.authorization !== undefined)
+
+callHistory?.filterCalls(/"errors": "wrong body"/)
+
+// Logs with a hash containing `my-hash` OR a path equal to `/endpoint`.
+callHistory?.filterCalls({ hash: /my-hash/, path: '/endpoint' })
+
+// Logs with a hash containing `my-hash` AND a path equal to `/endpoint`.
+callHistory?.filterCalls(
+  { hash: /my-hash/, path: '/endpoint' },
+  { operator: 'AND' }
+)
 ```
 
-### filterCallsByProtocol
+### `mockCallHistory.filterCallsByProtocol(criteria)`
 
-Filter MockCallHistoryLog by protocol.
+<!-- YAML
+added: v7.5.0
+-->
 
-> more details for the first parameter can be found [here](/docs/docs/api/MockCallHistory.md#filter-parameter)
+* `criteria` {string|RegExp|null|undefined} See
+  [filter parameter](#filter-parameter).
+* Returns: {MockCallHistoryLog[]} The logs whose protocol matches `criteria`.
 
-```js
+Filters the recorded logs by request protocol.
+
+```mjs
 mockAgent.getCallHistory()?.filterCallsByProtocol(/https/)
 mockAgent.getCallHistory()?.filterCallsByProtocol('https:')
 ```
 
-### filterCallsByHost
+### `mockCallHistory.filterCallsByHost(criteria)`
+
+<!-- YAML
+added: v7.5.0
+-->
 
-Filter MockCallHistoryLog by host.
+* `criteria` {string|RegExp|null|undefined} See
+  [filter parameter](#filter-parameter).
+* Returns: {MockCallHistoryLog[]} The logs whose host matches `criteria`.
 
-> more details for the first parameter can be found [here](/docs/docs/api/MockCallHistory.md#filter-parameter)
+Filters the recorded logs by request host.
 
-```js
+```mjs
 mockAgent.getCallHistory()?.filterCallsByHost(/localhost/)
 mockAgent.getCallHistory()?.filterCallsByHost('localhost:3000')
 ```
 
-### filterCallsByPort
+### `mockCallHistory.filterCallsByPort(criteria)`
+
+<!-- YAML
+added: v7.5.0
+-->
 
-Filter MockCallHistoryLog by port.
+* `criteria` {string|RegExp|null|undefined} See
+  [filter parameter](#filter-parameter).
+* Returns: {MockCallHistoryLog[]} The logs whose port matches `criteria`.
 
-> more details for the first parameter can be found [here](/docs/docs/api/MockCallHistory.md#filter-parameter)
+Filters the recorded logs by request port.
 
-```js
+```mjs
 mockAgent.getCallHistory()?.filterCallsByPort(/3000/)
 mockAgent.getCallHistory()?.filterCallsByPort('3000')
 mockAgent.getCallHistory()?.filterCallsByPort('')
 ```
 
-### filterCallsByOrigin
+### `mockCallHistory.filterCallsByOrigin(criteria)`
 
-Filter MockCallHistoryLog by origin.
+<!-- YAML
+added: v7.5.0
+-->
 
-> more details for the first parameter can be found [here](/docs/docs/api/MockCallHistory.md#filter-parameter)
+* `criteria` {string|RegExp|null|undefined} See
+  [filter parameter](#filter-parameter).
+* Returns: {MockCallHistoryLog[]} The logs whose origin matches `criteria`.
 
-```js
+Filters the recorded logs by request origin.
+
+```mjs
 mockAgent.getCallHistory()?.filterCallsByOrigin(/http:\/\/localhost:3000/)
 mockAgent.getCallHistory()?.filterCallsByOrigin('http://localhost:3000')
 ```
 
-### filterCallsByPath
+### `mockCallHistory.filterCallsByPath(criteria)`
+
+<!-- YAML
+added: v7.5.0
+-->
 
-Filter MockCallHistoryLog by path.
+* `criteria` {string|RegExp|null|undefined} See
+  [filter parameter](#filter-parameter).
+* Returns: {MockCallHistoryLog[]} The logs whose path matches `criteria`.
 
-> more details for the first parameter can be found [here](/docs/docs/api/MockCallHistory.md#filter-parameter)
+Filters the recorded logs by request path.
 
-```js
+```mjs
 mockAgent.getCallHistory()?.filterCallsByPath(/api\/v1\/graphql/)
 mockAgent.getCallHistory()?.filterCallsByPath('/api/v1/graphql')
 ```
 
-### filterCallsByHash
+### `mockCallHistory.filterCallsByHash(criteria)`
+
+<!-- YAML
+added: v7.5.0
+-->
 
-Filter MockCallHistoryLog by hash.
+* `criteria` {string|RegExp|null|undefined} See
+  [filter parameter](#filter-parameter).
+* Returns: {MockCallHistoryLog[]} The logs whose hash matches `criteria`.
 
-> more details for the first parameter can be found [here](/docs/docs/api/MockCallHistory.md#filter-parameter)
+Filters the recorded logs by request hash.
 
-```js
-mockAgent.getCallHistory()?.filterCallsByPath(/hash/)
-mockAgent.getCallHistory()?.filterCallsByPath('#hash')
+```mjs
+mockAgent.getCallHistory()?.filterCallsByHash(/hash/)
+mockAgent.getCallHistory()?.filterCallsByHash('#hash')
 ```
 
-### filterCallsByFullUrl
+### `mockCallHistory.filterCallsByFullUrl(criteria)`
 
-Filter MockCallHistoryLog by fullUrl. fullUrl contains protocol, host, port, path, hash, and query params
+<!-- YAML
+added: v7.5.0
+-->
 
-> more details for the first parameter can be found [here](/docs/docs/api/MockCallHistory.md#filter-parameter)
+* `criteria` {string|RegExp|null|undefined} See
+  [filter parameter](#filter-parameter).
+* Returns: {MockCallHistoryLog[]} The logs whose full URL matches `criteria`.
 
-```js
+Filters the recorded logs by request full URL. The full URL contains the
+protocol, host, port, path, query parameters, and hash.
+
+```mjs
 mockAgent.getCallHistory()?.filterCallsByFullUrl(/https:\/\/localhost:3000\/\?query=value#hash/)
 mockAgent.getCallHistory()?.filterCallsByFullUrl('https://localhost:3000/?query=value#hash')
 ```
 
-### filterCallsByMethod
+### `mockCallHistory.filterCallsByMethod(criteria)`
+
+<!-- YAML
+added: v7.5.0
+-->
 
-Filter MockCallHistoryLog by method.
+* `criteria` {string|RegExp|null|undefined} See
+  [filter parameter](#filter-parameter).
+* Returns: {MockCallHistoryLog[]} The logs whose method matches `criteria`.
 
-> more details for the first parameter can be found [here](/docs/docs/api/MockCallHistory.md#filter-parameter)
+Filters the recorded logs by request method.
 
-```js
+```mjs
 mockAgent.getCallHistory()?.filterCallsByMethod(/POST/)
 mockAgent.getCallHistory()?.filterCallsByMethod('POST')
 ```
 
-### filterCalls
+### `mockCallHistory.clear()`
 
-This class method is a meta function / alias to apply complex filtering in a single way.
+<!-- YAML
+added: v7.5.0
+-->
 
-Parameters :
+* Returns: {undefined}
 
-- criteria : the first parameter. a function, regexp or object.
-  - function : filter MockCallHistoryLog when the function returns false
-  - regexp : filter MockCallHistoryLog when the regexp does not match on MockCallHistoryLog.toString() ([see](/docs/docs/api/MockCallHistoryLog.md#to-string))
-  - object : an object with MockCallHistoryLog properties as keys to apply multiple filters. each values are a [filter parameter](/docs/docs/api/MockCallHistory.md#filter-parameter)
-- options : the second parameter. an object.
-  - options.operator : `'AND'` or `'OR'` (default `'OR'`). Used only if criteria is an object. see below
+Removes every recorded [`MockCallHistoryLog`][]. This is performed
+automatically when `mockAgent.close()` is called.
 
-```js
-mockAgent.getCallHistory()?.filterCalls((log) => log.hash === value && log.headers?.['authorization'] !== undefined)
-mockAgent.getCallHistory()?.filterCalls(/"data": "{ "errors": "wrong body" }"/)
+```mjs
+mockAgent.clearCallHistory()
+// Equivalent to:
+mockAgent.getCallHistory()?.clear()
+```
+
+### `mockCallHistory[Symbol.iterator]()`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+* Returns: {Generator} A generator yielding each recorded
+  [`MockCallHistoryLog`][] in order.
 
-// returns an Array of MockCallHistoryLog which all have
-// - a hash containing my-hash
-// - OR
-// - a path equal to /endpoint
-mockAgent.getCallHistory()?.filterCalls({ hash: /my-hash/, path: '/endpoint' })
+Makes a `MockCallHistory` iterable, yielding the same logs returned by
+`calls()`. This enables `for...of` iteration, the spread operator, and
+constructing other iterables from a history.
 
-// returns an Array of MockCallHistoryLog which all have
-// - a hash containing my-hash
-// - AND
-// - a path equal to /endpoint
-mockAgent.getCallHistory()?.filterCalls({ hash: /my-hash/, path: '/endpoint' }, { operator: 'AND' })
+```mjs
+const callHistory = mockAgent.getCallHistory()
+
+for (const log of callHistory) {
+  console.log(log.method, log.fullUrl)
+}
+
+const logs = [...callHistory]
 ```
 
-## filter parameter
+## Filter parameter
+
+The per-field `filterCallsBy*` helpers and the object form of `filterCalls()`
+accept a filter parameter that is matched against the corresponding field of each
+[`MockCallHistoryLog`][]:
+
+* A {string} keeps a log only when the field is strictly equal to the value.
+* `null` keeps a log only when the field is strictly equal to `null`.
+* `undefined` keeps a log only when the field is strictly equal to `undefined`.
+* A {RegExp} keeps a log only when the expression matches the field.
 
-Can be :
+Any other value throws an [`InvalidArgumentError`][].
 
-- string. MockCallHistoryLog filtered if `value !== parameterValue`
-- null. MockCallHistoryLog filtered if `value !== parameterValue`
-- undefined. MockCallHistoryLog filtered if `value !== parameterValue`
-- regexp. MockCallHistoryLog filtered if `!parameterValue.test(value)`
+[`InvalidArgumentError`]: Errors.md#class-invalidargumenterror
+[`MockAgent`]: MockAgent.md#class-mockagent
+[`MockCallHistoryLog`]: MockCallHistoryLog.md#class-mockcallhistorylog
+[`mockCallHistoryLog.toString()`]: MockCallHistoryLog.md#mockcallhistorylogtostring
diff --git a/docs/docs/api/MockCallHistoryLog.md b/docs/docs/api/MockCallHistoryLog.md
index 3d38bdd29d5..40c1bdbfdf0 100644
--- a/docs/docs/api/MockCallHistoryLog.md
+++ b/docs/docs/api/MockCallHistoryLog.md
@@ -1,43 +1,206 @@
-# Class: MockCallHistoryLog
+# MockCallHistoryLog
 
-Access to an instance with :
+<!--introduced_in=v7.5.0-->
+<!--type=module-->
+<!-- source_link=lib/mock/mock-call-history.js -->
+
+> Stability: 2 - Stable
+
+A `MockCallHistoryLog` is an immutable snapshot of the configuration of a single
+request that was intercepted by a [`MockAgent`][]. Each property mirrors a part
+of the request, with the URL components already parsed by the WHATWG URL parser.
+
+Instances are not created directly. They are produced by a [`MockCallHistory`][]
+when call history is enabled on a [`MockAgent`][], and can be retrieved through
+the call history helpers such as `firstCall()`, `lastCall()`, `nthCall()`,
+`calls()`, and `filterCalls()`.
+
+```mjs
+import { MockAgent } from 'undici'
 
-```js
 const mockAgent = new MockAgent({ enableCallHistory: true })
-mockAgent.getCallHistory()?.firstCall()
+
+// after some requests have been intercepted:
+const log = mockAgent.getCallHistory()?.firstCall()
 ```
 
-## class properties
+## Class: `MockCallHistoryLog`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+Represents the configuration of one intercepted request.
+
+### `new MockCallHistoryLog(requestInit)`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+* `requestInit` {DispatchOptions} The dispatch options of the intercepted
+  request. **Default:** `{}`.
+
+Creates a new `MockCallHistoryLog`. The `body`, `headers`, and `method`
+properties are copied directly from `requestInit`, while the URL-derived
+properties (`fullUrl`, `origin`, `path`, `searchParams`, `protocol`, `host`,
+`port`, and `hash`) are computed from `requestInit.path` and `requestInit.origin`
+using the WHATWG URL parser.
+
+This constructor is internal-facing: instances are created by
+[`MockCallHistory`][] when a request is intercepted. It is documented because the
+class is part of the public API surface.
+
+### `mockCallHistoryLog.body`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+* Type: {string|null|undefined}
+
+The body of the intercepted request, exactly as supplied to the dispatcher.
+
+### `mockCallHistoryLog.headers`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+* Type: {Record<string, string|string[]>|null|undefined}
+
+The headers of the intercepted request.
+
+### `mockCallHistoryLog.method`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+* Type: {string}
+
+The HTTP method of the intercepted request, for example `'GET'` or `'PUT'`.
+
+### `mockCallHistoryLog.fullUrl`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+* Type: {string}
+
+The full URL of the intercepted request, including protocol, host, path, search
+parameters, and hash.
+
+### `mockCallHistoryLog.origin`
+
+<!-- YAML
+added: v7.5.0
+-->
 
-- body `mockAgent.getCallHistory()?.firstCall()?.body`
-- headers `mockAgent.getCallHistory()?.firstCall()?.headers` an object
-- method `mockAgent.getCallHistory()?.firstCall()?.method` a string
-- fullUrl `mockAgent.getCallHistory()?.firstCall()?.fullUrl` a string containing the protocol, origin, path, query and hash
-- origin `mockAgent.getCallHistory()?.firstCall()?.origin` a string containing the protocol and the host
-- headers `mockAgent.getCallHistory()?.firstCall()?.headers` an object
-- path `mockAgent.getCallHistory()?.firstCall()?.path` a string always starting with `/`
-- searchParams `mockAgent.getCallHistory()?.firstCall()?.searchParams` an object
-- protocol `mockAgent.getCallHistory()?.firstCall()?.protocol` a string (`https:`)
-- host `mockAgent.getCallHistory()?.firstCall()?.host` a string
-- port `mockAgent.getCallHistory()?.firstCall()?.port` an empty string or a string containing numbers
-- hash `mockAgent.getCallHistory()?.firstCall()?.hash` an empty string or a string starting with `#`
+* Type: {string}
 
-## class methods
+The origin of the intercepted request, comprising the protocol and host, for
+example `'https://localhost:4000'`.
 
-### toMap
+### `mockCallHistoryLog.path`
 
-Returns a Map instance
+<!-- YAML
+added: v7.5.0
+-->
 
-```js
-mockAgent.getCallHistory()?.firstCall()?.toMap()?.get('hash')
-// #hash
+* Type: {string}
+
+The pathname of the intercepted request. It always starts with `/` and never
+contains search parameters.
+
+### `mockCallHistoryLog.searchParams`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+* Type: {Record<string, string>}
+
+The search parameters of the intercepted request as a plain object of key/value
+pairs.
+
+### `mockCallHistoryLog.protocol`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+* Type: {string}
+
+The protocol of the intercepted request, including the trailing colon, for
+example `'https:'` or `'http:'`.
+
+### `mockCallHistoryLog.host`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+* Type: {string}
+
+The host of the intercepted request, including the port when present.
+
+### `mockCallHistoryLog.port`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+* Type: {string}
+
+The port of the intercepted request. It is an empty string when no explicit port
+was used, otherwise a string of digits.
+
+### `mockCallHistoryLog.hash`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+* Type: {string}
+
+The hash fragment of the intercepted request. It is an empty string when absent,
+otherwise a string starting with `#`.
+
+### `mockCallHistoryLog.toMap()`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+* Returns: {Map} A `Map` whose keys are the property names `protocol`, `host`,
+  `port`, `origin`, `path`, `hash`, `searchParams`, `fullUrl`, `method`, `body`,
+  and `headers`, each mapped to the corresponding value of this log.
+
+Returns the log as a `Map` of property name to value.
+
+```mjs
+mockAgent.getCallHistory()?.firstCall()?.toMap().get('hash')
+// '#hash'
 ```
 
-### toString
+### `mockCallHistoryLog.toString()`
 
-Returns a string computed with any class property name and value pair
+<!-- YAML
+added: v7.5.0
+-->
 
-```js
+* Returns: {string} A string representation of the log.
+
+Returns a string built from every property name and value pair. Each pair is
+joined with `->` and pairs are separated with `|`. Object values such as
+`searchParams` and `headers` are serialized with `JSON.stringify()`.
+
+```mjs
 mockAgent.getCallHistory()?.firstCall()?.toString()
 // protocol->https:|host->localhost:4000|port->4000|origin->https://localhost:4000|path->/endpoint|hash->#here|searchParams->{"query":"value"}|fullUrl->https://localhost:4000/endpoint?query=value#here|method->PUT|body->"{ "data": "hello" }"|headers->{"content-type":"application/json"}
 ```
+
+[`MockAgent`]: MockAgent.md#class-mockagent
+[`MockCallHistory`]: MockCallHistory.md#class-mockcallhistory
diff --git a/docs/docs/api/MockClient.md b/docs/docs/api/MockClient.md
index 0e6c57a1a84..56c92975634 100644
--- a/docs/docs/api/MockClient.md
+++ b/docs/docs/api/MockClient.md
@@ -1,73 +1,183 @@
-# Class: MockClient
+# MockClient
 
-Extends: `undici.Client`
+<!--introduced_in=v4.0.0-->
+<!--type=module-->
+<!-- source_link=lib/mock/mock-client.js -->
 
-A mock client class that implements the same api as [MockPool](/docs/docs/api/MockPool.md).
+> Stability: 2 - Stable
 
-## `new MockClient(origin, [options])`
+A `MockClient` is a [`Client`][] that intercepts requests matching registered
+routes and replies with mocked responses instead of contacting the network.
+It is created by a [`MockAgent`][] when the agent is configured with a single
+connection, and it exposes the same interception API as [`MockPool`][].
 
-Arguments:
+A `MockClient` is not constructed directly in most cases; instead it is obtained
+through [`mockAgent.get(origin)`][] once the agent has `connections` set to `1`.
 
-* **origin** `string` - It should only include the **protocol, hostname, and port**.
-* **options** `MockClientOptions` - It extends the `Client` options.
+```mjs
+import { MockAgent } from 'undici'
 
-Returns: `MockClient`
+// `connections: 1` makes the agent hand out `MockClient` instances.
+const mockAgent = new MockAgent({ connections: 1 })
+const mockClient = mockAgent.get('http://localhost:3000')
+```
 
-### Parameter: `MockClientOptions`
+```cjs
+const { MockAgent } = require('undici')
 
-Extends: `ClientOptions`
+const mockAgent = new MockAgent({ connections: 1 })
+const mockClient = mockAgent.get('http://localhost:3000')
+```
+
+## Class: `MockClient`
 
-* **agent** `Agent` - the agent to associate this MockClient with.
+<!-- YAML
+added: v4.0.0
+-->
 
-### Example - Basic MockClient instantiation
+* Extends: {Client}
 
-We can use MockAgent to instantiate a MockClient ready to be used to intercept specified requests. It will not do anything until registered as the agent to use and any mock request are registered.
+Extends [`Client`][] and implements the `Interceptable` interface, allowing
+requests made through it to be matched against registered mocks.
 
-```js
+### `new MockClient(origin[, options])`
+
+<!-- YAML
+added: v4.0.0
+-->
+
+* `origin` {string} The origin to associate this mock client with. It should
+  only include the protocol, hostname, and port.
+* `options` {MockClientOptions} Extends the [`Client`][] options.
+* Returns: {MockClient}
+
+The `agent` option is required and must implement the `Agent` interface;
+otherwise an `InvalidArgumentError` is thrown.
+
+#### Parameter: `MockClientOptions`
+
+Extends: `ClientOptions`
+
+* `agent` {MockAgent} The agent to associate this mock client with.
+* `ignoreTrailingSlash` {boolean} Whether trailing slashes should be ignored
+  when matching the path of intercepted requests. **Default:** `false`.
+
+### `mockClient.intercept(options)`
+
+<!-- YAML
+added: v4.0.0
+-->
+
+* `options` {MockInterceptor.Options} The matching criteria for the requests to
+  intercept.
+  * `path` {string|RegExp|Function} The path to match against. A function
+    receives the request path as a `string` and returns a `boolean`.
+  * `method` {string|RegExp|Function} The method to match against. A function
+    receives the request method as a `string` and returns a `boolean`.
+    **Default:** `'GET'`.
+  * `body` {string|RegExp|Function} The body to match against. A function
+    receives the request body as a `string` and returns a `boolean`.
+  * `headers` {Object|Function} The headers to match against, as a map of header
+    name to a `string`, `RegExp`, or matching function, or a single function
+    that receives all headers and returns a `boolean`.
+  * `query` {Object} The query parameters to match against.
+  * `ignoreTrailingSlash` {boolean} Whether a trailing slash on `path` is
+    ignored when matching. Inherited from the mock client's
+    `ignoreTrailingSlash` option when not set.
+* Returns: {MockInterceptor} The interceptor used to define the mocked reply.
+
+Registers a route on the mock client and returns a [`MockInterceptor`][] for any
+matching request that uses the same origin as this mock client. The interceptor
+is then used to define the reply, for example with `reply()` or
+`replyWithError()`.
+
+```mjs
 import { MockAgent } from 'undici'
 
-// Connections must be set to 1 to return a MockClient instance
 const mockAgent = new MockAgent({ connections: 1 })
+const mockClient = mockAgent.get('http://localhost:3000')
+
+mockClient.intercept({ path: '/foo', method: 'GET' }).reply(200, 'foo')
+```
+
+### `mockClient.cleanMocks()`
+
+<!-- YAML
+added: v7.11.0
+-->
 
+Removes all registered interceptors from the mock client. Pending mocks defined
+before this call no longer match incoming requests.
+
+```mjs
+import { MockAgent } from 'undici'
+
+const mockAgent = new MockAgent({ connections: 1 })
 const mockClient = mockAgent.get('http://localhost:3000')
+
+mockClient.intercept({ path: '/foo' }).reply(200, 'foo')
+mockClient.cleanMocks()
 ```
 
-## Instance Methods
+### `mockClient.close()`
 
-### `MockClient.intercept(options)`
+<!-- YAML
+added: v4.0.0
+-->
 
-Implements: [`MockPool.intercept(options)`](/docs/docs/api/MockPool.md#mockpoolinterceptoptions)
+* Returns: {Promise} Fulfills with `undefined` once the mock client is closed.
 
-### `MockClient.cleanMocks()`
+Closes the mock client, gracefully waiting for any enqueued requests to
+complete, and removes it from the associated [`MockAgent`][].
 
-Implements: [`MockPool.cleanMocks()`](/docs/docs/api/MockPool.md#mockpoolcleanmocks)
+```mjs
+import { MockAgent } from 'undici'
 
-### `MockClient.close()`
+const mockAgent = new MockAgent({ connections: 1 })
+const mockClient = mockAgent.get('http://localhost:3000')
+
+await mockClient.close()
+```
 
-Implements: [`MockPool.close()`](/docs/docs/api/MockPool.md#mockpoolclose)
+### `mockClient.dispatch(options, handlers)`
 
-### `MockClient.dispatch(options, handlers)`
+<!-- YAML
+added: v4.0.0
+-->
 
-Implements [`Dispatcher.dispatch(options, handlers)`](/docs/docs/api/Dispatcher.md#dispatcherdispatchoptions-handler).
+* `options` {DispatchOptions} The request options.
+* `handlers` {DispatchHandler} The handlers invoked over the request lifecycle.
+* Returns: {boolean} `false` if the dispatcher is busy and the caller should
+  wait before dispatching further requests, otherwise `true`.
 
-### `MockClient.request(options[, callback])`
+Dispatches a request, matching it against the registered mocks. This override of
+[`dispatcher.dispatch(options, handlers)`][] is what drives the mocking
+behaviour for every higher-level method such as `request`.
 
-See [`Dispatcher.request(options [, callback])`](/docs/docs/api/Dispatcher.md#dispatcherrequestoptions-callback).
+### `mockClient.request(options[, callback])`
 
-#### Example - MockClient request
+<!-- YAML
+added: v4.0.0
+-->
 
-```js
+* `options` {DispatchOptions}
+* `callback` {Function} (optional) Invoked with the response when no `Promise`
+  is requested.
+* Returns: {Promise} Fulfills with the mocked response when no `callback` is
+  provided.
+
+Performs a request and resolves it against the registered mocks. Inherited from
+[`Client`][]; see [`dispatcher.request(options[, callback])`][] for the full
+parameter and return value documentation.
+
+```mjs
 import { MockAgent } from 'undici'
 
 const mockAgent = new MockAgent({ connections: 1 })
-
 const mockClient = mockAgent.get('http://localhost:3000')
 mockClient.intercept({ path: '/foo' }).reply(200, 'foo')
 
-const {
-  statusCode,
-  body
-} = await mockClient.request({
+const { statusCode, body } = await mockClient.request({
   origin: 'http://localhost:3000',
   path: '/foo',
   method: 'GET'
@@ -79,3 +189,11 @@ for await (const data of body) {
   console.log('data', data.toString('utf8')) // data foo
 }
 ```
+
+[`Client`]: Client.md#class-client
+[`MockAgent`]: MockAgent.md#class-mockagent
+[`MockInterceptor`]: MockPool.md#return-mockinterceptor
+[`MockPool`]: MockPool.md#class-mockpool
+[`dispatcher.dispatch(options, handlers)`]: Dispatcher.md#dispatcherdispatchoptions-handler
+[`dispatcher.request(options[, callback])`]: Dispatcher.md#dispatcherrequestoptions-callback
+[`mockAgent.get(origin)`]: MockAgent.md#mockagentgetorigin
diff --git a/docs/docs/api/MockErrors.md b/docs/docs/api/MockErrors.md
index c1aa3dbee8e..4842cc773d8 100644
--- a/docs/docs/api/MockErrors.md
+++ b/docs/docs/api/MockErrors.md
@@ -1,12 +1,63 @@
 # MockErrors
 
-Undici exposes a variety of mock error objects that you can use to enhance your mock error handling.
-You can find all the mock error objects inside the `mockErrors` key.
+<!--introduced_in=v4.0.0-->
+<!--type=module-->
+<!-- source_link=lib/mock/mock-errors.js -->
+
+> Stability: 2 - Stable
+
+undici raises a dedicated error when a mocked request cannot be matched against
+any registered interceptor. The mock error classes are exposed through the
+`mockErrors` namespace of the package:
+
+```js
+import { mockErrors } from 'undici'
+
+if (err instanceof mockErrors.MockNotMatchedError) {
+  // handle an unmatched mocked request
+}
+```
+
+Like every other undici error, the classes in this namespace extend
+[`UndiciError`][] and carry a stable `code` string, so failures can be
+distinguished programmatically without relying on the error message.
+
+## Class: `MockNotMatchedError`
+
+<!-- YAML
+added: v4.0.0
+-->
+
+* Extends: {UndiciError}
+
+Thrown when a request issued against a [`MockAgent`][] does not match any of the
+registered mock dispatches and the agent is configured to disable net connect.
+
+* `name` {string} Always `'MockNotMatchedError'`.
+* `code` {string} Always `'UND_MOCK_ERR_MOCK_NOT_MATCHED'`.
+
+### `new MockNotMatchedError([message])`
+
+<!-- YAML
+added: v4.0.0
+-->
+
+* `message` {string} The error message. **Default:** `'The request does not match any registered mock dispatches'`.
+
+Creates a new `MockNotMatchedError`. When `message` is omitted, a default
+message describing the unmatched request is used.
 
 ```js
 import { mockErrors } from 'undici'
+
+try {
+  // ... perform a request that no mock matches ...
+} catch (err) {
+  if (err.code === 'UND_MOCK_ERR_MOCK_NOT_MATCHED') {
+    console.error('No registered mock matched the request')
+  }
+}
 ```
 
-| Mock Error            | Mock Error Codes                | Description                                                |
-| --------------------- | ------------------------------- | ---------------------------------------------------------- |
-| `MockNotMatchedError` | `UND_MOCK_ERR_MOCK_NOT_MATCHED` | The request does not match any registered mock dispatches. |
+[`MockAgent`]: MockAgent.md#class-mockagent
+[`UndiciError`]: Errors.md#class-undicierror
diff --git a/docs/docs/api/MockPool.md b/docs/docs/api/MockPool.md
index 64a7044b805..dc6474c5a23 100644
--- a/docs/docs/api/MockPool.md
+++ b/docs/docs/api/MockPool.md
@@ -1,109 +1,209 @@
-# Class: MockPool
+# MockPool
 
-Extends: `undici.Pool`
+<!--introduced_in=v4.0.0-->
+<!--type=module-->
+<!-- source_link=lib/mock/mock-pool.js -->
 
-A mock Pool class that implements the Pool API and is used by MockAgent to intercept real requests and return mocked responses.
+> Stability: 2 - Stable
 
-## `new MockPool(origin, [options])`
+A `MockPool` is a [`Pool`][] that intercepts requests matching registered routes
+and replies with mocked responses instead of contacting the network. It is
+created by a [`MockAgent`][] and exposes the same interception API as
+[`MockClient`][].
 
-Arguments:
+A `MockPool` is not constructed directly in most cases; instead it is obtained
+through [`mockAgent.get(origin)`][]. Once registered as the global dispatcher,
+any request whose origin matches the pool is matched against the mocks it holds.
 
-* **origin** `string` - It should only include the **protocol, hostname, and port**.
-* **options** `MockPoolOptions` - It extends the `Pool` options.
-
-Returns: `MockPool`
-
-### Parameter: `MockPoolOptions`
-
-Extends: `PoolOptions`
-
-* **agent** `Agent` - the agent to associate this MockPool with.
-
-### Example - Basic MockPool instantiation
-
-We can use MockAgent to instantiate a MockPool ready to be used to intercept specified requests. It will not do anything until registered as the agent to use and any mock request are registered.
-
-```js
+```mjs
 import { MockAgent } from 'undici'
 
 const mockAgent = new MockAgent()
-
 const mockPool = mockAgent.get('http://localhost:3000')
 ```
 
-## Instance Methods
-
-### `MockPool.intercept(options)`
-
-This method defines the interception rules for matching against requests for a MockPool or MockPool. We can intercept multiple times on a single instance, but each intercept is only used once. For example if you expect to make 2 requests inside a test, you need to call `intercept()` twice. Assuming you use `disableNetConnect()` you will get `MockNotMatchedError` on the second request when you only call `intercept()` once.
-
-When defining interception rules, all the rules must pass for a request to be intercepted. If a request is not intercepted, a real request will be attempted.
-
-| Matcher type | Condition to pass          |
-|:------------:| -------------------------- |
-| `string`     | Exact match against string |
-| `RegExp`     | Regex must pass            |
-| `Function`   | Function must return true  |
-
-Arguments:
-
-* **options** `MockPoolInterceptOptions` - Interception options.
-
-Returns: `MockInterceptor` corresponding to the input options.
+```cjs
+const { MockAgent } = require('undici')
 
-### Parameter: `MockPoolInterceptOptions`
-
-* **path** `string | RegExp | (path: string) => boolean` - a matcher for the HTTP request path. When a `RegExp` or callback is used, it will match against the request path including all query parameters in alphabetical order. When a `string` is provided, the query parameters can be conveniently specified through the `MockPoolInterceptOptions.query` setting.
-* **method** `string | RegExp | (method: string) => boolean` - (optional) - a matcher for the HTTP request method. Defaults to `GET`.
-* **body** `string | RegExp | (body: string) => boolean` - (optional) - a matcher for the HTTP request body.
-* **headers** `Record<string, string | RegExp | (body: string) => boolean`> - (optional) - a matcher for the HTTP request headers. To be intercepted, a request must match all defined headers. Extra headers not defined here may (or may not) be included in the request and do not affect the interception in any way.
-* **query** `Record<string, any> | null` - (optional) - a matcher for the HTTP request query string params. Only applies when a `string` was provided for `MockPoolInterceptOptions.path`.
-* **ignoreTrailingSlash** `boolean` - (optional) - set to `true` if the matcher should also match by ignoring potential trailing slashes in `MockPoolInterceptOptions.path`.
-
-### Return: `MockInterceptor`
+const mockAgent = new MockAgent()
+const mockPool = mockAgent.get('http://localhost:3000')
+```
 
-We can define the behaviour of an intercepted request with the following options.
+## Class: `MockPool`
 
-* **reply** `(statusCode: number, replyData: string | Buffer | object | MockInterceptor.MockResponseDataHandler, responseOptions?: MockResponseOptions) => MockScope` - define a reply for a matching request. You can define the replyData as a callback to read incoming request data. Default for `responseOptions` is `{}`.
-* **reply** `(callback: MockInterceptor.MockReplyOptionsCallback) => MockScope` - define a reply for a matching request, allowing dynamic mocking of all reply options rather than just the data.
-* **replyWithError** `(error: Error) => MockScope` - define an error for a matching request to throw.
-* **defaultReplyHeaders** `(headers: Record<string, string>) => MockInterceptor` - define default headers to be included in subsequent replies. These are in addition to headers on a specific reply.
-* **defaultReplyTrailers** `(trailers: Record<string, string>) => MockInterceptor` - define default trailers to be included in subsequent replies. These are in addition to trailers on a specific reply.
-* **replyContentLength** `() => MockInterceptor` - define automatically calculated `content-length` headers to be included in subsequent replies.
+<!-- YAML
+added: v4.0.0
+-->
 
-The reply data of an intercepted request may either be a string, buffer, or JavaScript object. Objects are converted to JSON while strings and buffers are sent as-is.
+* Extends: {Pool}
 
-By default, `reply` and `replyWithError` define the behaviour for the first matching request only. Subsequent requests will not be affected (this can be changed using the returned `MockScope`).
+Extends [`Pool`][] and implements the `Interceptable` interface, allowing
+requests made through it to be matched against registered mocks.
 
-### Parameter: `MockResponseOptions`
+### `new MockPool(origin[, options])`
 
-* **headers** `Record<string, string>` - headers to be included on the mocked reply.
-* **trailers** `Record<string, string>` - trailers to be included on the mocked reply.
+<!-- YAML
+added: v4.0.0
+-->
 
-### Return: `MockScope`
+* `origin` {string} The origin to associate this mock pool with. It should only
+  include the protocol, hostname, and port.
+* `options` {MockPoolOptions} Extends the [`Pool`][] options.
+* Returns: {MockPool}
 
-A `MockScope` is associated with a single `MockInterceptor`. With this, we can configure the default behaviour of an intercepted reply.
+The `agent` option is required and must implement the `Agent` interface;
+otherwise an `InvalidArgumentError` is thrown.
 
-* **delay** `(waitInMs: number) => MockScope` - delay the associated reply by a set amount in ms.
-* **persist** `() => MockScope` - any matching request will always reply with the defined response indefinitely.
-* **times** `(repeatTimes: number) => MockScope` - any matching request will reply with the defined response a fixed amount of times. This is overridden by **persist**.
+#### Parameter: `MockPoolOptions`
 
-#### Example - Basic Mocked Request
+Extends: `PoolOptions`
 
-```js
+* `agent` {MockAgent} The agent to associate this mock pool with.
+* `ignoreTrailingSlash` {boolean} Whether trailing slashes should be ignored
+  when matching the path of intercepted requests. **Default:** `false`.
+
+### `mockPool.intercept(options)`
+
+<!-- YAML
+added: v4.0.0
+-->
+
+* `options` {MockPoolInterceptOptions} The matching criteria for the requests to
+  intercept.
+* Returns: {MockInterceptor} The interceptor used to define the mocked reply.
+
+Registers a route on the mock pool and returns a [`MockInterceptor`][] for any
+matching request that uses the same origin as this mock pool. The interceptor is
+then used to define the reply, for example with `reply()` or `replyWithError()`.
+
+Each `intercept()` call is consumed by a single matching request. To match more
+than one request, call `intercept()` once per expected request, or use
+`persist()` or `times()` on the returned [`MockScope`][]. When no registered
+mock matches a request, a real request is attempted unless network connections
+have been disabled on the [`MockAgent`][], in which case a `MockNotMatchedError`
+is thrown.
+
+A request is intercepted only when every defined matcher passes. The accepted
+matcher forms behave as follows:
+
+| Matcher type | Condition to pass            |
+| :----------: | ---------------------------- |
+| `string`     | Exact match against the value |
+| `RegExp`     | The expression must match    |
+| `Function`   | The function must return `true` |
+
+#### Parameter: `MockPoolInterceptOptions`
+
+* `path` {string|RegExp|Function} A matcher for the HTTP request path. The
+  function form has the signature `(path: string) => boolean`. When a `RegExp`
+  or function is used, it matches against the request path including all query
+  parameters in alphabetical order. When a `string` is used, query parameters
+  can instead be supplied through `query`.
+* `method` {string|RegExp|Function} A matcher for the HTTP request method. The
+  function form has the signature `(method: string) => boolean`.
+  **Default:** `'GET'`.
+* `body` {string|RegExp|Function} A matcher for the HTTP request body. The
+  function form has the signature `(body: string) => boolean`.
+* `headers` {Object|Function} A matcher for the HTTP request headers, given
+  either as a map of header name to a `string`, `RegExp`, or
+  `(value: string) => boolean` matcher, or as a single function that receives
+  all headers and returns a `boolean`. When a map is used, the request must
+  match every defined header; extra headers not listed here do not affect
+  matching.
+* `query` {Object} A matcher for the HTTP request query string parameters. Only
+  applies when a `string` was provided for `path`.
+* `ignoreTrailingSlash` {boolean} Whether a trailing slash on `path` is ignored
+  when matching. Inherited from the mock pool's `ignoreTrailingSlash` option
+  when not set.
+
+#### Return: `MockInterceptor`
+
+The reply behaviour of a matching request is defined through the returned
+`MockInterceptor`.
+
+* `reply(statusCode[, data[, responseOptions]])` {Function} Defines the reply
+  for a matching request.
+  * `statusCode` {number} The status code of the mocked reply.
+  * `data` {string|Buffer|Object|Function} The body of the mocked reply.
+    Objects are serialized to JSON; strings and `Buffer`s are sent as-is. The
+    function form has the signature
+    `(opts: MockResponseCallbackOptions) => string | Buffer | Object` and is
+    invoked with the incoming request to compute the reply body.
+  * `responseOptions` {MockResponseOptions} Additional reply options.
+    **Default:** `{}`.
+  * Returns: {MockScope}
+* `reply(callback)` {Function} Defines the reply for a matching request,
+  computing all reply options dynamically rather than just the body.
+  * `callback` {Function} A `(opts: MockResponseCallbackOptions) =>
+    { statusCode, data, responseOptions }` function invoked with the incoming
+    request.
+  * Returns: {MockScope}
+* `replyWithError(error)` {Function} Defines an error for a matching request to
+  throw.
+  * `error` {Error} The error thrown when a request matches.
+  * Returns: {MockScope}
+* `defaultReplyHeaders(headers)` {Function} Sets default headers included on
+  every subsequent reply defined on this interceptor, in addition to any headers
+  set on a specific reply.
+  * `headers` {Object} A map of header name to value.
+  * Returns: {MockInterceptor}
+* `defaultReplyTrailers(trailers)` {Function} Sets default trailers included on
+  every subsequent reply defined on this interceptor, in addition to any
+  trailers set on a specific reply.
+  * `trailers` {Object} A map of trailer name to value.
+  * Returns: {MockInterceptor}
+* `replyContentLength()` {Function} Sets an automatically calculated
+  `content-length` header on every subsequent reply defined on this interceptor.
+  * Returns: {MockInterceptor}
+
+By default, `reply()` and `replyWithError()` define the behaviour for the first
+matching request only; subsequent requests are not affected unless `persist()`
+or `times()` is used on the returned [`MockScope`][].
+
+#### Parameter: `MockResponseCallbackOptions`
+
+The argument passed to the `reply()` data and options callbacks.
+
+* `path` {string} The path of the intercepted request.
+* `method` {string} The method of the intercepted request.
+* `headers` {Object|Headers} The headers of the intercepted request.
+* `origin` {string} The origin of the intercepted request.
+* `body` {string|null} The body of the intercepted request.
+
+#### Parameter: `MockResponseOptions`
+
+* `headers` {Object} Headers to include on the mocked reply.
+* `trailers` {Object} Trailers to include on the mocked reply.
+
+#### Return: `MockScope`
+
+A `MockScope` is associated with a single [`MockInterceptor`][] and configures
+how many times the defined reply is used.
+
+* `delay(waitInMs)` {Function} Delays the associated reply by a set amount of
+  time.
+  * `waitInMs` {number} The delay in milliseconds.
+  * Returns: {MockScope}
+* `persist()` {Function} Makes the associated reply match indefinitely, so every
+  matching request receives the defined response.
+  * Returns: {MockScope}
+* `times(repeatTimes)` {Function} Makes the associated reply match a fixed number
+  of times. This is overridden by `persist()`.
+  * `repeatTimes` {number} The number of matching requests the reply applies to.
+  * Returns: {MockScope}
+
+The following examples show common interception patterns.
+
+```mjs displayName="Basic mocked request"
 import { MockAgent, setGlobalDispatcher, request } from 'undici'
 
 const mockAgent = new MockAgent()
 setGlobalDispatcher(mockAgent)
 
-// MockPool
 const mockPool = mockAgent.get('http://localhost:3000')
 mockPool.intercept({ path: '/foo' }).reply(200, 'foo')
 
-const {
-  statusCode,
-  body
-} = await request('http://localhost:3000/foo')
+const { statusCode, body } = await request('http://localhost:3000/foo')
 
 console.log('response received', statusCode) // response received 200
 
@@ -112,9 +212,7 @@ for await (const data of body) {
 }
 ```
 
-#### Example - Mocked request using reply data callbacks
-
-```js
+```mjs displayName="Reply with a data callback"
 import { MockAgent, setGlobalDispatcher, request } from 'undici'
 
 const mockAgent = new MockAgent()
@@ -124,30 +222,21 @@ const mockPool = mockAgent.get('http://localhost:3000')
 
 mockPool.intercept({
   path: '/echo',
-  method: 'GET',
-  headers: {
-    'User-Agent': 'undici',
-    Host: 'example.com'
-  }
-}).reply(200, ({ headers }) => ({ message: headers.get('message') }))
+  method: 'GET'
+}).reply(200, ({ headers }) => ({ message: headers.message }))
 
-const { statusCode, body, headers } = await request('http://localhost:3000', {
-  headers: {
-    message: 'hello world!'
-  }
+const { statusCode, body } = await request('http://localhost:3000/echo', {
+  headers: { message: 'hello world!' }
 })
 
 console.log('response received', statusCode) // response received 200
-console.log('headers', headers) // { 'content-type': 'application/json' }
 
 for await (const data of body) {
-  console.log('data', data.toString('utf8')) // { "message":"hello world!" }
+  console.log('data', data.toString('utf8')) // {"message":"hello world!"}
 }
 ```
 
-#### Example - Mocked request using reply options callback
-
-```js
+```mjs displayName="Reply with an options callback"
 import { MockAgent, setGlobalDispatcher, request } from 'undici'
 
 const mockAgent = new MockAgent()
@@ -157,30 +246,24 @@ const mockPool = mockAgent.get('http://localhost:3000')
 
 mockPool.intercept({
   path: '/echo',
-  method: 'GET',
-  headers: {
-    'User-Agent': 'undici',
-    Host: 'example.com'
-  }
-}).reply(({ headers }) => ({ statusCode: 200, data: { message: headers.get('message') }})))
+  method: 'GET'
+}).reply(({ headers }) => ({
+  statusCode: 200,
+  data: { message: headers.message }
+}))
 
-const { statusCode, body, headers } = await request('http://localhost:3000', {
-  headers: {
-    message: 'hello world!'
-  }
+const { statusCode, body } = await request('http://localhost:3000/echo', {
+  headers: { message: 'hello world!' }
 })
 
 console.log('response received', statusCode) // response received 200
-console.log('headers', headers) // { 'content-type': 'application/json' }
 
 for await (const data of body) {
-  console.log('data', data.toString('utf8')) // { "message":"hello world!" }
+  console.log('data', data.toString('utf8')) // {"message":"hello world!"}
 }
 ```
 
-#### Example - Basic Mocked requests with multiple intercepts
-
-```js
+```mjs displayName="Multiple intercepts"
 import { MockAgent, setGlobalDispatcher, request } from 'undici'
 
 const mockAgent = new MockAgent()
@@ -188,36 +271,21 @@ setGlobalDispatcher(mockAgent)
 
 const mockPool = mockAgent.get('http://localhost:3000')
 
-mockPool.intercept({
-  path: '/foo',
-  method: 'GET'
-}).reply(200, 'foo')
+mockPool.intercept({ path: '/foo', method: 'GET' }).reply(200, 'foo')
+mockPool.intercept({ path: '/hello', method: 'GET' }).reply(200, 'hello')
 
-mockPool.intercept({
-  path: '/hello',
-  method: 'GET',
-}).reply(200, 'hello')
-
-const result1 = await request('http://localhost:3000/foo')
-
-console.log('response received', result1.statusCode) // response received 200
-
-for await (const data of result1.body) {
+const fooResult = await request('http://localhost:3000/foo')
+for await (const data of fooResult.body) {
   console.log('data', data.toString('utf8')) // data foo
 }
 
-const result2 = await request('http://localhost:3000/hello')
-
-console.log('response received', result2.statusCode) // response received 200
-
-for await (const data of result2.body) {
+const helloResult = await request('http://localhost:3000/hello')
+for await (const data of helloResult.body) {
   console.log('data', data.toString('utf8')) // data hello
 }
 ```
 
-#### Example - Mocked request with query body, request headers and response headers and trailers
-
-```js
+```mjs displayName="Match query, body, request headers; reply with headers and trailers"
 import { MockAgent, setGlobalDispatcher, request } from 'undici'
 
 const mockAgent = new MockAgent()
@@ -238,12 +306,9 @@ mockPool.intercept({
   trailers: { 'Content-MD5': 'test' }
 })
 
-const {
-  statusCode,
-  headers,
-  trailers,
-  body
-} = await request('http://localhost:3000/foo?hello=there&see=ya', {
+const { statusCode, headers, trailers, body } = await request(
+  'http://localhost:3000/foo?hello=there&see=ya',
+  {
     method: 'POST',
     body: 'form1=data1&form2=data2',
     headers: {
@@ -251,21 +316,20 @@ const {
       'User-Agent': 'undici',
       Host: 'example.com'
     }
-  })
+  }
+)
 
 console.log('response received', statusCode) // response received 200
 console.log('headers', headers) // { 'content-type': 'application/json' }
 
 for await (const data of body) {
-  console.log('data', data.toString('utf8')) // '{"foo":"bar"}'
+  console.log('data', data.toString('utf8')) // {"foo":"bar"}
 }
 
 console.log('trailers', trailers) // { 'content-md5': 'test' }
 ```
 
-#### Example - Mocked request using different matchers
-
-```js
+```mjs displayName="Different matcher forms"
 import { MockAgent, setGlobalDispatcher, request } from 'undici'
 
 const mockAgent = new MockAgent()
@@ -279,14 +343,11 @@ mockPool.intercept({
   body: (value) => value === 'form=data',
   headers: {
     'User-Agent': 'undici',
-    Host: /^example.com$/
+    Host: /^example\.com$/
   }
 }).reply(200, 'foo')
 
-const {
-  statusCode,
-  body
-} = await request('http://localhost:3000/foo', {
+const { statusCode, body } = await request('http://localhost:3000/foo', {
   method: 'GET',
   body: 'form=data',
   headers: {
@@ -303,9 +364,7 @@ for await (const data of body) {
 }
 ```
 
-#### Example - Mocked request with reply with a defined error
-
-```js
+```mjs displayName="Reply with an error"
 import { MockAgent, setGlobalDispatcher, request } from 'undici'
 
 const mockAgent = new MockAgent()
@@ -319,18 +378,13 @@ mockPool.intercept({
 }).replyWithError(new Error('kaboom'))
 
 try {
-  await request('http://localhost:3000/foo', {
-    method: 'GET'
-  })
+  await request('http://localhost:3000/foo', { method: 'GET' })
 } catch (error) {
-  console.error(error) // TypeError: fetch failed
-  console.error(error.cause) // Error: kaboom
+  console.error(error.message) // kaboom
 }
 ```
 
-#### Example - Mocked request with defaultReplyHeaders
-
-```js
+```mjs displayName="Default reply headers"
 import { MockAgent, setGlobalDispatcher, request } from 'undici'
 
 const mockAgent = new MockAgent()
@@ -338,10 +392,8 @@ setGlobalDispatcher(mockAgent)
 
 const mockPool = mockAgent.get('http://localhost:3000')
 
-mockPool.intercept({
-  path: '/foo',
-  method: 'GET'
-}).defaultReplyHeaders({ foo: 'bar' })
+mockPool.intercept({ path: '/foo', method: 'GET' })
+  .defaultReplyHeaders({ foo: 'bar' })
   .reply(200, 'foo')
 
 const { headers } = await request('http://localhost:3000/foo')
@@ -349,9 +401,7 @@ const { headers } = await request('http://localhost:3000/foo')
 console.log('headers', headers) // headers { foo: 'bar' }
 ```
 
-#### Example - Mocked request with defaultReplyTrailers
-
-```js
+```mjs displayName="Default reply trailers"
 import { MockAgent, setGlobalDispatcher, request } from 'undici'
 
 const mockAgent = new MockAgent()
@@ -359,10 +409,8 @@ setGlobalDispatcher(mockAgent)
 
 const mockPool = mockAgent.get('http://localhost:3000')
 
-mockPool.intercept({
-  path: '/foo',
-  method: 'GET'
-}).defaultReplyTrailers({ foo: 'bar' })
+mockPool.intercept({ path: '/foo', method: 'GET' })
+  .defaultReplyTrailers({ foo: 'bar' })
   .reply(200, 'foo')
 
 const { trailers } = await request('http://localhost:3000/foo')
@@ -370,9 +418,7 @@ const { trailers } = await request('http://localhost:3000/foo')
 console.log('trailers', trailers) // trailers { foo: 'bar' }
 ```
 
-#### Example - Mocked request with automatic content-length calculation
-
-```js
+```mjs displayName="Automatic content-length"
 import { MockAgent, setGlobalDispatcher, request } from 'undici'
 
 const mockAgent = new MockAgent()
@@ -380,19 +426,16 @@ setGlobalDispatcher(mockAgent)
 
 const mockPool = mockAgent.get('http://localhost:3000')
 
-mockPool.intercept({
-  path: '/foo',
-  method: 'GET'
-}).replyContentLength().reply(200, 'foo')
+mockPool.intercept({ path: '/foo', method: 'GET' })
+  .replyContentLength()
+  .reply(200, 'foo')
 
 const { headers } = await request('http://localhost:3000/foo')
 
 console.log('headers', headers) // headers { 'content-length': '3' }
 ```
 
-#### Example - Mocked request with automatic content-length calculation on an object
-
-```js
+```mjs displayName="Persisted reply"
 import { MockAgent, setGlobalDispatcher, request } from 'undici'
 
 const mockAgent = new MockAgent()
@@ -400,43 +443,13 @@ setGlobalDispatcher(mockAgent)
 
 const mockPool = mockAgent.get('http://localhost:3000')
 
-mockPool.intercept({
-  path: '/foo',
-  method: 'GET'
-}).replyContentLength().reply(200, { foo: 'bar' })
-
-const { headers } = await request('http://localhost:3000/foo')
-
-console.log('headers', headers) // headers { 'content-length': '13' }
-```
-
-#### Example - Mocked request with persist enabled
-
-```js
-import { MockAgent, setGlobalDispatcher, request } from 'undici'
-
-const mockAgent = new MockAgent()
-setGlobalDispatcher(mockAgent)
-
-const mockPool = mockAgent.get('http://localhost:3000')
-
-mockPool.intercept({
-  path: '/foo',
-  method: 'GET'
-}).reply(200, 'foo').persist()
-
-const result1 = await request('http://localhost:3000/foo')
-// Will match and return mocked data
-
-const result2 = await request('http://localhost:3000/foo')
-// Will match and return mocked data
+mockPool.intercept({ path: '/foo', method: 'GET' }).reply(200, 'foo').persist()
 
-// Etc
+await request('http://localhost:3000/foo') // Matches and returns the mock
+await request('http://localhost:3000/foo') // Matches again, indefinitely
 ```
 
-#### Example - Mocked request with times enabled
-
-```js
+```mjs displayName="Reply a fixed number of times"
 import { MockAgent, setGlobalDispatcher, request } from 'undici'
 
 const mockAgent = new MockAgent()
@@ -444,33 +457,23 @@ setGlobalDispatcher(mockAgent)
 
 const mockPool = mockAgent.get('http://localhost:3000')
 
-mockPool.intercept({
-  path: '/foo',
-  method: 'GET'
-}).reply(200, 'foo').times(2)
-
-const result1 = await request('http://localhost:3000/foo')
-// Will match and return mocked data
-
-const result2 = await request('http://localhost:3000/foo')
-// Will match and return mocked data
+mockPool.intercept({ path: '/foo', method: 'GET' }).reply(200, 'foo').times(2)
 
-const result3 = await request('http://localhost:3000/foo')
-// Will not match and make attempt a real request
+await request('http://localhost:3000/foo') // Matches and returns the mock
+await request('http://localhost:3000/foo') // Matches and returns the mock
+await request('http://localhost:3000/foo') // No match; a real request is attempted
 ```
 
-#### Example - Mocked request with path callback
-
-```js
+```mjs displayName="Match the path with a function"
 import { MockAgent, setGlobalDispatcher, request } from 'undici'
-import querystring from 'querystring'
+import querystring from 'node:querystring'
 
 const mockAgent = new MockAgent()
 setGlobalDispatcher(mockAgent)
 
 const mockPool = mockAgent.get('http://localhost:3000')
 
-const matchPath = requestPath => {
+const matchPath = (requestPath) => {
   const [pathname, search] = requestPath.split('?')
   const requestQuery = querystring.parse(search)
 
@@ -478,31 +481,26 @@ const matchPath = requestPath => {
     return false
   }
 
-  if (!Object.keys(requestQuery).includes('foo') || requestQuery.foo !== 'bar') {
-    return false
-  }
-
-  return true
+  return requestQuery.foo === 'bar'
 }
 
-mockPool.intercept({
-  path: matchPath,
-  method: 'GET'
-}).reply(200, 'foo')
+mockPool.intercept({ path: matchPath, method: 'GET' }).reply(200, 'foo')
 
-const result = await request('http://localhost:3000/foo?foo=bar')
-// Will match and return mocked data
+await request('http://localhost:3000/foo?foo=bar') // Matches and returns the mock
 ```
 
-### `MockPool.close()`
+### `mockPool.close()`
 
-Closes the mock pool and de-registers from associated MockAgent.
+<!-- YAML
+added: v4.0.0
+-->
 
-Returns: `Promise<void>`
+* Returns: {Promise} Fulfills with `undefined` once the mock pool is closed.
 
-#### Example - clean up after tests are complete
+Closes the mock pool, gracefully waiting for any enqueued requests to complete,
+and removes it from the associated [`MockAgent`][].
 
-```js
+```mjs
 import { MockAgent } from 'undici'
 
 const mockAgent = new MockAgent()
@@ -511,31 +509,45 @@ const mockPool = mockAgent.get('http://localhost:3000')
 await mockPool.close()
 ```
 
-### `MockPool.dispatch(options, handlers)`
+### `mockPool.dispatch(options, handlers)`
+
+<!-- YAML
+added: v4.0.0
+-->
+
+* `options` {DispatchOptions} The request options.
+* `handlers` {DispatchHandler} The handlers invoked over the request lifecycle.
+* Returns: {boolean} `false` if the dispatcher is busy and the caller should
+  wait before dispatching further requests, otherwise `true`.
+
+Dispatches a request, matching it against the registered mocks. This override of
+[`dispatcher.dispatch(options, handlers)`][] is what drives the mocking
+behaviour for every higher-level method such as `request`.
 
-Implements [`Dispatcher.dispatch(options, handlers)`](/docs/docs/api/Dispatcher.md#dispatcherdispatchoptions-handler).
+### `mockPool.request(options[, callback])`
 
-### `MockPool.request(options[, callback])`
+<!-- YAML
+added: v4.0.0
+-->
 
-See [`Dispatcher.request(options [, callback])`](/docs/docs/api/Dispatcher.md#dispatcherrequestoptions-callback).
+* `options` {DispatchOptions}
+* `callback` {Function} (optional) Invoked with the response when no `Promise`
+  is requested.
+* Returns: {Promise} Fulfills with the mocked response when no `callback` is
+  provided.
 
-#### Example - MockPool request
+Performs a request and resolves it against the registered mocks. Inherited from
+[`Pool`][]; see [`dispatcher.request(options[, callback])`][] for the full
+parameter and return value documentation.
 
-```js
+```mjs
 import { MockAgent } from 'undici'
 
 const mockAgent = new MockAgent()
-
 const mockPool = mockAgent.get('http://localhost:3000')
-mockPool.intercept({
-  path: '/foo',
-  method: 'GET',
-}).reply(200, 'foo')
+mockPool.intercept({ path: '/foo', method: 'GET' }).reply(200, 'foo')
 
-const {
-  statusCode,
-  body
-} = await mockPool.request({
+const { statusCode, body } = await mockPool.request({
   origin: 'http://localhost:3000',
   path: '/foo',
   method: 'GET'
@@ -548,8 +560,32 @@ for await (const data of body) {
 }
 ```
 
-### `MockPool.cleanMocks()`
+### `mockPool.cleanMocks()`
+
+<!-- YAML
+added: v7.11.0
+-->
+
+* Returns: {undefined}
+
+Removes all registered interceptors from the mock pool. Pending mocks defined
+before this call no longer match incoming requests.
 
-This method cleans up all the prepared mocks.
+```mjs
+import { MockAgent } from 'undici'
+
+const mockAgent = new MockAgent()
+const mockPool = mockAgent.get('http://localhost:3000')
+
+mockPool.intercept({ path: '/foo' }).reply(200, 'foo')
+mockPool.cleanMocks()
+```
 
-Returns: `void`
+[`MockAgent`]: MockAgent.md#class-mockagent
+[`MockClient`]: MockClient.md#class-mockclient
+[`MockInterceptor`]: MockPool.md#return-mockinterceptor
+[`MockScope`]: MockPool.md#return-mockscope
+[`Pool`]: Pool.md#class-pool
+[`dispatcher.dispatch(options, handlers)`]: Dispatcher.md#dispatcherdispatchoptions-handler
+[`dispatcher.request(options[, callback])`]: Dispatcher.md#dispatcherrequestoptions-callback
+[`mockAgent.get(origin)`]: MockAgent.md#mockagentgetorigin
diff --git a/docs/docs/api/Pool.md b/docs/docs/api/Pool.md
index 1d1f7e140ef..dc0bd2d0f68 100644
--- a/docs/docs/api/Pool.md
+++ b/docs/docs/api/Pool.md
@@ -1,87 +1,279 @@
-# Class: Pool
+# Pool
+
+<!--introduced_in=v1.0.0-->
+
+<!--type=module-->
+
+<!-- source_link=lib/dispatcher/pool.js -->
+
+> Stability: 2 - Stable
+
+A pool of [`Client`][] instances connected to the same upstream origin. A `Pool`
+spreads requests across several connections to the same host, which allows more
+than one request to be in flight at a time without enabling pipelining on a
+single connection.
+
+`Pool` extends [`Dispatcher`][]. Each [`Client`][] in the pool is created lazily
+through a configurable `factory` and shares the same options. Requests are not
+guaranteed to be dispatched in the order in which they are invoked.
+
+```mjs
+import { Pool } from 'undici'
+
+const pool = new Pool('http://localhost:3000', { connections: 10 })
+const { statusCode, body } = await pool.request({ path: '/', method: 'GET' })
+console.log(statusCode, await body.text())
+await pool.close()
+```
+
+## Class: `Pool`
+
+<!-- YAML
+added: v1.0.0
+changes:
+  - version: v4.10.4
+    pr-url: https://github.com/nodejs/undici/pull/1114
+    description: Reworked as part of the balanced pool implementation.
+-->
+
+* Extends: {Dispatcher}
+
+### `new Pool(url[, options])`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* `url` {URL|string} The upstream origin. It should only include the protocol,
+  hostname, and port.
+* `options` {PoolOptions} (optional) Extends {ClientOptions}, so every
+  [`Client`][] option is also accepted and forwarded to each pooled client.
+  * `factory` {Function} Creates the [`Client`][] (or other [`Dispatcher`][])
+    instances used by the pool.
+    **Default:** `(origin, opts) => new Client(origin, opts)`.
+    * `origin` {URL} The parsed upstream origin.
+    * `opts` {Object} The resolved client options.
+    * Returns: {Dispatcher}
+  * `connections` {number|null} The maximum number of [`Client`][] instances the
+    pool may create. When set to `null` the pool creates an unlimited number of
+    clients. **Default:** `null`.
+  * `clientTtl` {number|null} The amount of time, in milliseconds, before an idle
+    [`Client`][] is removed from the pool and closed. When set to `null` clients
+    are never removed based on age. **Default:** `null`.
+
+Creates a new `Pool` against `url`. If `connections` is provided it must be a
+finite, non-negative number, otherwise an [`InvalidArgumentError`][] is thrown.
+The `factory` must be a function, and `connect` (inherited from {ClientOptions})
+must be a function or an object when provided.
+
+The connection-related {ClientOptions} (`connect`, `connectTimeout`, `tls`,
+`maxCachedSessions`, `socketPath`, `autoSelectFamily`,
+`autoSelectFamilyAttemptTimeout`, `allowH2`, and `useH2c`) are used to build the
+connector shared by every pooled client.
 
-Extends: `undici.Dispatcher`
+> [!NOTE]
+> `Pool` inherits all {ClientOptions}, including `allowH2` and
+> `maxConcurrentStreams`. With the default unlimited `connections`, the pool
+> opens a new client - and therefore a new TCP/TLS socket - per concurrent
+> dispatch, which defeats HTTP/2 multiplexing over a shared session. To benefit
+> from h2 multiplexing on a single session, cap `connections` (for example
+> `connections: 1`) so that concurrent requests share a session up to
+> `maxConcurrentStreams`.
 
-A pool of [Client](/docs/docs/api/Client.md) instances connected to the same upstream target.
+```mjs
+import { Pool } from 'undici'
 
-Requests are not guaranteed to be dispatched in order of invocation.
+const pool = new Pool('http://localhost:3000', {
+  connections: 128,
+  pipelining: 1
+})
+```
 
-## `new Pool(url[, options])`
+### `pool.closed`
 
-Arguments:
+<!-- YAML
+added: v1.0.0
+-->
 
-* **url** `URL | string` - It should only include the **protocol, hostname, and port**.
-* **options** `PoolOptions` (optional)
+* Type: {boolean}
 
-### Parameter: `PoolOptions`
+`true` after [`pool.close()`][] has been called.
 
-Extends: [`ClientOptions`](/docs/docs/api/Client.md#parameter-clientoptions)
+### `pool.destroyed`
 
-* **factory** `(origin: URL, opts: Object) => Dispatcher` - Default: `(origin, opts) => new Client(origin, opts)`
-* **connections** `number | null` (optional) - Default: `null` - The number of `Client` instances to create. When set to `null`, the `Pool` instance will create an unlimited amount of `Client` instances.
-* **clientTtl** `number | null` (optional) - Default: `null` - The amount of time before a `Client` instance is removed from the `Pool` and closed.   When set to `null`, `Client` instances will not be removed or closed based on age.
+<!-- YAML
+added: v1.0.0
+changes:
+  - version: v2.0.0
+    pr-url: https://github.com/nodejs/undici/pull/384
+    description: Reflects the state set by `pool.close()`.
+  - version: v4.10.4
+    pr-url: https://github.com/nodejs/undici/pull/1114
+    description: Reworked as part of the balanced pool implementation.
+-->
 
-> [!NOTE]
-> `Pool` inherits all [`ClientOptions`](/docs/docs/api/Client.md#parameter-clientoptions), including `allowH2` (default `true`) and `maxConcurrentStreams` (default `100`). With the unlimited default of `connections`, `Pool` will open a new `Client` — and therefore a new TCP/TLS socket — per concurrent dispatch, which defeats HTTP/2 multiplexing on a shared session. To benefit from h2 multiplexing on a single session, cap `connections` (e.g. `connections: 1`) so that concurrent requests share a session up to `maxConcurrentStreams`.
+* Type: {boolean}
+
+`true` after [`pool.destroy()`][] has been called, or after [`pool.close()`][]
+has been called and the pool shutdown has completed.
+
+### `pool.stats`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* Type: {PoolStats}
 
-## Instance Properties
+Aggregate statistics for the pool. See [`PoolStats`][].
 
-### `Pool.closed`
+### `pool.close([callback])`
 
-Implements [Client.closed](/docs/docs/api/Client.md#clientclosed)
+<!-- YAML
+added: v1.0.0
+-->
 
-### `Pool.destroyed`
+Implements [`dispatcher.close([callback])`][]. Gracefully closes the pool and
+all of its clients, waiting for in-flight requests to complete. Resolves once
+every pooled client has closed.
 
-Implements [Client.destroyed](/docs/docs/api/Client.md#clientdestroyed)
+### `pool.destroy([error[, callback]])`
 
-### `Pool.stats`
+<!-- YAML
+added: v1.0.0
+-->
 
-Returns [`PoolStats`](/docs/docs/api/PoolStats.md) instance for this pool.
+Implements [`dispatcher.destroy([error[, callback]])`][]. Forcefully destroys
+the pool and all of its clients, aborting any in-flight requests with `error`.
 
-## Instance Methods
+### `pool.connect(options[, callback])`
 
-### `Pool.close([callback])`
+<!-- YAML
+added: v1.0.0
+-->
 
-Implements [`Dispatcher.close([callback])`](/docs/docs/api/Dispatcher.md#dispatcherclosecallback-promise).
+See [`dispatcher.connect(options[, callback])`][]. Performs an HTTP `CONNECT`
+request through one of the pooled clients.
 
-### `Pool.destroy([error, callback])`
+### `pool.dispatch(options, handler)`
 
-Implements [`Dispatcher.destroy([error, callback])`](/docs/docs/api/Dispatcher.md#dispatcherdestroyerror-callback-promise).
+<!-- YAML
+added: v1.3.0
+changes:
+  - version: v4.10.4
+    pr-url: https://github.com/nodejs/undici/pull/1114
+    description: Reworked as part of the balanced pool implementation.
+-->
 
-### `Pool.connect(options[, callback])`
+Implements [`dispatcher.dispatch(options, handler)`][]. Selects an available
+client - creating a new one through `factory` when none is free and the
+`connections` limit has not been reached - and dispatches the request to it.
 
-See [`Dispatcher.connect(options[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherconnectoptions-callback).
+### `pool.pipeline(options, handler)`
 
-### `Pool.dispatch(options, handler)`
+<!-- YAML
+added: v1.0.0
+-->
 
-Implements [`Dispatcher.dispatch(options, handler)`](/docs/docs/api/Dispatcher.md#dispatcherdispatchoptions-handler).
+See [`dispatcher.pipeline(options, handler)`][]. Sends a request and returns a
+{Duplex} stream that pipes the request body to the response body through
+`handler`.
 
-### `Pool.pipeline(options, handler)`
+### `pool.request(options[, callback])`
 
-See [`Dispatcher.pipeline(options, handler)`](/docs/docs/api/Dispatcher.md#dispatcherpipelineoptions-handler).
+<!-- YAML
+added: v1.0.0
+-->
 
-### `Pool.request(options[, callback])`
+See [`dispatcher.request(options[, callback])`][]. Performs a request through one
+of the pooled clients.
 
-See [`Dispatcher.request(options [, callback])`](/docs/docs/api/Dispatcher.md#dispatcherrequestoptions-callback).
+```mjs
+import { Pool } from 'undici'
 
-### `Pool.stream(options, factory[, callback])`
+const pool = new Pool('http://localhost:3000', { connections: 10 })
+const { statusCode, headers, body } = await pool.request({
+  path: '/',
+  method: 'GET'
+})
+console.log(statusCode, headers)
+console.log(await body.text())
+await pool.close()
+```
 
-See [`Dispatcher.stream(options, factory[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherstreamoptions-factory-callback).
+### `pool.stream(options, factory[, callback])`
 
-### `Pool.upgrade(options[, callback])`
+<!-- YAML
+added: v1.0.0
+-->
 
-See [`Dispatcher.upgrade(options[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherupgradeoptions-callback).
+See [`dispatcher.stream(options, factory[, callback])`][]. Performs a request and
+writes the response body into the {Writable} stream returned by `factory`.
 
-## Instance Events
+### `pool.upgrade(options[, callback])`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+See [`dispatcher.upgrade(options[, callback])`][]. Upgrades a connection
+(for example to a WebSocket) through one of the pooled clients.
 
 ### Event: `'connect'`
 
-See [Dispatcher Event: `'connect'`](/docs/docs/api/Dispatcher.md#event-connect).
+<!-- YAML
+added: v1.0.0
+-->
+
+* `origin` {URL}
+* `targets` {Array} The pool followed by the client that connected,
+  `[pool, ...targets]`.
+
+Emitted by a pooled client when a socket has connected. See
+[`Dispatcher` Event: `'connect'`][]. When `clientTtl` is set, the connecting
+client's time-to-live timer starts on this event.
 
 ### Event: `'disconnect'`
 
-See [Dispatcher Event: `'disconnect'`](/docs/docs/api/Dispatcher.md#event-disconnect).
+<!-- YAML
+added: v1.0.0
+-->
+
+* `origin` {URL}
+* `targets` {Array} The pool followed by the client that disconnected,
+  `[pool, ...targets]`.
+* `error` {Error}
+
+Emitted by a pooled client when a socket has disconnected. See
+[`Dispatcher` Event: `'disconnect'`][].
 
 ### Event: `'drain'`
 
-See [Dispatcher Event: `'drain'`](/docs/docs/api/Dispatcher.md#event-drain).
+<!-- YAML
+added: v1.0.0
+-->
+
+* `origin` {URL}
+* `targets` {Array} The pool followed by the client that drained,
+  `[pool, ...targets]`.
+
+Emitted when a pooled client is no longer busy and can accept more requests. See
+[`Dispatcher` Event: `'drain'`][].
+
+[`Client`]: Client.md#class-client
+[`Dispatcher` Event: `'connect'`]: Dispatcher.md#event-connect
+[`Dispatcher` Event: `'disconnect'`]: Dispatcher.md#event-disconnect
+[`Dispatcher` Event: `'drain'`]: Dispatcher.md#event-drain
+[`Dispatcher`]: Dispatcher.md#class-dispatcher
+[`InvalidArgumentError`]: Errors.md#class-invalidargumenterror
+[`PoolStats`]: PoolStats.md
+[`dispatcher.close([callback])`]: Dispatcher.md#dispatcherclosecallback
+[`dispatcher.connect(options[, callback])`]: Dispatcher.md#dispatcherconnectoptions-callback
+[`dispatcher.destroy([error[, callback]])`]: Dispatcher.md#dispatcherdestroyerror-callback
+[`dispatcher.dispatch(options, handler)`]: Dispatcher.md#dispatcherdispatchoptions-handler
+[`dispatcher.pipeline(options, handler)`]: Dispatcher.md#dispatcherpipelineoptions-handler
+[`dispatcher.request(options[, callback])`]: Dispatcher.md#dispatcherrequestoptions-callback
+[`dispatcher.stream(options, factory[, callback])`]: Dispatcher.md#dispatcherstreamoptions-factory-callback
+[`dispatcher.upgrade(options[, callback])`]: Dispatcher.md#dispatcherupgradeoptions-callback
+[`pool.close()`]: #poolclosecallback
+[`pool.destroy()`]: #pooldestroyerror-callback
diff --git a/docs/docs/api/PoolStats.md b/docs/docs/api/PoolStats.md
index 3cbe0d82e17..758068d12ce 100644
--- a/docs/docs/api/PoolStats.md
+++ b/docs/docs/api/PoolStats.md
@@ -1,35 +1,141 @@
-# Class: PoolStats
+# PoolStats
 
-Aggregate stats for a [Pool](/docs/docs/api/Pool.md) or [BalancedPool](/docs/docs/api/BalancedPool.md).
+<!--introduced_in=v4.15.0-->
+<!--type=module-->
+<!-- source_link=lib/util/stats.js -->
 
-## `new PoolStats(pool)`
+> Stability: 2 - Stable
 
-Arguments:
+`PoolStats` exposes a read-only snapshot of the aggregate connection and request
+counters for a [`Pool`][] or [`BalancedPool`][]. An instance is created lazily
+each time the `pool.stats` getter is accessed, so the values reflect the state of
+the pool at the moment of access.
 
-* **pool** `Pool` - Pool or BalancedPool from which to return stats.
+`PoolStats` is not constructed directly in normal use; obtain an instance from
+the `stats` property of a pool:
 
-## Instance Properties
+```mjs
+import { Pool } from 'undici'
 
-### `PoolStats.connected`
+const pool = new Pool('http://localhost:3000')
+const { stats } = pool
+
+console.log(stats.connected, stats.running, stats.size)
+```
+
+## Class: `PoolStats`
+
+<!-- YAML
+added: v4.15.0
+changes:
+  - version: v7.9.0
+    pr-url: https://github.com/nodejs/undici/pull/4157
+    description: Pool and client stats are exposed through `Agent`.
+-->
+
+Each property is a plain number computed from the pool's internal state when the
+instance is created. The instance is a snapshot; read `pool.stats` again to
+observe later changes.
+
+### `new PoolStats(pool)`
+
+<!-- YAML
+added: v4.15.0
+changes:
+  - version: v7.9.0
+    pr-url: https://github.com/nodejs/undici/pull/4157
+    description: Pool and client stats are exposed through `Agent`.
+-->
+
+* `pool` {Pool|BalancedPool} The pool to read counters from.
+
+Creates a new `PoolStats` instance from the current state of `pool`. Prefer the
+`pool.stats` getter, which returns a fresh `PoolStats` on each access.
+
+### `poolStats.connected`
+
+<!-- YAML
+added: v4.15.0
+changes:
+  - version: v7.9.0
+    pr-url: https://github.com/nodejs/undici/pull/4157
+    description: Pool and client stats are exposed through `Agent`.
+-->
+
+* Type: {number}
 
 Number of open socket connections in this pool.
 
-### `PoolStats.free`
+### `poolStats.free`
 
-Number of open socket connections in this pool that do not have an active request.
+<!-- YAML
+added: v4.15.0
+changes:
+  - version: v7.9.0
+    pr-url: https://github.com/nodejs/undici/pull/4157
+    description: Pool and client stats are exposed through `Agent`.
+-->
 
-### `PoolStats.pending`
+* Type: {number}
+
+Number of open socket connections in this pool that do not have an active
+request.
+
+### `poolStats.pending`
+
+<!-- YAML
+added: v4.15.0
+changes:
+  - version: v7.9.0
+    pr-url: https://github.com/nodejs/undici/pull/4157
+    description: Pool and client stats are exposed through `Agent`.
+-->
+
+* Type: {number}
 
 Number of pending requests across all clients in this pool.
 
-### `PoolStats.queued`
+### `poolStats.queued`
+
+<!-- YAML
+added: v4.15.0
+changes:
+  - version: v7.9.0
+    pr-url: https://github.com/nodejs/undici/pull/4157
+    description: Pool and client stats are exposed through `Agent`.
+-->
+
+* Type: {number}
 
 Number of queued requests across all clients in this pool.
 
-### `PoolStats.running`
+### `poolStats.running`
+
+<!-- YAML
+added: v4.15.0
+changes:
+  - version: v7.9.0
+    pr-url: https://github.com/nodejs/undici/pull/4157
+    description: Pool and client stats are exposed through `Agent`.
+-->
+
+* Type: {number}
 
 Number of currently active requests across all clients in this pool.
 
-### `PoolStats.size`
+### `poolStats.size`
+
+<!-- YAML
+added: v4.15.0
+changes:
+  - version: v7.9.0
+    pr-url: https://github.com/nodejs/undici/pull/4157
+    description: Pool and client stats are exposed through `Agent`.
+-->
+
+* Type: {number}
 
 Number of active, pending, or queued requests across all clients in this pool.
+
+[`BalancedPool`]: BalancedPool.md#class-balancedpool
+[`Pool`]: Pool.md#class-pool
diff --git a/docs/docs/api/ProxyAgent.md b/docs/docs/api/ProxyAgent.md
index 8db7221a362..1b454085353 100644
--- a/docs/docs/api/ProxyAgent.md
+++ b/docs/docs/api/ProxyAgent.md
@@ -1,229 +1,241 @@
-# Class: ProxyAgent
+# ProxyAgent
 
-Extends: `undici.Dispatcher`
+<!--introduced_in=v4.8.2-->
+<!--type=module-->
+<!-- source_link=lib/dispatcher/proxy-agent.js -->
 
-A Proxy Agent class that implements the Agent API. It allows the connection through proxy in a simple way.
+> Stability: 2 - Stable
 
-## `new ProxyAgent([options])`
+A `ProxyAgent` routes every request through an HTTP, HTTPS, or SOCKS5 proxy
+server. It implements the [`Agent`][] API, so it can be used wherever a
+dispatcher is accepted, for example with [`request`][] or [`fetch`][], or
+installed globally with [`setGlobalDispatcher`][].
 
-Arguments:
+For secure (`https:`) endpoints the proxy connection is established through an
+HTTP `CONNECT` tunnel. SOCKS5 proxies (`socks5:` or `socks:` URIs) are handled
+by delegating to a [`Socks5ProxyAgent`][].
 
-* **options** `ProxyAgentOptions` (required) - It extends the `Agent` options.
-
-Returns: `ProxyAgent`
-
-### Parameter: `ProxyAgentOptions`
+```mjs
+import { ProxyAgent, setGlobalDispatcher } from 'undici'
 
-Extends: [`AgentOptions`](/docs/docs/api/Agent.md#parameter-agentoptions)
-> It ommits `AgentOptions#connect`.
+const proxyAgent = new ProxyAgent('http://localhost:8000')
+setGlobalDispatcher(proxyAgent)
+```
 
-> **Note:** When `AgentOptions#connections` is set, and different from `0`, the non-standard [`proxy-connection` header](https://udger.com/resources/http-request-headers-detail?header=Proxy-Connection) will be set to `keep-alive` in the request.
+## Class: `ProxyAgent`
+
+<!-- YAML
+added: v4.8.2
+-->
+
+* Extends: {Dispatcher}
+
+`ProxyAgent` keeps an internal [`Agent`][] that creates per-origin dispatchers
+on demand. The proxy connection is set up lazily when the first request to an
+origin is dispatched, then reused for subsequent requests to the same origin.
+
+### `new ProxyAgent(options)`
+
+<!-- YAML
+added: v4.8.2
+-->
+
+* `options` {ProxyAgentOptions|string|URL} The proxy URI, or an options object.
+  Required. When a `string` or {URL} is passed it is used as the proxy `uri`.
+  The options object extends {AgentOptions} (omitting `connect`).
+  * `uri` {string} The URI of the proxy server. Required when `options` is an
+    object. Parsed into a {URL} according to the
+    [WHATWG URL Specification][].
+  * `token` {string} A pre-formatted `proxy-authorization` header value sent to
+    the proxy on every request, for example `` `Bearer ${apiKey}` ``.
+  * `auth` {string} A base64-encoded `username:password` credential sent as a
+    `Basic` `proxy-authorization` header. Cannot be combined with `token`.
+  * `headers` {Object} Additional headers sent to the proxy server on the
+    `CONNECT` request (or on every request for an untunneled HTTP proxy).
+    **Default:** `{}`.
+  * `requestTls` {BuildOptions} TLS options for the connection to the request
+    endpoint, passed to the connector builder.
+  * `proxyTls` {BuildOptions} TLS options for the connection to the proxy
+    server, passed to the connector builder.
+  * `clientFactory` {Function} Builds the {Dispatcher} used to talk to the proxy
+    server itself. **Default:** `(origin, opts) => new Pool(origin, opts)`.
+    * `origin` {URL} The proxy origin.
+    * `opts` {Object} The resolved options for the dispatcher.
+    * Returns: {Dispatcher}
+  * `proxyTunnel` {boolean} Forces tunneling through the proxy. When `false`,
+    requests where both the proxy and the endpoint use the insecure `http:`
+    protocol are sent directly to the proxy with the absolute request URI rather
+    than through a `CONNECT` tunnel, matching `curl` behavior. Secure
+    connections always use a tunnel regardless of this option. **Default:**
+    `true`.
+
+Throws an {InvalidArgumentError} when no proxy URI is provided, when
+`clientFactory` is not a function, or when both `auth` and `token` are supplied.
+
+The `proxy-authorization` header is derived, in order of precedence, from
+`token`, then `auth`, then the `username` and `password` embedded in the proxy
+`uri`. Credentials in the URI are URL-decoded before being base64-encoded.
+
+> [!NOTE]
+> Unless {AgentOptions} `connections` is set to `0`, the non-standard
+> `proxy-connection: keep-alive` header is added to the tunnel `CONNECT`
+> request. This includes the default case where `connections` is unset.
+
+The `auth` option is deprecated; use `token` instead.
+
+```mjs
+import { ProxyAgent } from 'undici'
 
-* **uri** `string | URL` (required) - The URI of the proxy server.  This can be provided as a string, as an instance of the URL class, or as an object with a `uri` property of type string.
-If the `uri` is provided as a string or `uri` is an object with an `uri` property of type string, then it will be parsed into a `URL` object according to the [WHATWG URL Specification](https://url.spec.whatwg.org).
-For detailed information on the parsing process and potential validation errors, please refer to the ["Writing" section](https://url.spec.whatwg.org/#writing) of the WHATWG URL Specification.
-* **token** `string` (optional) - It can be passed by a string of token for authentication.
-* **auth** `string` (**deprecated**) - Use token.
-* **clientFactory** `(origin: URL, opts: Object) => Dispatcher` (optional) - Default: `(origin, opts) => new Pool(origin, opts)`
-* **requestTls** `BuildOptions` (optional) - Options object passed when creating the underlying socket via the connector builder for the request. It extends from [`Client#ConnectOptions`](/docs/docs/api/Client.md#parameter-connectoptions).
-* **proxyTls** `BuildOptions` (optional) - Options object passed when creating the underlying socket via the connector builder for the proxy server. It extends from [`Client#ConnectOptions`](/docs/docs/api/Client.md#parameter-connectoptions).
-* **proxyTunnel** `boolean` (optional) - For connections involving secure protocols, Undici will always establish a tunnel via the HTTP2  CONNECT extension. If proxyTunnel is set to true, this will occur for unsecured proxy/endpoint connections as well. Currently, there is no way to facilitate HTTP1 IP tunneling as described in https://www.rfc-editor.org/rfc/rfc9484.html#name-http-11-request. If proxyTunnel is set to false (the default), ProxyAgent connections where both the Proxy and Endpoint are unsecured will issue all requests to the Proxy, and prefix the endpoint request path with the endpoint origin address.
+// A string or URL is treated as the proxy uri.
+const a = new ProxyAgent('http://localhost:8000')
+const b = new ProxyAgent(new URL('http://localhost:8000'))
 
-Examples:
+// An options object requires a `uri`.
+const c = new ProxyAgent({ uri: 'http://localhost:8000' })
 
-```js
-import { ProxyAgent } from 'undici'
-
-const proxyAgent = new ProxyAgent('my.proxy.server')
-// or
-const proxyAgent = new ProxyAgent(new URL('my.proxy.server'))
-// or
-const proxyAgent = new ProxyAgent({ uri: 'my.proxy.server' })
-// or
-const proxyAgent = new ProxyAgent({
-  uri: new URL('my.proxy.server'),
+// With proxy TLS settings.
+const d = new ProxyAgent({
+  uri: 'https://secure.proxy.server',
   proxyTls: {
-    signal: AbortSignal.timeout(1000)
-  }
+    signal: AbortSignal.timeout(1000),
+  },
 })
 ```
 
-#### Example - Basic ProxyAgent instantiation
-
-This will instantiate the ProxyAgent. It will not do anything until registered as the agent to use with requests.
+#### Example - proxy request with the global dispatcher
 
-```js
-import { ProxyAgent } from 'undici'
-
-const proxyAgent = new ProxyAgent('my.proxy.server')
-```
-
-#### Example - Basic Proxy Request with global agent dispatcher
-
-```js
+```mjs
 import { setGlobalDispatcher, request, ProxyAgent } from 'undici'
 
-const proxyAgent = new ProxyAgent('my.proxy.server')
+const proxyAgent = new ProxyAgent('http://localhost:8000')
 setGlobalDispatcher(proxyAgent)
 
 const { statusCode, body } = await request('http://localhost:3000/foo')
 
-console.log('response received', statusCode) // response received 200
-
-for await (const data of body) {
-  console.log('data', data.toString('utf8')) // data foo
-}
+console.log('response received', statusCode)
+console.log('data', await body.text())
 ```
 
-#### Example - Basic Proxy Request with local agent dispatcher
+#### Example - proxy request with a local dispatcher
 
-```js
+```mjs
 import { ProxyAgent, request } from 'undici'
 
-const proxyAgent = new ProxyAgent('my.proxy.server')
+const proxyAgent = new ProxyAgent('http://localhost:8000')
 
-const {
-  statusCode,
-  body
-} = await request('http://localhost:3000/foo', { dispatcher: proxyAgent })
-
-console.log('response received', statusCode) // response received 200
+const { statusCode, body } = await request('http://localhost:3000/foo', {
+  dispatcher: proxyAgent,
+})
 
-for await (const data of body) {
-  console.log('data', data.toString('utf8')) // data foo
-}
+console.log('response received', statusCode)
+console.log('data', await body.text())
 ```
 
-#### Example - Basic Proxy Request with authentication
+#### Example - proxy request with authentication
 
-```js
-import { setGlobalDispatcher, request, ProxyAgent } from 'undici';
+```mjs
+import { setGlobalDispatcher, request, ProxyAgent } from 'undici'
 
 const proxyAgent = new ProxyAgent({
-  uri: 'my.proxy.server',
-  // token: 'Bearer xxxx'
-  token: `Basic ${Buffer.from('username:password').toString('base64')}`
-});
-setGlobalDispatcher(proxyAgent);
-
-const { statusCode, body } = await request('http://localhost:3000/foo');
-
-console.log('response received', statusCode); // response received 200
-
-for await (const data of body) {
-  console.log('data', data.toString('utf8')); // data foo
-}
-```
-
-### `ProxyAgent.close()`
-
-Closes the proxy agent and waits for registered pools and clients to also close before resolving.
-
-Returns: `Promise<void>`
-
-#### Example - clean up after tests are complete
-
-```js
-import { ProxyAgent, setGlobalDispatcher } from 'undici'
-
-const proxyAgent = new ProxyAgent('my.proxy.server')
+  uri: 'http://localhost:8000',
+  token: `Basic ${Buffer.from('username:password').toString('base64')}`,
+})
 setGlobalDispatcher(proxyAgent)
 
-await proxyAgent.close()
+const { statusCode } = await request('http://localhost:3000/foo')
+
+console.log('response received', statusCode)
 ```
 
-### `ProxyAgent.dispatch(options, handlers)`
+### `proxyAgent.dispatch(options, handler)`
 
-Implements [`Agent.dispatch(options, handlers)`](/docs/docs/api/Agent.md#parameter-agentdispatchoptions).
+<!-- YAML
+added: v4.8.2
+-->
 
-### `ProxyAgent.request(options[, callback])`
+* `options` {AgentDispatchOptions} Extends {DispatchOptions}.
+  * `origin` {string|URL} The origin to dispatch the request against. Required.
+* `handler` {DispatchHandler}
+* Returns: {boolean} `false` if the dispatcher is busy and the caller should
+  wait for the [`'drain'`][] event before dispatching again.
 
-See [`Dispatcher.request(options [, callback])`](/docs/docs/api/Dispatcher.md#dispatcherrequestoptions-callback).
+Dispatches the request through the proxy. Throws an {InvalidArgumentError} if
+the request headers contain a `proxy-authorization` header, which must instead
+be supplied through the constructor's `token` or `auth` option. A `host` header
+is derived from `options.origin` when one is not already present. Implements
+[`Dispatcher.dispatch()`][].
 
+### `proxyAgent.close()`
 
-#### Example - ProxyAgent with Fetch
+<!-- YAML
+added: v4.8.2
+changes:
+  - version: v7.10.0
+    pr-url: https://github.com/nodejs/undici/pull/4180
+    description: Untunneled HTTP-to-HTTP proxy connections match `curl` behavior.
+-->
 
-This example demonstrates how to use `fetch` with a proxy via `ProxyAgent`. It is particularly useful for scenarios requiring proxy tunneling.
+* Returns: {Promise<void>}
 
-```javascript
-import { ProxyAgent, fetch } from 'undici';
+Closes the proxy agent and waits for its internal agent and proxy client (when
+present) to close before resolving. Implements [`Dispatcher.close()`][].
 
-// Define the ProxyAgent
-const proxyAgent = new ProxyAgent('http://localhost:8000');
+```mjs
+import { ProxyAgent, setGlobalDispatcher } from 'undici'
 
-// Make a GET request through the proxy
-const response = await fetch('http://localhost:3000/foo', {
-  dispatcher: proxyAgent,
-  method: 'GET',
-});
+const proxyAgent = new ProxyAgent('http://localhost:8000')
+setGlobalDispatcher(proxyAgent)
 
-console.log('Response status:', response.status);
-console.log('Response data:', await response.text());
+await proxyAgent.close()
 ```
 
----
+### `proxyAgent.request(options[, callback])`
 
-#### Example - ProxyAgent with a Custom Proxy Server
+<!-- YAML
+added: v5.0.0
+-->
 
-This example shows how to create a custom proxy server and use it with `ProxyAgent`.
+See [`Dispatcher.request()`][]. The request is routed through the proxy.
 
-```javascript
-import * as http from 'node:http';
-import { createProxy } from 'proxy';
-import { ProxyAgent, fetch } from 'undici';
+#### Example - proxy request with `fetch`
 
-// Create a proxy server
-const proxyServer = createProxy(http.createServer());
-proxyServer.listen(8000, () => {
-  console.log('Proxy server running on port 8000');
-});
+```mjs
+import { ProxyAgent, fetch } from 'undici'
 
-// Define and use the ProxyAgent
-const proxyAgent = new ProxyAgent('http://localhost:8000');
+const proxyAgent = new ProxyAgent('http://localhost:8000')
 
-const response = await fetch('http://example.com', {
+const response = await fetch('http://localhost:3000/foo', {
   dispatcher: proxyAgent,
   method: 'GET',
-});
+})
 
-console.log('Response status:', response.status);
-console.log('Response data:', await response.text());
+console.log('response status', response.status)
+console.log('response data', await response.text())
 ```
 
----
-
-#### Example - ProxyAgent with HTTPS Tunneling
+#### Example - HTTPS tunneling
 
-This example demonstrates how to perform HTTPS tunneling using a proxy.
+```mjs
+import { ProxyAgent, fetch } from 'undici'
 
-```javascript
-import { ProxyAgent, fetch } from 'undici';
+const proxyAgent = new ProxyAgent('https://secure.proxy.server')
 
-// Define a ProxyAgent for HTTPS proxy
-const proxyAgent = new ProxyAgent('https://secure.proxy.server');
-
-// Make a request to an HTTPS endpoint via the proxy
 const response = await fetch('https://secure.endpoint.com/api/data', {
   dispatcher: proxyAgent,
   method: 'GET',
-});
+})
 
-console.log('Response status:', response.status);
-console.log('Response data:', await response.json());
+console.log('response status', response.status)
+console.log('response data', await response.json())
 ```
 
-#### Example - ProxyAgent as a Global Dispatcher
-
-`ProxyAgent` can be configured as a global dispatcher, making it available for all requests without explicitly passing it. This simplifies code and is useful when a single proxy configuration applies to all requests.
-
-```javascript
-import { ProxyAgent, setGlobalDispatcher, fetch } from 'undici';
-
-// Define and configure the ProxyAgent
-const proxyAgent = new ProxyAgent('http://localhost:8000');
-setGlobalDispatcher(proxyAgent);
-
-// Make requests without specifying the dispatcher
-const response = await fetch('http://example.com');
-console.log('Response status:', response.status);
-console.log('Response data:', await response.text());
+[WHATWG URL Specification]: https://url.spec.whatwg.org
+[`'drain'`]: Dispatcher.md#event-drain
+[`Agent`]: Agent.md#class-agent
+[`Dispatcher.close()`]: Dispatcher.md#dispatcherclosecallback-promise
+[`Dispatcher.dispatch()`]: Dispatcher.md#dispatcherdispatchoptions-handler
+[`Dispatcher.request()`]: Dispatcher.md#dispatcherrequestoptions-callback
+[`Socks5ProxyAgent`]: Socks5ProxyAgent.md#class-socks5proxyagent
+[`fetch`]: Fetch.md
+[`request`]: Dispatcher.md#dispatcherrequestoptions-callback
+[`setGlobalDispatcher`]: Dispatcher.md#setglobaldispatcherdispatcher
diff --git a/docs/docs/api/RedirectHandler.md b/docs/docs/api/RedirectHandler.md
index 5d49653be0d..cedb0291d8a 100644
--- a/docs/docs/api/RedirectHandler.md
+++ b/docs/docs/api/RedirectHandler.md
@@ -1,101 +1,276 @@
-# Class: RedirectHandler
+# RedirectHandler
+
+<!--introduced_in=v4.0.0-->
+<!--type=module-->
+<!-- source_link=lib/handler/redirect-handler.js -->
+
+> Stability: 2 - Stable
+
+A dispatch handler that follows HTTP redirects on behalf of another handler. It
+wraps a downstream `handler` and a `dispatch` function: when a redirectable
+response is received it transparently re-dispatches the request to the new
+location, forwarding the lifecycle callbacks to the wrapped `handler` only once a
+final (non-redirect) response is reached.
+
+Redirects are followed for the `300`, `301`, `302`, `303`, `307`, and `308`
+status codes, up to `maxRedirections` hops. Following the relevant HTTP
+specifications, the method is downgraded to `GET` for `301`/`302` `POST`
+responses and for `303` responses with any method other than `HEAD`, request
+bodies that have already been consumed are not replayed, and headers that refer
+to the original URL (such as `host`) are stripped on each hop, with additional
+credential headers removed on cross-origin redirects.
+
+```mjs
+import { RedirectHandler } from 'undici'
+```
+
+```cjs
+const { RedirectHandler } = require('undici')
+```
+
+Most users do not construct `RedirectHandler` directly. The `maxRedirections`
+option on [`Dispatcher`][] methods and the higher-level clients use it
+internally.
+
+## Class: `RedirectHandler`
+
+<!-- YAML
+added: v4.0.0
+-->
+
+* Extends: {DispatchHandler}
+
+Implements the [`DispatchHandler`][] interface, delegating every callback to the
+wrapped `handler` while intercepting redirect responses.
+
+### `new RedirectHandler(dispatch, maxRedirections, opts, handler)`
+
+<!-- YAML
+added: v4.0.0
+-->
+
+* `dispatch` {Function} The dispatch function used to issue the original request
+  and every subsequent redirect. Called as `dispatch(options, handler)`.
+* `maxRedirections` {number|null} The maximum number of redirects to follow. Must
+  be a non-negative integer or `null`. When `null` or `0`, no redirects are
+  followed and redirect responses are passed through to the wrapped `handler`.
+* `opts` {DispatchOptions} The dispatch options for the request. In addition to
+  the standard dispatch options, the following redirect-specific fields are
+  recognized:
+  * `throwOnMaxRedirect` {boolean} When `true`, an error is thrown once
+    `maxRedirections` is reached instead of returning the last redirect response.
+    **Default:** `false`.
+  * `stripHeadersOnRedirect` {string[]} Header names to remove from the request on
+    every redirect hop. **Default:** `null`.
+  * `stripHeadersOnCrossOriginRedirect` {string[]} Additional header names to
+    remove from the request when a redirect points to a different origin.
+    **Default:** `null`.
+* `handler` {DispatchHandler} The downstream handler that receives the lifecycle
+  callbacks for the final response.
+
+Throws an [`InvalidArgumentError`][] when `maxRedirections` is not a non-negative
+integer, when `throwOnMaxRedirect` is not a boolean, or when either
+`stripHeadersOnRedirect` or `stripHeadersOnCrossOriginRedirect` is not an array of
+header-name strings.
+
+```mjs
+import { Client, RedirectHandler } from 'undici'
+
+const client = new Client('http://example.com')
+const dispatch = client.dispatch.bind(client)
+
+const handler = new RedirectHandler(dispatch, 5, {
+  method: 'GET',
+  path: '/',
+  origin: 'http://example.com',
+}, {
+  onRequestStart () {},
+  onResponseStart (controller, statusCode, headers) {
+    console.log(statusCode)
+  },
+  onResponseData (controller, chunk) {},
+  onResponseEnd () {},
+})
+
+dispatch({ method: 'GET', path: '/', origin: 'http://example.com' }, handler)
+```
+
+### Static method: `RedirectHandler.buildDispatch(dispatcher, maxRedirections)`
+
+<!-- YAML
+added: v7.0.0
+-->
+
+* `dispatcher` {Dispatcher} The dispatcher whose `dispatch` method is wrapped.
+* `maxRedirections` {number|null} The maximum number of redirects to follow. Must
+  be a non-negative integer or `null`.
+* Returns: {Function} A `dispatch(options, handler)` function that wraps each call
+  in a `RedirectHandler` before delegating to `dispatcher`.
+
+Builds a redirect-aware dispatch function from an existing dispatcher. The
+returned function has the same shape as `dispatcher.dispatch` but follows
+redirects automatically. Throws an [`InvalidArgumentError`][] when
+`maxRedirections` is not a non-negative integer.
+
+```mjs
+import { Client, RedirectHandler } from 'undici'
+
+const client = new Client('http://example.com')
+const dispatch = RedirectHandler.buildDispatch(client, 5)
 
-A class that handles redirection logic for HTTP requests.
+dispatch({ method: 'GET', path: '/', origin: 'http://example.com' }, {
+  onRequestStart () {},
+  onResponseStart (controller, statusCode) {
+    console.log(statusCode)
+  },
+  onResponseData () {},
+  onResponseEnd () {},
+})
+```
 
-## `new RedirectHandler(dispatch, maxRedirections, opts, handler)`
+### `redirectHandler.onRequestStart(controller, context)`
 
-Arguments:
+<!-- YAML
+added: v7.0.0
+-->
 
-- **dispatch** `function` - The dispatch function to be called after every retry.
-- **maxRedirections** `number` - Maximum number of redirections allowed.
-- **opts** `object` - Options for handling redirection. Supports `throwOnMaxRedirect`, `stripHeadersOnRedirect`, and `stripHeadersOnCrossOriginRedirect`.
-- **handler** `object` - An object containing handlers for different stages of the request lifecycle.
+* `controller` {DispatchController} The controller for the in-flight request.
+* `context` {Object} The dispatch context.
 
-Returns: `RedirectHandler`
+Forwards the request-start event to the wrapped `handler`, augmenting `context`
+with the current redirect `history`.
 
-### Parameters
+### `redirectHandler.onRequestUpgrade(controller, statusCode, headers, socket)`
 
-- **dispatch** `(options: Dispatch.DispatchOptions, handlers: Dispatch.DispatchHandler) => Promise<Dispatch.DispatchResponse>` (required) - Dispatch function to be called after every redirection.
-- **maxRedirections** `number` (required) - Maximum number of redirections allowed.
-- **opts** `object` (required) - Options for handling redirection.
-  - **throwOnMaxRedirect** `boolean` - Throw when the maximum number of redirections is reached.
-  - **stripHeadersOnRedirect** `string[]` - Header names to remove from all redirected requests.
-  - **stripHeadersOnCrossOriginRedirect** `string[]` - Header names to remove from cross-origin redirected requests.
-- **handler** `object` (required) - Handlers for different stages of the request lifecycle.
+<!-- YAML
+added: v7.0.0
+-->
 
-### Properties
+* `controller` {DispatchController} The controller for the in-flight request.
+* `statusCode` {number} The HTTP status code of the upgrade response.
+* `headers` {Object} The response headers.
+* `socket` {Duplex} The upgraded socket.
 
-- **location** `string` - The current redirection location.
-- **abort** `function` - The abort function.
-- **opts** `object` - The options for handling redirection.
-- **maxRedirections** `number` - Maximum number of redirections allowed.
-- **handler** `object` - Handlers for different stages of the request lifecycle.
-- **history** `Array` - An array representing the history of URLs during redirection.
+Forwards a connection upgrade to the wrapped `handler`.
 
-### Methods
+### `redirectHandler.onResponseStart(controller, statusCode, headers, statusMessage)`
 
-#### `onRequestStart(controller, context)`
+<!-- YAML
+added: v7.0.0
+-->
 
-Called when the request starts.
+* `controller` {DispatchController} The controller for the in-flight request.
+* `statusCode` {number} The HTTP status code of the response.
+* `headers` {Object} The response headers.
+* `statusMessage` {string} The HTTP status message.
 
-Parameters:
+Inspects the response headers to decide whether to follow a redirect. When the
+status code is redirectable, the `maxRedirections` limit has not been reached, and
+the request body has not been consumed, the `location` property is set, the method
+and headers are adjusted for the next hop, and the response is not forwarded.
+Otherwise the event is forwarded to the wrapped `handler`.
 
-- **controller** `DispatchController` - The request controller.
-- **context** `object` - The dispatch context.
+Throws when `throwOnMaxRedirect` is `true` and the number of recorded redirects
+has reached `maxRedirections`, and throws an [`InvalidArgumentError`][] if a
+redirect loop is detected (for example when a [`Client`][] or [`Pool`][] is used
+for a cross-origin redirect; use an [`Agent`][] instead).
 
-#### `onRequestUpgrade(controller, statusCode, headers, socket)`
+### `redirectHandler.onResponseData(controller, chunk)`
 
-Called when an upgrade is requested.
+<!-- YAML
+added: v7.0.0
+-->
 
-Parameters:
+* `controller` {DispatchController} The controller for the in-flight request.
+* `chunk` {Buffer} A chunk of the response body.
 
-- **controller** `DispatchController` - The request controller.
-- **statusCode** `number` - The HTTP status code.
-- **headers** `object` - The headers received in the response.
-- **socket** `object` - The socket object.
+Forwards body data to the wrapped `handler`. While a redirect is pending
+(`location` is set), the `3xx` response body is ignored.
 
-#### `onResponseError(controller, error)`
+### `redirectHandler.onResponseEnd(controller, trailers)`
 
-Called when an error occurs.
+<!-- YAML
+added: v7.0.0
+-->
 
-Parameters:
+* `controller` {DispatchController} The controller for the in-flight request.
+* `trailers` {Object} The response trailers.
 
-- **controller** `DispatchController` - The request controller.
-- **error** `Error` - The error that occurred.
+Completes the response. When a redirect is pending, the request is re-dispatched
+to the new `location`; otherwise the end event is forwarded to the wrapped
+`handler`.
 
-#### `onResponseStart(controller, statusCode, headers, statusText)`
+### `redirectHandler.onResponseError(controller, error)`
 
-Called when headers are received.
+<!-- YAML
+added: v7.0.0
+-->
 
-Parameters:
+* `controller` {DispatchController} The controller for the in-flight request.
+* `error` {Error} The error that occurred.
 
-- **controller** `DispatchController` - The request controller.
-- **statusCode** `number` - The HTTP status code.
-- **headers** `object` - The headers received in the response.
-- **statusText** `string` - The status text.
+Forwards the error to the wrapped `handler`.
 
-#### `onResponseData(controller, chunk)`
+### `redirectHandler.location`
 
-Called when data is received.
+<!-- YAML
+added: v4.0.0
+-->
 
-Parameters:
+* Type: {string|null}
 
-- **controller** `DispatchController` - The request controller.
-- **chunk** `Buffer` - The data chunk received.
+The `Location` header value of the redirect currently being followed, or `null`
+when no redirect is pending and the response is being passed through to the
+wrapped `handler`.
 
-#### `onResponseEnd(controller, trailers)`
+### `redirectHandler.opts`
 
-Called when the request is complete.
+<!-- YAML
+added: v7.12.0
+-->
 
-Parameters:
+* Type: {DispatchOptions}
 
-- **controller** `DispatchController` - The request controller.
-- **trailers** `object` - The trailers received.
+A copy of the dispatch options for the next request. It excludes the redirect
+control fields (`maxRedirections`, `stripHeadersOnRedirect`, and
+`stripHeadersOnCrossOriginRedirect`) and is mutated on each hop to reflect the
+updated method, path, origin, and headers.
 
-#### `onBodySent(chunk)`
+### `redirectHandler.maxRedirections`
 
-Called when the request body is sent.
+<!-- YAML
+added: v4.0.0
+-->
 
-Parameters:
+* Type: {number|null}
 
-- **chunk** `Buffer` - The chunk of the request body sent.
+The maximum number of redirects this handler will follow.
+
+### `redirectHandler.handler`
+
+<!-- YAML
+added: v4.0.0
+-->
+
+* Type: {DispatchHandler}
+
+The wrapped downstream handler that receives the lifecycle callbacks for the final
+response.
+
+### `redirectHandler.history`
+
+<!-- YAML
+added: v4.0.0
+-->
+
+* Type: {URL[]}
+
+The ordered list of URLs visited while following redirects. It is used to enforce
+`maxRedirections` and to detect redirect loops.
+
+[`Agent`]: Agent.md#class-agent
+[`Client`]: Client.md#class-client
+[`Dispatcher`]: Dispatcher.md#class-dispatcher
+[`DispatchHandler`]: Dispatcher.md#parameter-dispatchhandler
+[`InvalidArgumentError`]: Errors.md#class-invalidargumenterror
+[`Pool`]: Pool.md#class-pool
diff --git a/docs/docs/api/RetryAgent.md b/docs/docs/api/RetryAgent.md
index 3dc206ce63f..726620b72f2 100644
--- a/docs/docs/api/RetryAgent.md
+++ b/docs/docs/api/RetryAgent.md
@@ -1,49 +1,136 @@
-# Class: RetryAgent
+# RetryAgent
 
-Extends: `undici.Dispatcher`
+<!--introduced_in=v6.7.0-->
+<!--type=module-->
+<!-- source_link=lib/dispatcher/retry-agent.js -->
 
-A `undici.Dispatcher` that allows to automatically retry a request.
-Wraps a `undici.RetryHandler`.
+> Stability: 2 - Stable
 
-## `new RetryAgent(dispatcher, [options])`
+A [`Dispatcher`][] that automatically retries failed requests by wrapping
+another dispatcher with the retry logic of [`RetryHandler`][]. Requests that fail
+with a retryable status code or transport error are re-dispatched according to
+the configured retry policy.
 
-Arguments:
+```mjs
+import { RetryAgent } from 'undici'
+```
+
+## Class: `RetryAgent`
 
-* **dispatcher** `undici.Dispatcher` (required) - the dispatcher to wrap
-* **options** `RetryHandlerOptions` (optional) - the options
+<!-- YAML
+added: v6.7.0
+-->
 
-Returns: `RetryAgent`
+* Extends: {Dispatcher}
 
-### Parameter: `RetryHandlerOptions`
+Wraps an existing dispatcher and applies retry behaviour to every request it
+dispatches. Lifecycle methods such as [`retryAgent.close()`][] and
+[`retryAgent.destroy()`][] are forwarded to the wrapped dispatcher.
 
-- **throwOnError** `boolean` (optional) - Disable to prevent throwing error on last retry attept, useful if you need the body on errors from server or if you have custom error handler. Default: `true`
-- **retry** `(err: Error, context: RetryContext, callback: (err?: Error | null) => void) => void` (optional) - Function to be called after every retry. It should pass error if no more retries should be performed.
-- **maxRetries** `number` (optional) - Maximum number of retries. Default: `5`
-- **maxTimeout** `number` (optional) - Maximum number of milliseconds to wait before retrying. Default: `30000` (30 seconds)
-- **minTimeout** `number` (optional) - Minimum number of milliseconds to wait before retrying. Default: `500` (half a second)
-- **timeoutFactor** `number` (optional) - Factor to multiply the timeout by for each retry attempt. Default: `2`
-- **retryAfter** `boolean` (optional) - It enables automatic retry after the `Retry-After` header is received. Default: `true`
-- **methods** `string[]` (optional) - Array of HTTP methods to retry. Default: `['GET', 'HEAD', 'OPTIONS', 'PUT', 'DELETE', 'TRACE']`
-- **statusCodes** `number[]` (optional) - Array of HTTP status codes to retry. Default: `[429, 500, 502, 503, 504]`
-- **errorCodes** `string[]` (optional) - Array of Error codes to retry. Default: `['ECONNRESET', 'ECONNREFUSED', 'ENOTFOUND', 'ENETDOWN', 'ENETUNREACH', 'EHOSTDOWN', 'EHOSTUNREACH', 'EPIPE', 'UND_ERR_SOCKET']`
+### `new RetryAgent(dispatcher[, options])`
 
-**`RetryContext`**
+<!-- YAML
+added: v6.7.0
+-->
 
-- `state`: `RetryState` - Current retry state. It can be mutated.
-- `opts`: `Dispatch.DispatchOptions & RetryOptions` - Options passed to the retry handler.
+* `dispatcher` {Dispatcher} The dispatcher to wrap and add retry behaviour to.
+* `options` {RetryOptions} (optional)
+  * `throwOnError` {boolean} When `true`, an error is thrown on the final retry
+    attempt, preventing the following handlers from being called and destroying
+    the socket. Disable it when you need the response body for error responses
+    or when you provide a custom error handler. **Default:** `true`.
+  * `retry` {Function} Callback invoked on every retry iteration. It receives the
+    error, the current retry state, and a callback. Pass an error to the callback
+    to stop retrying, or call it with no argument to perform the retry.
+    * `err` {Error} The error that caused the retry attempt.
+    * `context` {RetryContext} The current retry context.
+      * `state` {RetryState} The mutable retry state.
+        * `counter` {number} The number of retries performed so far.
+      * `opts` {Object} The options passed to the retry handler, combining the
+        dispatch options with `retryOptions`.
+    * `callback` {Function} Called to continue. Pass an `Error` to stop retrying,
+      or `null`/`undefined` to perform the next retry.
+  * `maxRetries` {number} Maximum number of retries to allow. **Default:** `5`.
+  * `maxTimeout` {number} Maximum number of milliseconds to wait between retries.
+    **Default:** `30000` (30 seconds).
+  * `minTimeout` {number} Initial number of milliseconds to wait before the first
+    retry. **Default:** `500` (half a second).
+  * `timeoutFactor` {number} Factor by which the timeout is multiplied between
+    retries. **Default:** `2`.
+  * `retryAfter` {boolean} When `true`, the delay between retries is inferred from
+    the `Retry-After` response header when present. **Default:** `true`.
+  * `methods` {string[]} HTTP methods that are eligible for retry.
+    **Default:** `['GET', 'HEAD', 'OPTIONS', 'PUT', 'DELETE', 'TRACE']`.
+  * `statusCodes` {number[]} HTTP status codes that trigger a retry.
+    **Default:** `[500, 502, 503, 504, 429]`.
+  * `errorCodes` {string[]} Transport error codes that trigger a retry.
+    **Default:** `['ECONNRESET', 'ECONNREFUSED', 'ENOTFOUND', 'ENETDOWN', 'ENETUNREACH', 'EHOSTDOWN', 'EHOSTUNREACH', 'EPIPE', 'UND_ERR_SOCKET']`.
 
-Example:
+Creates a new `RetryAgent` that wraps `dispatcher`. The `options` are stored and
+used to construct a [`RetryHandler`][] for each dispatched request.
 
-```js
+```mjs
 import { Agent, RetryAgent } from 'undici'
 
-const agent = new RetryAgent(new Agent())
+const agent = new RetryAgent(new Agent(), {
+  maxRetries: 3,
+  minTimeout: 1000,
+  timeoutFactor: 2,
+})
 
 const res = await agent.request({
   method: 'GET',
   origin: 'http://example.com',
   path: '/',
 })
+
 console.log(res.statusCode)
 console.log(await res.body.text())
 ```
+
+### `retryAgent.dispatch(options, handler)`
+
+<!-- YAML
+added: v6.7.0
+-->
+
+* `options` {DispatchOptions} The dispatch options, identical to
+  [`dispatcher.dispatch()`][].
+* `handler` {DispatchHandler} The dispatch handler.
+* Returns: {boolean}
+
+Dispatches `options` through the wrapped dispatcher, installing a
+[`RetryHandler`][] that applies the configured retry policy before delegating to
+`handler`. Returns `false` if the dispatcher is busy and the caller should wait
+before dispatching again, otherwise `true`.
+
+### `retryAgent.close()`
+
+<!-- YAML
+added: v6.7.0
+-->
+
+* Returns: {Promise} Resolves when the wrapped dispatcher has closed.
+
+Gracefully closes the wrapped dispatcher, waiting for in-flight requests to
+complete. Equivalent to calling [`dispatcher.close()`][] on the wrapped
+dispatcher.
+
+### `retryAgent.destroy()`
+
+<!-- YAML
+added: v6.7.0
+-->
+
+* Returns: {Promise} Resolves when the wrapped dispatcher has been destroyed.
+
+Forcefully destroys the wrapped dispatcher, aborting all pending requests.
+Equivalent to calling [`dispatcher.destroy()`][] on the wrapped dispatcher.
+
+[`Dispatcher`]: Dispatcher.md#class-dispatcher
+[`RetryHandler`]: RetryHandler.md#class-retryhandler
+[`dispatcher.close()`]: Dispatcher.md#dispatcherclosecallback
+[`dispatcher.destroy()`]: Dispatcher.md#dispatcherdestroyerror-callback
+[`dispatcher.dispatch()`]: Dispatcher.md#dispatcherdispatchoptions-handler
+[`retryAgent.close()`]: #retryagentclose
+[`retryAgent.destroy()`]: #retryagentdestroy
diff --git a/docs/docs/api/RetryHandler.md b/docs/docs/api/RetryHandler.md
index 00ef0a9000f..fa028ef1d59 100644
--- a/docs/docs/api/RetryHandler.md
+++ b/docs/docs/api/RetryHandler.md
@@ -1,116 +1,200 @@
-# Class: RetryHandler
+# RetryHandler
 
-Extends: `undici.DispatcherHandlers`
+<!--introduced_in=v5.28.0-->
+<!--type=module-->
+<!-- source_link=lib/handler/retry-handler.js -->
 
-A handler class that implements the retry logic for a request.
+> Stability: 2 - Stable
 
-## `new RetryHandler(opts, { dispatch, handler })`
+A [`Dispatcher`][] handler that automatically retries a request when it fails
+with a recoverable network error or an eligible HTTP status code. It wraps an
+inner handler and re-dispatches the request, applying an exponential backoff and
+honouring the `Retry-After` response header. When a response is partially
+consumed before the failure, the handler resumes the download with a `Range`
+request guarded by the original `ETag`.
 
-Arguments:
+The handler is most often used indirectly through [`RetryAgent`][], but it can
+also be supplied directly to [`dispatcher.dispatch()`][] for fine-grained
+control over the retry behaviour.
 
-- **opts** `Dispatch.DispatchOptions & { retryOptions?: RetryOptions }` (required) - An intersection of `Dispatcher.DispatchOptions` and an optional `RetryOptions` object.
-- **{ dispatch, handler }** `RetryHandlers` (required) - Object containing the `dispatch` to be used on every retry, and `handler` for handling the `dispatch` lifecycle.
-
-Returns: `retryHandler`
-
-### Parameter: `Dispatch.DispatchOptions & RetryOptions`
-
-Extends: [`Dispatch.DispatchOptions`](/docs/docs/api/Dispatcher.md#parameter-dispatchoptions).
-
-#### `RetryOptions`
+```mjs
+import { RetryHandler } from 'undici'
+```
 
-- **throwOnError** `boolean` (optional) - Disable to prevent throwing error on last retry attept, useful if you need the body on errors from server or if you have custom error handler.
-- **retry** `(err: Error, context: RetryContext, callback: (err?: Error | null) => void) => void` (optional) - Function to be called after every retry. It should pass error if no more retries should be performed.
-- **maxRetries** `number` (optional) - Maximum number of retries. Default: `5`
-- **maxTimeout** `number` (optional) - Maximum number of milliseconds to wait before retrying. Default: `30000` (30 seconds)
-- **minTimeout** `number` (optional) - Minimum number of milliseconds to wait before retrying. Default: `500` (half a second)
-- **timeoutFactor** `number` (optional) - Factor to multiply the timeout by for each retry attempt. Default: `2`
-- **retryAfter** `boolean` (optional) - It enables automatic retry after the `Retry-After` header is received. Default: `true`
-- **methods** `string[]` (optional) - Array of HTTP methods to retry. Default: `['GET', 'HEAD', 'OPTIONS', 'PUT', 'DELETE', 'TRACE']`
-- **statusCodes** `number[]` (optional) - Array of HTTP status codes to retry. Default: `[429, 500, 502, 503, 504]`
-- **errorCodes** `string[]` (optional) - Array of Error codes to retry. Default: `['ECONNRESET', 'ECONNREFUSED', 'ENOTFOUND', 'ENETDOWN', 'ENETUNREACH', 'EHOSTDOWN', 'EHOSTUNREACH', 'EPIPE', 'UND_ERR_SOCKET']`
+## Class: `RetryHandler`
 
-**`RetryContext`**
+<!-- YAML
+added: v5.28.0
+-->
 
-- `state`: `RetryState` - Current retry state. It can be mutated.
-- `opts`: `Dispatch.DispatchOptions & RetryOptions` - Options passed to the retry handler.
+* Extends: {DispatchHandler}
 
-**`RetryState`**
+Implements the [`DispatchHandler`][] interface. An instance is consumed by a
+single dispatch call and forwards the dispatch lifecycle to the inner `handler`,
+re-issuing the request through the supplied `dispatch` function whenever a retry
+is warranted.
 
-It represents the retry state for a given request.
+> **Note:** The `RetryHandler` does not retry over stateful bodies (for example
+> streams or `AsyncIterable`), because once consumed they cannot be replayed. In
+> these situations the body is identified as stateful and the request is rejected
+> with the `UND_ERR_REQ_RETRY` error instead of being retried.
 
-- `counter`: `number` - Current retry attempt.
+### `new RetryHandler(options, retryHandlers)`
 
-### Parameter `RetryHandlers`
+<!-- YAML
+added: v5.28.0
+changes:
+  - version: v7.0.0
+    pr-url: https://github.com/nodejs/undici/pull/3883
+    description: Reimplemented on top of the new dispatch lifecycle hooks.
+-->
 
-- **dispatch** `(options: Dispatch.DispatchOptions, handlers: Dispatch.DispatchHandler) => Promise<Dispatch.DispatchResponse>` (required) - Dispatch function to be called after every retry.
-- **handler** Extends [`Dispatch.DispatchHandler`](/docs/docs/api/Dispatcher.md#dispatcherdispatchoptions-handler) (required) - Handler function to be called after the request is successful or the retries are exhausted.
+* `options` {DispatchOptions} The dispatch options for the request, extended with
+  an optional `retryOptions` field. Type is
+  `DispatchOptions & { retryOptions?: RetryOptions }`.
+  * `retryOptions` {RetryOptions} (optional) Configuration controlling when and
+    how the request is retried. See [`RetryOptions`](#retryoptions).
+* `retryHandlers` {RetryHandlers} The handlers used to drive the retry loop. See
+  [`RetryHandlers`](#parameter-retryhandlers).
+* Returns: {RetryHandler}
 
->__Note__: The `RetryHandler` does not retry over stateful bodies (e.g. streams, AsyncIterable) as those, once consumed, are left in a state that cannot be reutilized. For these situations the `RetryHandler` will identify
->the body as stateful and will not retry the request rejecting with the error `UND_ERR_REQ_RETRY`.
+#### `RetryOptions`
 
-Examples:
+* `throwOnError` {boolean} When `true`, an error is thrown on the last retry
+  attempt and propagated to the inner handler; when `false`, the failing response
+  is passed through instead, which is useful when the error body is needed or a
+  custom error handler is in place. **Default:** `true`.
+* `retry` {Function} Callback invoked on every retry iteration to decide whether
+  another attempt should be made. It receives the error, the retry context, and a
+  callback. Call the callback with an `Error` to stop retrying, or with `null` to
+  schedule another attempt. **Default:** the built-in retry strategy described
+  below.
+  * `err` {Error} The error that triggered the retry.
+  * `context` {RetryContext} The current retry context. See
+    [`RetryContext`](#retrycontext).
+  * `callback` {Function} Signals the outcome of this iteration.
+    * `result` {Error|null} (optional) An `Error` to abort retrying, or `null` to
+      retry.
+* `maxRetries` {number} Maximum number of retries allowed. **Default:** `5`.
+* `maxTimeout` {number} Maximum number of milliseconds to wait between retries.
+  **Default:** `30000` (30 seconds).
+* `minTimeout` {number} Initial number of milliseconds to wait before the first
+  retry. **Default:** `500` (half a second).
+* `timeoutFactor` {number} Multiplier applied to the timeout between successive
+  retries to produce an exponential backoff. **Default:** `2`.
+* `retryAfter` {boolean} When `true`, the delay before the next retry is inferred
+  from the `Retry-After` response header when present. **Default:** `true`.
+* `methods` {string[]} HTTP methods that are eligible for retrying. **Default:**
+  `['GET', 'HEAD', 'OPTIONS', 'PUT', 'DELETE', 'TRACE']`.
+* `statusCodes` {number[]} HTTP status codes that trigger a retry. **Default:**
+  `[500, 502, 503, 504, 429]`.
+* `errorCodes` {string[]} Network error codes that trigger a retry. **Default:**
+  `['ECONNRESET', 'ECONNREFUSED', 'ENOTFOUND', 'ENETDOWN', 'ENETUNREACH', 'EHOSTDOWN', 'EHOSTUNREACH', 'EPIPE', 'UND_ERR_SOCKET']`.
+
+The default `retry` strategy computes the delay before the next attempt as
+`minTimeout * timeoutFactor ** (counter - 1)`, capped at `maxTimeout`. When a
+`Retry-After` header is present it takes precedence (interpreted as seconds, or as
+an HTTP date), still capped at `maxTimeout`. The default strategy stops retrying
+once `counter` exceeds `maxRetries`, when the error code is not in `errorCodes`,
+when the method is not in `methods`, or when the response status code is not in
+`statusCodes`.
+
+#### `RetryContext`
+
+* `state` {RetryState} The current retry state. See [`RetryState`](#retrystate).
+* `opts` {DispatchOptions} The dispatch options passed to the handler, including
+  the resolved `retryOptions`. Type is
+  `DispatchOptions & { retryOptions?: RetryOptions }`.
+
+The context object passed as the second argument to the `retry` callback.
+
+#### `RetryState`
+
+* `counter` {number} The current retry attempt, starting at `1` for the first
+  retry.
+
+Represents the retry state for a given request.
+
+#### Parameter: `RetryHandlers`
+
+* `dispatch` {Function} The dispatch function called to (re-)issue the request on
+  every attempt. Type is `(options, handler) => boolean`.
+* `handler` {DispatchHandler} The inner handler invoked once the request succeeds
+  or the retries are exhausted.
+
+### Examples
+
+```mjs
+import { Client, RetryHandler } from 'undici'
+
+const client = new Client(`http://localhost:${server.address().port}`)
+const chunks = []
 
-```js
-const client = new Client(`http://localhost:${server.address().port}`);
-const chunks = [];
 const handler = new RetryHandler(
   {
     ...dispatchOptions,
     retryOptions: {
-      // custom retry function
-      retry: function (err, state, callback) {
-        counter++;
-
-        if (err.code && err.code === "UND_ERR_DESTROYED") {
-          callback(err);
-          return;
+      // Custom retry decision function.
+      retry (err, { state, opts }, callback) {
+        if (err.code === 'UND_ERR_DESTROYED') {
+          callback(err)
+          return
         }
 
         if (err.statusCode === 206) {
-          callback(err);
-          return;
+          callback(err)
+          return
         }
 
-        setTimeout(() => callback(null), 1000);
-      },
-    },
+        setTimeout(() => callback(null), 1000)
+      }
+    }
   },
   {
-    dispatch: (...args) => {
-      return client.dispatch(...args);
+    dispatch (...args) {
+      return client.dispatch(...args)
     },
     handler: {
-      onRequestStart() {},
-      onBodySent(chunk) {},
-      onResponseStart(_controller, status, headers) {
-        // do something with headers
+      onRequestStart () {},
+      onResponseStart (controller, status, headers) {
+        // Do something with the response headers.
       },
-      onResponseData(_controller, chunk) {
-        chunks.push(chunk);
+      onResponseData (controller, chunk) {
+        chunks.push(chunk)
       },
-      onResponseEnd() {},
-      onResponseError(_controller, err) {
-        // handle error properly
-      },
-    },
+      onResponseEnd () {},
+      onResponseError (controller, err) {
+        // Handle the error.
+      }
+    }
   }
-);
+)
+
+client.dispatch(dispatchOptions, handler)
 ```
 
-#### Example - Basic RetryHandler with defaults
+A minimal handler that relies entirely on the default retry options:
+
+```mjs
+import { Client, RetryHandler } from 'undici'
+
+const client = new Client(`http://localhost:${server.address().port}`)
 
-```js
-const client = new Client(`http://localhost:${server.address().port}`);
 const handler = new RetryHandler(dispatchOptions, {
   dispatch: client.dispatch.bind(client),
   handler: {
-    onRequestStart() {},
-    onBodySent(chunk) {},
-    onResponseStart(_controller, status, headers) {},
-    onResponseData(_controller, chunk) {},
-    onResponseEnd() {},
-    onResponseError(_controller, err) {},
-  },
-});
+    onRequestStart () {},
+    onResponseStart (controller, status, headers) {},
+    onResponseData (controller, chunk) {},
+    onResponseEnd () {},
+    onResponseError (controller, err) {}
+  }
+})
+
+client.dispatch(dispatchOptions, handler)
 ```
+
+[`Dispatcher`]: Dispatcher.md#class-dispatcher
+[`DispatchHandler`]: Dispatcher.md#parameter-dispatchhandler
+[`RetryAgent`]: RetryAgent.md#class-retryagent
+[`dispatcher.dispatch()`]: Dispatcher.md#dispatcherdispatchoptions-handler
diff --git a/docs/docs/api/RoundRobinPool.md b/docs/docs/api/RoundRobinPool.md
index ea9a3e1aa54..2e979284a60 100644
--- a/docs/docs/api/RoundRobinPool.md
+++ b/docs/docs/api/RoundRobinPool.md
@@ -1,131 +1,213 @@
-# Class: RoundRobinPool
+# RoundRobinPool
 
-Extends: `undici.Dispatcher`
+<!--introduced_in=v7.17.0-->
+<!--type=module-->
+<!-- source_link=lib/dispatcher/round-robin-pool.js -->
 
-A pool of [Client](/docs/docs/api/Client.md) instances connected to the same upstream target with round-robin client selection.
+> Stability: 2 - Stable
 
-Unlike [`Pool`](/docs/docs/api/Pool.md), which always selects the first available client, `RoundRobinPool` cycles through clients in a round-robin fashion. This ensures even distribution of requests across all connections, which is particularly useful when the upstream target is behind a load balancer that round-robins TCP connections across multiple backend servers (e.g., Kubernetes Services).
+A pool of [`Client`][] instances connected to the same upstream target that
+selects clients in a round-robin fashion.
 
-Requests are not guaranteed to be dispatched in order of invocation.
+Unlike [`Pool`][], which always reuses the first available client,
+`RoundRobinPool` cycles through its clients so that requests are distributed
+evenly across every open connection. This is useful when the upstream target is
+fronted by a load balancer that distributes TCP connections across multiple
+backend servers (for example, a Kubernetes Service): each connection is pinned
+to a backend by the load balancer, and `RoundRobinPool` spreads requests across
+those connections so every backend receives a comparable share of traffic.
 
-## `new RoundRobinPool(url[, options])`
+Requests are not guaranteed to be dispatched in the order they were invoked.
 
-Arguments:
+```mjs
+import { RoundRobinPool } from 'undici'
+
+const pool = new RoundRobinPool('http://localhost:3000', { connections: 10 })
+```
+
+`RoundRobinPool` distributes HTTP requests evenly across TCP connections, not
+across backend servers directly. Even backend distribution therefore depends on
+the load balancer assigning different connections to different backends (for
+example, round-robin, random, or least-connections without client affinity). If
+the load balancer pins all connections from one source to the same backend (for
+example, source-IP affinity or sticky sessions), consider [`BalancedPool`][]
+with the individual backend addresses instead.
+
+## Class: `RoundRobinPool`
+
+<!-- YAML
+added: v7.17.0
+-->
+
+* Extends: {Dispatcher}
+
+### `new RoundRobinPool(url[, options])`
 
-* **url** `URL | string` - It should only include the **protocol, hostname, and port**.
-* **options** `RoundRobinPoolOptions` (optional)
+<!-- YAML
+added: v7.17.0
+-->
 
-### Parameter: `RoundRobinPoolOptions`
+* `url` {URL|string} The upstream target. It should only include the
+  **protocol, hostname, and port**.
+* `options` {RoundRobinPoolOptions} (optional)
 
-Extends: [`ClientOptions`](/docs/docs/api/Client.md#parameter-clientoptions)
+#### Parameter: `RoundRobinPoolOptions`
 
-* **factory** `(origin: URL, opts: Object) => Dispatcher` - Default: `(origin, opts) => new Client(origin, opts)`
-* **connections** `number | null` (optional) - Default: `null` - The number of `Client` instances to create. When set to `null`, the `RoundRobinPool` instance will create an unlimited amount of `Client` instances.
-* **clientTtl** `number | null` (optional) - Default: `null` - The amount of time before a `Client` instance is removed from the `RoundRobinPool` and closed. When set to `null`, `Client` instances will not be removed or closed based on age.
+Extends: {ClientOptions}
 
-## Use Case
+* `factory` {Function} A function used to create the underlying {Client}
+  instances. **Default:** `(origin, opts) => new Client(origin, opts)`.
+  * `origin` {URL}
+  * `opts` {Object}
+  * Returns: {Dispatcher}
+* `connections` {number|null} (optional) The maximum number of {Client}
+  instances to create. When set to `null`, the `RoundRobinPool` instance creates
+  an unlimited number of {Client} instances. **Default:** `null`.
+* `clientTtl` {number|null} (optional) The amount of time, in milliseconds,
+  before a {Client} instance is removed from the `RoundRobinPool` and closed.
+  When set to `null`, {Client} instances are not removed or closed based on age.
+  **Default:** `null`.
 
-`RoundRobinPool` is designed for scenarios where:
+`RoundRobinPool` inherits all [`Client`][] options. A [`Client`][] instance is
+created lazily on the first dispatch and additional instances are created on
+demand, up to `connections`, when every existing client is busy.
 
-1. You connect to a single origin (e.g., `http://my-service.namespace.svc`)
-2. That origin is backed by a load balancer distributing TCP connections across multiple servers
-3. You want requests evenly distributed across all backend servers
+### `roundRobinPool.closed`
 
-**Example**: In Kubernetes, when using a Service DNS name with multiple Pod replicas, kube-proxy load balances TCP connections. `RoundRobinPool` ensures each connection (and thus each Pod) receives an equal share of requests.
+<!-- YAML
+added: v7.17.0
+-->
 
-### Important: Backend Distribution Considerations
+* Type: {boolean}
 
-`RoundRobinPool` distributes **HTTP requests** evenly across **TCP connections**. Whether this translates to even backend server distribution depends on the load balancer's behavior:
+`true` after `roundRobinPool.close()` has been called.
 
-**✓ Works when the load balancer**:
-- Assigns different backends to different TCP connections from the same client
-- Uses algorithms like: round-robin, random, least-connections (without client affinity)
-- Example: Default Kubernetes Services without `sessionAffinity`
+### `roundRobinPool.destroyed`
 
-**✗ Does NOT work when**:
-- Load balancer has client/source IP affinity (all connections from one IP → same backend)
-- Load balancer uses source-IP-hash or sticky sessions
+<!-- YAML
+added: v7.17.0
+-->
 
-**How it works:**
-1. `RoundRobinPool` creates N TCP connections to the load balancer endpoint
-2. Load balancer assigns each TCP connection to a backend (per its algorithm)
-3. `RoundRobinPool` cycles HTTP requests across those N connections
-4. Result: Requests distributed proportionally to how the LB distributed the connections
+* Type: {boolean}
 
-If the load balancer assigns all connections to the same backend (e.g., due to session affinity), `RoundRobinPool` cannot overcome this. In such cases, consider using [`BalancedPool`](/docs/docs/api/BalancedPool.md) with direct backend addresses (e.g., individual pod IPs) instead of a load-balanced endpoint.
+`true` after `roundRobinPool.destroy()` has been called, or after
+`roundRobinPool.close()` has been called and the pool shutdown has completed.
 
-## Instance Properties
+### `roundRobinPool.stats`
 
-### `RoundRobinPool.closed`
+<!-- YAML
+added: v7.17.0
+-->
 
-Implements [Client.closed](/docs/docs/api/Client.md#clientclosed)
+* Type: {PoolStats}
 
-### `RoundRobinPool.destroyed`
+Aggregate connection statistics for the pool. See [`PoolStats`][].
 
-Implements [Client.destroyed](/docs/docs/api/Client.md#clientdestroyed)
+### `roundRobinPool.close([callback])`
 
-### `RoundRobinPool.stats`
+<!-- YAML
+added: v7.17.0
+-->
 
-Returns [`PoolStats`](/docs/docs/api/PoolStats.md) instance for this pool.
+Closes the pool and gracefully waits for enqueued requests to complete before
+resolving. Implements [`dispatcher.close([callback])`][].
 
-## Instance Methods
+### `roundRobinPool.destroy([error[, callback]])`
 
-### `RoundRobinPool.close([callback])`
+<!-- YAML
+added: v7.17.0
+-->
 
-Implements [`Dispatcher.close([callback])`](/docs/docs/api/Dispatcher.md#dispatcherclosecallback-promise).
+Destroys the pool abruptly. All pending and running requests are aborted with
+the given `error`. Implements [`dispatcher.destroy([error[, callback]])`][].
 
-### `RoundRobinPool.destroy([error, callback])`
+### `roundRobinPool.connect(options[, callback])`
 
-Implements [`Dispatcher.destroy([error, callback])`](/docs/docs/api/Dispatcher.md#dispatcherdestroyerror-callback-promise).
+<!-- YAML
+added: v7.17.0
+-->
 
-### `RoundRobinPool.connect(options[, callback])`
+Starts two-way communications with the requested resource using
+[HTTP CONNECT][]. See [`dispatcher.connect(options[, callback])`][].
 
-See [`Dispatcher.connect(options[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherconnectoptions-callback).
+### `roundRobinPool.dispatch(options, handler)`
 
-### `RoundRobinPool.dispatch(options, handler)`
+<!-- YAML
+added: v7.17.0
+-->
 
-Implements [`Dispatcher.dispatch(options, handler)`](/docs/docs/api/Dispatcher.md#dispatcherdispatchoptions-handler).
+Dispatches a request through the next client selected in round-robin order.
+Implements [`dispatcher.dispatch(options, handler)`][].
 
-### `RoundRobinPool.pipeline(options, handler)`
+### `roundRobinPool.pipeline(options, handler)`
 
-See [`Dispatcher.pipeline(options, handler)`](/docs/docs/api/Dispatcher.md#dispatcherpipelineoptions-handler).
+<!-- YAML
+added: v7.17.0
+-->
 
-### `RoundRobinPool.request(options[, callback])`
+For easy use with [`stream.pipeline`][]. See
+[`dispatcher.pipeline(options, handler)`][].
 
-See [`Dispatcher.request(options [, callback])`](/docs/docs/api/Dispatcher.md#dispatcherrequestoptions-callback).
+### `roundRobinPool.request(options[, callback])`
 
-### `RoundRobinPool.stream(options, factory[, callback])`
+<!-- YAML
+added: v7.17.0
+-->
 
-See [`Dispatcher.stream(options, factory[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherstreamoptions-factory-callback).
+Performs an HTTP request. See [`dispatcher.request(options[, callback])`][].
 
-### `RoundRobinPool.upgrade(options[, callback])`
+### `roundRobinPool.stream(options, factory[, callback])`
 
-See [`Dispatcher.upgrade(options[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherupgradeoptions-callback).
+<!-- YAML
+added: v7.17.0
+-->
 
-## Instance Events
+A faster version of [`roundRobinPool.request()`][]. See
+[`dispatcher.stream(options, factory[, callback])`][].
+
+### `roundRobinPool.upgrade(options[, callback])`
+
+<!-- YAML
+added: v7.17.0
+-->
+
+Upgrades a connection to a different protocol. See
+[`dispatcher.upgrade(options[, callback])`][].
 
 ### Event: `'connect'`
 
-See [Dispatcher Event: `'connect'`](/docs/docs/api/Dispatcher.md#event-connect).
+<!-- YAML
+added: v7.17.0
+-->
+
+See [Dispatcher Event: `'connect'`][].
 
 ### Event: `'disconnect'`
 
-See [Dispatcher Event: `'disconnect'`](/docs/docs/api/Dispatcher.md#event-disconnect).
+<!-- YAML
+added: v7.17.0
+-->
+
+See [Dispatcher Event: `'disconnect'`][].
 
 ### Event: `'drain'`
 
-See [Dispatcher Event: `'drain'`](/docs/docs/api/Dispatcher.md#event-drain).
+<!-- YAML
+added: v7.17.0
+-->
+
+See [Dispatcher Event: `'drain'`][].
 
 ## Example
 
-```javascript
+```mjs
 import { RoundRobinPool } from 'undici'
 
-const pool = new RoundRobinPool('http://my-service.default.svc.cluster.local', {
+const pool = new RoundRobinPool('http://localhost:3000', {
   connections: 10
 })
 
-// Requests will be distributed evenly across all 10 connections
+// Requests are distributed evenly across all 10 connections.
 for (let i = 0; i < 100; i++) {
   const { body } = await pool.request({
     path: '/api/data',
@@ -137,9 +219,21 @@ for (let i = 0; i < 100; i++) {
 await pool.close()
 ```
 
-## See Also
-
-- [Pool](/docs/docs/api/Pool.md) - Connection pool without round-robin
-- [BalancedPool](/docs/docs/api/BalancedPool.md) - Load balancing across multiple origins
-- [Issue #3648](https://github.com/nodejs/undici/issues/3648) - Original issue describing uneven distribution
-
+[HTTP CONNECT]: https://developer.mozilla.org/docs/Web/HTTP/Methods/CONNECT
+[`BalancedPool`]: BalancedPool.md#class-balancedpool
+[`Client`]: Client.md#class-client
+[`Pool`]: Pool.md#class-pool
+[`PoolStats`]: PoolStats.md#class-poolstats
+[`dispatcher.close([callback])`]: Dispatcher.md#dispatcherclosecallback-promise
+[`dispatcher.connect(options[, callback])`]: Dispatcher.md#dispatcherconnectoptions-callback
+[`dispatcher.destroy([error[, callback]])`]: Dispatcher.md#dispatcherdestroyerror-callback-promise
+[`dispatcher.dispatch(options, handler)`]: Dispatcher.md#dispatcherdispatchoptions-handler
+[`dispatcher.pipeline(options, handler)`]: Dispatcher.md#dispatcherpipelineoptions-handler
+[`dispatcher.request(options[, callback])`]: Dispatcher.md#dispatcherrequestoptions-callback
+[`dispatcher.stream(options, factory[, callback])`]: Dispatcher.md#dispatcherstreamoptions-factory-callback
+[`dispatcher.upgrade(options[, callback])`]: Dispatcher.md#dispatcherupgradeoptions-callback
+[`roundRobinPool.request()`]: #roundrobinpoolrequestoptions-callback
+[`stream.pipeline`]: https://nodejs.org/api/stream.html#streampipelinesource-transforms-destination-callback
+[Dispatcher Event: `'connect'`]: Dispatcher.md#event-connect
+[Dispatcher Event: `'disconnect'`]: Dispatcher.md#event-disconnect
+[Dispatcher Event: `'drain'`]: Dispatcher.md#event-drain
diff --git a/docs/docs/api/SnapshotAgent.md b/docs/docs/api/SnapshotAgent.md
index cac2981c67c..27c132ba763 100644
--- a/docs/docs/api/SnapshotAgent.md
+++ b/docs/docs/api/SnapshotAgent.md
@@ -1,639 +1,361 @@
 # SnapshotAgent
 
-The `SnapshotAgent` provides a powerful way to record and replay HTTP requests for testing purposes. It extends `MockAgent` to enable automatic snapshot testing, eliminating the need to manually define mock responses.
+<!--introduced_in=v7.13.0-->
+<!--type=module-->
+<!-- source_link=lib/mock/snapshot-agent.js -->
 
-## Use Cases
+> Stability: 1 - Experimental
 
-- **Integration Testing**: Record real API interactions and replay them in tests
-- **Offline Development**: Work with APIs without network connectivity
-- **Consistent Test Data**: Ensure tests use the same responses across runs
-- **API Contract Testing**: Capture and validate API behavior over time
+`SnapshotAgent` records real HTTP responses and replays them on later requests,
+allowing tests to run against deterministic, captured data instead of a live
+network. It extends [`MockAgent`][], so it can be installed with
+[`setGlobalDispatcher()`][] or passed explicitly through the `dispatcher`
+option, and it works with every undici API (`fetch`, `request`, `stream`,
+`pipeline`, and so on).
 
-## Constructor
+A `SnapshotAgent` operates in one of three modes. In `'record'` mode it performs
+real requests and writes the responses to a snapshot file. In `'playback'` mode
+it serves responses from the snapshot file without touching the network. In
+`'update'` mode it replays existing snapshots and records any request that has no
+matching snapshot.
 
-```javascript
-new SnapshotAgent([options])
-```
-
-### Parameters
-
-- **options** `Object` (optional)
-  - **mode** `String` - The snapshot mode: `'record'`, `'playback'`, or `'update'`. Default: `'record'`
-  - **snapshotPath** `String` - Path to the snapshot file for loading/saving
-  - **maxSnapshots** `Number` - Maximum number of snapshots to keep in memory. Default: `Infinity`
-  - **autoFlush** `Boolean` - Whether to automatically save snapshots to disk. Default: `false`
-  - **flushInterval** `Number` - Interval in milliseconds for auto-flush. Default: `30000`
-  - **matchHeaders** `Array<String>` - Specific headers to include in request matching. Default: all headers
-  - **ignoreHeaders** `Array<String>` - Headers to ignore during request matching
-  - **excludeHeaders** `Array<String>` - Headers to exclude from snapshots (for security)
-  - **matchBody** `Boolean` - Whether to include request body in matching. Default: `true`
-  - **normalizeBody** `Function` - Optional function `(body) => string` to normalize the request body before matching (e.g. strip volatile fields like timestamps). Only used when `matchBody` is `true`.
-  - **matchQuery** `Boolean` - Whether to include query parameters in matching. Default: `true`
-  - **normalizeQuery** `Function` - Optional function `(query: URLSearchParams) => string` to normalize query parameters before matching (e.g. strip volatile params like cache-busters). Only used when `matchQuery` is `true`.
-  - **caseSensitive** `Boolean` - Whether header matching is case-sensitive. Default: `false`
-  - **shouldRecord** `Function` - Callback to determine if a request should be recorded
-  - **shouldPlayback** `Function` - Callback to determine if a request should be played back
-  - **excludeUrls** `Array` - URL patterns (strings or RegExp) to exclude from recording/playback
-  - All other options from `MockAgent` are supported
-
-### Modes
-
-#### Record Mode (`'record'`)
-Makes real HTTP requests and saves the responses to snapshots.
-
-```javascript
-import { SnapshotAgent, setGlobalDispatcher } from 'undici'
+```mjs
+import { SnapshotAgent, setGlobalDispatcher, fetch } from 'undici'
 
-const agent = new SnapshotAgent({ 
+const agent = new SnapshotAgent({
   mode: 'record',
-  snapshotPath: './test/snapshots/api-calls.json'
+  snapshotPath: './snapshots/api.json'
 })
 setGlobalDispatcher(agent)
 
-// Makes real requests and records them
 const response = await fetch('https://api.example.com/users')
 const users = await response.json()
 
-// Save recorded snapshots
-await agent.saveSnapshots()
-```
-
-#### Playback Mode (`'playback'`)
-Replays recorded responses without making real HTTP requests.
-
-```javascript
+await agent.close()
+```
+
+Constructing a `SnapshotAgent` emits an `ExperimentalWarning` once per process.
+
+## Class: `SnapshotAgent`
+
+<!-- YAML
+added: v7.13.0
+-->
+
+* Extends: {MockAgent}
+
+The captured interactions are managed by an internal `SnapshotRecorder`, which
+is accessible through [`agent.getRecorder()`][]. Because `SnapshotAgent` extends
+[`MockAgent`][], all `MockAgent` and [`Dispatcher`][] methods and events are also
+available.
+
+### `new SnapshotAgent([options])`
+
+<!-- YAML
+added: v7.13.0
+-->
+
+* `options` {Object} (optional) Accepts all [`MockAgent`][] options plus the
+  following snapshot-specific options.
+  * `mode` {string} The snapshot mode. One of `'record'`, `'playback'`, or
+    `'update'`. **Default:** `'record'`.
+  * `snapshotPath` {string} Path to the snapshot file used for loading and
+    saving. Required when `mode` is `'playback'` or `'update'`. **Default:**
+    `null`.
+  * `maxSnapshots` {number} Maximum number of snapshots to keep in memory.
+    **Default:** `Infinity`.
+  * `autoFlush` {boolean} When `true`, snapshots are written to `snapshotPath`
+    automatically as they are recorded. **Default:** `false`.
+  * `flushInterval` {number} Interval, in milliseconds, between automatic flushes
+    when `autoFlush` is enabled. **Default:** `30000`.
+  * `matchHeaders` {string[]} Names of the only headers to include when matching
+    a request against a snapshot. When omitted, all headers are matched.
+  * `ignoreHeaders` {string[]} Header names to ignore when matching a request.
+  * `excludeHeaders` {string[]} Header names to strip from snapshots entirely,
+    so that sensitive values are never written to disk.
+  * `matchBody` {boolean} When `true`, the request body is included in request
+    matching. **Default:** `true`.
+  * `normalizeBody` {Function} Normalizes the request body before it is matched
+    or stored, for example to strip volatile fields such as timestamps. Only
+    applied when `matchBody` is `true`.
+    * `body` {string|Buffer|null|undefined} The raw request body.
+    * Returns: {string} The normalized body used for matching.
+  * `matchQuery` {boolean} When `true`, query parameters are included in request
+    matching. **Default:** `true`.
+  * `normalizeQuery` {Function} Normalizes the query string before it is matched,
+    for example to strip cache-busting parameters. Only applied when `matchQuery`
+    is `true`.
+    * `query` {URLSearchParams} The parsed query parameters.
+    * Returns: {string} The normalized query string used for matching.
+  * `caseSensitive` {boolean} When `true`, header matching is case-sensitive.
+    **Default:** `false`.
+  * `shouldRecord` {Function} Decides whether a given request is recorded. Only
+    used in `'record'` and `'update'` modes.
+    * `requestOpts` {Object} The dispatch options of the request.
+    * Returns: {boolean} `true` to record the request.
+  * `shouldPlayback` {Function} Decides whether a given request is served from a
+    snapshot. Only used in `'playback'` and `'update'` modes.
+    * `requestOpts` {Object} The dispatch options of the request.
+    * Returns: {boolean} `true` to play the request back from a snapshot.
+  * `excludeUrls` {Array<string|RegExp>} URL patterns that are excluded from
+    recording and playback. String patterns match case-insensitively as
+    substrings of the URL; `RegExp` patterns are tested against the URL. Matching
+    requests are passed through to a real [`Agent`][] instead.
+
+Creates a new `SnapshotAgent`. Throws an [`InvalidArgumentError`][] when `mode`
+is `'playback'` or `'update'` and `snapshotPath` is not provided, and throws an
+`InvalidArgumentError` when `mode` is not one of the supported values.
+
+When `mode` is `'playback'` or `'update'` and `snapshotPath` is set, snapshots
+are loaded from the file automatically; a missing file is ignored until the first
+request requires it.
+
+```mjs
 import { SnapshotAgent, setGlobalDispatcher } from 'undici'
 
 const agent = new SnapshotAgent({
   mode: 'playback',
-  snapshotPath: './test/snapshots/api-calls.json'
-})
-setGlobalDispatcher(agent)
-
-// Uses recorded response instead of real request
-const response = await fetch('https://api.example.com/users')
-```
-
-#### Update Mode (`'update'`)
-Uses existing snapshots when available, but records new ones for missing requests.
-
-```javascript
-import { SnapshotAgent, setGlobalDispatcher } from 'undici'
-
-const agent = new SnapshotAgent({
-  mode: 'update',
-  snapshotPath: './test/snapshots/api-calls.json'
+  snapshotPath: './snapshots/api.json'
 })
 setGlobalDispatcher(agent)
-
-// Uses snapshot if exists, otherwise makes real request and records it
-const response = await fetch('https://api.example.com/new-endpoint')
 ```
 
-## Instance Methods
-
-### `agent.saveSnapshots([filePath])`
-
-Saves all recorded snapshots to a file.
-
-#### Parameters
-
-- **filePath** `String` (optional) - Path to save snapshots. Uses constructor `snapshotPath` if not provided.
-
-#### Returns
-
-`Promise<void>`
-
-```javascript
-await agent.saveSnapshots('./custom-snapshots.json')
-```
-
-## Advanced Configuration
-
-### Body Matching
-
-By default (`matchBody: true`) the full request body string is included in the snapshot key. Set it to `false` to ignore the body entirely, or use `normalizeBody` to strip volatile fields (like timestamps) before matching:
-
-```javascript
-const agent = new SnapshotAgent({
-  mode: 'playback',
-  snapshotPath: './snapshots.json',
-
-  // Match on everything except the timestamp field
-  normalizeBody: (body) => {
-    if (!body) return ''
-    const parsed = JSON.parse(String(body))
-    delete parsed.timestamp
-    return JSON.stringify(parsed)
-  }
-})
-```
-
-`normalizeBody` receives the raw body (`string | Buffer | null | undefined`) and must return a `string`. It runs at both record and playback time so the hash is consistent. Two requests match the same snapshot whenever their normalized strings are identical.
-
-### Header Filtering
-
-Control which headers are used for request matching and what gets stored in snapshots:
-
-```javascript
-const agent = new SnapshotAgent({
-  mode: 'record',
-  snapshotPath: './snapshots.json',
-  
-  // Only match these specific headers
-  matchHeaders: ['content-type', 'accept'],
-  
-  // Ignore these headers during matching (but still store them)
-  ignoreHeaders: ['user-agent', 'date'],
-  
-  // Exclude sensitive headers from snapshots entirely
-  excludeHeaders: ['authorization', 'x-api-key', 'cookie']
-})
-```
+The mode controls how requests are handled:
 
-### Custom Request/Response Filtering
+* `'record'` performs the real request and stores the response.
 
-Use callback functions to determine what gets recorded or played back:
+  ```mjs
+  import { SnapshotAgent, setGlobalDispatcher, fetch } from 'undici'
 
-```javascript
-const agent = new SnapshotAgent({
-  mode: 'record',
-  snapshotPath: './snapshots.json',
-  
-  // Only record GET requests to specific endpoints
-  shouldRecord: (requestOpts) => {
-    const url = new URL(requestOpts.path, requestOpts.origin)
-    return requestOpts.method === 'GET' && url.pathname.startsWith('/api/v1/')
-  },
-  
-  // Skip authentication endpoints during playback
-  shouldPlayback: (requestOpts) => {
-    const url = new URL(requestOpts.path, requestOpts.origin)
-    return !url.pathname.includes('/auth/')
-  }
-})
-```
-
-### URL Pattern Exclusion
-
-Exclude specific URLs from recording/playback using patterns:
-
-```javascript
-const agent = new SnapshotAgent({
-  mode: 'record',
-  snapshotPath: './snapshots.json',
-  
-  excludeUrls: [
-    'https://analytics.example.com',  // String match
-    /\/api\/v\d+\/health/,           // Regex pattern
-    'telemetry'                      // Substring match
-  ]
-})
-```
-
-### Memory Management
-
-Configure automatic memory and disk management:
-
-```javascript
-const agent = new SnapshotAgent({
-  mode: 'record',
-  snapshotPath: './snapshots.json',
-  
-  // Keep only 1000 snapshots in memory
-  maxSnapshots: 1000,
-  
-  // Automatically save to disk every 30 seconds
-  autoFlush: true,
-  flushInterval: 30000
-})
-```
-
-### Sequential Response Handling
-
-Handle multiple responses for the same request (similar to nock):
-
-```javascript
-// In record mode, multiple identical requests get recorded as separate responses
-const agent = new SnapshotAgent({ mode: 'record', snapshotPath: './sequential.json' })
+  const agent = new SnapshotAgent({
+    mode: 'record',
+    snapshotPath: './snapshots/api.json'
+  })
+  setGlobalDispatcher(agent)
 
-// First call returns response A
-await fetch('https://api.example.com/random')
+  await fetch('https://api.example.com/users')
+  await agent.saveSnapshots()
+  ```
 
-// Second call returns response B  
-await fetch('https://api.example.com/random')
+* `'playback'` serves the recorded response without any network access. A
+  request with no matching snapshot rejects with an [`UndiciError`][] whose
+  message begins with `No snapshot found`.
 
-await agent.saveSnapshots()
+  ```mjs
+  import { SnapshotAgent, setGlobalDispatcher, fetch } from 'undici'
 
-// In playback mode, calls return responses in sequence
-const playbackAgent = new SnapshotAgent({ mode: 'playback', snapshotPath: './sequential.json' })
+  const agent = new SnapshotAgent({
+    mode: 'playback',
+    snapshotPath: './snapshots/api.json'
+  })
+  setGlobalDispatcher(agent)
 
-// Returns response A
-const first = await fetch('https://api.example.com/random')
+  const response = await fetch('https://api.example.com/users')
+  ```
 
-// Returns response B
-const second = await fetch('https://api.example.com/random')
+* `'update'` replays an existing snapshot when one is found and otherwise records
+  the request like `'record'` mode.
 
-// Third call repeats the last response (B)
-const third = await fetch('https://api.example.com/random')
-```
+  ```mjs
+  import { SnapshotAgent, setGlobalDispatcher, fetch } from 'undici'
 
-## Managing Snapshots
+  const agent = new SnapshotAgent({
+    mode: 'update',
+    snapshotPath: './snapshots/api.json'
+  })
+  setGlobalDispatcher(agent)
 
-### Replacing Existing Snapshots
+  await fetch('https://api.example.com/new-endpoint')
+  ```
 
-```javascript
-// Load existing snapshots
-await agent.loadSnapshots('./old-snapshots.json')
+### `agent.loadSnapshots([filePath])`
 
-// Get snapshot data
-const recorder = agent.getRecorder()
-const snapshots = recorder.getSnapshots()
+<!-- YAML
+added: v7.13.0
+-->
 
-// Modify or filter snapshots
-const filteredSnapshots = snapshots.filter(s => 
-  !s.request.url.includes('deprecated')
-)
+* `filePath` {string} (optional) Path to read snapshots from. **Default:** the
+  `snapshotPath` given to the constructor.
+* Returns: {Promise<void>} Resolves when the snapshots have been loaded.
 
-// Replace all snapshots
-agent.replaceSnapshots(filteredSnapshots.map((snapshot, index) => ({
-  hash: `new-hash-${index}`,
-  snapshot
-})))
+Loads snapshots from disk into memory. In `'playback'` mode this also installs
+the corresponding [`MockAgent`][] interceptors so that subsequent requests are
+matched against the loaded snapshots.
 
-// Save updated snapshots
-await agent.saveSnapshots('./updated-snapshots.json')
+```mjs
+await agent.loadSnapshots('./snapshots/api.json')
 ```
 
-### `agent.loadSnapshots([filePath])`
-
-Loads snapshots from a file.
-
-#### Parameters
+### `agent.saveSnapshots([filePath])`
 
-- **filePath** `String` (optional) - Path to load snapshots from. Uses constructor `snapshotPath` if not provided.
+<!-- YAML
+added: v7.13.0
+-->
 
-#### Returns
+* `filePath` {string} (optional) Path to write snapshots to. **Default:** the
+  `snapshotPath` given to the constructor.
+* Returns: {Promise<void>} Resolves when the snapshots have been written.
 
-`Promise<void>`
+Writes all recorded snapshots to disk.
 
-```javascript
-await agent.loadSnapshots('./existing-snapshots.json')
+```mjs
+await agent.saveSnapshots('./snapshots/api.json')
 ```
 
 ### `agent.getRecorder()`
 
-Gets the underlying `SnapshotRecorder` instance.
+<!-- YAML
+added: v7.13.0
+-->
 
-#### Returns
+* Returns: {SnapshotRecorder} The internal recorder that stores the captured
+  interactions.
 
-`SnapshotRecorder`
+Returns the underlying `SnapshotRecorder`. The recorder exposes lower-level
+operations over the captured data, including `record()`, `findSnapshot()`,
+`getSnapshots()`, `size()`, and `clear()`. The recorder is an internal type
+returned for inspection; it is not exported from the package root.
 
-```javascript
+```mjs
 const recorder = agent.getRecorder()
 console.log(`Recorded ${recorder.size()} interactions`)
 ```
 
 ### `agent.getMode()`
 
-Gets the current snapshot mode.
+<!-- YAML
+added: v7.13.0
+-->
 
-#### Returns
+* Returns: {string} The current mode: `'record'`, `'playback'`, or `'update'`.
 
-`String` - The current mode (`'record'`, `'playback'`, or `'update'`)
+Returns the mode the agent was constructed with.
 
 ### `agent.clearSnapshots()`
 
-Clears all recorded snapshots from memory.
+<!-- YAML
+added: v7.13.0
+-->
 
-```javascript
-agent.clearSnapshots()
-```
-
-## Working with Different Request Types
-
-### GET Requests
-
-```javascript
-// Record mode
-const agent = new SnapshotAgent({ mode: 'record', snapshotPath: './get-snapshots.json' })
-setGlobalDispatcher(agent)
-
-const response = await fetch('https://jsonplaceholder.typicode.com/posts/1')
-const post = await response.json()
-
-await agent.saveSnapshots()
-```
-
-### POST Requests with Body
-
-```javascript
-// Record mode
-const agent = new SnapshotAgent({ mode: 'record', snapshotPath: './post-snapshots.json' })
-setGlobalDispatcher(agent)
-
-const response = await fetch('https://jsonplaceholder.typicode.com/posts', {
-  method: 'POST',
-  headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify({ title: 'Test Post', body: 'Content' })
-})
-
-await agent.saveSnapshots()
-```
-
-### Using with `undici.request`
-
-SnapshotAgent works with all undici APIs, not just fetch:
-
-```javascript
-import { SnapshotAgent, request, setGlobalDispatcher } from 'undici'
-
-const agent = new SnapshotAgent({ mode: 'record', snapshotPath: './request-snapshots.json' })
-setGlobalDispatcher(agent)
+* Returns: {undefined}
 
-const { statusCode, headers, body } = await request('https://api.example.com/data')
-const data = await body.json()
+Removes all snapshots from memory.
 
-await agent.saveSnapshots()
-```
-
-## Test Integration
-
-### Basic Test Setup
-
-```javascript
-import { test } from 'node:test'
-import { SnapshotAgent, setGlobalDispatcher, getGlobalDispatcher } from 'undici'
-
-test('API integration test', async (t) => {
-  const originalDispatcher = getGlobalDispatcher()
-  
-  const agent = new SnapshotAgent({
-    mode: 'playback',
-    snapshotPath: './test/snapshots/api-test.json'
-  })
-  setGlobalDispatcher(agent)
-  
-  t.after(() => setGlobalDispatcher(originalDispatcher))
-  
-  // This will use recorded data
-  const response = await fetch('https://api.example.com/users')
-  const users = await response.json()
-  
-  assert(Array.isArray(users))
-  assert(users.length > 0)
-})
+```mjs
+agent.clearSnapshots()
 ```
 
-### Environment-Based Mode Selection
-
-```javascript
-const mode = process.env.SNAPSHOT_MODE || 'playback'
-
-const agent = new SnapshotAgent({
-  mode,
-  snapshotPath: './test/snapshots/integration.json'
-})
+### `agent.resetCallCounts()`
 
-// Run with: SNAPSHOT_MODE=record npm test (to record)
-// Run with: npm test (to playback)
-```
+<!-- YAML
+added: v7.13.0
+-->
 
-### Test Helper Function
+* Returns: {undefined}
 
-```javascript
-function createSnapshotAgent(testName, mode = 'playback') {
-  return new SnapshotAgent({
-    mode,
-    snapshotPath: `./test/snapshots/${testName}.json`
-  })
-}
+Resets the call count of every snapshot to zero. Useful between tests when the
+same agent is reused, since matching a snapshot in `'playback'` mode increments
+its call count.
 
-test('user API test', async (t) => {
-  const agent = createSnapshotAgent('user-api')
-  setGlobalDispatcher(agent)
-  
-  // Test implementation...
-})
+```mjs
+agent.resetCallCounts()
 ```
 
-## Snapshot File Format
-
-Snapshots are stored as JSON with the following structure:
-
-```json
-[
-  {
-    "hash": "dGVzdC1oYXNo...",
-    "snapshot": {
-      "request": {
-        "method": "GET",
-        "url": "https://api.example.com/users",
-        "headers": {
-          "authorization": "Bearer token"
-        },
-        "body": undefined
-      },
-      "response": {
-        "statusCode": 200,
-        "headers": {
-          "content-type": "application/json"
-        },
-        "body": "eyJkYXRhIjoidGVzdCJ9", // base64 encoded
-        "trailers": {}
-      },
-      "timestamp": "2024-01-01T00:00:00.000Z"
-    }
-  }
-]
-```
+### `agent.deleteSnapshot(requestOpts)`
 
-## Security Considerations
+<!-- YAML
+added: v7.13.0
+-->
 
-### Sensitive Data in Snapshots
+* `requestOpts` {Object} Dispatch options identifying the snapshot to remove.
+* Returns: {boolean} `true` if a matching snapshot was deleted, `false` if none
+  was found.
 
-By default, SnapshotAgent records all headers and request/response data. For production use, always exclude sensitive information:
+Deletes a single snapshot that matches the given request options.
 
-```javascript
-const agent = new SnapshotAgent({
-  mode: 'record',
-  snapshotPath: './snapshots.json',
-  
-  // Exclude sensitive headers from snapshots
-  excludeHeaders: [
-    'authorization',
-    'x-api-key', 
-    'cookie',
-    'set-cookie',
-    'x-auth-token',
-    'x-csrf-token'
-  ],
-  
-  // Filter out requests with sensitive data
-  shouldRecord: (requestOpts) => {
-    const url = new URL(requestOpts.path, requestOpts.origin)
-    
-    // Don't record authentication endpoints
-    if (url.pathname.includes('/auth/') || url.pathname.includes('/login')) {
-      return false
-    }
-    
-    // Don't record if request contains sensitive body data
-    if (requestOpts.body && typeof requestOpts.body === 'string') {
-      const body = requestOpts.body.toLowerCase()
-      if (body.includes('password') || body.includes('secret')) {
-        return false
-      }
-    }
-    
-    return true
-  }
+```mjs
+const deleted = agent.deleteSnapshot({
+  method: 'GET',
+  origin: 'https://api.example.com',
+  path: '/users'
 })
 ```
 
-### Snapshot File Security
-
-**Important**: Snapshot files may contain sensitive data. Handle them securely:
-
-- ✅ Add snapshot files to `.gitignore` if they contain real API data
-- ✅ Use environment-specific snapshots (dev/staging/prod)
-- ✅ Regularly review snapshot contents for sensitive information
-- ✅ Use the `excludeHeaders` option for production snapshots
-- ❌ Never commit snapshots with real authentication tokens
-- ❌ Don't share snapshot files containing personal data
-
-```gitignore
-# Exclude snapshots with real data
-/test/snapshots/production-*.json
-/test/snapshots/*-real-data.json
-
-# Include sanitized test snapshots
-!/test/snapshots/mock-*.json
-```
-
-## Error Handling
-
-### Missing Snapshots in Playback Mode
-
-```javascript
-try {
-  const response = await fetch('https://api.example.com/nonexistent')
-} catch (error) {
-  if (error.message.includes('No snapshot found')) {
-    // Handle missing snapshot
-    console.log('Snapshot not found for this request')
-  }
-}
-```
-
-### Handling Network Errors in Record Mode
-
-```javascript
-const agent = new SnapshotAgent({ mode: 'record', snapshotPath: './snapshots.json' })
-
-try {
-  const response = await fetch('https://nonexistent-api.example.com/data')
-} catch (error) {
-  // Network errors are not recorded as snapshots
-  console.log('Network error:', error.message)
-}
-```
-
-## Best Practices
-
-### 1. Organize Snapshots by Test Suite
-
-```javascript
-// Use descriptive snapshot file names
-const agent = new SnapshotAgent({
-  mode: 'playback',
-  snapshotPath: `./test/snapshots/${testSuiteName}-${testName}.json`
+### `agent.getSnapshotInfo(requestOpts)`
+
+<!-- YAML
+added: v7.13.0
+-->
+
+* `requestOpts` {Object} Dispatch options identifying the snapshot to inspect.
+* Returns: {Object|null} Information about the matching snapshot, or `null` when
+  none is found.
+  * `hash` {string} The hash used to key the snapshot.
+  * `request` {Object} The recorded request.
+    * `method` {string} The request method.
+    * `url` {string} The request URL.
+    * `headers` {Record<string, string>} The recorded request headers.
+    * `body` {string} The recorded request body, when present.
+  * `responseCount` {number} The number of recorded responses for the request.
+  * `callCount` {number} The number of times the snapshot has been matched.
+  * `timestamp` {string} The ISO timestamp at which the snapshot was recorded.
+
+Returns metadata about a snapshot without returning the response payload.
+
+```mjs
+const info = agent.getSnapshotInfo({
+  method: 'GET',
+  origin: 'https://api.example.com',
+  path: '/users'
 })
 ```
 
-### 2. Version Control Snapshots
-
-Add snapshot files to version control to ensure consistent test behavior across environments:
+### `agent.replaceSnapshots(snapshotData)`
 
-```gitignore
-# Include snapshots in version control
-!/test/snapshots/*.json
-```
+<!-- YAML
+added: v7.13.0
+-->
 
-### 3. Clean Up Test Data
+* `snapshotData` {Array} The snapshot data to load, replacing any existing
+  snapshots.
+  * `hash` {string} The hash used to key the snapshot.
+  * `snapshot` {Object} The snapshot entry.
+* Returns: {undefined}
 
-```javascript
-test('API test', async (t) => {
-  const agent = new SnapshotAgent({
-    mode: 'playback',
-    snapshotPath: './test/snapshots/temp-test.json'
-  })
-  
-  // Clean up after test
-  t.after(() => {
-    agent.clearSnapshots()
-  })
-})
-```
+Replaces all in-memory snapshots with the provided data.
 
-### 4. Snapshot Validation
+```mjs
+const recorder = agent.getRecorder()
+const snapshots = recorder.getSnapshots()
 
-```javascript
-test('validate snapshot contents', async (t) => {
-  const agent = new SnapshotAgent({
-    mode: 'playback',
-    snapshotPath: './test/snapshots/validation.json'
-  })
-  
-  const recorder = agent.getRecorder()
-  const snapshots = recorder.getSnapshots()
-  
-  // Validate snapshot structure
-  assert(snapshots.length > 0, 'Should have recorded snapshots')
-  assert(snapshots[0].request.url.startsWith('https://'), 'Should use HTTPS')
-})
+agent.replaceSnapshots(snapshots.map((snapshot, index) => ({
+  hash: `snapshot-${index}`,
+  snapshot
+})))
 ```
 
-## Comparison with Other Tools
-
-### vs Manual MockAgent Setup
+### `agent.close()`
 
-**Manual MockAgent:**
-```javascript
-const mockAgent = new MockAgent()
-const mockPool = mockAgent.get('https://api.example.com')
+<!-- YAML
+added: v7.13.0
+-->
 
-mockPool.intercept({
-  path: '/users',
-  method: 'GET'
-}).reply(200, [
-  { id: 1, name: 'User 1' },
-  { id: 2, name: 'User 2' }
-])
-```
+* Returns: {Promise<void>} Resolves once the agent and its resources are closed.
 
-**SnapshotAgent:**
-```javascript
-// Record once
-const agent = new SnapshotAgent({ mode: 'record', snapshotPath: './snapshots.json' })
-// Real API call gets recorded automatically
+Closes the agent and releases its resources. In `'record'` and `'update'` modes
+the recorder is flushed to disk first. In `'playback'` mode nothing is written,
+because matching a snapshot mutates its call count and saving would needlessly
+rewrite the snapshot file. The real [`Agent`][], when one was created, and the
+underlying [`MockAgent`][] are closed as well.
 
-// Use in tests
-const agent = new SnapshotAgent({ mode: 'playback', snapshotPath: './snapshots.json' })
-// Automatically replays recorded response
+```mjs
+await agent.close()
 ```
 
-### vs nock
-
-SnapshotAgent provides similar functionality to nock but is specifically designed for undici:
-
-- ✅ Works with all undici APIs (`request`, `stream`, `pipeline`, etc.)
-- ✅ Supports undici-specific features (RetryAgent, connection pooling)
-- ✅ Better TypeScript integration
-- ✅ More efficient for high-performance scenarios
-
-## See Also
-
-- [MockAgent](/docs/docs/api/MockAgent.md) - Manual mocking for more control
-- [MockCallHistory](/docs/docs/api/MockCallHistory.md) - Inspecting request history
-- [Testing Best Practices](/docs/docs/best-practices/writing-tests.md) - General testing guidance
\ No newline at end of file
+[`Agent`]: Agent.md#class-agent
+[`Dispatcher`]: Dispatcher.md#class-dispatcher
+[`InvalidArgumentError`]: Errors.md#undicierrorsundiciinvalidargumenterror
+[`MockAgent`]: MockAgent.md#class-mockagent
+[`UndiciError`]: Errors.md#undicierrorsundicierror
+[`agent.getRecorder()`]: #agentgetrecorder
+[`setGlobalDispatcher()`]: Dispatcher.md#setglobaldispatcherdispatcher
diff --git a/docs/docs/api/Socks5ProxyAgent.md b/docs/docs/api/Socks5ProxyAgent.md
index 3ef0f852f27..21fec19b141 100644
--- a/docs/docs/api/Socks5ProxyAgent.md
+++ b/docs/docs/api/Socks5ProxyAgent.md
@@ -1,275 +1,250 @@
-# Class: Socks5ProxyAgent
+# Socks5ProxyAgent
 
-Extends: `undici.Dispatcher`
+<!--introduced_in=v7.23.0-->
+<!--type=module-->
+<!-- source_link=lib/dispatcher/socks5-proxy-agent.js -->
 
-A SOCKS5 proxy wrapper class that implements the Dispatcher API. It enables HTTP requests to be routed through a SOCKS5 proxy server, providing connection tunneling and authentication support.
+> Stability: 1 - Experimental
 
-## `new Socks5ProxyAgent(proxyUrl[, options])`
+A [`Dispatcher`][] implementation that routes requests through a [SOCKS5][]
+proxy server. It tunnels both HTTP and HTTPS traffic over the proxy, supports
+optional username/password authentication, and pools connections per origin so
+that subsequent requests to the same host reuse the established tunnel.
 
-Arguments:
+DNS resolution is delegated to the proxy: target host names are sent to the
+proxy as domain names rather than being resolved locally. For HTTPS targets the
+TLS session is negotiated end-to-end through the tunnel, so the proxy only sees
+encrypted bytes.
 
-* **proxyUrl** `string | URL` (required) - The SOCKS5 proxy server URL. Must use `socks5://` or `socks://` protocol.
-* **options** `Socks5ProxyAgent.Options` (optional) - Additional configuration options.
+Import it from `'undici'`:
 
-Returns: `Socks5ProxyAgent`
-
-### Parameter: `Socks5ProxyAgent.Options`
-
-Extends: [`PoolOptions`](/docs/docs/api/Pool.md#parameter-pooloptions)
-
-* **headers** `IncomingHttpHeaders` (optional) - Additional headers to send with proxy connections.
-* **username** `string` (optional) - SOCKS5 proxy username for authentication. Can also be provided in the proxy URL.
-* **password** `string` (optional) - SOCKS5 proxy password for authentication. Can also be provided in the proxy URL.
-* **connect** `Function` (optional) - Custom connector function for the proxy connection.
-* **proxyTls** `BuildOptions` (optional) - TLS options for the proxy connection (when using SOCKS5 over TLS).
-* **requestTls** `BuildOptions` (optional) - TLS options applied to the HTTPS connection to the target server through the SOCKS5 tunnel. Use this to configure `ca`, `cert`, `key`, `rejectUnauthorized`, `servername`, etc. for the target HTTPS endpoint.
-
-Examples:
-
-```js
+```mjs
 import { Socks5ProxyAgent } from 'undici'
-
-const socks5Proxy = new Socks5ProxyAgent('socks5://localhost:1080')
-// or with authentication
-const socks5ProxyWithAuth = new Socks5ProxyAgent('socks5://user:pass@localhost:1080')
-// or with options
-const socks5ProxyWithOptions = new Socks5ProxyAgent('socks5://localhost:1080', {
-  username: 'user',
-  password: 'pass',
-  connections: 10
-})
 ```
 
-#### Example - Basic SOCKS5 Proxy instantiation
+Constructing the agent emits a one-time `ExperimentalWarning`, reflecting the
+experimental status of SOCKS5 support.
 
-This will instantiate the Socks5ProxyAgent. It will not do anything until registered as the dispatcher to use with requests.
+## Class: `Socks5ProxyAgent`
 
-```js
-import { Socks5ProxyAgent } from 'undici'
+<!-- YAML
+added: v7.23.0
+-->
 
-const socks5Proxy = new Socks5ProxyAgent('socks5://localhost:1080')
-```
+> Stability: 1 - Experimental
 
-#### Example - Basic SOCKS5 Proxy Request with global dispatcher
+* Extends: {Dispatcher}
 
-```js
-import { setGlobalDispatcher, request, Socks5ProxyAgent } from 'undici'
+Routes dispatched requests through a SOCKS5 proxy. Register an instance as the
+global dispatcher with [`setGlobalDispatcher()`][], or pass it per request via
+the `dispatcher` option.
 
-const socks5Proxy = new Socks5ProxyAgent('socks5://localhost:1080')
-setGlobalDispatcher(socks5Proxy)
+### `new Socks5ProxyAgent(proxyUrl[, options])`
 
-const { statusCode, body } = await request('http://localhost:3000/foo')
+<!-- YAML
+added: v7.23.0
+-->
 
-console.log('response received', statusCode) // response received 200
+> Stability: 1 - Experimental
 
-for await (const data of body) {
-  console.log('data', data.toString('utf8')) // data foo
-}
-```
-
-#### Example - Basic SOCKS5 Proxy Request with local dispatcher
+* `proxyUrl` {string|URL} The SOCKS5 proxy server URL. Must use the `socks5:` or
+  `socks:` protocol. Credentials may be embedded in the URL userinfo (for
+  example `socks5://user:pass@host:1080`).
+* `options` {Object} (optional) Extends {PoolOptions}; the pool options are
+  applied to the per-origin pools created behind the tunnel.
+  * `headers` {Object} Additional headers to send with the proxy connection.
+    **Default:** `{}`.
+  * `username` {string} Username for SOCKS5 authentication. Takes precedence over
+    a username embedded in `proxyUrl`. **Default:** the URL username, if any.
+  * `password` {string} Password for SOCKS5 authentication. Takes precedence over
+    a password embedded in `proxyUrl`. **Default:** the URL password, if any.
+  * `connect` {Function} Custom connector used to open the socket to the proxy.
+    **Default:** a connector built from `proxyTls`.
+  * `proxyTls` {BuildOptions} TLS options for the connection to the proxy itself
+    (SOCKS5 over TLS). When set, the proxy connection is established over TLS and
+    `servername` defaults to the proxy host name.
+  * `requestTls` {BuildOptions} TLS options applied to the end-to-end connection
+    to an HTTPS target through the tunnel, such as `ca`, `cert`, `key`,
+    `rejectUnauthorized`, and `servername`. `servername` defaults to the target
+    host name.
 
-```js
-import { Socks5ProxyAgent, request } from 'undici'
+Throws an `InvalidArgumentError` if `proxyUrl` is missing or does not use the
+`socks5:` or `socks:` protocol.
 
-const socks5Proxy = new Socks5ProxyAgent('socks5://localhost:1080')
+```mjs
+import { Socks5ProxyAgent } from 'undici'
 
-const {
-  statusCode,
-  body
-} = await request('http://localhost:3000/foo', { dispatcher: socks5Proxy })
+// Without authentication.
+const agent = new Socks5ProxyAgent('socks5://localhost:1080')
 
-console.log('response received', statusCode) // response received 200
+// With credentials in the URL.
+const authAgent = new Socks5ProxyAgent('socks5://user:pass@localhost:1080')
 
-for await (const data of body) {
-  console.log('data', data.toString('utf8')) // data foo
-}
+// With credentials and pool options.
+const configuredAgent = new Socks5ProxyAgent('socks5://localhost:1080', {
+  username: 'user',
+  password: 'pass',
+  connections: 10
+})
 ```
 
-#### Example - SOCKS5 Proxy Request with authentication
+Using the agent as the global dispatcher:
 
-```js
+```mjs
 import { setGlobalDispatcher, request, Socks5ProxyAgent } from 'undici'
 
-// Authentication via URL
-const socks5Proxy = new Socks5ProxyAgent('socks5://username:password@localhost:1080')
-
-// Or authentication via options
-// const socks5Proxy = new Socks5ProxyAgent('socks5://localhost:1080', {
-//   username: 'username',
-//   password: 'password'
-// })
-
-setGlobalDispatcher(socks5Proxy)
+const agent = new Socks5ProxyAgent('socks5://localhost:1080')
+setGlobalDispatcher(agent)
 
 const { statusCode, body } = await request('http://localhost:3000/foo')
-
-console.log('response received', statusCode) // response received 200
+console.log('response received', statusCode)
 
 for await (const data of body) {
-  console.log('data', data.toString('utf8')) // data foo
+  console.log('data', data.toString('utf8'))
 }
 ```
 
-#### Example - SOCKS5 Proxy with HTTPS requests
-
-SOCKS5 proxy supports both HTTP and HTTPS requests through tunneling:
+Using the agent per request:
 
-```js
-import { Socks5ProxyAgent, request } from 'undici'
+```mjs
+import { request, Socks5ProxyAgent } from 'undici'
 
-const socks5Proxy = new Socks5ProxyAgent('socks5://localhost:1080')
+const agent = new Socks5ProxyAgent('socks5://localhost:1080')
 
-const response = await request('https://api.example.com/data', {
-  dispatcher: socks5Proxy,
-  method: 'GET'
+const { statusCode, body } = await request('http://localhost:3000/foo', {
+  dispatcher: agent
 })
 
-console.log('Response status:', response.statusCode)
-console.log('Response data:', await response.body.json())
+console.log('response received', statusCode)
 ```
 
-#### Example - SOCKS5 Proxy with Fetch
+HTTPS targets are tunnelled and encrypted end-to-end:
 
-```js
-import { Socks5ProxyAgent, fetch } from 'undici'
+```mjs
+import { request, Socks5ProxyAgent } from 'undici'
 
-const socks5Proxy = new Socks5ProxyAgent('socks5://localhost:1080')
+const agent = new Socks5ProxyAgent('socks5://localhost:1080')
 
-const response = await fetch('http://localhost:3000/api/users', {
-  dispatcher: socks5Proxy,
-  method: 'GET'
+const { statusCode, body } = await request('https://api.example.com/data', {
+  dispatcher: agent
 })
 
-console.log('Response status:', response.status)
-console.log('Response data:', await response.text())
+console.log('Response status:', statusCode)
+console.log('Response data:', await body.json())
 ```
 
-#### Example - Connection Pooling
+### `socks5ProxyAgent.close()`
 
-SOCKS5ProxyWrapper automatically manages connection pooling for better performance:
+<!-- YAML
+added: v7.23.0
+-->
 
-```js
-import { Socks5ProxyAgent, request } from 'undici'
+> Stability: 1 - Experimental
 
-const socks5Proxy = new Socks5ProxyAgent('socks5://localhost:1080', {
-  connections: 10, // Allow up to 10 concurrent connections
-  pipelining: 1    // Enable HTTP/1.1 pipelining
-})
+* Returns: {Promise<void>} Resolves once every per-origin pool has been closed.
 
-// Multiple requests will reuse connections through the SOCKS5 tunnel
-const responses = await Promise.all([
-  request('http://api.example.com/endpoint1', { dispatcher: socks5Proxy }),
-  request('http://api.example.com/endpoint2', { dispatcher: socks5Proxy }),
-  request('http://api.example.com/endpoint3', { dispatcher: socks5Proxy })
-])
+Gracefully closes the agent, waiting for all underlying pools and their
+connections to drain and close before resolving.
 
-console.log('All requests completed through the same SOCKS5 proxy')
-```
+```mjs
+import { setGlobalDispatcher, Socks5ProxyAgent } from 'undici'
 
-### `Socks5ProxyAgent.close()`
+const agent = new Socks5ProxyAgent('socks5://localhost:1080')
+setGlobalDispatcher(agent)
 
-Closes the SOCKS5 proxy wrapper and waits for all underlying pools and connections to close before resolving.
+// ... make requests ...
 
-Returns: `Promise<void>`
-
-#### Example - clean up after tests are complete
-
-```js
-import { Socks5ProxyAgent, setGlobalDispatcher } from 'undici'
-
-const socks5Proxy = new Socks5ProxyAgent('socks5://localhost:1080')
-setGlobalDispatcher(socks5Proxy)
-
-// ... make requests
-
-await socks5Proxy.close()
+await agent.close()
 ```
 
-### `Socks5ProxyAgent.destroy([err])`
+### `socks5ProxyAgent.destroy([err])`
 
-Destroys the SOCKS5 proxy wrapper and all underlying connections immediately.
+<!-- YAML
+added: v7.23.0
+-->
 
-Arguments:
-* **err** `Error` (optional) - The error that caused the destruction.
+> Stability: 1 - Experimental
 
-Returns: `Promise<void>`
+* `err` {Error} (optional) The error to reject in-flight requests with.
+* Returns: {Promise<void>} Resolves once every per-origin pool has been
+  destroyed.
 
-#### Example - force close all connections
+Forcibly destroys the agent and all underlying connections immediately, without
+waiting for in-flight requests to complete.
 
-```js
+```mjs
 import { Socks5ProxyAgent } from 'undici'
 
-const socks5Proxy = new Socks5ProxyAgent('socks5://localhost:1080')
+const agent = new Socks5ProxyAgent('socks5://localhost:1080')
 
-// Force close all connections
-await socks5Proxy.destroy()
+await agent.destroy()
 ```
 
-### `Socks5ProxyAgent.dispatch(options, handlers)`
-
-Implements [`Dispatcher.dispatch(options, handlers)`](/docs/docs/api/Dispatcher.md#dispatcherdispatchoptions-handlers).
+### `socks5ProxyAgent.dispatch(options, handlers)`
 
-### `Socks5ProxyAgent.request(options[, callback])`
+<!-- YAML
+added: v7.23.0
+-->
 
-See [`Dispatcher.request(options [, callback])`](/docs/docs/api/Dispatcher.md#dispatcherrequestoptions-callback).
+> Stability: 1 - Experimental
 
-## Debugging
-
-SOCKS5 proxy connections can be debugged using Node.js diagnostics:
-
-```sh
-NODE_DEBUG=undici:socks5 node script.js
-```
+* `options` {DispatchOptions}
+* `handlers` {DispatchHandler}
+* Returns: {boolean} `false` if the dispatcher is busy and the request should be
+  retried later, otherwise `true`.
 
-This will output detailed information about the SOCKS5 handshake, authentication, and connection establishment.
+Routes a request through the SOCKS5 tunnel. The agent maintains a [`Pool`][] per
+target origin; the first request to a given origin establishes the tunnel and
+upgrades to TLS when the target is HTTPS, and later requests reuse the pool.
 
-## SOCKS5 Protocol Support
+This is the lower-level entry point implementing
+[`Dispatcher.dispatch(options, handlers)`][]. Prefer
+[`socks5ProxyAgent.request()`][] for most use cases.
 
-The Socks5ProxyAgent supports the following SOCKS5 features:
+### `socks5ProxyAgent.request(options[, callback])`
 
-### Authentication Methods
+<!-- YAML
+added: v7.23.0
+-->
 
-- **No Authentication** (`0x00`) - For public or internal proxies
-- **Username/Password** (`0x02`) - RFC 1929 authentication
+> Stability: 1 - Experimental
 
-### Address Types
+* `options` {DispatchOptions}
+* `callback` {Function} (optional)
+* Returns: {Promise|void} A promise resolving to the response when `callback` is
+  omitted.
 
-- **IPv4** (`0x01`) - Standard IPv4 addresses
-- **Domain Name** (`0x03`) - Domain names (recommended for flexibility)
-- **IPv6** (`0x04`) - IPv6 addresses (full support for standard and compressed notation)
+Performs a request through the SOCKS5 proxy. Inherited from
+[`Dispatcher.request(options[, callback])`][]; see that method for the full set
+of options and the shape of the resolved response.
 
-### Commands
+```mjs
+import { fetch, Socks5ProxyAgent } from 'undici'
 
-- **CONNECT** (`0x01`) - Establish TCP connection (primary use case for HTTP)
+const agent = new Socks5ProxyAgent('socks5://localhost:1080')
 
-### Error Handling
-
-The wrapper handles various SOCKS5 error conditions:
-
-- Connection refused by proxy
-- Authentication failures
-- Network unreachable
-- Host unreachable
-- Unsupported address types or commands
+const response = await fetch('http://localhost:3000/api/users', {
+  dispatcher: agent
+})
 
-## Performance Considerations
+console.log('Response status:', response.status)
+console.log('Response data:', await response.text())
+```
 
-- **Connection Pooling**: Automatically pools connections through the SOCKS5 tunnel for better performance
-- **HTTP/1.1 Pipelining**: Supports pipelining when enabled
-- **DNS Resolution**: Domain names are resolved by the SOCKS5 proxy, reducing local DNS queries
-- **TLS Termination**: HTTPS connections are encrypted end-to-end, with the SOCKS5 proxy only handling the TCP tunnel
+## Debugging
 
-## Security Notes
+SOCKS5 proxy activity can be traced with the `undici:socks5-proxy` debug scope:
 
-1. **Authentication**: Credentials are sent to the SOCKS5 proxy in plaintext unless using SOCKS5 over TLS
-2. **DNS Leaks**: All DNS resolution happens on the proxy server, preventing DNS leaks
-3. **End-to-end Encryption**: HTTPS traffic remains encrypted between client and final destination
-4. **Connection Security**: Consider using authenticated proxies and secure networks
+```bash
+NODE_DEBUG=undici:socks5-proxy node script.js
+```
 
-## Compatibility
+This logs the SOCKS5 handshake, authentication, and tunnel establishment steps.
 
-- **Protocol**: SOCKS5 (RFC 1928) with Username/Password Authentication (RFC 1929)
-- **Transport**: TCP only (UDP support not implemented)
-- **Node.js**: Compatible with all supported Node.js versions
-- **HTTP Versions**: Works with HTTP/1.1 and HTTP/2 over the tunnel
\ No newline at end of file
+[SOCKS5]: https://www.rfc-editor.org/rfc/rfc1928
+[`Dispatcher.dispatch(options, handlers)`]: Dispatcher.md#dispatcherdispatchoptions-handler
+[`Dispatcher.request(options[, callback])`]: Dispatcher.md#dispatcherrequestoptions-callback
+[`Dispatcher`]: Dispatcher.md#class-dispatcher
+[`Pool`]: Pool.md#class-pool
+[`setGlobalDispatcher()`]: Dispatcher.md#setglobaldispatcherdispatcher
+[`socks5ProxyAgent.request()`]: #socks5proxyagentrequestoptions-callback
diff --git a/docs/docs/api/Util.md b/docs/docs/api/Util.md
index 53b96e3ed3f..2468c72224d 100644
--- a/docs/docs/api/Util.md
+++ b/docs/docs/api/Util.md
@@ -1,25 +1,82 @@
 # Util
 
-Utility API for third-party implementations of the dispatcher API.
+<!--introduced_in=v1.2.0-->
+<!--type=module-->
+<!-- source_link=lib/core/util.js -->
 
-## `parseHeaders(headers, [obj])`
+> Stability: 2 - Stable
 
-Receives a header object and returns the parsed value.
+A small set of utility helpers exposed for third-party implementations of the
+[`Dispatcher`][] API. They cover the header-handling primitives undici uses
+internally, so that custom dispatchers and handlers can normalize header names
+and parse raw header lists exactly the way undici does.
 
-Arguments:
+```mjs
+import { util } from 'undici'
 
-- **headers** `(Buffer | string | (Buffer | string)[])[]` (required) - Header object.
+const { parseHeaders, headerNameToString } = util
+```
 
-- **obj** `Record<string, string | string[]>` (optional) - Object to specify a proxy object. The parsed value is assigned to this object. But, if **headers** is an object, it is not used.
+```cjs
+const { util } = require('undici')
 
-Returns: `Record<string, string | string[]>` If **obj** is specified, it is equivalent to **obj**.
+const { parseHeaders, headerNameToString } = util
+```
+
+## `parseHeaders(headers[, obj])`
+
+<!-- YAML
+added: v1.2.0
+changes:
+  - version: v6.1.0
+    pr-url: https://github.com/nodejs/undici/pull/2501
+    description: Header names supplied as a `Buffer` are accepted and normalized.
+-->
+
+* `headers` {Array} A flat list of raw header entries where even indices are
+  header names and odd indices are the corresponding values. Each entry is a
+  {string}, {Buffer}, or an array of {string}/{Buffer}.
+* `obj` {Record<string, string|string[]>} An object to assign the parsed values
+  to. When omitted, a new object is created. **Default:** `{}`.
+* Returns: {Record<string, string|string[]>} The object the parsed headers were
+  assigned to. When `obj` is provided, the same reference is returned.
+
+Receives a flat list of raw header name/value pairs and returns them as an
+object keyed by lowercased header name. Header names are normalized with
+[`headerNameToString()`][], and `Buffer` values are decoded as `latin1`. When a
+header name appears more than once, its values are collected into an array.
+
+```mjs
+import { util } from 'undici'
+
+const raw = ['Content-Type', 'text/plain', 'Set-Cookie', 'a=1', 'Set-Cookie', 'b=2']
+
+console.log(util.parseHeaders(raw))
+// { 'content-type': 'text/plain', 'set-cookie': [ 'a=1', 'b=2' ] }
+```
 
 ## `headerNameToString(value)`
 
-Retrieves a header name and returns its lowercase value.
+<!-- YAML
+added: v6.1.0
+-->
+
+* `value` {string|Buffer} The header name to normalize.
+* Returns: {string} The lowercased header name.
+
+Returns the lowercased form of a header name. The `value` may be provided as a
+{string} or as a {Buffer}, in which case it is decoded as `latin1`. Common
+header names are resolved through an internal lookup table for performance.
+
+```mjs
+import { util } from 'undici'
 
-Arguments:
+console.log(util.headerNameToString('Content-Type'))
+// 'content-type'
 
-- **value** `string | Buffer` (required) - Header name.
+console.log(util.headerNameToString(Buffer.from('X-Custom-Header')))
+// 'x-custom-header'
+```
 
-Returns: `string`
+[`Dispatcher`]: Dispatcher.md#class-dispatcher
+[`headerNameToString()`]: #headernametostringvalue
diff --git a/docs/docs/api/WebSocket.md b/docs/docs/api/WebSocket.md
index 55a76aae64e..316d222915d 100644
--- a/docs/docs/api/WebSocket.md
+++ b/docs/docs/api/WebSocket.md
@@ -1,141 +1,536 @@
-# Class: WebSocket
+# WebSocket
 
-Extends: [`EventTarget`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget)
+<!--introduced_in=v5.15.0-->
+<!--type=module-->
+<!-- source_link=lib/web/websocket/websocket.js -->
 
-The WebSocket object provides a way to manage a WebSocket connection to a server, allowing bidirectional communication. The API follows the [WebSocket spec](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) and [RFC 6455](https://datatracker.ietf.org/doc/html/rfc6455).
+> Stability: 2 - Stable
 
-## `new WebSocket(url[, protocol])`
+The `WebSocket` API provides a way to manage a WebSocket connection to a
+server, allowing bidirectional communication. It follows the
+[WHATWG WebSocket specification][] and [RFC 6455][], and is intended to be
+interchangeable with the global `WebSocket` available in browsers.
 
-Arguments:
+```mjs
+import { WebSocket } from 'undici'
 
-* **url** `URL | string`
-* **protocol** `string | string[] | WebSocketInit` (optional) - Subprotocol(s) to request the server use, or a [`Dispatcher`](/docs/docs/api/Dispatcher.md).
+const ws = new WebSocket('wss://echo.websocket.events')
 
-### WebSocketInit
+ws.addEventListener('open', () => {
+  ws.send('Hello, world!')
+})
 
-When passing an object as the second argument, the following options are available:
+ws.addEventListener('message', (event) => {
+  console.log('received:', event.data)
+})
+```
 
-* **protocols** `string | string[]` (optional) - Subprotocol(s) to request the server use.
-* **dispatcher** `Dispatcher` (optional) - A custom [`Dispatcher`](/docs/docs/api/Dispatcher.md) to use for the connection.
-* **headers** `HeadersInit` (optional) - Custom headers to include in the WebSocket handshake request.
+In addition to the standard `WebSocket` interface, this module exports the
+streams-based [`WebSocketStream`][] and [`WebSocketError`][] APIs, as well as a
+[`ping()`][] helper for sending ping frames.
 
-### Example:
+## Class: `WebSocket`
 
-This example will not work in browsers or other platforms that don't allow passing an object.
+<!-- YAML
+added: v5.15.0
+-->
 
-```js
-import { WebSocket, ProxyAgent } from 'undici'
+* Extends: {EventTarget}
 
-const proxyAgent = new ProxyAgent('my.proxy.server')
+The `WebSocket` object represents a single WebSocket connection. Constructing a
+`WebSocket` immediately begins the opening handshake; the connection cannot be
+reused once it has been closed.
 
-const ws = new WebSocket('wss://echo.websocket.events', {
-  dispatcher: proxyAgent,
-  protocols: ['echo', 'chat']
-})
-```
+### `new WebSocket(url[, protocols])`
+
+<!-- YAML
+added: v5.15.0
+-->
+
+* `url` {URL|string} The URL of the server to connect to. Must use the `ws:`
+  or `wss:` scheme.
+* `protocols` {string|string[]|WebSocketInit} A single subprotocol, a list of
+  subprotocols to negotiate with the server, or a `WebSocketInit` object.
+  **Default:** `[]`.
+  * `protocols` {string|string[]} Subprotocol(s) to request the server use.
+    **Default:** `[]`.
+  * `dispatcher` {Dispatcher} The dispatcher used to open the connection.
+    **Default:** the global dispatcher.
+  * `headers` {HeadersInit|null} Additional headers to send with the handshake
+    request. (optional)
 
-If you do not need a custom Dispatcher, it's recommended to use the following pattern:
+Creates a new `WebSocket` and begins connecting to `url`. The second argument
+may be a string or array of subprotocols, or a `WebSocketInit` object. The
+object form is an undici extension and is not available in browsers; it allows a
+custom `dispatcher` and additional `headers` to be supplied.
 
-```js
+If a value in `protocols` is repeated or is not a valid subprotocol name, the
+constructor throws a `SyntaxError` `DOMException`.
+
+```mjs
 import { WebSocket } from 'undici'
 
 const ws = new WebSocket('wss://echo.websocket.events', ['echo', 'chat'])
 ```
 
-### Example with HTTP/2:
+To route the connection through a custom dispatcher, such as a
+[`ProxyAgent`][], pass a `WebSocketInit` object:
 
-> ⚠️ Warning: WebSocket over HTTP/2 is experimental, it is likely to change in the future.
+```mjs
+import { WebSocket, ProxyAgent } from 'undici'
 
-> 🗒️ Note: WebSocket over HTTP/2 may be enabled by default in a future version,
-> this will happen by enabling HTTP/2 connections as the default behavior of Undici's Agent as well the global dispatcher.
-> Stay tuned to the changelog for more information.
+const dispatcher = new ProxyAgent('http://localhost:8080')
 
-This example will not work in browsers or other platforms that don't allow passing an object.
+const ws = new WebSocket('wss://echo.websocket.events', {
+  dispatcher,
+  protocols: ['echo', 'chat']
+})
+```
 
-```js
-import { Agent } from 'undici'
+WebSocket over HTTP/2 is experimental and may change in the future. It can be
+enabled by passing a dispatcher configured with `allowH2`:
 
-const agent = new Agent({ allowH2: true })
+```mjs
+import { WebSocket, Agent } from 'undici'
+
+const dispatcher = new Agent({ allowH2: true })
 
 const ws = new WebSocket('wss://echo.websocket.events', {
-  dispatcher: agent,
+  dispatcher,
   protocols: ['echo', 'chat']
 })
 ```
 
-# Class: WebSocketStream
+### `websocket.close([code[, reason]])`
+
+<!-- YAML
+added: v5.15.0
+-->
 
-> ⚠️ Warning: the WebSocketStream API has not been finalized and is likely to change.
+* `code` {number} The status code explaining why the connection is being
+  closed. **Default:** `null`.
+* `reason` {string} A human-readable string explaining why the connection is
+  being closed. **Default:** `''`.
 
-See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/WebSocketStream) for more information.
+Starts the closing handshake. The `code` is clamped to an unsigned 16-bit
+integer; when omitted, no status code is sent. The `reason` is encoded as
+UTF-8 and must not exceed 123 bytes.
 
-## `new WebSocketStream(url[, protocol])`
+```mjs
+ws.close(1000, 'Done')
+```
 
-Arguments:
+### `websocket.send(data)`
 
-* **url** `URL | string`
-* **options** `WebSocketStreamOptions` (optional)
+<!-- YAML
+added: v5.15.0
+-->
 
-### WebSocketStream Example
+* `data` {string|ArrayBuffer|TypedArray|DataView|Blob} The data to enqueue for
+  transmission.
 
-```js
-const stream = new WebSocketStream('https://echo.websocket.org/')
-const { readable, writable } = await stream.opened
+Enqueues `data` to be transmitted to the server. String data is sent as a text
+frame; `ArrayBuffer`, any `TypedArray`, `DataView`, and `Blob` values are sent
+as binary frames. The number of bytes queued is added to
+[`websocket.bufferedAmount`][].
 
-async function read () {
-  /** @type {ReadableStreamReader} */
-  const reader = readable.getReader()
+If [`websocket.readyState`][] is `CONNECTING`, an `InvalidStateError`
+`DOMException` is thrown. If the connection is closing or already closed, the
+call is silently ignored.
 
-  while (true) {
-    const { done, value } = await reader.read()
-    if (done) break
+```mjs
+ws.send('a text message')
+ws.send(new Uint8Array([1, 2, 3]))
+```
 
-    // do something with value
-  }
-}
+### `websocket.readyState`
 
-async function write () {
-  /** @type {WritableStreamDefaultWriter} */
-  const writer = writable.getWriter()
-  writer.write('Hello, world!')
-  writer.releaseLock()
-}
+<!-- YAML
+added: v5.15.0
+-->
 
-read()
+* Type: {number}
 
-setInterval(() => write(), 5000)
+The current state of the connection. One of the numeric constants
+`WebSocket.CONNECTING` (`0`), `WebSocket.OPEN` (`1`),
+`WebSocket.CLOSING` (`2`), or `WebSocket.CLOSED` (`3`). This property is
+read-only.
 
-```
+### `websocket.bufferedAmount`
+
+<!-- YAML
+added: v5.15.0
+-->
+
+* Type: {number}
+
+The number of bytes of data that have been queued using
+[`websocket.send()`][] but not yet transmitted to the network. This value
+resets to `0` once all queued data is sent. This property is read-only.
+
+### `websocket.url`
+
+<!-- YAML
+added: v5.15.0
+-->
+
+* Type: {string}
+
+The absolute URL of the WebSocket as resolved during construction. This
+property is read-only.
+
+### `websocket.extensions`
+
+<!-- YAML
+added: v5.15.0
+-->
+
+* Type: {string}
+
+The extensions negotiated by the server, taken from the
+`Sec-WebSocket-Extensions` response header. Empty until the connection is
+established. This property is read-only.
+
+### `websocket.protocol`
+
+<!-- YAML
+added: v5.15.0
+-->
+
+* Type: {string}
+
+The subprotocol selected by the server, taken from the
+`Sec-WebSocket-Protocol` response header. Empty until the connection is
+established and only set when a subprotocol was negotiated. This property is
+read-only.
+
+### `websocket.binaryType`
+
+<!-- YAML
+added: v5.15.0
+-->
+
+* Type: {string} **Default:** `'blob'`.
+
+Controls the type used to represent binary data delivered by the
+[`'message'`][] event. Must be either `'blob'` (binary frames are exposed as a
+`Blob`) or `'arraybuffer'` (binary frames are exposed as an `ArrayBuffer`).
+Assigning any other value resets it to `'blob'`.
+
+### `websocket.onopen`
+
+<!-- YAML
+added: v5.15.0
+-->
+
+* Type: {Function|null} **Default:** `null`.
+
+An event handler for the [`'open'`][] event. Setting this property replaces any
+previously registered `onopen` handler.
+
+### `websocket.onerror`
+
+<!-- YAML
+added: v5.15.0
+-->
+
+* Type: {Function|null} **Default:** `null`.
+
+An event handler for the [`'error'`][] event. Setting this property replaces any
+previously registered `onerror` handler.
+
+### `websocket.onclose`
+
+<!-- YAML
+added: v5.15.0
+-->
+
+* Type: {Function|null} **Default:** `null`.
+
+An event handler for the [`'close'`][] event. Setting this property replaces any
+previously registered `onclose` handler.
+
+### `websocket.onmessage`
+
+<!-- YAML
+added: v5.15.0
+-->
+
+* Type: {Function|null} **Default:** `null`.
+
+An event handler for the [`'message'`][] event. Setting this property replaces
+any previously registered `onmessage` handler.
+
+### Event: `'open'`
+
+<!-- YAML
+added: v5.21.0
+-->
+
+Emitted when the WebSocket connection is established. After this event,
+[`websocket.readyState`][] is `OPEN` and data may be sent with
+[`websocket.send()`][]. The listener receives an `Event`.
+
+### Event: `'message'`
+
+<!-- YAML
+added: v7.0.0
+-->
+
+Emitted when a message is received from the server. The listener receives a
+`MessageEvent` whose `data` property is a `string` for text frames, and either a
+`Blob` or an `ArrayBuffer` for binary frames depending on
+[`websocket.binaryType`][]. The event's `origin` is the origin of
+[`websocket.url`][].
 
-## ping(websocket, payload)
-Arguments:
+### Event: `'error'`
 
-* **websocket** `WebSocket` - The WebSocket instance to send the ping frame on
-* **payload** `Buffer|undefined` (optional) - Optional payload data to include with the ping frame. Must not exceed 125 bytes.
+<!-- YAML
+added: v7.0.0
+-->
 
-Sends a ping frame to the WebSocket server. The server must respond with a pong frame containing the same payload data. This can be used for keepalive purposes or to verify that the connection is still active.
+Emitted when the connection is terminated abnormally, for example when no close
+frame was received before the underlying transport was lost. The listener
+receives an `ErrorEvent`.
 
-### Example:
+### Event: `'close'`
 
-```js
+<!-- YAML
+added: v7.0.0
+-->
+
+Emitted when the connection is closed. The listener receives a `CloseEvent`
+whose `code` and `reason` describe why the connection closed, and whose
+`wasClean` property is `true` only when the closing handshake completed in both
+directions.
+
+## `ping(websocket[, payload])`
+
+<!-- YAML
+added: v7.12.0
+-->
+
+* `websocket` {WebSocket} The WebSocket to send the ping frame on.
+* `payload` {Buffer} Optional payload to include in the ping frame. Must not
+  exceed 125 bytes. **Default:** `undefined`.
+
+Sends a ping control frame to the server. A conforming server replies with a
+pong frame containing the same payload, which can be used to keep the connection
+alive or to verify that it is still active.
+
+The frame is only sent when the connection is open; if it is connecting,
+closing, or closed, the call is a no-op. A `TypeError` is thrown if `payload`
+is not a `Buffer` or is larger than 125 bytes.
+
+```mjs
 import { WebSocket, ping } from 'undici'
 
 const ws = new WebSocket('wss://echo.websocket.events')
 
 ws.addEventListener('open', () => {
-  // Send ping with no payload
   ping(ws)
-
-  // Send ping with payload
-  const payload = Buffer.from('hello')
-  ping(ws, payload)
+  ping(ws, Buffer.from('hello'))
 })
 ```
 
-**Note**: A ping frame cannot have a payload larger than 125 bytes. The ping will only be sent if the WebSocket connection is in the OPEN state.
+## Class: `WebSocketStream`
+
+<!-- YAML
+added: v7.0.0
+-->
+
+> Stability: 1 - Experimental
+
+`WebSocketStream` is a streams-based alternative to the event-based
+[`WebSocket`][] interface, exposing a connection as a pair of `ReadableStream`
+and `WritableStream` objects. See [MDN][MDN WebSocketStream] for background.
+
+Constructing a `WebSocketStream` for the first time emits an
+`ExperimentalWarning` with the code `UNDICI-WSS`.
+
+### `new WebSocketStream(url[, options])`
+
+<!-- YAML
+added: v7.0.0
+-->
+
+> Stability: 1 - Experimental
+
+* `url` {URL|string} The URL of the server to connect to.
+* `options` {WebSocketStreamOptions}
+  * `protocols` {string|string[]} Subprotocol(s) to request the server use.
+    **Default:** `[]`.
+  * `signal` {AbortSignal|null} An `AbortSignal` that aborts the opening
+    handshake and rejects [`webSocketStream.opened`][] and
+    [`webSocketStream.closed`][] when triggered. **Default:** `null`.
+
+Creates a new `WebSocketStream` and begins connecting to `url`. As with
+[`new WebSocket()`][], a repeated or invalid subprotocol causes a `SyntaxError`
+`DOMException` to be thrown.
+
+```mjs
+import { WebSocketStream } from 'undici'
+
+const stream = new WebSocketStream('wss://echo.websocket.events')
+const { readable, writable } = await stream.opened
+
+const writer = writable.getWriter()
+await writer.write('Hello, world!')
+writer.releaseLock()
+
+const reader = readable.getReader()
+const { value } = await reader.read()
+console.log('received:', value)
+```
+
+### `webSocketStream.url`
+
+<!-- YAML
+added: v5.15.0
+-->
+
+> Stability: 1 - Experimental
+
+* Type: {string}
+
+The serialized URL of the WebSocket. This property is read-only.
+
+### `webSocketStream.opened`
+
+<!-- YAML
+added: v5.15.0
+-->
+
+> Stability: 1 - Experimental
+
+* Type: {Promise} Fulfills once the connection is established.
+
+A promise that resolves with an object describing the open connection, or
+rejects if the connection could not be established. The fulfillment value has
+the following shape:
+
+* `extensions` {string} The negotiated extensions.
+* `protocol` {string} The negotiated subprotocol.
+* `readable` {ReadableStream} A stream of incoming messages. Text frames are
+  delivered as strings and binary frames as `Uint8Array` chunks.
+* `writable` {WritableStream} A stream for sending messages. Writing a string
+  sends a text frame; writing a `BufferSource` sends a binary frame.
+
+### `webSocketStream.closed`
+
+<!-- YAML
+added: v5.15.0
+-->
+
+> Stability: 1 - Experimental
+
+* Type: {Promise} Fulfills once the connection is closed cleanly.
+
+A promise that resolves with a `WebSocketCloseInfo` object when the connection
+closes cleanly, or rejects with a [`WebSocketError`][] when it closes
+abnormally. The fulfillment value has the following shape:
+
+* `closeCode` {number} The status code the connection was closed with.
+* `reason` {string} The reason the connection was closed with.
+
+### `webSocketStream.close([closeInfo])`
+
+<!-- YAML
+added: v5.15.0
+-->
+
+> Stability: 1 - Experimental
+
+* `closeInfo` {Object}
+  * `closeCode` {number} The status code to close with.
+  * `reason` {string} The reason to close with. **Default:** `''`.
+
+Starts the closing handshake. When `closeInfo` is omitted, the connection is
+closed without a status code.
+
+## Class: `WebSocketError`
+
+<!-- YAML
+added: v7.0.0
+-->
+
+> Stability: 1 - Experimental
+
+* Extends: {DOMException}
+
+An error type used by [`WebSocketStream`][] to report close information. It is
+used to reject [`webSocketStream.closed`][] when the connection closes
+abnormally, and may be passed to a stream's abort or cancel operations to close
+the connection with a specific code and reason.
+
+### `new WebSocketError([message[, init]])`
+
+<!-- YAML
+added: v7.0.0
+-->
+
+> Stability: 1 - Experimental
+
+* `message` {string} A human-readable description of the error.
+  **Default:** `''`.
+* `init` {Object}
+  * `closeCode` {number} The status code to associate with the error.
+  * `reason` {string} The reason to associate with the error.
+    **Default:** `''`.
+
+Creates a new `WebSocketError`. If `reason` is non-empty but no `closeCode` is
+given, `closeCode` defaults to `1000` ("Normal Closure"). The `closeCode` and
+`reason` are validated, so an out-of-range code or an over-long reason throws.
+
+### `webSocketError.closeCode`
+
+<!-- YAML
+added: v5.15.0
+-->
+
+> Stability: 1 - Experimental
+
+* Type: {number|null}
+
+The status code associated with the error, or `null` if none was set. This
+property is read-only.
+
+### `webSocketError.reason`
+
+<!-- YAML
+added: v5.15.0
+-->
+
+> Stability: 1 - Experimental
+
+* Type: {string}
+
+The reason associated with the error. This property is read-only.
+
+## Read more
 
-## Read More
+* [MDN: WebSocket][]
+* [RFC 6455][]
+* [WHATWG WebSocket specification][]
 
-- [MDN - WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket)
-- [The WebSocket Specification](https://www.rfc-editor.org/rfc/rfc6455)
-- [The WHATWG WebSocket Specification](https://websockets.spec.whatwg.org/)
+[MDN WebSocketStream]: https://developer.mozilla.org/docs/Web/API/WebSocketStream
+[MDN: WebSocket]: https://developer.mozilla.org/docs/Web/API/WebSocket
+[RFC 6455]: https://www.rfc-editor.org/rfc/rfc6455
+[WHATWG WebSocket specification]: https://websockets.spec.whatwg.org/
+[`'close'`]: #event-close
+[`'error'`]: #event-error
+[`'message'`]: #event-message
+[`'open'`]: #event-open
+[`ProxyAgent`]: ProxyAgent.md#class-proxyagent
+[`WebSocket`]: #class-websocket
+[`WebSocketError`]: #class-websocketerror
+[`WebSocketStream`]: #class-websocketstream
+[`new WebSocket()`]: #new-websocketurl-protocols
+[`ping()`]: #pingwebsocket-payload
+[`webSocketStream.closed`]: #websocketstreamclosed
+[`webSocketStream.opened`]: #websocketstreamopened
+[`websocket.bufferedAmount`]: #websocketbufferedamount
+[`websocket.binaryType`]: #websocketbinarytype
+[`websocket.readyState`]: #websocketreadystate
+[`websocket.send()`]: #websocketsenddata
+[`websocket.url`]: #websocketurl
diff --git a/docs/docs/api/api-lifecycle.md b/docs/docs/api/api-lifecycle.md
index 7abefc9b7ee..c43adc908a2 100644
--- a/docs/docs/api/api-lifecycle.md
+++ b/docs/docs/api/api-lifecycle.md
@@ -1,27 +1,49 @@
 # Client Lifecycle
 
-An Undici [Client](/docs/docs/api/Client.md) can be best described as a state machine. The following list is a summary of the various state transitions the `Client` will go through in its lifecycle. This document also contains detailed breakdowns of each state.
-
-> This diagram is not a perfect representation of the undici Client. Since the Client class is not actually implemented as a state-machine, actual execution may deviate slightly from what is described below. Consider this as a general resource for understanding the inner workings of the Undici client rather than some kind of formal specification.
-
-## State Transition Overview
-
-* A `Client` begins in the **idle** state with no socket connection and no requests in queue.
-  * The *connect* event transitions the `Client` to the **pending** state where requests can be queued prior to processing.
-  * The *close* and *destroy* events transition the `Client` to the **destroyed** state. Since there are no requests in the queue, the *close* event immediately transitions to the **destroyed** state.
-* The **pending** state indicates the underlying socket connection has been successfully established and requests are queueing.
-  * The *process* event transitions the `Client` to the **processing** state where requests are processed.
-  * If requests are queued, the *close* event transitions to the **processing** state; otherwise, it transitions to the **destroyed** state.
-  * The *destroy* event transitions to the **destroyed** state.
-* The **processing** state initializes to the **processing.running** state.
-  * If the current request requires draining, the *needDrain* event transitions the `Client` into the **processing.busy** state which will return to the **processing.running** state with the *drainComplete* event.
-  * After all queued requests are completed, the *keepalive* event transitions the `Client` back to the **pending** state. If no requests are queued during the timeout, the **close** event transitions the `Client` to the **destroyed** state.
-  * If the *close* event is fired while the `Client` still has queued requests, the `Client` transitions to the **process.closing** state where it will complete all existing requests before firing the *done* event.
-  * The *done* event gracefully transitions the `Client` to the **destroyed** state.
-  * At any point in time, the *destroy* event will transition the `Client` from the **processing** state to the **destroyed** state, destroying any queued requests.
-* The **destroyed** state is a final state and the `Client` is no longer functional.
-
-A state diagram representing an Undici Client instance:
+<!--type=misc-->
+
+A {Client} can be understood as a state machine. As requests are dispatched,
+processed, and drained, the client moves through a well-defined set of states
+until it is eventually destroyed. This document describes those states and the
+transitions between them.
+
+The {Client} class is not literally implemented as a state machine, so the
+actual execution may deviate slightly from what is described here. Treat this
+guide as a conceptual model for reasoning about a client's behavior rather than
+as a formal specification.
+
+## State transition overview
+
+* A {Client} begins in the **idle** state with no socket connection and no
+  queued requests.
+  * The *connect* transition moves the {Client} to the **pending** state, where
+    requests can be queued before they are processed.
+  * Calling [`client.close()`][] or [`client.destroy()`][] moves the {Client}
+    to the **destroyed** state. Because there are no queued requests in this
+    state, *close* transitions straight to **destroyed**.
+* The **pending** state indicates that the underlying socket connection has been
+  established and that requests are queueing.
+  * The *process* transition moves the {Client} to the **processing** state,
+    where requests are processed.
+  * If requests are queued, *close* transitions to **processing**; otherwise it
+    transitions to **destroyed**.
+  * The *destroy* transition moves the {Client} to **destroyed**.
+* The **processing** state initializes to the **processing.running** sub-state.
+  * If the current request body requires draining, *needDrain* moves the
+    {Client} into the **processing.busy** sub-state, which returns to
+    **processing.running** once *drainComplete* fires.
+  * After all queued requests complete, *keepalive* moves the {Client} back to
+    the **pending** state. If no requests are queued before the socket times
+    out, the {Client} transitions to **idle**.
+  * If *close* is fired while the {Client} still has queued requests, the
+    {Client} transitions to **processing.closing**, where it completes all
+    outstanding requests before firing *done*.
+  * The *done* transition moves the {Client} gracefully to **destroyed**.
+  * At any time, *destroy* moves the {Client} from **processing** to
+    **destroyed**, aborting any queued requests.
+* The **destroyed** state is final; the {Client} is no longer functional.
+
+A state diagram representing a {Client} instance:
 
 ```mermaid
 stateDiagram-v2
@@ -54,38 +76,84 @@ stateDiagram-v2
       closing --> [*] : done
   }
 ```
+
 ## State details
 
 ### idle
 
-The **idle** state is the initial state of a `Client` instance. While an `origin` is required for instantiating a `Client` instance, the underlying socket connection will not be established until a request is queued using [`Client.dispatch()`](/docs/docs/api/Client.md#clientdispatchoptions-handlers). By calling `Client.dispatch()` directly or using one of the multiple implementations ([`Client.connect()`](/docs/docs/api/Client.md#clientconnectoptions-callback), [`Client.pipeline()`](/docs/docs/api/Client.md#clientpipelineoptions-handler), [`Client.request()`](/docs/docs/api/Client.md#clientrequestoptions-callback), [`Client.stream()`](/docs/docs/api/Client.md#clientstreamoptions-factory-callback), and [`Client.upgrade()`](/docs/docs/api/Client.md#clientupgradeoptions-callback)), the `Client` instance will transition from **idle** to [**pending**](/docs/docs/api/Client.md#pending) and then most likely directly to [**processing**](/docs/docs/api/Client.md#processing).
+**idle** is the initial state of a {Client} instance. Although an `origin` is
+required to construct a {Client}, the underlying socket connection is not
+established until a request is queued through [`client.dispatch()`][]. Calling
+`client.dispatch()` directly, or through one of its higher-level wrappers
+([`client.connect()`][], [`client.pipeline()`][], [`client.request()`][],
+[`client.stream()`][], or [`client.upgrade()`][]), moves the {Client} from
+**idle** to **pending**, and then usually directly on to **processing**.
 
-Calling [`Client.close()`](/docs/docs/api/Client.md#clientclosecallback) or [`Client.destroy()`](/docs/docs/api/Client.md#clientdestroyerror-callback) transitions directly to the [**destroyed**](/docs/docs/api/Client.md#destroyed) state since the `Client` instance will have no queued requests in this state.
+Calling [`client.close()`][] or [`client.destroy()`][] in this state moves the
+{Client} straight to **destroyed**, since there are no queued requests.
 
 ### pending
 
-The **pending** state signifies a non-processing `Client`. Upon entering this state, the `Client` establishes a socket connection and emits the [`'connect'`](/docs/docs/api/Client.md#event-connect) event signalling a connection was successfully established with the `origin` provided during `Client` instantiation. The internal queue is initially empty, and requests can start queueing.
+**pending** signifies a connected but non-processing {Client}. On entering this
+state, the {Client} establishes a socket connection and emits the
+[`'connect'`][] event, signalling that a connection to the `origin` supplied at
+construction time has been established. The internal queue starts empty, and
+requests can begin queueing.
 
-Calling [`Client.close()`](/docs/docs/api/Client.md#clientclosecallback) with queued requests, transitions the `Client` to the [**processing**](/docs/docs/api/Client.md#processing) state. Without queued requests, it transitions to the [**destroyed**](/docs/docs/api/Client.md#destroyed) state.
+Calling [`client.close()`][] with queued requests moves the {Client} to the
+**processing** state; without queued requests it moves to **destroyed**.
 
-Calling [`Client.destroy()`](/docs/docs/api/Client.md#clientdestroyerror-callback) transitions directly to the [**destroyed**](/docs/docs/api/Client.md#destroyed) state regardless of existing requests.
+Calling [`client.destroy()`][] moves the {Client} directly to **destroyed**,
+regardless of any queued requests.
 
 ### processing
 
-The **processing** state is a state machine within itself. It initializes to the [**processing.running**](/docs/docs/api/Client.md#running) state. The [`Client.dispatch()`](/docs/docs/api/Client.md#clientdispatchoptions-handlers), [`Client.close()`](/docs/docs/api/Client.md#clientclosecallback), and [`Client.destroy()`](/docs/docs/api/Client.md#clientdestroyerror-callback) can be called at any time while the `Client` is in this state. `Client.dispatch()` will add more requests to the queue while existing requests continue to be processed. `Client.close()` will transition to the [**processing.closing**](/docs/docs/api/Client.md#closing) state. And `Client.destroy()` will transition to [**destroyed**](/docs/docs/api/Client.md#destroyed).
+**processing** is itself a sub-state machine that initializes to the
+**processing.running** sub-state. [`client.dispatch()`][], [`client.close()`][],
+and [`client.destroy()`][] can all be called while the {Client} is in this
+state. `client.dispatch()` queues additional requests while existing ones
+continue to be processed, `client.close()` moves the {Client} to the
+**processing.closing** sub-state, and `client.destroy()` moves it to
+**destroyed**.
 
 #### running
 
-In the **processing.running** sub-state, queued requests are being processed in a FIFO order. If a request body requires draining, the *needDrain* event transitions to the [**processing.busy**](/docs/docs/api/Client.md#busy) sub-state. The *close* event transitions the Client to the [**process.closing**](/docs/docs/api/Client.md#closing) sub-state. If all queued requests are processed and neither [`Client.close()`](/docs/docs/api/Client.md#clientclosecallback) nor [`Client.destroy()`](/docs/docs/api/Client.md#clientdestroyerror-callback) are called, then the [**processing**](/docs/docs/api/Client.md#processing) machine will trigger a *keepalive* event transitioning the `Client` back to the [**pending**](/docs/docs/api/Client.md#pending) state. During this time, the `Client` is waiting for the socket connection to timeout, and once it does, it triggers the *timeout* event and transitions to the [**idle**](/docs/docs/api/Client.md#idle) state.
+In **processing.running**, queued requests are processed in FIFO order. If a
+request body requires draining, *needDrain* moves the {Client} to the
+**processing.busy** sub-state. The *close* transition moves the {Client} to the
+**processing.closing** sub-state. When all queued requests have completed and
+neither [`client.close()`][] nor [`client.destroy()`][] has been called, the
+*keepalive* transition moves the {Client} back to the **pending** state. There
+the {Client} waits for the socket connection to time out; once it does, the
+{Client} returns to the **idle** state.
 
 #### busy
 
-This sub-state is only entered when a request body is an instance of [Stream](https://nodejs.org/api/stream.html) and requires draining. The `Client` cannot process additional requests while in this state and must wait until the currently processing request body is completely drained before transitioning back to [**processing.running**](/docs/docs/api/Client.md#running).
+This sub-state is entered only when a request body is a {stream.Readable} that
+requires draining. The {Client} cannot process additional requests while in
+this state and waits until the current request body has been fully drained
+before returning to **processing.running**.
 
 #### closing
 
-This sub-state is only entered when a `Client` instance has queued requests and the [`Client.close()`](/docs/docs/api/Client.md#clientclosecallback) method is called. In this state, the `Client` instance continues to process requests as usual, with the one exception that no additional requests can be queued. Once all of the queued requests are processed, the `Client` will trigger the *done* event gracefully entering the [**destroyed**](/docs/docs/api/Client.md#destroyed) state without an error.
+This sub-state is entered only when a {Client} has queued requests and
+[`client.close()`][] is called. The {Client} continues to process requests as
+usual, except that no additional requests may be queued. Once all queued
+requests have been processed, *done* fires and the {Client} moves gracefully to
+**destroyed** without an error.
 
 ### destroyed
 
-The **destroyed** state is a final state for the `Client` instance. Once in this state, a `Client` is nonfunctional. Calling any other `Client` methods will result in an `ClientDestroyedError`.
+**destroyed** is the final state of a {Client} instance. Once in this state, the
+{Client} is no longer functional, and calling any further {Client} method
+rejects or fails with a {ClientDestroyedError}.
+
+[`'connect'`]: Client.md#event-connect
+[`client.close()`]: Client.md#clientclosecallback
+[`client.connect()`]: Client.md#clientconnectoptions-callback
+[`client.destroy()`]: Client.md#clientdestroyerror-callback
+[`client.dispatch()`]: Client.md#clientdispatchoptions-handlers
+[`client.pipeline()`]: Client.md#clientpipelineoptions-handler
+[`client.request()`]: Client.md#clientrequestoptions-callback
+[`client.stream()`]: Client.md#clientstreamoptions-factory-callback
+[`client.upgrade()`]: Client.md#clientupgradeoptions-callback
diff --git a/docs/docs/best-practices/client-certificate.md b/docs/docs/best-practices/client-certificate.md
index 9ead733af9e..82ae4e76b36 100644
--- a/docs/docs/best-practices/client-certificate.md
+++ b/docs/docs/best-practices/client-certificate.md
@@ -1,5 +1,7 @@
 # Client certificate
 
+<!--type=misc-->
+
 Client certificate authentication can be configured with the `Client`, the required options are passed along through the `connect` option.
 
 The client certificates must be signed by a trusted CA. The Node.js default is to trust the well-known CAs curated by Mozilla.
diff --git a/docs/docs/best-practices/crawling.md b/docs/docs/best-practices/crawling.md
index 96d67b2f0cc..9ed235c1c8b 100644
--- a/docs/docs/best-practices/crawling.md
+++ b/docs/docs/best-practices/crawling.md
@@ -1,5 +1,7 @@
 # Crawling
 
+<!--type=misc-->
+
 [RFC 9309](https://datatracker.ietf.org/doc/html/rfc9309) defines crawlers as automated clients.
 
 Some web servers may reject requests that omit the `User-Agent` header or that use common defaults such as `'curl/7.79.1'`.
@@ -10,7 +12,7 @@ It is recommended to specify a **custom `User-Agent` header** when implementing
 
 A user agent string should include sufficient detail to identify the crawler and provide contact information. For example:
 
-```
+```text
 AcmeCo Crawler - acme.co - contact@acme.co
 ```
 
diff --git a/docs/docs/best-practices/migrating-from-v7-to-v8.md b/docs/docs/best-practices/migrating-from-v7-to-v8.md
index 9db950570ff..b5f18224e21 100644
--- a/docs/docs/best-practices/migrating-from-v7-to-v8.md
+++ b/docs/docs/best-practices/migrating-from-v7-to-v8.md
@@ -1,5 +1,7 @@
 # Migrating from Undici 7 to 8
 
+<!--type=misc-->
+
 This guide covers the changes you are most likely to hit when upgrading an
 application or library from Undici v7 to v8.
 
@@ -225,7 +227,7 @@ After moving to Undici v8, it is worth checking these paths in your test suite:
 
 ## Related documentation
 
-- [Dispatcher](/docs/api/Dispatcher.md)
-- [Client](/docs/api/Client.md)
-- [Global Installation](/docs/api/GlobalInstallation.md)
-- [Undici Module vs. Node.js Built-in Fetch](/docs/best-practices/undici-vs-builtin-fetch.md)
+- [Dispatcher](../api/Dispatcher.md)
+- [Client](../api/Client.md)
+- [Global Installation](../api/GlobalInstallation.md)
+- [Undici Module vs. Node.js Built-in Fetch](./undici-vs-builtin-fetch.md)
diff --git a/docs/docs/best-practices/mocking-request.md b/docs/docs/best-practices/mocking-request.md
index ce56a09f5dd..8f8c73f68e6 100644
--- a/docs/docs/best-practices/mocking-request.md
+++ b/docs/docs/best-practices/mocking-request.md
@@ -1,6 +1,8 @@
 # Mocking Request
 
-Undici has its own mocking [utility](/docs/docs/api/MockAgent.md). It allow us to intercept undici HTTP requests and return mocked values instead. It can be useful for testing purposes.
+<!--type=misc-->
+
+Undici has its own mocking [utility](../api/MockAgent.md). It allow us to intercept undici HTTP requests and return mocked values instead. It can be useful for testing purposes.
 
 Example:
 
@@ -73,7 +75,7 @@ const badRequest = await bankTransfer('1234567890', '100')
 assert.deepEqual(badRequest, { message: 'bank account not found' })
 ```
 
-Explore other MockAgent functionality [here](/docs/docs/api/MockAgent.md)
+Explore other MockAgent functionality [here](../api/MockAgent.md)
 
 ## Access agent call history
 
@@ -123,11 +125,11 @@ assert.ok(mockAgent.getCallHistory()?.calls().length === 0)
 
 Calling `mockAgent.close()` will automatically clear and delete every call history for you.
 
-Explore other MockAgent functionality [here](/docs/docs/api/MockAgent.md)
+Explore other MockAgent functionality [here](../api/MockAgent.md)
 
-Explore other MockCallHistory functionality [here](/docs/docs/api/MockCallHistory.md)
+Explore other MockCallHistory functionality [here](../api/MockCallHistory.md)
 
-Explore other MockCallHistoryLog functionality [here](/docs/docs/api/MockCallHistoryLog.md)
+Explore other MockCallHistoryLog functionality [here](../api/MockCallHistoryLog.md)
 
 ## Debug Mock Value
 
@@ -179,7 +181,7 @@ mockPool.intercept({
 
 in this case opts will be
 
-```
+```js
 {
   method: 'POST',
   headers: { 'X-TOKEN-SECRET': 'SuperSecretToken' },
diff --git a/docs/docs/best-practices/proxy.md b/docs/docs/best-practices/proxy.md
index 8b1a7210e8c..c1fded96885 100644
--- a/docs/docs/best-practices/proxy.md
+++ b/docs/docs/best-practices/proxy.md
@@ -1,8 +1,10 @@
 # Connecting through a proxy
 
+<!--type=misc-->
+
 Connecting through a proxy is possible by:
 
-- Using [ProxyAgent](/docs/docs/api/ProxyAgent.md).
+- Using {ProxyAgent}.
 - Configuring `Client` or `Pool` constructor.
 
 The proxy url should be passed to the `Client` or `Pool` constructor, while the upstream server url
diff --git a/docs/docs/best-practices/undici-vs-builtin-fetch.md b/docs/docs/best-practices/undici-vs-builtin-fetch.md
index 979801ca817..42ce9e10d36 100644
--- a/docs/docs/best-practices/undici-vs-builtin-fetch.md
+++ b/docs/docs/best-practices/undici-vs-builtin-fetch.md
@@ -1,5 +1,7 @@
 # Undici Module vs. Node.js Built-in Fetch
 
+<!--type=misc-->
+
 Node.js has shipped a built-in `fetch()` implementation powered by undici since
 Node.js v18. This guide explains the relationship between the `undici` npm
 package and the built-in `fetch`, and when you should install one versus relying
@@ -57,7 +59,7 @@ await fetch('https://example.com', {
 ### `undici.install()` globals
 
 If you want the installed `undici` package to provide the globals, call
-[`install()`](/docs/api/GlobalInstallation.md):
+[`install()`](../api/GlobalInstallation.md):
 
 ```js
 import { install } from 'undici'
@@ -207,7 +209,7 @@ You can always check the exact bundled version at runtime with
 
 Installing undici from npm does not replace the built-in globals. If you want
 your installed version to replace the global `fetch` and related classes, use
-[`install()`](/docs/api/GlobalInstallation.md). Otherwise, import `fetch`
+[`install()`](../api/GlobalInstallation.md). Otherwise, import `fetch`
 directly from `'undici'`:
 
 ```js
@@ -216,9 +218,9 @@ import { fetch } from 'undici' // uses your installed version, not the built-in
 
 ## Further reading
 
-- [API Reference: Fetch](/docs/api/Fetch.md)
-- [API Reference: Client](/docs/api/Client.md)
-- [API Reference: Pool](/docs/api/Pool.md)
-- [API Reference: ProxyAgent](/docs/api/ProxyAgent.md)
-- [API Reference: MockAgent](/docs/api/MockAgent.md)
-- [API Reference: Global Installation](/docs/api/GlobalInstallation.md)
+- [API Reference: Fetch](../api/Fetch.md)
+- [API Reference: Client](../api/Client.md)
+- [API Reference: Pool](../api/Pool.md)
+- [API Reference: ProxyAgent](../api/ProxyAgent.md)
+- [API Reference: MockAgent](../api/MockAgent.md)
+- [API Reference: Global Installation](../api/GlobalInstallation.md)
diff --git a/docs/docs/best-practices/writing-tests.md b/docs/docs/best-practices/writing-tests.md
index 40939542e41..7c5fe167349 100644
--- a/docs/docs/best-practices/writing-tests.md
+++ b/docs/docs/best-practices/writing-tests.md
@@ -1,5 +1,7 @@
 # Writing tests
 
+<!--type=misc-->
+
 Undici is tuned for a production use case and its default will keep
 a socket open for a few seconds after an HTTP request is completed to
 remove the overhead of opening up a new socket. These settings that makes
diff --git a/docs/docs/GettingStarted.md b/docs/docs/getting-started.md
similarity index 84%
rename from docs/docs/GettingStarted.md
rename to docs/docs/getting-started.md
index 829a5c9f580..4e35f8b5420 100644
--- a/docs/docs/GettingStarted.md
+++ b/docs/docs/getting-started.md
@@ -1,5 +1,7 @@
 # Getting Started
 
+<!--type=misc-->
+
 ## Installation
 
 ```bash
@@ -12,7 +14,7 @@ The quickest way to get started is with `fetch`, which follows the
 [Fetch Standard](https://fetch.spec.whatwg.org/) and works the same way as
 the browser API:
 
-```js
+```mjs
 import { fetch } from 'undici'
 
 const res = await fetch('https://example.com')
@@ -24,7 +26,7 @@ console.log(data)
 
 undici also exports a `Request` class that follows the Fetch Standard:
 
-```js
+```mjs
 import { fetch, Request } from 'undici'
 
 const req = new Request('https://example.com', {
@@ -41,7 +43,7 @@ console.log(res.status)
 `res.body` is a web `ReadableStream`. Use `pipeline` from
 `node:stream/promises` to stream it to a file:
 
-```js
+```mjs
 import { fetch } from 'undici'
 import { pipeline } from 'node:stream/promises'
 import { createWriteStream } from 'node:fs'
@@ -53,10 +55,10 @@ await pipeline(res.body, createWriteStream('./file.zip'))
 > Always consume or cancel the response body. In Node.js, garbage collection
 > is not aggressive enough to release connections promptly, so leaving a body
 > unread can cause connection leaks and stalled requests. See
-> [Specification Compliance - Garbage Collection](/docs/#garbage-collection)
+> [Specification Compliance - Garbage Collection](/#garbage-collection)
 > for details.
 
-For more on `fetch`, see [API Reference: Fetch](/docs/docs/api/Fetch.md).
+For more on `fetch`, see [API Reference: Fetch](api/Fetch.md).
 
 ## Dispatchers: Connection reuse and pooling
 
@@ -127,9 +129,9 @@ client.close()
 ```
 
 For more on dispatcher options and lifecycle, see:
-- [API Reference: Agent](/docs/docs/api/Agent.md)
-- [API Reference: Pool](/docs/docs/api/Pool.md)
-- [API Reference: Client](/docs/docs/api/Client.md)
+- [API Reference: Agent](api/Agent.md)
+- [API Reference: Pool](api/Pool.md)
+- [API Reference: Client](api/Client.md)
 
 ## Timeouts
 
@@ -152,7 +154,7 @@ setGlobalDispatcher(agent)
 ```
 
 Timeout errors are thrown as `HeadersTimeoutError` and `BodyTimeoutError`.
-See [API Reference: Errors](/docs/docs/api/Errors.md) for the full list.
+See [API Reference: Errors](api/Errors.md) for the full list.
 
 ## Error handling
 
@@ -217,8 +219,8 @@ const proxy = new ProxyAgent('http://proxy.internal:8080')
 setGlobalDispatcher(proxy)
 ```
 
-See [Best Practices: Proxy](/docs/docs/best-practices/proxy.md) and
-[API Reference: ProxyAgent](/docs/docs/api/ProxyAgent.md).
+See [Best Practices: Proxy](best-practices/proxy.md) and
+[API Reference: ProxyAgent](api/ProxyAgent.md).
 
 ### Mocking in tests
 
@@ -235,8 +237,8 @@ const { body } = await request('https://api.example.com/users')
 console.log(await body.json())
 ```
 
-See [Best Practices: Mocking Request](/docs/docs/best-practices/mocking-request.md)
-and [API Reference: MockAgent](/docs/docs/api/MockAgent.md).
+See [Best Practices: Mocking Request](best-practices/mocking-request.md)
+and [API Reference: MockAgent](api/MockAgent.md).
 
 ### Testing with undici
 
@@ -252,7 +254,7 @@ const agent = new Agent({
 setGlobalDispatcher(agent)
 ```
 
-See [Best Practices: Writing Tests](/docs/docs/best-practices/writing-tests.md).
+See [Best Practices: Writing Tests](best-practices/writing-tests.md).
 
 ### Customizing the global fetch
 
@@ -268,11 +270,11 @@ install()
 const res = await fetch('https://example.com')
 ```
 
-See [API Reference: Global Installation](/docs/docs/api/GlobalInstallation.md).
+See [API Reference: Global Installation](api/GlobalInstallation.md).
 
 ## Further reading
 
-- [Undici vs. Built-in Fetch](/docs/docs/best-practices/undici-vs-builtin-fetch.md) —
+- [Undici vs. Built-in Fetch](best-practices/undici-vs-builtin-fetch.md) —
   when to install undici vs using Node.js built-in fetch
-- [API Reference](/docs/docs/api/Dispatcher.md) — full dispatcher API documentation
-- [Examples](/docs/examples/) — runnable code examples
+- [API Reference](api/Dispatcher.md) — full dispatcher API documentation
+- [Examples](/examples/) — runnable code examples
diff --git a/docs/docs/index.md b/docs/docs/index.md
new file mode 100644
index 00000000000..2da017aae0d
--- /dev/null
+++ b/docs/docs/index.md
@@ -0,0 +1,778 @@
+# undici
+
+<!--type=misc-->
+
+[![Node CI](https://github.com/nodejs/undici/actions/workflows/ci.yml/badge.svg)](https://github.com/nodejs/undici/actions/workflows/nodejs.yml) [![neostandard javascript style](https://img.shields.io/badge/neo-standard-7fffff?style=flat\&labelColor=ff80ff)](https://github.com/neostandard/neostandard) [![npm version](https://badge.fury.io/js/undici.svg)](https://badge.fury.io/js/undici) [![codecov](https://codecov.io/gh/nodejs/undici/branch/main/graph/badge.svg?token=yZL6LtXkOA)](https://codecov.io/gh/nodejs/undici)
+
+An HTTP/1.1 client, written from scratch for Node.js.
+
+> Undici means eleven in Italian. 1.1 -> 11 -> Eleven -> Undici.
+It is also a Stranger Things reference.
+
+## How to get involved
+
+Have a question about using Undici? Open a [Q&A Discussion](https://github.com/nodejs/undici/discussions/new) or join our official OpenJS [Slack](https://openjs-foundation.slack.com/archives/C01QF9Q31QD) channel.
+
+Looking to contribute? Start by reading the [contributing guide](./CONTRIBUTING.md)
+
+## Install
+
+```bash
+npm i undici
+```
+
+## Benchmarks
+
+The benchmark is a simple getting data [example](https://github.com/nodejs/undici/blob/main/benchmarks/benchmark.js) using
+50 TCP connections with a pipelining depth of 10 running on Node 24.14.1.
+
+### HTTP/1.1
+
+```text
+┌────────────────────────┬─────────┬────────────────────┬────────────┬─────────────────────────┐
+│  Tests                 │ Samples │ Result             │ Tolerance  │ Difference with slowest │
+├────────────────────────┼─────────┼────────────────────┼────────────┼─────────────────────────┤
+│  'node-fetch'          │ 50      │ '4711.86 req/sec'  │ '± 2.92 %' │ '-'                     │
+│  'undici - fetch'      │ 75      │ '5438.50 req/sec'  │ '± 2.97 %' │ '+ 15.42 %'             │
+│  'axios'               │ 45      │ '5448.08 req/sec'  │ '± 2.98 %' │ '+ 15.62 %'             │
+│  'request'             │ 65      │ '5809.63 req/sec'  │ '± 2.90 %' │ '+ 23.30 %'             │
+│  'http - no keepalive' │ 35      │ '5910.77 req/sec'  │ '± 2.87 %' │ '+ 25.44 %'             │
+│  'got'                 │ 50      │ '6047.80 req/sec'  │ '± 2.91 %' │ '+ 28.35 %'             │
+│  'superagent'          │ 60      │ '7534.53 req/sec'  │ '± 2.97 %' │ '+ 59.91 %'             │
+│  'http - keepalive'    │ 75      │ '9343.41 req/sec'  │ '± 2.90 %' │ '+ 98.30 %'             │
+│  'undici - pipeline'   │ 65      │ '13470.70 req/sec' │ '± 2.93 %' │ '+ 185.89 %'            │
+│  'undici - request'    │ 80      │ '16850.87 req/sec' │ '± 2.93 %' │ '+ 257.63 %'            │
+│  'undici - stream'     │ 101     │ '18488.56 req/sec' │ '± 3.81 %' │ '+ 292.38 %'            │
+│  'undici - dispatch'   │ 101     │ '20786.44 req/sec' │ '± 3.08 %' │ '+ 341.15 %'            │
+└────────────────────────┴─────────┴────────────────────┴────────────┴─────────────────────────┘
+```
+
+### HTTP/1.1 over HTTPS
+
+Using [benchmark-https.js](https://github.com/nodejs/undici/blob/main/benchmarks/benchmark-https.js) against an h1-over-TLS server (50 connections, pipelining depth 10, Node 24.14.1).
+
+```text
+┌────────────────────────┬─────────┬───────────────────┬────────────┬─────────────────────────┐
+│  Tests                 │ Samples │ Result            │ Tolerance  │ Difference with slowest │
+├────────────────────────┼─────────┼───────────────────┼────────────┼─────────────────────────┤
+│  'https - no keepalive'│ 10      │ '1358.40 req/sec' │ '± 1.99 %' │ '-'                     │
+│  'undici - fetch'      │ 30      │ '3721.76 req/sec' │ '± 2.97 %' │ '+ 173.98 %'            │
+│  'https - keepalive'   │ 35      │ '5633.91 req/sec' │ '± 2.84 %' │ '+ 314.75 %'            │
+│  'undici - pipeline'   │ 15      │ '6254.05 req/sec' │ '± 2.80 %' │ '+ 360.40 %'            │
+│  'undici - request'    │ 25      │ '6669.80 req/sec' │ '± 2.73 %' │ '+ 391.01 %'            │
+│  'undici - stream'     │ 25      │ '7019.04 req/sec' │ '± 2.77 %' │ '+ 416.71 %'            │
+│  'undici - dispatch'   │ 20      │ '7361.85 req/sec' │ '± 2.90 %' │ '+ 441.95 %'            │
+└────────────────────────┴─────────┴───────────────────┴────────────┴─────────────────────────┘
+```
+
+### HTTP/2
+
+Using [benchmark-http2.js](https://github.com/nodejs/undici/blob/main/benchmarks/benchmark-http2.js) against an h2 server (50 connections, pipelining depth 10, Node 24.14.1).
+
+```text
+┌────────────────────────┬─────────┬───────────────────┬────────────┬─────────────────────────┐
+│  Tests                 │ Samples │ Result            │ Tolerance  │ Difference with slowest │
+├────────────────────────┼─────────┼───────────────────┼────────────┼─────────────────────────┤
+│  'undici - fetch'      │ 45      │ '3499.03 req/sec' │ '± 2.93 %' │ '-'                     │
+│  'native - http2'      │ 25      │ '4904.58 req/sec' │ '± 2.81 %' │ '+ 40.17 %'             │
+│  'undici - pipeline'   │ 60      │ '5836.82 req/sec' │ '± 2.99 %' │ '+ 66.81 %'             │
+│  'undici - request'    │ 65      │ '6831.25 req/sec' │ '± 2.83 %' │ '+ 95.23 %'             │
+│  'undici - stream'     │ 55      │ '6874.30 req/sec' │ '± 2.91 %' │ '+ 96.46 %'             │
+│  'undici - dispatch'   │ 55      │ '7791.23 req/sec' │ '± 2.96 %' │ '+ 122.67 %'            │
+└────────────────────────┴─────────┴───────────────────┴────────────┴─────────────────────────┘
+```
+
+## Undici vs. Fetch
+
+### Overview
+
+Node.js includes a built-in `fetch()` implementation powered by undici starting from Node.js v18. However, there are important differences between using the built-in fetch and installing undici as a separate module.
+
+### Built-in Fetch (Node.js v18+)
+
+Node.js's built-in fetch is powered by a bundled version of undici:
+
+```js
+// Available globally in Node.js v18+
+const response = await fetch('https://api.example.com/data');
+const data = await response.json();
+
+// Check the bundled undici version
+console.log(process.versions.undici); // e.g., "5.28.4"
+```
+
+**Pros:**
+- No additional dependencies required
+- Works across different JavaScript runtimes
+- Automatic compression handling (gzip, deflate, br)
+- Built-in caching support (in development)
+
+**Cons:**
+- Limited to the undici version bundled with your Node.js version
+- Less control over connection pooling and advanced features
+- Error handling follows Web API standards (errors wrapped in `TypeError`)
+- Performance overhead due to Web Streams implementation
+
+### Undici Module
+
+Installing undici as a separate module gives you access to the latest features and APIs:
+
+```bash
+npm install undici
+```
+
+```js
+import { request, fetch, Agent, setGlobalDispatcher } from 'undici';
+
+// Use undici.request for maximum performance
+const { statusCode, headers, body } = await request('https://api.example.com/data');
+const data = await body.json();
+
+// Or use undici.fetch with custom configuration
+const agent = new Agent({ keepAliveTimeout: 10000 });
+setGlobalDispatcher(agent);
+const response = await fetch('https://api.example.com/data');
+```
+
+**Pros:**
+- Latest undici features and bug fixes
+- Access to advanced APIs (`request`, `stream`, `pipeline`)
+- Fine-grained control over connection pooling
+- Better error handling with clearer error messages
+- Superior performance, especially with `undici.request`
+- HTTP/1.1 pipelining support
+- Custom interceptors and middleware
+- Advanced features like `ProxyAgent`, `Socks5Agent`, `MockAgent`
+
+**Cons:**
+- Additional dependency to manage
+- Larger bundle size
+
+### When to Use Each
+
+#### Use Built-in Fetch When:
+- You want zero dependencies
+- Building isomorphic code that runs in browsers and Node.js
+- Publishing to npm and want to maximize compatibility with JS runtimes
+- Simple HTTP requests without advanced configuration
+- You're publishing to npm and you want to maximize compatiblity
+- You don't depend on features from a specific version of undici
+
+#### Use Undici Module When:
+- You need the latest undici features and performance improvements
+- You require advanced connection pooling configuration
+- You need APIs not available in the built-in fetch (`ProxyAgent`, `Socks5Agent`, `MockAgent`, etc.)
+- Performance is critical (use `undici.request` for maximum speed)
+- You want better error handling and debugging capabilities
+- You need HTTP/1.1 pipelining or advanced interceptors
+- You prefer decoupled protocol and API interfaces
+
+### Performance Comparison
+
+Based on benchmarks, here's the typical performance hierarchy:
+
+1. **`undici.request()`** - Fastest, most efficient
+2. **`undici.fetch()`** - Good performance, standard compliance
+3. **Node.js `http`/`https`** - Baseline performance
+
+### Migration Guide
+
+If you're currently using built-in fetch and want to migrate to undici:
+
+```js
+// Before: Built-in fetch
+const response = await fetch('https://api.example.com/data');
+
+// After: Undici fetch (drop-in replacement)
+import { fetch } from 'undici';
+const response = await fetch('https://api.example.com/data');
+
+// Or: Undici request (better performance)
+import { request } from 'undici';
+const { statusCode, body } = await request('https://api.example.com/data');
+const data = await body.json();
+```
+
+### Keep `fetch` and `FormData` together
+
+When you send a `FormData` body, keep `fetch` and `FormData` from the same
+implementation.
+
+Use one of these patterns:
+
+```js
+// Built-in globals
+const body = new FormData()
+body.set('name', 'some')
+await fetch('https://example.com', {
+  method: 'POST',
+  body
+})
+```
+
+```js
+// undici module imports
+import { fetch, FormData } from 'undici'
+
+const body = new FormData()
+body.set('name', 'some')
+await fetch('https://example.com', {
+  method: 'POST',
+  body
+})
+```
+
+If you want the installed `undici` package to provide the globals, call
+`install()` first:
+
+```js
+import { install } from 'undici'
+
+install()
+
+const body = new FormData()
+body.set('name', 'some')
+await fetch('https://example.com', {
+  method: 'POST',
+  body
+})
+```
+
+`install()` replaces the global `fetch`, `Headers`, `Response`, `Request`, and
+`FormData` implementations with undici's versions, so they all match. It also
+installs undici's `WebSocket`, `CloseEvent`, `ErrorEvent`, `MessageEvent`, and
+`EventSource` globals.
+
+Avoid mixing a global `FormData` with `undici.fetch()`, or `undici.FormData`
+with the built-in global `fetch()`.
+
+### Version Compatibility
+
+You can check which version of undici is bundled with your Node.js version:
+
+```js
+console.log(process.versions.undici);
+```
+
+Installing undici as a module allows you to use a newer version than what's bundled with Node.js, giving you access to the latest features and performance improvements.
+
+## Quick Start
+
+### Basic Request
+
+```js
+import { request } from 'undici'
+
+const {
+  statusCode,
+  headers,
+  trailers,
+  body
+} = await request('http://localhost:3000/foo')
+
+console.log('response received', statusCode)
+console.log('headers', headers)
+
+for await (const data of body) { console.log('data', data) }
+
+console.log('trailers', trailers)
+```
+
+### Using Cache Interceptor
+
+Undici provides a powerful HTTP caching interceptor that follows HTTP caching best practices. Here's how to use it:
+
+```js
+import { fetch, Agent, interceptors, cacheStores } from 'undici';
+
+// Create a client with cache interceptor
+const client = new Agent().compose(interceptors.cache({
+  // Optional: Configure cache store (defaults to MemoryCacheStore)
+  store: new cacheStores.MemoryCacheStore({
+    maxSize: 100 * 1024 * 1024, // 100MB
+    maxCount: 1000,
+    maxEntrySize: 5 * 1024 * 1024 // 5MB
+  }),
+  
+  // Optional: Specify which HTTP methods to cache (default: ['GET', 'HEAD'])
+  methods: ['GET', 'HEAD']
+}));
+
+// Set the global dispatcher to use our caching client
+setGlobalDispatcher(client);
+
+// Now all fetch requests will use the cache
+async function getData() {
+  const response = await fetch('https://api.example.com/data');
+  // The server should set appropriate Cache-Control headers in the response
+  // which the cache will respect based on the cache policy
+  return response.json();
+}
+
+// First request - fetches from origin
+const data1 = await getData();
+
+// Second request - served from cache if within max-age
+const data2 = await getData();
+```
+
+#### Key Features:
+- **Automatic Caching**: Respects `Cache-Control` and `Expires` headers
+- **Validation**: Supports `ETag` and `Last-Modified` validation
+- **Storage Options**: In-memory or persistent SQLite storage
+- **Flexible**: Configure cache size, TTL, and more
+
+## Global Installation
+
+Undici provides an `install()` function to add fetch-related and other web API classes to `globalThis`, making them available globally:
+
+```js
+import { install } from 'undici'
+
+// Install undici's global web APIs
+install()
+
+// Now you can use fetch classes globally without importing
+const response = await fetch('https://api.example.com/data')
+const data = await response.json()
+
+// All classes are available globally:
+const headers = new Headers([['content-type', 'application/json']])
+const request = new Request('https://example.com')
+const formData = new FormData()
+const ws = new WebSocket('wss://example.com')
+const eventSource = new EventSource('https://example.com/events')
+```
+
+The `install()` function adds the following classes to `globalThis`:
+
+- `fetch` - The fetch function
+- `Headers` - HTTP headers management
+- `Response` - HTTP response representation
+- `Request` - HTTP request representation
+- `FormData` - Form data handling
+- `WebSocket` - WebSocket client
+- `CloseEvent`, `ErrorEvent`, `MessageEvent` - WebSocket events
+- `EventSource` - Server-sent events client
+
+When you call `install()`, these globals come from the same undici
+implementation. For example, global `fetch` and global `FormData` will both be
+undici's versions, and `WebSocket` and `EventSource` will also come from
+undici, which is the recommended setup if you want to use undici through
+globals.
+
+This is useful for:
+- Polyfilling environments that don't have fetch
+- Ensuring consistent fetch behavior across different Node.js versions
+- Making undici's implementations available globally for libraries that expect them
+
+## Body Mixins
+
+The `body` mixins are the most common way to format the request/response body. Mixins include:
+
+- [`.arrayBuffer()`](https://fetch.spec.whatwg.org/#dom-body-arraybuffer)
+- [`.blob()`](https://fetch.spec.whatwg.org/#dom-body-blob)
+- [`.bytes()`](https://fetch.spec.whatwg.org/#dom-body-bytes)
+- [`.json()`](https://fetch.spec.whatwg.org/#dom-body-json)
+- [`.text()`](https://fetch.spec.whatwg.org/#dom-body-text)
+
+> [!NOTE]
+> The body returned from `undici.request` does not implement `.formData()`.
+
+> [!WARNING]
+> Calling `body.formData()` on a fetch response causes undici to buffer and parse the entire body. Since this is dictated by the spec, `body.formData()` must only be called on responses from trusted servers.
+
+Example usage:
+
+```js
+import { request } from 'undici'
+
+const {
+  statusCode,
+  headers,
+  trailers,
+  body
+} = await request('http://localhost:3000/foo')
+
+console.log('response received', statusCode)
+console.log('headers', headers)
+console.log('data', await body.json())
+console.log('trailers', trailers)
+```
+
+_Note: Once a mixin has been called then the body cannot be reused, thus calling additional mixins on `.body`, e.g. `.body.json(); .body.text()` will result in an error `TypeError: unusable` being thrown and returned through the `Promise` rejection._
+
+Should you need to access the `body` in plain-text after using a mixin, the best practice is to use the `.text()` mixin first and then manually parse the text to the desired format.
+
+For more information about their behavior, please reference the body mixin from the [Fetch Standard](https://fetch.spec.whatwg.org/#body-mixin).
+
+## Common API Methods
+
+This section documents our most commonly used API methods. Additional APIs are documented in their own files within the [docs](./docs/) folder and are accessible via the navigation list on the left side of the docs site.
+
+### `undici.request([url, options])`
+
+* `url` {string|URL|UrlObject}
+* `options` {RequestOptions} See [`RequestOptions`](./docs/docs/api/Dispatcher.md#parameter-requestoptions).
+  * `dispatcher` {Dispatcher} **Default:** [getGlobalDispatcher](#undicigetglobaldispatcher).
+  * `method` {string} **Default:** `PUT` if `options.body`, otherwise `GET`.
+* Returns: {Promise} A promise with the result of the `Dispatcher.request` method.
+
+Calls `options.dispatcher.request(options)`.
+
+See [Dispatcher.request](./docs/docs/api/Dispatcher.md#dispatcherrequestoptions-callback) for more details, and [request examples](./docs/examples/README.md) for examples.
+
+### `undici.stream([url, options, ]factory)`
+
+* `url` {string|URL|UrlObject}
+* `options` {StreamOptions} See [`StreamOptions`](./docs/docs/api/Dispatcher.md#parameter-streamoptions).
+  * `dispatcher` {Dispatcher} **Default:** [getGlobalDispatcher](#undicigetglobaldispatcher).
+  * `method` {string} **Default:** `PUT` if `options.body`, otherwise `GET`.
+* `factory` {Function} `Dispatcher.stream.factory`.
+* Returns: {Promise} A promise with the result of the `Dispatcher.stream` method.
+
+Calls `options.dispatcher.stream(options, factory)`.
+
+See [Dispatcher.stream](./docs/docs/api/Dispatcher.md#dispatcherstreamoptions-factory-callback) for more details.
+
+### `undici.pipeline([url, options, ]handler)`
+
+* `url` {string|URL|UrlObject}
+* `options` {PipelineOptions} See [`PipelineOptions`](./docs/docs/api/Dispatcher.md#parameter-pipelineoptions).
+  * `dispatcher` {Dispatcher} **Default:** [getGlobalDispatcher](#undicigetglobaldispatcher).
+  * `method` {string} **Default:** `PUT` if `options.body`, otherwise `GET`.
+* `handler` {Function} `Dispatcher.pipeline.handler`.
+* Returns: {Duplex} A `stream.Duplex`.
+
+Calls `options.dispatch.pipeline(options, handler)`.
+
+See [Dispatcher.pipeline](./docs/docs/api/Dispatcher.md#dispatcherpipelineoptions-handler) for more details.
+
+### `undici.connect([url, options])`
+
+Starts two-way communications with the requested resource using [HTTP CONNECT](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/CONNECT).
+
+* `url` {string|URL|UrlObject}
+* `options` {ConnectOptions} See [`ConnectOptions`](./docs/docs/api/Dispatcher.md#parameter-connectoptions).
+  * `dispatcher` {Dispatcher} **Default:** [getGlobalDispatcher](#undicigetglobaldispatcher).
+* `callback` {Function} (optional) — `(err, data) => void`.
+* Returns: {Promise} A promise with the result of the `Dispatcher.connect` method.
+
+Calls `options.dispatch.connect(options)`.
+
+See [Dispatcher.connect](./docs/docs/api/Dispatcher.md#dispatcherconnectoptions-callback) for more details.
+
+### `undici.fetch(input[, init])`
+
+Implements [fetch](https://fetch.spec.whatwg.org/#fetch-method).
+
+* https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch
+* https://fetch.spec.whatwg.org/#fetch-method
+
+Basic usage example:
+
+```js
+import { fetch } from 'undici'
+
+
+const res = await fetch('https://example.com')
+const json = await res.json()
+console.log(json)
+```
+
+You can pass an optional dispatcher to `fetch` as:
+
+```js
+import { fetch, Agent } from 'undici'
+
+const res = await fetch('https://example.com', {
+  // Mocks are also supported
+  dispatcher: new Agent({
+    keepAliveTimeout: 10,
+    keepAliveMaxTimeout: 10
+  })
+})
+const json = await res.json()
+console.log(json)
+```
+
+#### `request.body`
+
+A body can be of the following types:
+
+- ArrayBuffer
+- ArrayBufferView
+- AsyncIterables
+- Blob
+- Iterables
+- String
+- URLSearchParams
+- FormData
+
+In this implementation of fetch, ```request.body``` now accepts ```Async Iterables```. It is not present in the [Fetch Standard](https://fetch.spec.whatwg.org).
+
+```js
+import { fetch } from 'undici'
+
+const data = {
+  async *[Symbol.asyncIterator]() {
+    yield 'hello'
+    yield 'world'
+  },
+}
+
+await fetch('https://example.com', { body: data, method: 'POST', duplex: 'half' })
+```
+
+[FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) besides text data and buffers can also utilize streams via [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob) objects:
+
+```js
+import { openAsBlob } from 'node:fs'
+
+const file = await openAsBlob('./big.csv')
+const body = new FormData()
+body.set('file', file, 'big.csv')
+
+await fetch('http://example.com', { method: 'POST', body })
+```
+
+#### `request.duplex`
+
+- `'half'`
+
+In this implementation of fetch, `request.duplex` must be set if `request.body` is `ReadableStream` or `Async Iterables`, however, even though the value must be set to `'half'`, it is actually a _full_ duplex. For more detail refer to the [Fetch Standard](https://fetch.spec.whatwg.org/#dom-requestinit-duplex).
+
+#### `response.body`
+
+Nodejs has two kinds of streams: [web streams](https://nodejs.org/api/webstreams.html), which follow the API of the WHATWG web standard found in browsers, and an older Node-specific [streams API](https://nodejs.org/api/stream.html). `response.body` returns a readable web stream. If you would prefer to work with a Node stream you can convert a web stream using `.fromWeb()`.
+
+```js
+import { fetch } from 'undici'
+import { Readable } from 'node:stream'
+
+const response = await fetch('https://example.com')
+const readableWebStream = response.body
+const readableNodeStream = Readable.fromWeb(readableWebStream)
+```
+
+## Specification Compliance
+
+This section documents parts of the [HTTP/1.1](https://www.rfc-editor.org/rfc/rfc9110.html) and [Fetch Standard](https://fetch.spec.whatwg.org) that Undici does
+not support or does not fully implement.
+
+#### CORS
+
+Unlike browsers, Undici does not implement CORS (Cross-Origin Resource Sharing) checks by default. This means:
+
+- No preflight requests are automatically sent for cross-origin requests
+- No validation of `Access-Control-Allow-Origin` headers is performed
+- Requests to any origin are allowed regardless of the source
+
+This behavior is intentional for server-side environments where CORS restrictions are typically unnecessary. If your application requires CORS-like protections, you will need to implement these checks manually.
+
+#### Garbage Collection
+
+* https://fetch.spec.whatwg.org/#garbage-collection
+
+The [Fetch Standard](https://fetch.spec.whatwg.org) allows users to skip consuming the response body by relying on
+[garbage collection](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Memory_Management#garbage_collection) to release connection resources.
+
+Garbage collection in Node is less aggressive and deterministic
+(due to the lack of clear idle periods that browsers have through the rendering refresh rate)
+which means that leaving the release of connection resources to the garbage collector can lead
+to excessive connection usage, reduced performance (due to less connection re-use), and even
+stalls or deadlocks when running out of connections.
+Therefore, __it is important to always either consume or cancel the response body anyway__.
+
+```js
+// Do
+const { body, headers } = await fetch(url);
+for await (const chunk of body) {
+  // force consumption of body
+}
+
+// Do not
+const { headers } = await fetch(url);
+```
+
+However, if you want to get only headers, it might be better to use `HEAD` request method. Usage of this method will obviate the need for consumption or cancelling of the response body. See [MDN - HTTP - HTTP request methods - HEAD](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD) for more details.
+
+```js
+const headers = await fetch(url, { method: 'HEAD' })
+  .then(res => res.headers)
+```
+
+Note that consuming the response body is _mandatory_ for `request`:
+
+```js
+// Do
+const { body, headers } = await request(url);
+await body.dump(); // force consumption of body
+
+// Do not
+const { headers } = await request(url);
+```
+
+#### Forbidden and Safelisted Header Names
+
+* https://fetch.spec.whatwg.org/#cors-safelisted-response-header-name
+* https://fetch.spec.whatwg.org/#forbidden-header-name
+* https://fetch.spec.whatwg.org/#forbidden-response-header-name
+* https://github.com/wintercg/fetch/issues/6
+
+The [Fetch Standard](https://fetch.spec.whatwg.org) requires implementations to exclude certain headers from requests and responses. In browser environments, some headers are forbidden so the user agent remains in full control over them. In Undici, these constraints are removed to give more control to the user.
+
+#### Content-Encoding
+
+* https://www.rfc-editor.org/rfc/rfc9110#field.content-encoding
+
+Undici limits the number of `Content-Encoding` layers in a response to **5** to prevent resource exhaustion attacks. If a server responds with more than 5 content-encodings (e.g., `Content-Encoding: gzip, gzip, gzip, gzip, gzip, gzip`), the fetch will be rejected with an error. This limit matches the approach taken by [curl](https://curl.se/docs/CVE-2022-32206.html) and [urllib3](https://github.com/advisories/GHSA-gm62-xv2j-4rw9).
+
+#### `undici.upgrade([url, options])`
+
+Upgrade to a different protocol. See [MDN - HTTP - Protocol upgrade mechanism](https://developer.mozilla.org/en-US/docs/Web/HTTP/Protocol_upgrade_mechanism) for more details.
+
+* `url` {string|URL|UrlObject}
+* `options` {UpgradeOptions} See [`UpgradeOptions`](./docs/docs/api/Dispatcher.md#parameter-upgradeoptions).
+  * `dispatcher` {Dispatcher} **Default:** [getGlobalDispatcher](#undicigetglobaldispatcher).
+* `callback` {Function} (optional) — `(error, data) => void`.
+* Returns: {Promise} A promise with the result of the `Dispatcher.upgrade` method.
+
+Calls `options.dispatcher.upgrade(options)`.
+
+See [Dispatcher.upgrade](./docs/docs/api/Dispatcher.md#dispatcherupgradeoptions-callback) for more details.
+
+### `undici.setGlobalDispatcher(dispatcher)`
+
+* `dispatcher` {Dispatcher}
+
+Sets the global dispatcher used by Common API Methods. Global dispatcher is shared among compatible undici modules,
+including undici that is bundled internally with node.js.
+
+Undici stores this dispatcher under `Symbol.for('undici.globalDispatcher.2')`.
+
+`setGlobalDispatcher()` also mirrors the configured dispatcher to
+`Symbol.for('undici.globalDispatcher.1')` using `Dispatcher1Wrapper`, so Node.js built-in `fetch`
+can keep using the legacy handler contract while Undici uses the new handler API.
+
+### `undici.getGlobalDispatcher()`
+
+Gets the global dispatcher used by Common API Methods.
+
+* Returns: {Dispatcher}
+
+### `undici.setGlobalOrigin(origin)`
+
+* `origin` {string|URL|undefined}
+
+Sets the global origin used in `fetch`.
+
+If `undefined` is passed, the global origin will be reset. This will cause `Response.redirect`, `new Request()`, and `fetch` to throw an error when a relative path is passed.
+
+```js
+setGlobalOrigin('http://localhost:3000')
+
+const response = await fetch('/api/ping')
+
+console.log(response.url) // http://localhost:3000/api/ping
+```
+
+### `undici.getGlobalOrigin()`
+
+Gets the global origin used in `fetch`.
+
+* Returns: {URL}
+
+### `UrlObject`
+
+* `port` {string|number} (optional)
+* `path` {string} (optional)
+* `pathname` {string} (optional)
+* `hostname` {string} (optional)
+* `origin` {string} (optional)
+* `protocol` {string} (optional)
+* `search` {string} (optional)
+
+#### Expect
+
+Undici does not support the `Expect` request header field. The request
+body is  always immediately sent and the `100 Continue` response will be
+ignored.
+
+Refs: https://tools.ietf.org/html/rfc7231#section-5.1.1
+
+#### Pipelining
+
+Undici will only use pipelining if configured with a `pipelining` factor
+greater than `1`. Also it is important to pass `blocking: false` to the
+request options to properly pipeline requests.
+
+Undici always assumes that connections are persistent and will immediately
+pipeline requests, without checking whether the connection is persistent.
+Hence, automatic fallback to HTTP/1.0 or HTTP/1.1 without pipelining is
+not supported.
+
+Undici will immediately pipeline when retrying requests after a failed
+connection. However, Undici will not retry the first remaining requests in
+the prior pipeline and instead error the corresponding callback/promise/stream.
+
+Undici will abort all running requests in the pipeline when any of them are
+aborted.
+
+* Refs: https://tools.ietf.org/html/rfc2616#section-8.1.2.2
+* Refs: https://tools.ietf.org/html/rfc7230#section-6.3.2
+
+#### Manual Redirect
+
+Since it is not possible to manually follow an HTTP redirect on the server-side,
+Undici returns the actual response instead of an `opaqueredirect` filtered one
+when invoked with a `manual` redirect. This aligns `fetch()` with the other
+implementations in Deno and Cloudflare Workers.
+
+Refs: https://fetch.spec.whatwg.org/#atomic-http-redirect-handling
+
+### Workarounds
+
+#### Network address family autoselection.
+
+If you experience problem when connecting to a remote server that is resolved by your DNS servers to a IPv6 (AAAA record)
+first, there are chances that your local router or ISP might have problem connecting to IPv6 networks. In that case
+undici will throw an error with code `UND_ERR_CONNECT_TIMEOUT`.
+
+If the target server resolves to both a IPv6 and IPv4 (A records) address and you are using a compatible Node version
+(18.3.0 and above), you can fix the problem by providing the `autoSelectFamily` option (support by both `undici.request`
+and `undici.Agent`) which will enable the family autoselection algorithm when establishing the connection.
+
+## Collaborators
+
+* [__Daniele Belardi__](https://github.com/dnlup), <https://www.npmjs.com/~dnlup>
+* [__Ethan Arrowood__](https://github.com/ethan-arrowood), <https://www.npmjs.com/~ethan_arrowood>
+* [__Matteo Collina__](https://github.com/mcollina), <https://www.npmjs.com/~matteo.collina>
+* [__Matthew Aitken__](https://github.com/KhafraDev), <https://www.npmjs.com/~khaf>
+* [__Robert Nagy__](https://github.com/ronag), <https://www.npmjs.com/~ronag>
+* [__Szymon Marczak__](https://github.com/szmarczak), <https://www.npmjs.com/~szmarczak>
+
+## Past Collaborators
+* [__Tomas Della Vedova__](https://github.com/delvedor), <https://www.npmjs.com/~delvedor>
+
+### Releasers
+
+* [__Ethan Arrowood__](https://github.com/ethan-arrowood), <https://www.npmjs.com/~ethan_arrowood>
+* [__Matteo Collina__](https://github.com/mcollina), <https://www.npmjs.com/~matteo.collina>
+* [__Robert Nagy__](https://github.com/ronag), <https://www.npmjs.com/~ronag>
+* [__Matthew Aitken__](https://github.com/KhafraDev), <https://www.npmjs.com/~khaf>
+
+## Long Term Support
+
+Undici aligns with the Node.js LTS schedule. The following table shows the supported versions:
+
+| Undici Version | Bundled in Node.js | Node.js Versions Supported | End of Life |
+|----------------|--------------------|----------------------------|-------------|
+| 5.x            | 18.x               | ≥14.0 (tested: 14, 16, 18) | 2024-04-30  |
+| 6.x            | 20.x, 22.x         | ≥18.17 (tested: 18, 20, 21, 22) | 2027-04-30  |
+| 7.x            | 24.x               | ≥20.18.1 (tested: 20, 22, 24) | 2028-04-30  |
+| 8.x            | 26.x               | ≥22.19.0 (tested: 22, 24, 26) | 2029-04-30  |
+
+## License
+
+MIT
diff --git a/docs/docs/site.json b/docs/docs/site.json
new file mode 100644
index 00000000000..d5708269deb
--- /dev/null
+++ b/docs/docs/site.json
@@ -0,0 +1,119 @@
+{
+  "sidebar": [
+    {
+      "groupName": "Documentation",
+      "items": [
+        { "link": "/", "label": "Home" },
+        { "link": "/getting-started", "label": "Getting Started" }
+      ]
+    },
+    {
+      "groupName": "API",
+      "items": [
+        {
+          "label": "Core",
+          "items": [
+            { "link": "/api/Dispatcher", "label": "Dispatcher" },
+            { "link": "/api/Client", "label": "Client" },
+            { "link": "/api/H2CClient", "label": "H2CClient" },
+            { "link": "/api/Pool", "label": "Pool" },
+            { "link": "/api/BalancedPool", "label": "BalancedPool" },
+            { "link": "/api/RoundRobinPool", "label": "RoundRobinPool" },
+            { "link": "/api/Agent", "label": "Agent" },
+            { "link": "/api/PoolStats", "label": "PoolStats" },
+            { "link": "/api/Connector", "label": "Connector" }
+          ]
+        },
+        {
+          "label": "Proxy & Agents",
+          "items": [
+            { "link": "/api/ProxyAgent", "label": "ProxyAgent" },
+            {
+              "link": "/api/EnvHttpProxyAgent",
+              "label": "EnvHttpProxyAgent"
+            },
+            { "link": "/api/Socks5ProxyAgent", "label": "Socks5ProxyAgent" },
+            { "link": "/api/RetryAgent", "label": "RetryAgent" }
+          ]
+        },
+        {
+          "label": "Web Standards",
+          "items": [
+            { "link": "/api/Fetch", "label": "Fetch" },
+            { "link": "/api/EventSource", "label": "EventSource" },
+            { "link": "/api/WebSocket", "label": "WebSocket" },
+            { "link": "/api/Cookies", "label": "Cookies" },
+            { "link": "/api/CacheStorage", "label": "CacheStorage" },
+            { "link": "/api/ContentType", "label": "MIME Type Parsing" }
+          ]
+        },
+        {
+          "label": "Mocking",
+          "items": [
+            { "link": "/api/MockClient", "label": "MockClient" },
+            { "link": "/api/MockPool", "label": "MockPool" },
+            { "link": "/api/MockAgent", "label": "MockAgent" },
+            { "link": "/api/SnapshotAgent", "label": "SnapshotAgent" },
+            { "link": "/api/MockCallHistory", "label": "MockCallHistory" },
+            {
+              "link": "/api/MockCallHistoryLog",
+              "label": "MockCallHistoryLog"
+            },
+            { "link": "/api/MockErrors", "label": "MockErrors" }
+          ]
+        },
+        {
+          "label": "Handlers",
+          "items": [
+            { "link": "/api/RedirectHandler", "label": "RedirectHandler" },
+            { "link": "/api/RetryHandler", "label": "RetryHandler" }
+          ]
+        },
+        {
+          "label": "Diagnostics & Utilities",
+          "items": [
+            { "link": "/api/Errors", "label": "Errors" },
+            {
+              "link": "/api/DiagnosticsChannel",
+              "label": "Diagnostics Channel Support"
+            },
+            { "link": "/api/Debug", "label": "Debug" },
+            { "link": "/api/Util", "label": "Util" },
+            {
+              "link": "/api/GlobalInstallation",
+              "label": "Global Installation"
+            },
+            { "link": "/api/api-lifecycle", "label": "API Lifecycle" }
+          ]
+        }
+      ]
+    },
+    {
+      "groupName": "Best Practices",
+      "items": [
+        {
+          "link": "/best-practices/undici-vs-builtin-fetch",
+          "label": "Undici vs. Built-in Fetch"
+        },
+        {
+          "link": "/best-practices/migrating-from-v7-to-v8",
+          "label": "Migrating from Undici 7 to 8"
+        },
+        { "link": "/best-practices/proxy", "label": "Proxy" },
+        {
+          "link": "/best-practices/client-certificate",
+          "label": "Client Certificate"
+        },
+        {
+          "link": "/best-practices/writing-tests",
+          "label": "Writing Tests"
+        },
+        {
+          "link": "/best-practices/mocking-request",
+          "label": "Mocking Request"
+        },
+        { "link": "/best-practices/crawling", "label": "Crawling" }
+      ]
+    }
+  ]
+}
\ No newline at end of file
diff --git a/docs/docs/type-map.json b/docs/docs/type-map.json
new file mode 100644
index 00000000000..307b159bc89
--- /dev/null
+++ b/docs/docs/type-map.json
@@ -0,0 +1,79 @@
+{
+  "AbortError": "/api/Errors.md#class-aborterror",
+  "Agent": "/api/Agent.md#class-agent",
+  "AgentDispatchOptions": "/api/Agent.md#agentdispatchoptions-handler",
+  "AgentOptions": "/api/Agent.md#new-agentoptions",
+  "BalancedPool": "/api/BalancedPool.md#class-balancedpool",
+  "BalancedPoolOptions": "/api/BalancedPool.md#parameter-balancedpooloptions",
+  "BodyMixin": "/api/Fetch.md#new-formdata",
+  "Buffer": "https://nodejs.org/api/buffer.html#class-buffer",
+  "BuildOptions": "/api/Connector.md#buildconnectoroptions",
+  "CacheKey": "/api/CacheStore.md#cachekey",
+  "CacheStore": "/api/CacheStore.md#new-memorycachestoreoptions",
+  "CacheValue": "/api/CacheStore.md#cachevalue",
+  "ClientDestroyedError": "/api/Errors.md#class-clientdestroyederror",
+  "ClientOptions": "/api/Client.md#new-clienturl-options",
+  "ClientStats": "/api/ClientStats.md#class-clientstats",
+  "ConnectOptions": "/api/Dispatcher.md#class-dispatcher",
+  "Cookie": "/api/Cookies.md#cookie",
+  "DispatchController": "/api/Dispatcher.md#class-dispatcher",
+  "DispatchHandler": "/api/Dispatcher.md#class-dispatcher",
+  "DispatchOptions": "/api/Dispatcher.md#class-dispatcher",
+  "Dispatcher": "/api/Dispatcher.md#class-dispatcher",
+  "Duplex": "https://nodejs.org/api/stream.html#class-streamduplex",
+  "EnvHttpProxyAgent": "/api/EnvHttpProxyAgent.md#class-envhttpproxyagent",
+  "EnvHttpProxyAgentOptions": "/api/EnvHttpProxyAgent.md#new-envhttpproxyagentoptions",
+  "EventEmitter": "https://nodejs.org/api/events.html#class-eventemitter",
+  "GetResult": "/api/CacheStore.md#getresult",
+  "H2CClientOptions": "/api/H2CClient.md#new-h2cclienturl-options",
+  "HeadersInit": "https://developer.mozilla.org/docs/Web/API/Headers/Headers",
+  "InvalidArgumentError": "/api/Errors.md#class-invalidargumenterror",
+  "Iterable": "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Iteration_protocols",
+  "MaxOriginsReachedError": "/api/Errors.md#class-maxoriginsreachederror",
+  "MockAgent": "/api/MockAgent.md#class-mockagent",
+  "MockAgentOptions": "/api/MockAgent.md#parameter-mockagentoptions",
+  "MockCallHistory": "/api/MockCallHistory.md#class-mockcallhistory",
+  "MockCallHistoryLog": "/api/MockCallHistoryLog.md#class-mockcallhistorylog",
+  "MockClient": "/api/MockClient.md#class-mockclient",
+  "MockClientOptions": "/api/MockClient.md#parameter-mockclientoptions",
+  "MockInterceptor": "/api/MockPool.md#return-mockinterceptor",
+  "MockInterceptor.Options": "/api/MockPool.md#parameter-mockpoolinterceptoptions",
+  "MockPool": "/api/MockPool.md#class-mockpool",
+  "MockPoolInterceptOptions": "/api/MockPool.md#parameter-mockpoolinterceptoptions",
+  "MockPoolOptions": "/api/MockPool.md#parameter-mockpooloptions",
+  "MockResponseOptions": "/api/MockPool.md#parameter-mockresponseoptions",
+  "MockScope": "/api/MockPool.md#return-mockscope",
+  "PendingInterceptor": "/api/MockAgent.md#new-mockagentoptions",
+  "PipelineOptions": "/api/Dispatcher.md#class-dispatcher",
+  "Pool": "/api/Pool.md#class-pool",
+  "PoolOptions": "/api/Pool.md#new-poolurl-options",
+  "PoolStats": "/api/PoolStats.md#class-poolstats",
+  "ProxyAgent": "/api/ProxyAgent.md#class-proxyagent",
+  "ProxyAgentOptions": "/api/ProxyAgent.md#new-proxyagentoptions",
+  "Readable": "https://nodejs.org/api/stream.html#class-streamreadable",
+  "Record": "https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type",
+  "RequestInit": "/api/Fetch.md#new-formdata",
+  "RequestOptions": "/api/Dispatcher.md#class-dispatcher",
+  "ResponseInit": "/api/Fetch.md#new-formdata",
+  "RetryContext": "/api/RetryHandler.md#retrycontext",
+  "RetryHandler": "/api/RetryHandler.md#class-retryhandler",
+  "RetryHandlers": "/api/RetryHandler.md#parameter-retryhandlers",
+  "RetryOptions": "/api/RetryHandler.md#retryoptions",
+  "RetryState": "/api/RetryHandler.md#retrystate",
+  "RoundRobinPoolOptions": "/api/RoundRobinPool.md#parameter-roundrobinpooloptions",
+  "SnapshotRecorder": "/api/SnapshotAgent.md#new-snapshotagentoptions",
+  "Socket": "https://nodejs.org/api/net.html#class-netsocket",
+  "SocketInfo": "/api/Errors.md#new-requestretryerrormessage-code-options",
+  "StreamOptions": "/api/Dispatcher.md#class-dispatcher",
+  "TLSSocket": "https://nodejs.org/api/tls.html#class-tlstlssocket",
+  "UndiciError": "/api/Errors.md#class-undicierror",
+  "UndiciHeaders": "/api/Dispatcher.md#class-dispatcher",
+  "UpgradeOptions": "/api/Dispatcher.md#class-dispatcher",
+  "UrlObject": "/index.md#urlobject",
+  "WebSocketInit": "/api/WebSocket.md#new-websocketurl-protocols",
+  "WebSocketStreamOptions": "/api/WebSocket.md#new-websocketurl-protocols",
+  "Writable": "https://nodejs.org/api/stream.html#class-streamwritable",
+  "buildConnector.BuildOptions": "/api/Connector.md#buildconnectoroptions",
+  "net.Socket": "https://nodejs.org/api/net.html#class-netsocket",
+  "stream.Readable": "https://nodejs.org/api/stream.html#class-streamreadable"
+}
\ No newline at end of file
diff --git a/docs/docsify/sidebar.md b/docs/docsify/sidebar.md
deleted file mode 100644
index c80542c9e8e..00000000000
--- a/docs/docsify/sidebar.md
+++ /dev/null
@@ -1,50 +0,0 @@
-<!-- Sidebar for Docsify -->
-
-* [**Home**](/ "Node.js Undici")
-* [Getting Started](/docs/docs/GettingStarted.md "Getting Started with Undici")
-* API
-  * [Dispatcher](/docs/docs/api/Dispatcher.md "Undici API - Dispatcher")
-  * [Client](/docs/docs/api/Client.md "Undici API - Client")
-  * [H2CClient](/docs/docs/api/H2CClient.md "Undici H2C API - Client")
-  * [Pool](/docs/docs/api/Pool.md "Undici API - Pool")
-  * [BalancedPool](/docs/docs/api/BalancedPool.md "Undici API - BalancedPool")
-  * [RoundRobinPool](/docs/docs/api/RoundRobinPool.md "Undici API - RoundRobinPool")
-  * [Agent](/docs/docs/api/Agent.md "Undici API - Agent")
-  * [ProxyAgent](/docs/docs/api/ProxyAgent.md "Undici API - ProxyAgent")
-  * [Socks5ProxyAgent](/docs/docs/api/Socks5ProxyAgent.md "Undici API - SOCKS5 Proxy Agent")
-  * [RetryAgent](/docs/docs/api/RetryAgent.md "Undici API - RetryAgent")
-  * [Connector](/docs/docs/api/Connector.md "Custom connector")
-  * [Errors](/docs/docs/api/Errors.md "Undici API - Errors")
-  * [EventSource](/docs/docs/api/EventSource.md "Undici API - EventSource")
-  * [Fetch](/docs/docs/api/Fetch.md "Undici API - Fetch")
-  * [Global Installation](/docs/docs/api/GlobalInstallation.md "Undici API - Global Installation")
-  * [Cookies](/docs/docs/api/Cookies.md "Undici API - Cookies")
-  * [MockClient](/docs/docs/api/MockClient.md "Undici API - MockClient")
-  * [MockPool](/docs/docs/api/MockPool.md "Undici API - MockPool")
-  * [MockAgent](/docs/docs/api/MockAgent.md "Undici API - MockAgent")
-  * [SnapshotAgent](/docs/docs/api/SnapshotAgent.md "Undici API - SnapshotAgent")
-  * [MockCallHistory](/docs/docs/api/MockCallHistory.md "Undici API - MockCallHistory")
-  * [MockCallHistoryLog](/docs/docs/api/MockCallHistoryLog.md "Undici API - MockCallHistoryLog")
-  * [MockErrors](/docs/docs/api/MockErrors.md "Undici API - MockErrors")
-  * [API Lifecycle](/docs/docs/api/api-lifecycle.md "Undici API - Lifecycle")
-  * [Diagnostics Channel Support](/docs/docs/api/DiagnosticsChannel.md "Diagnostics Channel Support")
-  * [Debug](/docs/docs/api/Debug.md "Undici API - Debugging Undici")
-  * [WebSocket](/docs/docs/api/WebSocket.md "Undici API - WebSocket")
-  * [MIME Type Parsing](/docs/docs/api/ContentType.md "Undici API - MIME Type Parsing")
-  * [CacheStorage](/docs/docs/api/CacheStorage.md "Undici API - CacheStorage")
-  * [Util](/docs/docs/api/Util.md "Undici API - Util")
-  * [RedirectHandler](/docs/docs/api/RedirectHandler.md "Undici API - RedirectHandler")
-  * [RetryHandler](/docs/docs/api/RetryHandler.md "Undici API - RetryHandler")
-  * [DiagnosticsChannel](/docs/docs/api/DiagnosticsChannel.md "Undici API - DiagnosticsChannel")
-  * [EnvHttpProxyAgent](/docs/docs/api/EnvHttpProxyAgent.md "Undici API - EnvHttpProxyAgent")
-  * [PoolStats](/docs/docs/api/PoolStats.md "Undici API - PoolStats")
-* Examples
-  * [Undici Examples](/docs/examples/ "Undici Examples")
-* Best Practices
-  * [Undici vs. Built-in Fetch](/docs/docs/best-practices/undici-vs-builtin-fetch.md "When to install undici vs using Node.js built-in fetch")
-  * [Migrating from Undici 7 to 8](/docs/docs/best-practices/migrating-from-v7-to-v8.md "Upgrade applications and libraries from Undici v7 to v8")
-  * [Proxy](/docs/docs/best-practices/proxy.md "Connecting through a proxy")
-  * [Client Certificate](/docs/docs/best-practices/client-certificate.md "Connect using a client certificate")
-  * [Writing Tests](/docs/docs/best-practices/writing-tests.md "Using Undici inside tests")
-  * [Mocking Request](/docs/docs/best-practices/mocking-request.md "Using Undici inside tests")
-  * [Crawling](/docs/docs/best-practices/crawling.md "Crawling")
diff --git a/docs/index.html b/docs/index.html
deleted file mode 100644
index 780f0f1567c..00000000000
--- a/docs/index.html
+++ /dev/null
@@ -1,126 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-
-<head>
-  <meta charset="UTF-8">
-  <title>Node.js Undici</title>
-  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
-  <meta name="description" content="A HTTP/1.1 client, written from scratch for Node.js.">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
-  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">
-  <link
-  rel="stylesheet"
-  href="//cdn.jsdelivr.net/npm/docsify-darklight-theme@latest/dist/style.min.css"
-  title="docsify-darklight-theme"
-  type="text/css"
-/>
-  <link rel="icon" type="image/png" href="https://nodejs.org/static/images/favicons/favicon.png" />
-</head>
-
-<body>
-  <div id="app"></div>
-  <script>
-    window.$docsify = {
-      name: 'Node.js Undici',
-      repo: 'https://github.com/nodejs/undici',
-      loadSidebar: 'docsify/sidebar.md',
-      search: {
-        noData: {
-          '/': 'No results!'
-        },
-        paths: ['docs/'],
-        placeholder: {
-          '/': 'Search'
-        }
-      },
-      auto2top: true,
-      subMaxLevel: 3,
-      maxLevel: 3,
-      themeColor: '#2B91F0',
-      noCompileLinks: [
-        'benchmarks/.*'
-      ],
-      copyCode: {
-        buttonText: 'Copy Code',
-        errorText: 'Error',
-        successText: 'Copied',
-      },
-      relativePath: true,
-      markdown: {
-        renderer: {
-          // Mimic markedjs/marked behavior just modify href - https://github.com/markedjs/marked/blob/master/src/Renderer.ts#L178-L191
-          link(href, title, text) {
-            const originalHref = href;
-
-            if (href.startsWith('./')) {
-              // Use absolute path (e.g. ./docs/api.md => /docs/api.md) if href starts with ./ (e.g. ./api.md)
-              href = href.slice(1);
-            }
-
-            // Check for /docs/docs/ in the href and remove duplication it if present
-            href = href.startsWith('/docs/docs/') ? href.replace('/docs/', '/') : href;
-
-            // Check for /docs/ in the href and remove it if present
-            if (href.startsWith('/docs/')) {
-              // ignore paths /docs/api/ and /docs/best-practices/ in /docs/docs directory
-              if (!/^(\/docs\/(?:api|best-practices))(?:\/|$)/.test(href)) {
-                href = href.includes('/docs/') ? href.replace('/docs/', '/') : href;
-              }
-            }
-
-            let target = '';
-            if (originalHref.startsWith('http')) {
-              // External link - default behavior is to open in a new window
-              return `<a href="${originalHref}" ${title}" target="_blank" rel="noopener noreferrer">${text}</a>`;
-            }
-
-            title = title ? `title="${title}"` : '';
-            let out = `<a href="#${href}" ${title}">${text}</a>`;
-
-            return out;
-          },
-        },
-      },
-    }
-  </script>
-  <!-- Docsify v4 -->
-  <script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
-  <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>
-  <script src="https://unpkg.com/docsify-copy-code@3"></script>
-  <script
-  src="//cdn.jsdelivr.net/npm/docsify-darklight-theme@latest/dist/index.min.js"
-  type="text/javascript"
-></script>
-  <script type="module">
-    import mermaid from "//cdn.jsdelivr.net/npm/mermaid@10.8.0/+esm";
-    mermaid.initialize({ startOnLoad: true });
-    window.mermaid = mermaid;
-  </script>
-  <script>
-    const plugin = (config) => (hook) => {
-      hook.afterEach((html, next) => {
-        const container = document.createElement('div');
-        container.innerHTML = html;
-
-        const elements = container.querySelectorAll('pre[data-lang=mermaid]')
-        for (const element of elements) {
-          const replacement = document.createElement('div');
-          replacement.textContent = element.textContent;
-          replacement.classList.add('mermaid');
-          element.parentNode.replaceChild(replacement, element);
-        }
-
-        next(container.innerHTML);
-      });
-
-      hook.doneEach(() => mermaid.run(config));
-    }
-
-    window.$docsify = window.$docsify || {};
-
-    window.$docsify.plugins = window.$docsify.plugins || []
-    window.$docsify.plugins.push(plugin(window.$docsify.mermaidConfig || { querySelector: ".mermaid" }));
-  </script>
-</body>
-
-</html>
\ No newline at end of file
diff --git a/docs/package.json b/docs/package.json
deleted file mode 100644
index 491fcfc4f6c..00000000000
--- a/docs/package.json
+++ /dev/null
@@ -1,11 +0,0 @@
-{
-  "private": true,
-  "name": "@undici/documentation",
-  "description": "Documentation site for the `undici` package.",
-  "scripts": {
-    "serve": "docsify serve ."
-  },
-  "dependencies": {
-    "docsify-cli": "^4.4.4"
-  }
-}
diff --git a/scripts/release.js b/scripts/release.js
index 111b1daac93..7b6efb444f9 100644
--- a/scripts/release.js
+++ b/scripts/release.js
@@ -68,6 +68,16 @@ const release = async ({ github, context, versionTag, commitHash }) => {
     generate_release_notes: false
   })
 
+  await github.rest.actions.createWorkflowDispatch({
+    owner: 'nodejs',
+    repo: 'undici-website',
+    workflow_id: 'release.yml',
+    ref: 'main',
+    inputs: {
+      tag: versionTag
+    }
+  })
+
   try {
     await github.rest.git.deleteRef({
       owner,

From 3562ada50b5177b05cc74670459281e1b0e97b0f Mon Sep 17 00:00:00 2001
From: avivkeller <me@aviv.sh>
Date: Sat, 20 Jun 2026 11:33:13 -0400
Subject: [PATCH 2/2] fixup!

---
 scripts/release.js | 10 ----------
 1 file changed, 10 deletions(-)

diff --git a/scripts/release.js b/scripts/release.js
index 7b6efb444f9..111b1daac93 100644
--- a/scripts/release.js
+++ b/scripts/release.js
@@ -68,16 +68,6 @@ const release = async ({ github, context, versionTag, commitHash }) => {
     generate_release_notes: false
   })
 
-  await github.rest.actions.createWorkflowDispatch({
-    owner: 'nodejs',
-    repo: 'undici-website',
-    workflow_id: 'release.yml',
-    ref: 'main',
-    inputs: {
-      tag: versionTag
-    }
-  })
-
   try {
     await github.rest.git.deleteRef({
       owner,
