diff --git a/.changeset/client-generator.md b/.changeset/client-generator.md
new file mode 100644
index 0000000000..d19eeceddf
--- /dev/null
+++ b/.changeset/client-generator.md
@@ -0,0 +1,9 @@
+---
+'@redocly/client-generator': minor
+'@redocly/openapi-core': minor
+'@redocly/cli': minor
+---
+
+Added an experimental `generate-client` command that generates a typed, zero-dependency TypeScript client from an OpenAPI description — with auth, retries, middleware, typed SSE streaming, auto-pagination, and multipart support.
+The `--generator` option emits companion modules from the same description: `zod`, `tanstack-query`, `swr`, `transformers`, and `mock`.
+See the [`generate-client` command reference](https://redocly.com/docs/cli/commands/generate-client) and the [Use the generated client](https://redocly.com/docs/cli/guides/use-generated-client) guide.
diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml
index a9bd6ec2b0..fd322abf71 100644
--- a/.github/workflows/release.yaml
+++ b/.github/workflows/release.yaml
@@ -206,6 +206,11 @@ jobs:
           cache: npm
           registry-url: https://registry.npmjs.org
 
+      # Install before the version bump: npm links workspace packages only while
+      # their versions still match the dependency specs in package.json files.
+      - name: Install dependencies
+        run: npm install
+
       - name: Update package versions
         run: |
           TIMESTAMP=$(date +%s)
@@ -218,6 +223,10 @@ jobs:
           jq ".version = \"$VERSION\"" packages/respect-core/package.json > tmp.json && mv tmp.json packages/respect-core/package.json
           jq ".dependencies[\"@redocly/openapi-core\"] = \"$VERSION\"" packages/respect-core/package.json > tmp.json && mv tmp.json packages/respect-core/package.json
 
+          # Update Client Generator package version and dependencies
+          jq ".version = \"$VERSION\"" packages/client-generator/package.json > tmp.json && mv tmp.json packages/client-generator/package.json
+          jq ".dependencies[\"@redocly/openapi-core\"] = \"$VERSION\"" packages/client-generator/package.json > tmp.json && mv tmp.json packages/client-generator/package.json
+
           # Update CLI package version
           jq ".version = \"$VERSION\"" packages/cli/package.json > tmp.json && mv tmp.json packages/cli/package.json
 
@@ -236,9 +245,6 @@ jobs:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           PR_NUMBER: ${{ github.event.pull_request.number }}
 
-      - name: Install dependencies
-        run: npm install
-
       - name: Build packages
         run: npm run compile
 
@@ -258,3 +264,7 @@ jobs:
           npm run prepare:publish-dir
           npm publish ./.publish --tag snapshot
           npm run clean:publish-dir
+          sleep 10
+
+          cd ../client-generator
+          npm publish --tag snapshot
diff --git a/.github/workflows/tests.yaml b/.github/workflows/tests.yaml
index c7432bee66..fa05d472a5 100644
--- a/.github/workflows/tests.yaml
+++ b/.github/workflows/tests.yaml
@@ -7,6 +7,9 @@ on:
     branches:
       - main
 
+permissions:
+  contents: read
+
 env:
   CI: true
   REDOCLY_TELEMETRY: off
@@ -32,8 +35,44 @@ jobs:
         continue-on-error: true # Do not fail if there is an error during reporting
         uses: davelosert/vitest-coverage-report-action@d63aa97db4c0319f304f1787689de1ca548365cf # v2.11.1
 
-      - name: E2E Tests
-        run: npm run e2e
+  e2e:
+    # The e2e suite is split across shards so no single runner carries the whole set.
+    # Running all suites in one step was cancelled mid-run by the Actions service once the
+    # generate-client suites grew past ~28 (a healthy runner, no resource exhaustion);
+    # each shard stays well under that.
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: [1, 2]
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+        with:
+          node-version: 24
+          cache: npm
+      - name: Install dependencies
+        run: npm ci
+      - name: E2E Tests (shard ${{ matrix.shard }}/2)
+        run: npm run e2e -- --shard=${{ matrix.shard }}/2
+
+  examples:
+    # The examples gitignore their generated clients (only zero-install-quickstart commits
+    # its canonical copy), so this job regenerates every client and type-checks the
+    # hand-written consumer code against it.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+        with:
+          node-version: 24
+          cache: npm
+      - name: Install dependencies
+        run: npm ci
+      - name: Regenerate example clients
+        run: npm run examples:regen -w @redocly/client-generator
+      - name: Type-check examples
+        run: npm run typecheck:examples -w @redocly/client-generator
 
   code-style-check:
     runs-on: ubuntu-latest
diff --git a/.oxfmtrc.json b/.oxfmtrc.json
index 86a784dacb..fc6793d2c6 100644
--- a/.oxfmtrc.json
+++ b/.oxfmtrc.json
@@ -10,8 +10,11 @@
     "packages/respect-core/src/modules/runtime-expressions/abnf-parser.js",
     "packages/core/src/rules/common/__tests__/fixtures/invalid-yaml.yaml",
     "tests/performance/api-definitions/",
+    "tests/e2e/generate-client/examples/*/src/api/",
+    "tests/e2e/generate-client/*-consumer/api*.ts",
     "tests/smoke/**/*.yaml",
     "snapshot*.txt",
+    "tests/e2e/generate-client/*.snapshot.ts",
     "*.html",
     "*.hbs",
     "*.toml",
diff --git a/.oxlintrc.json b/.oxlintrc.json
index e98cdc4a7e..c6904b20a1 100644
--- a/.oxlintrc.json
+++ b/.oxlintrc.json
@@ -9,7 +9,15 @@
     "builtin": true,
     "es2026": true
   },
-  "ignorePatterns": ["packages/*/lib/**", "*.js", "*.cjs"],
+  "ignorePatterns": [
+    "packages/*/lib/**",
+    "*.js",
+    "*.cjs",
+    "tests/e2e/generate-client/examples/*/src/api/**",
+    "tests/e2e/generate-client/examples/*/generate.ts",
+    "tests/e2e/generate-client/*.snapshot.ts",
+    "tests/e2e/generate-client/*-consumer/api.ts"
+  ],
   "rules": {
     "eslint/no-array-constructor": "error",
     "eslint/no-case-declarations": "error",
@@ -68,6 +76,15 @@
       "rules": {
         "eslint/no-console": "allow"
       }
+    },
+    {
+      "files": [
+        "tests/e2e/generate-client/examples/*/src/**",
+        "tests/e2e/generate-client/examples/*/worker.ts"
+      ],
+      "rules": {
+        "eslint/no-console": "allow"
+      }
     }
   ]
 }
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c5b55c42b7..f6e570e780 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -212,6 +212,7 @@ Run `npm test` to start both unit and e2e tests (and additionally typecheck the
 ### Unit tests
 
 Run unit tests with this command: `npm run unit`.
+This command runs the suite for every package whose tests match the discovery glob — there is no per-package `npm test` script.
 
 Unit tests in the **cli** package are sensitive to top-level configuration file (**redocly.yaml**).
 
diff --git a/README.md b/README.md
index 7ffb8715b2..c08012b42e 100644
--- a/README.md
+++ b/README.md
@@ -139,6 +139,21 @@ Respect is Redocly's community-edition product. Looking for something more? We a
 
 Learn more about [Respect](https://redocly.com/respect) and [get started with API contract testing](https://redocly.com/docs/respect/get-started).
 
+### Generate a TypeScript client
+
+> ⚠️ **Experimental** — flags, output, and configuration may change in any minor release until declared stable.
+
+Turn an OpenAPI description (3.0/3.1/3.2 or Swagger 2.0) into a typed TypeScript client with the `generate-client` command.
+The emitted client has zero runtime dependencies and runs in browsers, Node, Bun, Deno, and edge runtimes.
+
+```sh
+redocly generate-client openapi.yaml --output src/client.ts
+```
+
+Inline types plus a typed client instance and one async function per operation, with auth, opt-in abort-aware retries, middleware, and typed Server-Sent Events.
+The same command can also emit Zod schemas, TanStack Query / SWR hooks, MSW mocks, and more via `--generators`.
+For detailed information, read the [ `generate-client` docs](./docs/@v2/commands/generate-client.md).
+
 ### Transform an OpenAPI description
 
 If your OpenAPI description isn't everything you hoped it would be, enhance it with the Redocly [decorators](https://redocly.com/docs/cli/decorators) feature.
diff --git a/docs/@v2/commands/generate-client.md b/docs/@v2/commands/generate-client.md
new file mode 100644
index 0000000000..48c909bf0a
--- /dev/null
+++ b/docs/@v2/commands/generate-client.md
@@ -0,0 +1,113 @@
+# `generate-client`
+
+{% admonition type="warning" name="Experimental" %}
+`generate-client` is an experimental feature: its flags, generated output, configuration schema, and custom-generator API may change in any minor release until it's stable.
+We'd love your feedback while we stabilize it.
+{% /admonition %}
+
+## Introduction
+
+The `generate-client` command generates a typed TypeScript client from an OpenAPI 3.x description.
+Swagger 2.0 descriptions are also accepted and normalized to the 3.x shape before generation.
+
+The generated client has zero runtime dependencies by default — it uses only web-standard APIs (`fetch`, `AbortController`, `URLSearchParams`), so it runs in browsers, Node, Bun, Deno, and edge runtimes.
+By default it emits a single self-contained file with inline types and one async function per operation.
+
+The `<api>` argument is a file path, a URL, or an [`apis:` alias](../configuration/index.md), resolved the same way as in other commands such as `bundle` and `lint`.
+An alias, or a path matching an api's `root`, uses that api's `client` block and `clientOutput`; an unmatched path or URL uses the top-level `client` defaults.
+With no argument, a client is generated for every api that declares a `client` block or a `clientOutput` (see [`client` configuration](../configuration/reference/client.md)).
+
+This page covers running the command; for the generated client's runtime API (auth, error handling, middleware, retries, and the add-on generators), see [Use the generated client](../guides/use-generated-client.md).
+
+## Usage
+
+```bash
+redocly generate-client
+redocly generate-client <api>
+redocly generate-client <api> [--output=<path>] [--output-mode=<mode>] [--runtime=<mode>]
+redocly generate-client <api> [--generator=<name>] [--args-style=<style>] [--error-mode=<mode>]
+redocly generate-client <api> [--config=<path>]
+```
+
+## Options
+
+| Option              | Type       | Description                                                                                                                                                                                                                                                      |
+| ------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `api`               | `string`   | OpenAPI description file path, URL, or an `apis:` alias. Omit it to generate for every api that has a `client` block or `clientOutput`.                                                                                                                          |
+| `--output`, `-o`    | `string`   | Output path (must end in `.ts`); the entry file in multi-file modes. Defaults to the api's `clientOutput`, else `<name>.client.ts` next to the configuration file. Single-API invocations only.                                                                  |
+| `--output-mode`     | `string`   | File layout. See [Choose an output mode](#choose-an-output-mode). <br/> **Possible values:** `single`, `split`. Default value is `single`.                                                                                                                       |
+| `--runtime`         | `string`   | Where the client's engine lives. See [Choose a runtime](#choose-a-runtime). <br/> **Possible values:** `inline`, `package`. Default value is `inline`.                                                                                                           |
+| `--import-ext`      | `string`   | Extension in generated relative imports. See [Run with Node directly](../guides/use-generated-client.md#run-with-node-directly). <br/> **Possible values:** `js` (the tsc/bundler convention), `ts` (for Node's built-in type stripping). Default value is `js`. |
+| `--generator`       | `[string]` | Generator to run — a built-in name or a custom generator's path or package; repeat the flag to run several. Default value is `sdk`. See [Generators](../guides/use-generated-client.md#generators).                                                              |
+| `--args-style`      | `string`   | How operation inputs are passed. See [Argument style](../guides/use-generated-client.md#argument-style). <br/> **Possible values:** `flat`, `grouped`. Default value is `flat`.                                                                                  |
+| `--enum-style`      | `string`   | How named string enums are emitted. <br/> **Possible values:** `const-object` (an `as const` object + union), `union` (union only). Default value is `const-object`.                                                                                             |
+| `--error-mode`      | `string`   | How operations report HTTP errors. See [Error handling](../guides/use-generated-client.md#error-handling). <br/> **Possible values:** `throw`, `result`. Default value is `throw`.                                                                               |
+| `--date-type`       | `string`   | Type of `date`/`date-time` fields; pair `Date` with the `transformers` generator. <br/> **Possible values:** `string`, `Date`. Default value is `string`.                                                                                                        |
+| `--query-framework` | `string`   | Framework adapter for the `tanstack-query` generator. <br/> **Possible values:** `react`, `vue`, `svelte`, `solid`. Default value is `react`.                                                                                                                    |
+| `--mock-data`       | `string`   | Data mode for the `mock` generator. <br/> **Possible values:** `baked` (deterministic literals), `faker` (`@faker-js/faker` calls). Default value is `baked`.                                                                                                    |
+| `--mock-seed`       | `number`   | Seed for `faker`-mode mocks, for reproducible data. Ignored in `baked` mode.                                                                                                                                                                                     |
+| `--server-url`      | `string`   | Override the server URL baked into the client. Accepts an absolute (`https://api.example.com`) or relative (`/v1`) URL. Defaults to `servers[0].url`.                                                                                                            |
+| `--setup`           | `string`   | Path to a publisher setup module baked into the client. See [Publisher defaults](../guides/use-generated-client.md#publisher-defaults).                                                                                                                          |
+| `--config`          | `string`   | Specify path to the [configuration file](#generate-from-the-configuration-file).                                                                                                                                                                                 |
+
+## Examples
+
+### Generate from the configuration file
+
+Instead of passing flags every time, keep the settings in `redocly.yaml` under a top-level `client` block and per-API `apis.<name>.client` / `clientOutput` — see the [`client` configuration reference](../configuration/reference/client.md) for the fields and how they layer.
+CLI flags take precedence over the configuration.
+Auto-pagination has no CLI flag; it's declared only as [`client.pagination`](../configuration/reference/client.md#pagination-object) configuration or the `x-pagination` operation extension.
+
+```yaml
+client:
+  generators:
+    - sdk
+apis:
+  cafe:
+    root: ./openapi.yaml
+    clientOutput: ./src/api/client.ts
+```
+
+```bash
+redocly generate-client            # every api with a `client` block or `clientOutput`
+redocly generate-client cafe       # just the `cafe` api
+```
+
+### Generate from a file path or URL
+
+An unmatched path or URL uses the top-level `client` defaults; `--output` names the entry file:
+
+```bash
+redocly generate-client openapi.yaml --output dist/client.ts
+```
+
+### Choose an output mode
+
+`--output-mode` controls how the client is split across files:
+
+- `single` (default) — one file (self-contained with the default `inline` runtime).
+- `split` — two files: the schema types and type guards move to a sibling `<name>.schemas.ts`, and the entry file re-exports them, so your imports are the same as in `single`.
+
+```bash
+redocly generate-client openapi.yaml -o src/api/client.ts --output-mode split
+```
+
+Both modes work with both runtimes.
+
+### Choose a runtime
+
+`--runtime` controls where the client's engine (request building, auth, retries, middleware, SSE) lives:
+
+- `inline` (default) — the runtime source is embedded in the generated output (only the parts your API needs): self-contained, zero runtime dependencies.
+- `package` — the generated file imports the runtime from `@redocly/client-generator` and contains only the types, operation descriptors, and thin call wrappers.
+
+Choose `package` when you want engine fixes to arrive via `npm update @redocly/client-generator` with no regeneration; the consuming app must then have that package installed as a regular dependency.
+Your application code is identical in both modes.
+See [Package runtime](../guides/use-generated-client.md#package-runtime) in the usage guide and the [`package-runtime` example](https://github.com/Redocly/redocly-cli/tree/main/tests/e2e/generate-client/examples/package-runtime).
+
+## Resources
+
+- [Use the generated client](../guides/use-generated-client.md) — the runtime API and the add-on generators.
+- [`client` configuration](../configuration/reference/client.md) — the `redocly.yaml` `client` block.
+- [Lint command](./lint.md) to validate your API description before generating a client.
+- [Bundle command](./bundle.md) to combine a multi-file description into a single input file.
diff --git a/docs/@v2/commands/index.md b/docs/@v2/commands/index.md
index 8f730333a4..424f18f0f1 100644
--- a/docs/@v2/commands/index.md
+++ b/docs/@v2/commands/index.md
@@ -14,6 +14,7 @@ Documentation commands:
 API management commands:
 
 - [`bundle`](bundle.md) Bundle API description.
+- [`generate-client`](generate-client.md) Generate a typed TypeScript client from an OpenAPI description [experimental feature].
 - [`join`](join.md) Join API descriptions [experimental feature].
 - [`score`](score.md) Score an API for integration simplicity and AI agent readiness.
 - [`split`](split.md) Split API description into a multi-file structure.
diff --git a/docs/@v2/configuration/reference/apis.md b/docs/@v2/configuration/reference/apis.md
index ae94b8cbe1..614dbb34ad 100644
--- a/docs/@v2/configuration/reference/apis.md
+++ b/docs/@v2/configuration/reference/apis.md
@@ -58,6 +58,18 @@ If your project contains multiple APIs, the `apis` configuration section allows
 - Output file path
 - When running `bundle` without specifying an API, the bundled API description is saved to this location.
 
+---
+
+- client
+- [Client object](./client.md)
+- Additional TypeScript client generation configuration for this API, used by the experimental `generate-client` command.
+
+---
+
+- clientOutput
+- Output file path
+- When running `generate-client` without specifying an API, the generated TypeScript client is saved to this location.
+
 {% /table %}
 
 ## Examples
diff --git a/docs/@v2/configuration/reference/client.md b/docs/@v2/configuration/reference/client.md
new file mode 100644
index 0000000000..bd090faffa
--- /dev/null
+++ b/docs/@v2/configuration/reference/client.md
@@ -0,0 +1,106 @@
+# `client`
+
+## Introduction
+
+The `client` configuration provides settings for the [`generate-client`](../../commands/generate-client.md) command.
+The block can be used at the root of the configuration file, where it holds shared defaults, and inside an [API-specific section](./apis.md) (`apis.<name>.client`), where it overrides the root block field by field.
+
+The input and output are not part of the `client` block:
+
+- **input** — `apis.<name>.root`, or a path or alias passed on the command line.
+- **output** — `apis.<name>.clientOutput`; when omitted it defaults to `<name>.client.ts` next to the configuration file. The `--output` flag overrides it for single-API invocations.
+
+## Options
+
+Each scalar option mirrors the matching CLI flag and shares its default — see the [command options](../../commands/generate-client.md#options) for the full description of each value.
+The `pagination` option is config-only and has no flag.
+
+| Option           | Type                                    | Description                                                                                                                                                              |
+| ---------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `generators`     | `[string]`                              | Generators to run, in order. Each entry is a built-in name (`sdk`, `zod`, `tanstack-query`, `swr`, `mock`, `transformers`) or a custom generator's path or package name. |
+| `outputMode`     | `string`                                | File layout: `single` or `split`.                                                                                                                                        |
+| `runtime`        | `string`                                | Runtime distribution: `inline` or `package`.                                                                                                                             |
+| `importExt`      | `string`                                | Extension in generated relative imports: `js` (default, for tsc and bundlers) or `ts` (for Node's built-in type stripping).                                              |
+| `argsStyle`      | `string`                                | How operation inputs are passed: `flat` or `grouped`.                                                                                                                    |
+| `enumStyle`      | `string`                                | How named string enums are emitted: `const-object` or `union`.                                                                                                           |
+| `errorMode`      | `string`                                | How operations report HTTP errors: `throw` or `result`.                                                                                                                  |
+| `dateType`       | `string`                                | Type of `date`/`date-time` fields: `string` or `Date`.                                                                                                                   |
+| `queryFramework` | `string`                                | Framework adapter for the `tanstack-query` generator: `react`, `vue`, `svelte`, or `solid`.                                                                              |
+| `mockData`       | `string`                                | Data mode for the `mock` generator: `baked` or `faker`.                                                                                                                  |
+| `mockSeed`       | `number`                                | Seed for `faker`-mode mocks.                                                                                                                                             |
+| `serverUrl`      | `string`                                | Server URL baked into the client; defaults to `servers[0].url`.                                                                                                          |
+| `setup`          | `string`                                | Path to a publisher setup module baked into the client.                                                                                                                  |
+| `pagination`     | [Pagination object](#pagination-object) | Declares how the API paginates, so paginated operations gain typed `.pages()`/`.items()` async iterators.                                                                |
+
+### Pagination object
+
+The `pagination` block is an optional convention rule (the rule fields below, applied to every operation it structurally fits when `style` is set), plus per-operation `operations` overrides and an `exclude` list.
+See [Pagination in the usage guide](../../guides/use-generated-client.md#pagination) for how the generated iterators behave.
+
+| Option        | Type                      | Description                                                                                                                                                                  |
+| ------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `style`       | `string`                  | How the iterator advances: `cursor` (follow a response cursor), `offset` (advance an offset by each page's item count), or `page` (increment a page number).                 |
+| `cursorParam` | `string`                  | The query parameter that receives the cursor. **REQUIRED** for the `cursor` style.                                                                                           |
+| `nextCursor`  | `string`                  | JSON pointer (RFC 6901, starts with `/`) to the next cursor in the response. **REQUIRED** for the `cursor` style.                                                            |
+| `hasMore`     | `string`                  | Optional (`cursor` style): JSON pointer to a boolean "more pages" flag — iteration stops when it resolves to `false`, for APIs whose cursor stays non-null on the last page. |
+| `offsetParam` | `string`                  | The query parameter the iterator advances. **REQUIRED** for the `offset` and `page` styles.                                                                                  |
+| `limitParam`  | `string`                  | Optional page-size query parameter for any style; recorded for tooling — the iterator never sets it.                                                                         |
+| `items`       | `string`                  | **REQUIRED**. JSON pointer to the page's item array in the response.                                                                                                         |
+| `exclude`     | `[string]`                | operationIds that no source may paginate; wins over overrides, extensions, and the convention.                                                                               |
+| `operations`  | map of operationId → rule | Per-operation rules taking the same fields as the convention; each entry beats the spec's `x-pagination` and the convention.                                                 |
+
+The rules are verified at generate time: the advance parameter must be a declared query parameter of the right type (string for `cursor`, numeric for `offset` and `page`), and the JSON pointers must resolve in the operation's JSON success-response schema, with `items` landing on an array and `hasMore` on a boolean.
+A convention that doesn't fit an operation skips it; an explicit rule that doesn't fit fails generation.
+The `x-pagination` operation extension in the API description takes the same rule fields.
+Per operation, precedence is `operations[id]`, then `x-pagination`, then the convention.
+
+## Examples
+
+### Configure shared defaults with a per-API override
+
+A per-API `client` block overrides the top-level `client` field by field; unspecified fields fall back to the top-level defaults.
+A file-path invocation matching no `apis:` entry uses only the top-level `client`, and CLI flags take precedence over the resolved configuration.
+
+```yaml
+client:
+  generators:
+    - sdk
+  argsStyle: flat
+apis:
+  cafe:
+    root: ./openapi.yaml
+    clientOutput: ./src/api/client.ts
+    client:
+      argsStyle: grouped
+```
+
+### Declare pagination
+
+The nested `pagination` block layers the same way: per-API `operations` merge by operationId, and `exclude` lists union with the top-level ones.
+
+```yaml
+client:
+  pagination:
+    style: cursor
+    cursorParam: cursor
+    nextCursor: /nextCursor
+    items: /orders
+    exclude:
+      - listOrderEvents
+    operations:
+      listMenuItems:
+        style: page
+        offsetParam: page
+        items: /data
+```
+
+For code-level control — including registering [custom generators](../../guides/use-generated-client.md#custom-generators) inline — use the programmatic `generateClient(...)` API instead.
+
+## Related options
+
+- [apis](./apis.md) settings define each API's root document, output, and per-API overrides.
+
+## Resources
+
+- [`generate-client` command](../../commands/generate-client.md) — flags, output modes, and invocation.
+- [Use the generated client](../../guides/use-generated-client.md) — the runtime API (auth, retries, middleware, extra generators).
diff --git a/docs/@v2/guides/use-generated-client.md b/docs/@v2/guides/use-generated-client.md
new file mode 100644
index 0000000000..4c2a7fba71
--- /dev/null
+++ b/docs/@v2/guides/use-generated-client.md
@@ -0,0 +1,457 @@
+# Use the generated client
+
+How to consume the TypeScript client produced by [`generate-client`](../commands/generate-client.md): authentication, argument styles, error handling, middleware, retries, and the optional add-on generators.
+For invoking the command itself (flags, output modes, config), see the [`generate-client` command reference](../commands/generate-client.md).
+
+## Generators
+
+`--generator` selects what to emit (default `sdk`).
+Each non-`sdk` generator adds a standalone sibling module next to the client; the client itself never imports it, so an add-on never adds a dependency to the client.
+Incompatible selections fail fast with an explanation.
+
+| Generator        | Emits                                                                                              | App peer dependency                                      |
+| ---------------- | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
+| `sdk`            | The typed client (default).                                                                        | none                                                     |
+| `zod`            | `<output>.zod.ts` — [Zod](https://zod.dev) schemas + [validation middleware](#runtime-validation). | `zod` `^3.23 \|\| ^4`                                    |
+| `tanstack-query` | `<output>.tanstack.ts` — [TanStack Query](https://tanstack.com/query) v5 factories.                | `@tanstack/<framework>-query` `^5`                       |
+| `swr`            | `<output>.swr.ts` — [SWR](https://swr.vercel.app) hooks.                                           | `swr` `^2`                                               |
+| `mock`           | `<output>.mocks.ts` — [MSW](https://mswjs.io) v2 handlers + `create<Schema>` factories.            | `msw` `^2` (+ `@faker-js/faker` for `--mock-data faker`) |
+| `transformers`   | `<output>.transformers.ts` — `transform<Name>` functions that parse wire dates to `Date`.          | none                                                     |
+
+```sh
+redocly generate-client openapi.yaml --output src/client.ts --generator sdk --generator zod --generator mock
+```
+
+`tanstack-query` and `swr` wrap the throw-mode `sdk` functions, so they require `--error-mode throw`; `transformers` requires `--date-type Date`.
+See the [`zod`](https://github.com/Redocly/redocly-cli/tree/main/tests/e2e/generate-client/examples/zod), [`tanstack-query`](https://github.com/Redocly/redocly-cli/tree/main/tests/e2e/generate-client/examples/tanstack-query), and [`mock`](https://github.com/Redocly/redocly-cli/tree/main/tests/e2e/generate-client/examples/mock) examples.
+
+## Package runtime
+
+By default the runtime is embedded in the generated file, so the client is self-contained.
+With [`--runtime package`](../commands/generate-client.md#runtime-distribution) the generated file instead imports the runtime from `@redocly/client-generator` — your application code is **identical in both modes** (same exports, same call shapes); only where the engine lives changes.
+Choose `package` when you want engine fixes and improvements via `npm update @redocly/client-generator`, with no regeneration.
+
+Install the runtime as a regular dependency and set the mode in `redocly.yaml`:
+
+```sh
+npm install @redocly/client-generator
+```
+
+```yaml
+client:
+  runtime: package # default: inline (self-contained)
+```
+
+An incompatible generated-file/runtime pair fails your `tsc` build (the descriptor `satisfies` check) rather than misbehaving at runtime.
+Package mode works with both output modes and every generator.
+See the [`package-runtime` example](https://github.com/Redocly/redocly-cli/tree/main/tests/e2e/generate-client/examples/package-runtime).
+
+## Run with Node directly
+
+Node 22.7+ runs TypeScript natively (type stripping), so you can execute a script that uses the generated client with plain `node` — no `tsx`, no build step.
+Node resolves import specifiers literally — there is no `.js` → `.ts` remap — so generate with [`--import-ext ts`](../commands/generate-client.md#options) to get real on-disk `.ts` specifiers, and import the client with a `.ts` extension in your own code:
+
+```bash
+redocly generate-client openapi.yaml -o src/api/client.ts --import-ext ts
+```
+
+```ts
+// src/main.ts
+import { listMenuItems } from './api/client.ts';
+
+const menu = await listMenuItems({ limit: 3 });
+```
+
+```bash
+node src/main.ts
+```
+
+Keep the default `js` when the client goes through `tsc` or a bundler — plain `tsc` rejects `.ts` specifiers unless the project enables `allowImportingTsExtensions`.
+Loaders such as `tsx` remap `.js` to `.ts` themselves, so they work with the default.
+See the [`node-native` example](https://github.com/Redocly/redocly-cli/tree/main/tests/e2e/generate-client/examples/node-native).
+
+## Authentication
+
+Credentials are **per instance**: they live in the client's config (`ClientConfig.auth`), and each operation automatically sends the credentials its `security` requires.
+A setter is generated for each `securityScheme` the runtime can apply:
+
+| Scheme                         | Setter                                    | Applied as                               |
+| ------------------------------ | ----------------------------------------- | ---------------------------------------- |
+| HTTP `bearer` / OAuth2         | `setBearer(token)`                        | `Authorization: Bearer <token>`          |
+| HTTP `basic`                   | `setBasicAuth(user, pass)`                | `Authorization: Basic <base64>`          |
+| `apiKey` (header/query/cookie) | `setApiKey(key)` / `setApiKey<Name>(key)` | the named header, query param, or cookie |
+
+`setApiKey` is unsuffixed for a single apiKey scheme; otherwise each gets `setApiKey<SchemeName>`.
+`mutualTLS` is not injectable.
+Cookie apiKey credentials travel in the `Cookie` request header, which browsers refuse to set — cookie auth works only in server-side clients (the generator warns when a spec declares one).
+Bearer and apiKey credentials accept a **`TokenProvider`** — a string or a (possibly async) function called per request, handy for refresh flows:
+
+```ts
+import { setBearer } from './client.ts';
+
+setBearer(async () => await getFreshAccessToken());
+```
+
+Each setter is sugar over the exported `client` instance's `auth` member (`export const setBearer = client.auth.bearer;`), so it configures that instance.
+Equivalently, pass credentials up front with `configure({ auth: { … } })` or set them via `client.auth.bearer(…)` / `client.auth.basic(…)` / `client.auth.apiKey(scheme, …)`.
+
+For **multiple independent instances** with different credentials, build extra clients over the same generated descriptors — the generated module exports `createClient`, the `OPERATIONS` descriptors, and the `Ops` type in both runtimes:
+
+```ts
+import { createClient } from '@redocly/client-generator';
+import { OPERATIONS, type Ops } from './client.ts';
+
+const internal = createClient<Ops>(OPERATIONS, {
+  serverUrl: 'https://api.example.com',
+  auth: { basic: { username: 'svc', password: 's3cr3t' } },
+});
+const publicApi = createClient<Ops>(OPERATIONS, { serverUrl: 'https://api.example.com' }); // no auth
+```
+
+## Argument style
+
+By default (`--args-style flat`) each operation takes positional arguments — path params in URL order, then `params` (query), `body`, `headers`, and `cookies` — with the per-call `init` last.
+Cookie parameters are serialized into the `Cookie` request header, which browsers refuse to set — like cookie apiKey auth, they work only in server-side clients.
+With `--args-style grouped`, every input is bundled into one `vars` object typed as the operation's `<Op>Variables`:
+
+```ts
+// flat (default)
+await updateOrder('ord_01khr…', { ...orderBody });
+
+// grouped — order-independent, a good fit for React Query / SWR mutationFns
+await updateOrder({ orderId: 'ord_01khr…', body: { ...orderBody } });
+```
+
+## Error handling
+
+By default (`--error-mode throw`) an operation throws `ApiError` on any non-2xx response and returns the success body directly.
+With `--error-mode result` it never throws for HTTP errors, returning a discriminated `Result<TData, TError>` whose `error` is typed from the spec's 4xx/5xx bodies:
+
+```ts
+// throw (default)
+try {
+  const order = await getOrderById('ord_123');
+} catch (err) {
+  if (err instanceof ApiError) console.error(err.status, err.body);
+}
+
+// result
+const { data, error, response } = await getOrderById('ord_123');
+if (error) console.error(response.status, error.title);
+else console.log(data.id);
+```
+
+Transport and abort failures still throw in both modes.
+The choice is fixed at generate time.
+
+## Middleware
+
+Beyond the single `onRequest`/`onResponse`/`onError` hooks on `ClientConfig`, the client takes **composable middleware** for cross-cutting concerns (auth refresh, logging, tracing, request IDs).
+Register with `use()` (sugar for `client.use()`); it accepts several at once:
+
+```ts
+import { use } from './client.ts';
+
+use({
+  onRequest: (ctx) => {
+    // ctx.operation is { id, path, tags } — target by identity, not URL matching
+    if (ctx.operation.tags.includes('Orders')) {
+      ctx.headers['X-Idempotency-Key'] = crypto.randomUUID();
+    }
+  },
+});
+```
+
+`onRequest` runs in registration order; `onResponse` runs in reverse (onion).
+`onRequest` may mutate `ctx` (`url`, `method`, `headers`, and `body` — body edits are serialized and sent); `onResponse` may return a replacement `Response`.
+`onError` (throw mode only) is threaded through each middleware.
+`ctx.operation`'s fields are typed as the spec's literal unions (`OperationId`/`OperationPath`/`OperationTag`), so `ctx.operation.id === '…'` and `ctx.operation.tags.includes('…')` autocomplete, and a misspelled operation id fails compilation instead of silently never matching.
+A header for a single call instead goes in that operation's trailing `init` argument.
+Per-request headers merge lowest to highest: injected auth credentials, then typed header parameters, then the caller's `init.headers` — the caller always wins.
+
+`use()` appends to the middleware chain, composing with any already-registered or baked-in middleware.
+`configure({ middleware: [...] })` replaces the whole chain — use it to reset, but prefer `use()` to add to existing (including [publisher-baked](#publisher-defaults)) middleware.
+
+See the [`configure-and-middleware` example](https://github.com/Redocly/redocly-cli/tree/main/tests/e2e/generate-client/examples/configure-and-middleware) for a runnable version.
+
+## Publisher defaults
+
+The middleware above is composed by the **consumer**.
+If you **publish an SDK**, bake defaults in at generation time with `--setup <file>`.
+The setup module imports its contract from `@redocly/client-generator` (so it resolves and is unit-testable) and default-exports `defineClientSetup({ config, middleware })`:
+
+```ts
+// client-setup.ts
+import { defineClientSetup, type RequestContext } from '@redocly/client-generator';
+
+export default defineClientSetup({
+  config: { serverUrl: 'https://api.acme.com', retry: { retries: 3 } },
+  middleware: [
+    {
+      onRequest: (ctx: RequestContext) => {
+        ctx.headers['X-Acme-SDK'] = '1.4.0';
+      },
+    },
+  ],
+});
+```
+
+```sh
+redocly generate-client openapi.yaml --output src/api/client.ts --setup ./client-setup.ts
+```
+
+The baked block runs before the consumer's own setup.
+**Config values** layer lowest → highest: the spec's defaults (e.g. `servers[0].url`) → the baked setup → the app's `configure()` — later always wins, so a consumer overrides a baked default.
+**Middleware composes** instead (baked first, then the consumer's).
+Express un-bypassable behavior as middleware, not a baked `fetch`.
+A setup file may import **only** from `@redocly/client-generator`.
+See the [`baked-setup` example](https://github.com/Redocly/redocly-cli/tree/main/tests/e2e/generate-client/examples/baked-setup).
+
+## Retries
+
+Retry is **opt-in**, configured through `ClientConfig` with an optional per-call override:
+
+```ts
+configure({ retry: { retries: 3 } }); // the module's client instance
+const other = createClient<Ops>(OPERATIONS, { retry: { retries: 3 } }); // another instance
+await getOrderById('ord_123', {}, { retry: { retries: 5 } }); // per call
+```
+
+By default only **idempotent** methods (`GET`, `HEAD`, `PUT`, `DELETE`, `OPTIONS`) are retried, on a network error or a transient status (`408`, `429`, `500`, `502`, `503`, `504`).
+`POST`/`PATCH` are not, since re-sending can duplicate side effects — opt in with a custom `retryOn` when safe.
+Backoff is exponential with full jitter (`retryStrategy: 'fixed'` for a constant delay); a `Retry-After` header takes precedence; an aborted `AbortSignal` stops retries immediately.
+
+A retry **resends the same request** — the `onRequest` chain, `config.headers()`, and body serialization run once and are reused across attempts.
+To refresh a token, signature, or timestamp per attempt, do it in `onResponse`/`onError` or a custom `retryOn` rather than expecting `onRequest` to re-run.
+
+| `RetryConfig` field | Type                                                 | Default                                            |
+| ------------------- | ---------------------------------------------------- | -------------------------------------------------- |
+| `retries`           | `number`                                             | `0` (extra attempts after the first; `0` disables) |
+| `retryDelay`        | `number`                                             | `1000` (base delay, ms)                            |
+| `retryStrategy`     | `'fixed' \| 'exponential'`                           | `'exponential'`                                    |
+| `jitter`            | `boolean`                                            | `true`                                             |
+| `retryOn`           | `(ctx: RetryContext) => boolean \| Promise<boolean>` | idempotent-only predicate                          |
+
+A custom `retryOn` receives the failed attempt's `RetryContext` (`attempt`, `request`, and exactly one of `response` / `error`) and **fully replaces** the default.
+To inspect a response body, read `ctx.response.clone()` — the body is a single-use stream:
+
+```ts
+await createOrder(body, {
+  retry: {
+    retries: 3,
+    retryOn: async (ctx) => {
+      if (ctx.error) return true; // transport error
+      return (ctx.response?.status ?? 0) >= 500; // server error
+    },
+  },
+});
+```
+
+## Query serialization
+
+Query parameters follow their OpenAPI `style` / `explode` / `allowReserved`.
+The default (`form`, `explode: true`) repeats array values:
+
+| `style`          | `explode` | `['a', 'b']` on the wire |
+| ---------------- | --------- | ------------------------ |
+| `form` (default) | `true`    | `key=a&key=b`            |
+| `form`           | `false`   | `key=a,b`                |
+| `spaceDelimited` | `false`   | `key=a%20b`              |
+| `pipeDelimited`  | `false`   | `key=a\|b`               |
+
+Delimiters are literal (values are still percent-encoded).
+`allowReserved: true` leaves the RFC-3986 reserved set un-encoded.
+Object-valued params serialize as `deepObject` brackets (`key[sub]=val`).
+
+## Multipart uploads
+
+A `multipart/form-data` body whose schema is an **object** is generated as a typed object; pass a plain object and the client serializes it to `FormData` (after the `onRequest` chain, so middleware can mutate it).
+Binary fields (`format: binary`) are typed as `Blob`:
+
+```ts
+// type UploadBody = { file: Blob; orgId: string; tags?: string[] };
+await upload({ file, orgId: 'org_1', tags: ['a', 'b'] });
+```
+
+`Blob`/strings pass through, arrays append one field per item, nested objects are JSON-encoded, `undefined`/`null` are skipped. A multipart body whose schema isn't a concrete object keeps the raw `FormData` type. `format: byte` (base64) stays a `string`.
+
+## Response decoding
+
+The client reads each response by negotiating from its `Content-Type` (JSON, then `text/*`, then `Blob`).
+Force a reader per call with `parseAs`:
+
+```ts
+const res = await getMenuItemPhoto('prd_123', { parseAs: 'stream' });
+```
+
+`parseAs` accepts `'json'`, `'text'`, `'blob'`, `'arrayBuffer'`, `'formData'`, `'stream'`, or `'auto'` (default). It changes the runtime reader only, not the static return type.
+
+## Runtime validation
+
+The `zod` generator emits `operationSchemas` — request/response validators keyed by operationId — and the `zodValidation` middleware that wires them into the client:
+
+```ts
+import { use } from './api/client';
+import { zodValidation } from './api/client.zod';
+
+use(zodValidation()); // validate request bodies and JSON responses
+```
+
+An invalid request body throws before any network call; a successful JSON response that doesn't match its schema throws after it.
+Both throw `ZodValidationError` (with `operationId`, `direction`, and the zod `issues`) — always thrown, even on result-mode clients.
+Payloads are never mutated, and operations without a JSON body pass through untouched.
+Pass `{ request: false }` or `{ response: false }` to narrow the scope, or import a schema from `operationSchemas` for a one-off check.
+
+## Operation metadata
+
+The client exports an `OPERATIONS` map keyed by operationId — the same **operation descriptors** the runtime routes requests by, holding each operation's `method`, `path` template, `tags`, and wire shape:
+
+```ts
+export const OPERATIONS = {
+  getOrderById: { id: 'getOrderById', method: 'GET', path: '/orders/{orderId}', tags: ['Orders'] },
+  // …
+} as const satisfies Record<string, OperationDescriptor>;
+```
+
+Because keys and values are plain string literals, they survive bundling/minification — making `OPERATIONS` the stable handle for cache keys, span names, or log labels (rather than `fn.name`, which a minifier can rename).
+The same `OperationId` / `OperationPath` / `OperationTag` unions type `ctx.operation` in middleware.
+
+## Discriminated unions
+
+A `oneOf` / `anyOf` with a usable discriminator gets an exported `is<Member>` type guard per member, taken from the spec's `discriminator` or inferred when every member pins a shared property to a distinct string `const`:
+
+```ts
+export type MenuItem = Beverage | Dessert;
+export function isBeverage(value: MenuItem): value is Beverage { … }
+```
+
+Guards are also emitted for unions nested inside another schema (array items, property values) as long as every member is a named schema.
+A union without a usable discriminator gets no guard.
+
+## Server-Sent Events
+
+An operation whose `2xx` response declares `text/event-stream` is generated as a typed **async-generator function** (a client method plus the matching free function) — no flag required.
+Each event's `data` is typed from the OpenAPI 3.2 `itemSchema` (falling back to the media `schema`, then `string`) and `JSON.parse`d when structured:
+
+```ts
+import { streamMessages } from './client.ts';
+
+for await (const ev of streamMessages()) {
+  console.log(ev.id, ev.data.text); // ServerSentEvent<T>: { event?, data, id?, retry? }
+}
+```
+
+The stream **auto-reconnects** on a dropped connection, resuming from the last event id via `Last-Event-ID` (backoff honors the server's `retry:`, then `reconnectDelay`, then 1s; capped at 30s).
+Tune per call with `{ reconnect: false }` or `{ reconnectDelay: 500 }`.
+`break`ing the loop or aborting an `AbortSignal` ends it cleanly (no throw).
+SSE always throws `ApiError` on a non-2xx initial response, regardless of `--error-mode`.
+
+## Pagination
+
+Pagination is declared, never guessed: describe how your API paginates in `redocly.yaml` under `client.pagination`, or per operation with the `x-pagination` extension in the spec.
+The rule fields, the generate-time verification, and the precedence between the convention, `x-pagination`, and per-operation overrides are documented in the [`client.pagination` reference](../configuration/reference/client.md#pagination-object); there is no CLI flag.
+Each paginated operation keeps its one-shot call and gains two async iterators — `.pages(args?, init?)` yielding full pages and `.items(args?, init?)` yielding individual items, typed statically from the response schema.
+
+Three styles are supported:
+`cursor` sends the response's `nextCursor` back in `cursorParam`, stops when it's absent, `null`, or empty, and throws if the server returns the same cursor twice in a row.
+For connection-style APIs whose cursor stays non-null on the last page, add the optional `hasMore` pointer (for example `/pageInfo/hasNextPage`) — iteration stops as soon as it resolves to `false`, skipping the follow-up empty request.
+`offset` advances `offsetParam` by each page's item count, and `page` increments `offsetParam` by 1; both stop on an empty page.
+`limitParam` is optional metadata for any style: the iterator never sets it, so pass your page size in `params` yourself.
+
+```ts
+import { client } from './client.ts';
+
+for await (const order of client.listOrders.items({ params: { limit: 20 } })) {
+  console.log(order.id); // `order` is `Order` — resolved from the response schema at generate time
+}
+
+for await (const page of client.listOrders.pages()) {
+  console.log(page.orders.length); // each full page, last one included
+}
+```
+
+The flat free functions keep both iterators, with one asymmetry to note: the flat function itself takes positional arguments, but its `.pages`/`.items` always take the grouped shape (they are the client method's iterators).
+
+Resume by passing the advance param in the initial args — iteration starts from there instead of the beginning.
+Abort by passing an `AbortSignal`, forwarded to every page request:
+
+```ts
+const controller = new AbortController();
+for await (const page of client.listOrders.pages(
+  { params: { cursor: 'c2' } }, // start from a saved cursor (or offset/page number)
+  { signal: controller.signal }
+)) {
+  // …
+}
+```
+
+A failed page always aborts iteration by throwing `ApiError`, even on an `--error-mode result` client — there `.pages()` yields raw pages (not `{ data, error, response }` envelopes; only the one-shot call keeps the envelope) and the throw-mode-only `onError` middleware hook is not invoked.
+
+For shapes the built-in styles don't cover — for example a cursor that travels in the request body or a header — page with a small hand-written helper over the generated call, which stays fully typed end to end (see the [`custom-pagination` example](https://github.com/Redocly/redocly-cli/tree/main/tests/e2e/generate-client/examples/custom-pagination)).
+
+## Custom generators
+
+The built-in generators cover common targets.
+For anything else derived from the same description (validators in another library, a permissions map, a house-style SDK), write a **custom generator**: it reads the same spec-agnostic model the built-ins consume, so its output never drifts from the spec.
+
+A generator is `{ name, run }` (plus optional compatibility metadata); author it with `defineGenerator`:
+
+```ts
+// route-map-generator.ts
+import { defineGenerator } from '@redocly/client-generator';
+
+export default defineGenerator({
+  name: 'route-map',
+  requires: ['sdk'],
+  run({ model, outputPath }) {
+    const routes = model.services
+      .flatMap((s) => s.operations)
+      .map((op) => `  ${op.name}: '${op.method.toUpperCase()} ${op.path}',`)
+      .join('\n');
+    return [
+      {
+        path: outputPath.replace(/\.ts$/, '.routes.ts'),
+        content: `export const routes = {\n${routes}\n} as const;\n`,
+      },
+    ];
+  },
+});
+```
+
+The `@redocly/client-generator/codegen` entry also exports the codegen toolkit (`ts`, `printStatements`, `parseStatements`, `operationSignature`, `schemaToTypeNode`, `pascalCase`, …), and the package root exports the IR types, so a custom generator emits TypeScript exactly as the first-party ones do.
+
+Select it in `redocly.yaml` by path or package name:
+
+```yaml
+apis:
+  cafe:
+    root: ./openapi.yaml
+    clientOutput: ./src/api/client.ts
+    client:
+      generators:
+        - sdk
+        - ./tools/route-map-generator.ts # local path (resolved against redocly.yaml)
+        - '@acme/openapi-valibot' # published package
+```
+
+Or register one **inline** with the programmatic API and select it by name:
+
+```ts
+import { generateClient } from '@redocly/client-generator';
+import routeMap from './tools/route-map-generator.ts';
+
+await generateClient({
+  api: './openapi.yaml',
+  output: './src/api/client.ts',
+  customGenerators: [routeMap],
+  generators: ['sdk', 'route-map'],
+});
+```
+
+Import-specifier generators execute at generation time — they carry the same trust level as any installed dependency you run.
+See the [`custom-generator` example](https://github.com/Redocly/redocly-cli/tree/main/tests/e2e/generate-client/examples/custom-generator).
+
+## Resources
+
+- [`generate-client` command](../commands/generate-client.md) — flags, output modes, and invocation.
+- [`client` configuration](../configuration/reference/client.md) — the `redocly.yaml` `client` block.
diff --git a/docs/@v2/v2.sidebars.yaml b/docs/@v2/v2.sidebars.yaml
index 99da0aac1e..a532a18151 100644
--- a/docs/@v2/v2.sidebars.yaml
+++ b/docs/@v2/v2.sidebars.yaml
@@ -20,6 +20,8 @@
           page: commands/eject.md
         - label: generate-arazzo
           page: commands/generate-arazzo.md
+        - label: generate-client
+          page: commands/generate-client.md
         - label: join
           page: commands/join.md
         - label: lint
@@ -58,6 +60,8 @@
         - page: guides/configure-rules.md
         - page: guides/lint-and-bundle.md
           label: Lint and bundle
+        - label: Use the generated client
+          page: guides/use-generated-client.md
         - label: Hide internal APIs
           page: guides/hide-apis.md
         - label: Replace the servers URL
@@ -204,6 +208,7 @@
         - group: Reference
           items:
             - page: configuration/reference/apis.md
+            - page: configuration/reference/client.md
             - page: configuration/reference/decorators.md
             - page: configuration/reference/extends.md
             - page: configuration/reference/plugins.md
diff --git a/package-lock.json b/package-lock.json
index 07c4329a5a..fe814eca22 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -13,21 +13,32 @@
       ],
       "devDependencies": {
         "@changesets/cli": "^2.26.2",
+        "@faker-js/faker": "^9.9.0",
+        "@redocly/mock-server": "^0.7.0",
+        "@tanstack/react-query": "^5.0.0",
+        "@testing-library/react": "^16.0.0",
         "@types/node": "^22.15.3",
+        "@types/react": "^19.2.17",
+        "@types/react-dom": "^19.2.3",
         "@vitest/coverage-istanbul": "^4.1.8",
         "husky": "^9.1.7",
         "jsdom": "^27.2.0",
         "json-schema-to-ts": "^3.0.0",
         "json-server": "1.0.0-beta.3",
         "lint-staged": "^15.4.3",
+        "msw": "^2.14.6",
         "outdent": "^0.7.1",
         "oxfmt": "^0.33.0",
         "oxlint": "^1.48.0",
         "pegjs": "0.11.0-master.b7b87ea",
+        "react": "^19.2.0",
+        "react-dom": "^19.2.0",
         "slackify-markdown": "^4.3.1",
+        "swr": "^2.4.1",
         "tsx": "^4.19.3",
         "typescript": "6.0.2",
-        "vitest": "^4.1.8"
+        "vitest": "^4.1.8",
+        "zod": "^4.0.0"
       },
       "engines": {
         "node": ">=22.12.0 || >=20.19.0 <21.0.0",
@@ -602,6 +613,30 @@
         "prettier": "^2.7.1"
       }
     },
+    "node_modules/@cspotcode/source-map-support": {
+      "version": "0.8.1",
+      "resolved": "https://registry.npmjs.org/@cspotcode/source-map-support/-/source-map-support-0.8.1.tgz",
+      "integrity": "sha512-IchNf6dN4tHoMFIn/7OE8LWZ19Y6q/67Bmf6vnGREv8RSbBVb9LPJxEcnwrcwX6ixSvaiGoomAUvu4YSxXrVgw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/trace-mapping": "0.3.9"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@cspotcode/source-map-support/node_modules/@jridgewell/trace-mapping": {
+      "version": "0.3.9",
+      "resolved": "https://registry.npmjs.org/@jridgewell/trace-mapping/-/trace-mapping-0.3.9.tgz",
+      "integrity": "sha512-3Belt6tdc8bPgAtbcmdtNJlirVoTmEb5e2gC94PnkwEW9jI6CAHUeoG85tjWP5WquqfavoMtMwiG4P926ZKKuQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/resolve-uri": "^3.0.3",
+        "@jridgewell/sourcemap-codec": "^1.4.10"
+      }
+    },
     "node_modules/@csstools/color-helpers": {
       "version": "5.1.0",
       "resolved": "https://registry.npmjs.org/@csstools/color-helpers/-/color-helpers-5.1.0.tgz",
@@ -1238,13 +1273,20 @@
       "license": "MIT"
     },
     "node_modules/@faker-js/faker": {
-      "version": "7.6.0",
-      "resolved": "https://registry.npmjs.org/@faker-js/faker/-/faker-7.6.0.tgz",
-      "integrity": "sha512-XK6BTq1NDMo9Xqw/YkYyGjSsg44fbNwYRx7QK2CuoQgyy+f1rrTDHoExVM5PsyXCtfl2vs2vVJ0MN0yN6LppRw==",
+      "version": "9.9.0",
+      "resolved": "https://registry.npmjs.org/@faker-js/faker/-/faker-9.9.0.tgz",
+      "integrity": "sha512-OEl393iCOoo/z8bMezRlJu+GlRGlsKbUAN7jKB6LhnKoqKve5DXRpalbItIIcwnCjs1k/FOPjFzcA6Qn+H+YbA==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/fakerjs"
+        }
+      ],
       "license": "MIT",
       "engines": {
-        "node": ">=14.0.0",
-        "npm": ">=6.0.0"
+        "node": ">=18.0.0",
+        "npm": ">=9.0.0"
       }
     },
     "node_modules/@humanwhocodes/momoa": {
@@ -1256,6 +1298,65 @@
         "node": ">=10.10.0"
       }
     },
+    "node_modules/@inquirer/ansi": {
+      "version": "2.0.7",
+      "resolved": "https://registry.npmjs.org/@inquirer/ansi/-/ansi-2.0.7.tgz",
+      "integrity": "sha512-3eTuUO1vH2cZm2ZKHeQxnOqlTi9EfZDGgIe3BL3I4u+rJHocr9Fz86M4fjYABPvFnQG/gGK551HqDiIcETwU6Q==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=23.5.0 || ^22.13.0 || ^20.17.0"
+      }
+    },
+    "node_modules/@inquirer/confirm": {
+      "version": "6.1.1",
+      "resolved": "https://registry.npmjs.org/@inquirer/confirm/-/confirm-6.1.1.tgz",
+      "integrity": "sha512-eb8DBZcz/2qHWQda4rk2JiQk5h9QV/cVHi1yjt0f69WFZMRFn0sJTye3EAP8icut8UDMjQPsaH5KbcOogefrFQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@inquirer/core": "^11.2.1",
+        "@inquirer/type": "^4.0.7"
+      },
+      "engines": {
+        "node": ">=23.5.0 || ^22.13.0 || ^20.17.0"
+      },
+      "peerDependencies": {
+        "@types/node": ">=18"
+      },
+      "peerDependenciesMeta": {
+        "@types/node": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@inquirer/core": {
+      "version": "11.2.1",
+      "resolved": "https://registry.npmjs.org/@inquirer/core/-/core-11.2.1.tgz",
+      "integrity": "sha512-Qd6GJT1yVyrZZCfN8W2qKF5ApmqryXRhRKCuip8h01x2w/esJQ2XIYc6f9abMIHgKQdBfFTSOdbHRLAhuM09UA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@inquirer/ansi": "^2.0.7",
+        "@inquirer/figures": "^2.0.7",
+        "@inquirer/type": "^4.0.7",
+        "cli-width": "^4.1.0",
+        "fast-wrap-ansi": "^0.2.0",
+        "mute-stream": "^3.0.0",
+        "signal-exit": "^4.1.0"
+      },
+      "engines": {
+        "node": ">=23.5.0 || ^22.13.0 || ^20.17.0"
+      },
+      "peerDependencies": {
+        "@types/node": ">=18"
+      },
+      "peerDependenciesMeta": {
+        "@types/node": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/@inquirer/external-editor": {
       "version": "1.0.3",
       "resolved": "https://registry.npmjs.org/@inquirer/external-editor/-/external-editor-1.0.3.tgz",
@@ -1295,6 +1396,34 @@
         "url": "https://opencollective.com/express"
       }
     },
+    "node_modules/@inquirer/figures": {
+      "version": "2.0.7",
+      "resolved": "https://registry.npmjs.org/@inquirer/figures/-/figures-2.0.7.tgz",
+      "integrity": "sha512-aJ8TBPOGB6f/2qziPfElISTCEd5XOYTFckA2SGjhNmiKzfK/u4ot3v0DUzGVdUnKjN10EqnnEPck36BkyfLnJw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=23.5.0 || ^22.13.0 || ^20.17.0"
+      }
+    },
+    "node_modules/@inquirer/type": {
+      "version": "4.0.7",
+      "resolved": "https://registry.npmjs.org/@inquirer/type/-/type-4.0.7.tgz",
+      "integrity": "sha512-t28inv14nMQ1PhKpsJPY+kEs/c00qzeCOS2gTNRyTjG5d6qsVA2fItxW4hkvGZ5lvanGLdtCzVIx5dwdRpN1+g==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=23.5.0 || ^22.13.0 || ^20.17.0"
+      },
+      "peerDependencies": {
+        "@types/node": ">=18"
+      },
+      "peerDependenciesMeta": {
+        "@types/node": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/@istanbuljs/schema": {
       "version": "0.1.6",
       "resolved": "https://registry.npmjs.org/@istanbuljs/schema/-/schema-0.1.6.tgz",
@@ -1427,6 +1556,31 @@
         "node": ">=6 <7 || >=8"
       }
     },
+    "node_modules/@mswjs/interceptors": {
+      "version": "0.41.9",
+      "resolved": "https://registry.npmjs.org/@mswjs/interceptors/-/interceptors-0.41.9.tgz",
+      "integrity": "sha512-VVPPgHyQ6ShqnrmDWuxjmUIsO9gWyOZFmuOfLd9LfBGQJwZfy0gvv9pbHSJuoFNIYC7ZDX9aoFwowjcdSC4E8w==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@open-draft/deferred-promise": "^2.2.0",
+        "@open-draft/logger": "^0.3.0",
+        "@open-draft/until": "^2.0.0",
+        "is-node-process": "^1.2.0",
+        "outvariant": "^1.4.3",
+        "strict-event-emitter": "^0.5.1"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@mswjs/interceptors/node_modules/@open-draft/deferred-promise": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/@open-draft/deferred-promise/-/deferred-promise-2.2.0.tgz",
+      "integrity": "sha512-CecwLWx3rhxVQF6V4bAgPS5t+So2sTbPgAzafKkVizyi7tlwpcFpdFqq+wqF2OwNBmqFuu6tOyouTuxgpMfzmA==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@napi-rs/wasm-runtime": {
       "version": "1.1.4",
       "resolved": "https://registry.npmjs.org/@napi-rs/wasm-runtime/-/wasm-runtime-1.1.4.tgz",
@@ -1508,6 +1662,31 @@
         "node": ">= 8"
       }
     },
+    "node_modules/@open-draft/deferred-promise": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/@open-draft/deferred-promise/-/deferred-promise-3.0.0.tgz",
+      "integrity": "sha512-XW375UK8/9SqUVNVa6M0yEy8+iTi4QN5VZ7aZuRFQmy76LRwI9wy5F4YIBU6T+eTe2/DNDo8tqu8RHlwLHM6RA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@open-draft/logger": {
+      "version": "0.3.0",
+      "resolved": "https://registry.npmjs.org/@open-draft/logger/-/logger-0.3.0.tgz",
+      "integrity": "sha512-X2g45fzhxH238HKO4xbSr7+wBS8Fvw6ixhTDuvLd5mqh6bJJCFAPwU9mPDxbcrRtfxv4u5IHCEH77BmxvXmmxQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "is-node-process": "^1.2.0",
+        "outvariant": "^1.4.0"
+      }
+    },
+    "node_modules/@open-draft/until": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/@open-draft/until/-/until-2.1.0.tgz",
+      "integrity": "sha512-U69T3ItWHvLwGg5eJ0n3I62nWuE6ilHlmz7zM0npLBRvPRd7e6NYmg54vvRtP5mZG7kZqZCFVdsTWo7BPtBujg==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@opentelemetry/api": {
       "version": "1.9.0",
       "resolved": "https://registry.npmjs.org/@opentelemetry/api/-/api-1.9.0.tgz",
@@ -2419,6 +2598,10 @@
         "ulid": "bin/cli.js"
       }
     },
+    "node_modules/@redocly/client-generator": {
+      "resolved": "packages/client-generator",
+      "link": true
+    },
     "node_modules/@redocly/config": {
       "version": "0.51.0",
       "resolved": "https://registry.npmjs.org/@redocly/config/-/config-0.51.0.tgz",
@@ -2448,6 +2631,230 @@
       "integrity": "sha512-kloPhf1hq3JbCPOTYoOWDKxebWjNb2o/LKnNfkWhxVVisFFmMJPPdJeGoGmM+iRLyoXAR61e08Pb+vUXINg8aA==",
       "license": "MIT"
     },
+    "node_modules/@redocly/mock-server": {
+      "version": "0.7.0",
+      "resolved": "https://registry.npmjs.org/@redocly/mock-server/-/mock-server-0.7.0.tgz",
+      "integrity": "sha512-gr9e1aq5iKy+AN3F+NwFC4cbi15XCdL1HTpfZudV9jg2OqTPRMZd1RNvFQvKUF0UZq+TLLpR88KmD+ufiVAX0w==",
+      "dev": true,
+      "license": "SEE LICENSE IN LICENSE",
+      "dependencies": {
+        "@redocly/ajv": "8.18.0",
+        "@redocly/openapi-core": "2.30.5",
+        "ajv": "8.18.0",
+        "ajv-formats": "^3.0.1",
+        "fast-xml-parser": "5.7.3",
+        "js-yaml": "4.1.1",
+        "openapi-sampler": "^1.7.2",
+        "punycode": "2.3.0",
+        "swagger2openapi": "^7.0.8",
+        "ts-node": "10.9.2",
+        "yargs": "^17.5.1"
+      }
+    },
+    "node_modules/@redocly/mock-server/node_modules/@redocly/ajv": {
+      "version": "8.18.0",
+      "resolved": "https://registry.npmjs.org/@redocly/ajv/-/ajv-8.18.0.tgz",
+      "integrity": "sha512-F+LMD2IDIXuHxgpLJh3nkLj9+tSaEzoUWd+7fONGq5pe2169FUDjpEkOfEpoGLz1sbZni/69p07OsecNfAOpqA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "fast-deep-equal": "^3.1.3",
+        "fast-uri": "^3.0.1",
+        "json-schema-traverse": "^1.0.0",
+        "require-from-string": "^2.0.2"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/epoberezkin"
+      }
+    },
+    "node_modules/@redocly/mock-server/node_modules/@redocly/config": {
+      "version": "0.48.2",
+      "resolved": "https://registry.npmjs.org/@redocly/config/-/config-0.48.2.tgz",
+      "integrity": "sha512-DUHthTRdj+caAQWCtJae4yzvxaUDuwQkFsZFVaAEyORd8Bt8K2wYso61jYZuR/kQZaDejfUREtQTVVZ5VYTqgw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "json-schema-to-ts": "2.7.2"
+      }
+    },
+    "node_modules/@redocly/mock-server/node_modules/@redocly/openapi-core": {
+      "version": "2.30.5",
+      "resolved": "https://registry.npmjs.org/@redocly/openapi-core/-/openapi-core-2.30.5.tgz",
+      "integrity": "sha512-ikljMaow1wX3GoRvLiJvqOq8H3f6XsuMBZqCGmeY0+UPmlnVhrvW8m/gC1vkKcGNvYINUrgi/Z6dBtzQ7854wA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@redocly/ajv": "^8.18.1",
+        "@redocly/config": "^0.48.1",
+        "ajv": "npm:@redocly/ajv@8.18.1",
+        "ajv-formats": "^3.0.1",
+        "colorette": "^1.2.0",
+        "js-levenshtein": "^1.1.6",
+        "js-yaml": "^4.1.0",
+        "picomatch": "^4.0.4",
+        "pluralize": "^8.0.0",
+        "yaml-ast-parser": "0.0.43"
+      },
+      "engines": {
+        "node": ">=22.12.0 || >=20.19.0 <21.0.0",
+        "npm": ">=10"
+      }
+    },
+    "node_modules/@redocly/mock-server/node_modules/@redocly/openapi-core/node_modules/@redocly/ajv": {
+      "version": "8.18.3",
+      "resolved": "https://registry.npmjs.org/@redocly/ajv/-/ajv-8.18.3.tgz",
+      "integrity": "sha512-l42u0of3hY98sN2A+M4qTX1O/KrpgGH32Hu9kP2GtHyD5Dfqq86PKFLe5dwaD8DEnNmlOlll2BAmeEtf0DaySg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "fast-deep-equal": "^3.1.3",
+        "fast-uri": "^3.0.1",
+        "json-schema-traverse": "^1.0.0",
+        "require-from-string": "^2.0.2"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/epoberezkin"
+      }
+    },
+    "node_modules/@redocly/mock-server/node_modules/@redocly/openapi-core/node_modules/ajv": {
+      "name": "@redocly/ajv",
+      "version": "8.18.1",
+      "resolved": "https://registry.npmjs.org/@redocly/ajv/-/ajv-8.18.1.tgz",
+      "integrity": "sha512-Ifm/pP/tul1qmAecpbVxCBluVE32rKfjf8gYXH4xI2gCv9mRWFhJMHzkPDM4TXlxwPQYIFegymlsy8lXz7optA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "fast-deep-equal": "^3.1.3",
+        "fast-uri": "^3.0.1",
+        "json-schema-traverse": "^1.0.0",
+        "require-from-string": "^2.0.2"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/epoberezkin"
+      }
+    },
+    "node_modules/@redocly/mock-server/node_modules/ajv": {
+      "version": "8.18.0",
+      "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.18.0.tgz",
+      "integrity": "sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "fast-deep-equal": "^3.1.3",
+        "fast-uri": "^3.0.1",
+        "json-schema-traverse": "^1.0.0",
+        "require-from-string": "^2.0.2"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/epoberezkin"
+      }
+    },
+    "node_modules/@redocly/mock-server/node_modules/cliui": {
+      "version": "8.0.1",
+      "resolved": "https://registry.npmjs.org/cliui/-/cliui-8.0.1.tgz",
+      "integrity": "sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "string-width": "^4.2.0",
+        "strip-ansi": "^6.0.1",
+        "wrap-ansi": "^7.0.0"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@redocly/mock-server/node_modules/js-yaml": {
+      "version": "4.1.1",
+      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.1.tgz",
+      "integrity": "sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "argparse": "^2.0.1"
+      },
+      "bin": {
+        "js-yaml": "bin/js-yaml.js"
+      }
+    },
+    "node_modules/@redocly/mock-server/node_modules/json-schema-to-ts": {
+      "version": "2.7.2",
+      "resolved": "https://registry.npmjs.org/json-schema-to-ts/-/json-schema-to-ts-2.7.2.tgz",
+      "integrity": "sha512-R1JfqKqbBR4qE8UyBR56Ms30LL62/nlhoz+1UkfI/VE7p54Awu919FZ6ZUPG8zIa3XB65usPJgr1ONVncUGSaQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/runtime": "^7.18.3",
+        "@types/json-schema": "^7.0.9",
+        "ts-algebra": "^1.2.0"
+      },
+      "engines": {
+        "node": ">=16"
+      }
+    },
+    "node_modules/@redocly/mock-server/node_modules/picomatch": {
+      "version": "4.0.5",
+      "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.5.tgz",
+      "integrity": "sha512-RvwwcruNjI1ncT5xRakeyS9Lf8lcItv34KD+aif+VH9kduAyfYBipGh12274xtenIPZ119/R9BdTBa8gAwSh0A==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/jonschlinkert"
+      }
+    },
+    "node_modules/@redocly/mock-server/node_modules/punycode": {
+      "version": "2.3.0",
+      "resolved": "https://registry.npmjs.org/punycode/-/punycode-2.3.0.tgz",
+      "integrity": "sha512-rRV+zQD8tVFys26lAGR9WUuS4iUAngJScM+ZRSKtvl5tKeZ2t5bvdNFdNHBW9FWR4guGHlgmsZ1G7BSm2wTbuA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/@redocly/mock-server/node_modules/ts-algebra": {
+      "version": "1.2.2",
+      "resolved": "https://registry.npmjs.org/ts-algebra/-/ts-algebra-1.2.2.tgz",
+      "integrity": "sha512-kloPhf1hq3JbCPOTYoOWDKxebWjNb2o/LKnNfkWhxVVisFFmMJPPdJeGoGmM+iRLyoXAR61e08Pb+vUXINg8aA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@redocly/mock-server/node_modules/yargs": {
+      "version": "17.7.3",
+      "resolved": "https://registry.npmjs.org/yargs/-/yargs-17.7.3.tgz",
+      "integrity": "sha512-GZtjxm/J/4TSxuL3FNYjCmLktBTnIw/rVmKSIyKeYAZpmJB2ig9VauCC5xsa82GNKVKDAqpOn3KVzNt0zmrU0g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "cliui": "^8.0.1",
+        "escalade": "^3.1.1",
+        "get-caller-file": "^2.0.5",
+        "require-directory": "^2.1.1",
+        "string-width": "^4.2.3",
+        "y18n": "^5.0.5",
+        "yargs-parser": "^21.1.1"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@redocly/mock-server/node_modules/yargs-parser": {
+      "version": "21.1.1",
+      "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-21.1.1.tgz",
+      "integrity": "sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==",
+      "dev": true,
+      "license": "ISC",
+      "engines": {
+        "node": ">=12"
+      }
+    },
     "node_modules/@redocly/openapi-core": {
       "resolved": "packages/core",
       "link": true
@@ -2727,6 +3134,83 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/@tanstack/query-core": {
+      "version": "5.101.2",
+      "resolved": "https://registry.npmjs.org/@tanstack/query-core/-/query-core-5.101.2.tgz",
+      "integrity": "sha512-hH5MLoJhF7KaIGd7q3xTXGXvslI+GYlM1Z/35aSHHWaCJWB7XvTSHYuV3eM7tw+aE0mT/xMro4M4Q9rCGHT0lw==",
+      "dev": true,
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/tannerlinsley"
+      }
+    },
+    "node_modules/@tanstack/react-query": {
+      "version": "5.101.2",
+      "resolved": "https://registry.npmjs.org/@tanstack/react-query/-/react-query-5.101.2.tgz",
+      "integrity": "sha512-seDkr6kzGzX1okaaTtZPtgA688CDPlXUz1C6xSg0ESqn04Vuc8tlrYms1s3de+znBqhPVxFRfpAfUf+6XvfPWg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@tanstack/query-core": "5.101.2"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/tannerlinsley"
+      },
+      "peerDependencies": {
+        "react": "^18 || ^19"
+      }
+    },
+    "node_modules/@testing-library/dom": {
+      "version": "10.4.1",
+      "resolved": "https://registry.npmjs.org/@testing-library/dom/-/dom-10.4.1.tgz",
+      "integrity": "sha512-o4PXJQidqJl82ckFaXUeoAW+XysPLauYI43Abki5hABd853iMhitooc6znOnczgbTYmEP6U6/y1ZyKAIsvMKGg==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "@babel/code-frame": "^7.10.4",
+        "@babel/runtime": "^7.12.5",
+        "@types/aria-query": "^5.0.1",
+        "aria-query": "5.3.0",
+        "dom-accessibility-api": "^0.5.9",
+        "lz-string": "^1.5.0",
+        "picocolors": "1.1.1",
+        "pretty-format": "^27.0.2"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@testing-library/react": {
+      "version": "16.3.2",
+      "resolved": "https://registry.npmjs.org/@testing-library/react/-/react-16.3.2.tgz",
+      "integrity": "sha512-XU5/SytQM+ykqMnAnvB2umaJNIOsLF3PVv//1Ew4CTcpz0/BRyy/af40qqrt7SjKpDdT1saBMc42CUok5gaw+g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/runtime": "^7.12.5"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "peerDependencies": {
+        "@testing-library/dom": "^10.0.0",
+        "@types/react": "^18.0.0 || ^19.0.0",
+        "@types/react-dom": "^18.0.0 || ^19.0.0",
+        "react": "^18.0.0 || ^19.0.0",
+        "react-dom": "^18.0.0 || ^19.0.0"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        },
+        "@types/react-dom": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/@tinyhttp/accepts": {
       "version": "2.2.3",
       "resolved": "https://registry.npmjs.org/@tinyhttp/accepts/-/accepts-2.2.3.tgz",
@@ -2991,6 +3475,34 @@
         "node": ">=12.20"
       }
     },
+    "node_modules/@tsconfig/node10": {
+      "version": "1.0.12",
+      "resolved": "https://registry.npmjs.org/@tsconfig/node10/-/node10-1.0.12.tgz",
+      "integrity": "sha512-UCYBaeFvM11aU2y3YPZ//O5Rhj+xKyzy7mvcIoAjASbigy8mHMryP5cK7dgjlz2hWxh1g5pLw084E0a/wlUSFQ==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@tsconfig/node12": {
+      "version": "1.0.11",
+      "resolved": "https://registry.npmjs.org/@tsconfig/node12/-/node12-1.0.11.tgz",
+      "integrity": "sha512-cqefuRsh12pWyGsIoBKJA9luFu3mRxCA+ORZvA4ktLSzIuCUtWVxGIuXigEwO5/ywWFMZ2QEGKWvkZG1zDMTag==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@tsconfig/node14": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/@tsconfig/node14/-/node14-1.0.3.tgz",
+      "integrity": "sha512-ysT8mhdixWK6Hw3i1V2AeRqZ5WfXg1G43mqoYlM2nc6388Fq5jcXyr5mRsqViLx/GJYdoL0bfXD8nmF+Zn/Iow==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@tsconfig/node16": {
+      "version": "1.0.4",
+      "resolved": "https://registry.npmjs.org/@tsconfig/node16/-/node16-1.0.4.tgz",
+      "integrity": "sha512-vxhUy4J8lyeyinH7Azl1pdd43GJhZH/tP2weN8TntQblOY+A0XbT8DJk1/oCPuOOyg/Ja757rG0CgHcWC8OfMA==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@tybys/wasm-util": {
       "version": "0.10.2",
       "resolved": "https://registry.npmjs.org/@tybys/wasm-util/-/wasm-util-0.10.2.tgz",
@@ -3002,6 +3514,14 @@
         "tslib": "^2.4.0"
       }
     },
+    "node_modules/@types/aria-query": {
+      "version": "5.0.4",
+      "resolved": "https://registry.npmjs.org/@types/aria-query/-/aria-query-5.0.4.tgz",
+      "integrity": "sha512-rfT93uj5s0PRL7EzccGMs3brplhcrghnDoV26NqKhCAS1hVo+WdNsPvE/yb6ilfr5hi2MEk6d5EWJTKdxg8jVw==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true
+    },
     "node_modules/@types/chai": {
       "version": "5.2.3",
       "resolved": "https://registry.npmjs.org/@types/chai/-/chai-5.2.3.tgz",
@@ -3100,9 +3620,9 @@
       "dev": true
     },
     "node_modules/@types/react": {
-      "version": "19.2.16",
-      "resolved": "https://registry.npmjs.org/@types/react/-/react-19.2.16.tgz",
-      "integrity": "sha512-esJiCAnl0kfpNdE69f3So4WJUXy95dLZydX0KwK46riIHDzHM7O9Vtf9xCHW0PXIqvgqNrswl522kA/5yx+F4w==",
+      "version": "19.2.17",
+      "resolved": "https://registry.npmjs.org/@types/react/-/react-19.2.17.tgz",
+      "integrity": "sha512-MXfmqaVPEVgkBT/aY0aGCkRWWtByiYQXo3xdQ8r5RzuFrPiRn8Gar2tQdXSUQ2GKV3bkXckek89V8wQBY2Q/Aw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -3135,6 +3655,13 @@
         "@types/node": "*"
       }
     },
+    "node_modules/@types/statuses": {
+      "version": "2.0.6",
+      "resolved": "https://registry.npmjs.org/@types/statuses/-/statuses-2.0.6.tgz",
+      "integrity": "sha512-xMAgYwceFhRA2zY+XbEA7mxYbA093wdiW8Vu6gZPGWy9cmOyU9XesH1tNcEWsKFd5Vzrqx5T3D38PWx1FIIXkA==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@types/trusted-types": {
       "version": "2.0.7",
       "resolved": "https://registry.npmjs.org/@types/trusted-types/-/trusted-types-2.0.7.tgz",
@@ -3275,6 +3802,32 @@
         "url": "https://opencollective.com/vitest"
       }
     },
+    "node_modules/acorn": {
+      "version": "8.17.0",
+      "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.17.0.tgz",
+      "integrity": "sha512-xRQbDb9BnwDafYNn6Vwl839DYVjqXYb1XVGtWAZ1kcDc6iwAL4hg3B1dZlRiuENFeO2H53gFG3in621AdERVAg==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "acorn": "bin/acorn"
+      },
+      "engines": {
+        "node": ">=0.4.0"
+      }
+    },
+    "node_modules/acorn-walk": {
+      "version": "8.3.5",
+      "resolved": "https://registry.npmjs.org/acorn-walk/-/acorn-walk-8.3.5.tgz",
+      "integrity": "sha512-HEHNfbars9v4pgpW6SO1KSPkfoS0xVOM/9UzkJltjlsHZmJasxg8aXkuZa7SMf8vKGIBhpUsPluQSqhJFCqebw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "acorn": "^8.11.0"
+      },
+      "engines": {
+        "node": ">=0.4.0"
+      }
+    },
     "node_modules/agent-base": {
       "version": "7.1.4",
       "resolved": "https://registry.npmjs.org/agent-base/-/agent-base-7.1.4.tgz",
@@ -3350,11 +3903,29 @@
         "url": "https://github.com/chalk/ansi-styles?sponsor=1"
       }
     },
+    "node_modules/arg": {
+      "version": "4.1.3",
+      "resolved": "https://registry.npmjs.org/arg/-/arg-4.1.3.tgz",
+      "integrity": "sha512-58S9QDqG0Xx27YwPSt9fJxivjYl432YCwfDMfZ+71RAqUrZef7LrKQZ3LHLOwCS4FLNBplP533Zx895SeOCHvA==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/argparse": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz",
       "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q=="
     },
+    "node_modules/aria-query": {
+      "version": "5.3.0",
+      "resolved": "https://registry.npmjs.org/aria-query/-/aria-query-5.3.0.tgz",
+      "integrity": "sha512-b0P0sZPKtyu8HkeRAfCq0IfURZK+SuwMjY1UXGBU27wpAiTwQAIlq56IbIO+ytk/JjS1fMR14ee5WBBfKi5J6A==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "peer": true,
+      "dependencies": {
+        "dequal": "^2.0.3"
+      }
+    },
     "node_modules/array-union": {
       "version": "2.1.0",
       "resolved": "https://registry.npmjs.org/array-union/-/array-union-2.1.0.tgz",
@@ -3723,6 +4294,16 @@
         "url": "https://github.com/chalk/strip-ansi?sponsor=1"
       }
     },
+    "node_modules/cli-width": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/cli-width/-/cli-width-4.1.0.tgz",
+      "integrity": "sha512-ouuZd4/dm2Sw5Gmqy6bGyNNNe1qt9RpmxveLSO7KcgsTnU7RXfsw+/bukWGo1abgBiMAic068rclZsO4IWmmxQ==",
+      "dev": true,
+      "license": "ISC",
+      "engines": {
+        "node": ">= 12"
+      }
+    },
     "node_modules/cliui": {
       "version": "7.0.4",
       "resolved": "https://registry.npmjs.org/cliui/-/cliui-7.0.4.tgz",
@@ -3795,6 +4376,13 @@
         "url": "https://opencollective.com/core-js"
       }
     },
+    "node_modules/create-require": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/create-require/-/create-require-1.1.1.tgz",
+      "integrity": "sha512-dcKFX3jn0MpIaXjisoRvexIJVEKzaq7z2rZKxf+MSr9TkdmHmsU4m2lcLojrj/FHl8mk5VxMmYA+ftRkP/3oKQ==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/cross-spawn": {
       "version": "7.0.6",
       "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz",
@@ -3956,6 +4544,16 @@
       "integrity": "sha512-m8FnyHXV1QX+S1cl+KPFDIl6NMkxtKsy6+U/aYyjrOqWMuwAwYWu7ePqrsUHtDR5Y8Yk2pi/KIDSgF+vT4cPOQ==",
       "dev": true
     },
+    "node_modules/dequal": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/dequal/-/dequal-2.0.3.tgz",
+      "integrity": "sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
     "node_modules/detect-indent": {
       "version": "6.1.0",
       "resolved": "https://registry.npmjs.org/detect-indent/-/detect-indent-6.1.0.tgz",
@@ -3976,6 +4574,16 @@
         "node": ">=8"
       }
     },
+    "node_modules/diff": {
+      "version": "4.0.4",
+      "resolved": "https://registry.npmjs.org/diff/-/diff-4.0.4.tgz",
+      "integrity": "sha512-X07nttJQkwkfKfvTPG/KSnE2OMdcUCao6+eXF3wmnIQRn2aPAHH3VxDbDOdegkd6JbPsXqShpvEOHfAT+nCNwQ==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "engines": {
+        "node": ">=0.3.1"
+      }
+    },
     "node_modules/dir-glob": {
       "version": "3.0.1",
       "resolved": "https://registry.npmjs.org/dir-glob/-/dir-glob-3.0.1.tgz",
@@ -3989,6 +4597,14 @@
         "node": ">=8"
       }
     },
+    "node_modules/dom-accessibility-api": {
+      "version": "0.5.16",
+      "resolved": "https://registry.npmjs.org/dom-accessibility-api/-/dom-accessibility-api-0.5.16.tgz",
+      "integrity": "sha512-X7BJ2yElsnOJ30pZF4uIIDfBEVgF4XEBxL9Bxhy6dnrm5hkzqmsWHGTiHqRiITNhMyFLyAiWndIJP7Z1NTteDg==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true
+    },
     "node_modules/dompurify": {
       "version": "3.4.11",
       "resolved": "https://registry.npmjs.org/dompurify/-/dompurify-3.4.11.tgz",
@@ -4263,6 +4879,23 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/fast-string-truncated-width": {
+      "version": "3.0.3",
+      "resolved": "https://registry.npmjs.org/fast-string-truncated-width/-/fast-string-truncated-width-3.0.3.tgz",
+      "integrity": "sha512-0jjjIEL6+0jag3l2XWWizO64/aZVtpiGE3t0Zgqxv0DPuxiMjvB3M24fCyhZUO4KomJQPj3LTSUnDP3GpdwC0g==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/fast-string-width": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/fast-string-width/-/fast-string-width-3.0.2.tgz",
+      "integrity": "sha512-gX8LrtNEI5hq8DVUfRQMbr5lpaS4nMIWV+7XEbXk2b8kiQIizgnlr12B4dA3ZEx3308ze0O4Q1R+cHts8kyUJg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "fast-string-truncated-width": "^3.0.2"
+      }
+    },
     "node_modules/fast-uri": {
       "version": "3.1.2",
       "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.2.tgz",
@@ -4279,6 +4912,16 @@
       ],
       "license": "BSD-3-Clause"
     },
+    "node_modules/fast-wrap-ansi": {
+      "version": "0.2.2",
+      "resolved": "https://registry.npmjs.org/fast-wrap-ansi/-/fast-wrap-ansi-0.2.2.tgz",
+      "integrity": "sha512-7F2Fl+TjRSenLqlU3UjSH0iyqopqoZIu7eZVpEirP2g1GtWa2G/ecEmBdgz31+Mxr+ELclgg6sokpSFIQiZ02Q==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "fast-string-width": "^3.0.2"
+      }
+    },
     "node_modules/fast-xml-builder": {
       "version": "1.2.0",
       "resolved": "https://registry.npmjs.org/fast-xml-builder/-/fast-xml-builder-1.2.0.tgz",
@@ -4296,9 +4939,9 @@
       }
     },
     "node_modules/fast-xml-parser": {
-      "version": "5.7.1",
-      "resolved": "https://registry.npmjs.org/fast-xml-parser/-/fast-xml-parser-5.7.1.tgz",
-      "integrity": "sha512-8Cc3f8GUGUULg34pBch/KGyPLglS+OFs05deyOlY7fL2MTagYPKrVQNmR1fLF/yJ9PH5ZSTd3YDF6pnmeZU+zA==",
+      "version": "5.7.3",
+      "resolved": "https://registry.npmjs.org/fast-xml-parser/-/fast-xml-parser-5.7.3.tgz",
+      "integrity": "sha512-C0AaNuC+mscy6vrAQKAc/rMq+zAPHodfHGZu4sGVehvAQt/JLG1O5zEcYcXSY5zSqr4YVgxsB+pHXTq0i7eDlg==",
       "funding": [
         {
           "type": "github",
@@ -4308,7 +4951,7 @@
       "license": "MIT",
       "dependencies": {
         "@nodable/entities": "^2.1.0",
-        "fast-xml-builder": "^1.1.5",
+        "fast-xml-builder": "^1.1.7",
         "path-expression-matcher": "^1.5.0",
         "strnum": "^2.2.3"
       },
@@ -4543,6 +5186,24 @@
         "node": ">=12.22.0"
       }
     },
+    "node_modules/headers-polyfill": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/headers-polyfill/-/headers-polyfill-5.0.1.tgz",
+      "integrity": "sha512-1TJ6Fih/b8h5TIcv+1+Hw0PDQWJTKDKzFZzcKOiW1wJza3XoAQlkCuXLbymPYB8+ZQyw8mHvdw560e8zVFIWyA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/set-cookie-parser": "^2.4.10",
+        "set-cookie-parser": "^3.0.1"
+      }
+    },
+    "node_modules/headers-polyfill/node_modules/set-cookie-parser": {
+      "version": "3.1.2",
+      "resolved": "https://registry.npmjs.org/set-cookie-parser/-/set-cookie-parser-3.1.2.tgz",
+      "integrity": "sha512-5/r/lTwbJ3zQ+qwdUFZYeRNqda7P5HD8zQKqlSjdGt1/S0cjLAphHusj4Y58ahDtWn/g32xrIS58/ikOvwl0Lw==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/html-encoding-sniffer": {
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/html-encoding-sniffer/-/html-encoding-sniffer-4.0.0.tgz",
@@ -4774,6 +5435,13 @@
         "url": "https://github.com/sponsors/wooorm"
       }
     },
+    "node_modules/is-node-process": {
+      "version": "1.2.0",
+      "resolved": "https://registry.npmjs.org/is-node-process/-/is-node-process-1.2.0.tgz",
+      "integrity": "sha512-Vg4o6/fqPxIjtxgUH5QLJhwZ7gW5diGCVlXpuUfELC62CuxM1iHcRe51f2W1FDy04Ai4KJkagKjx3XaqyfRKXw==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/is-number": {
       "version": "7.0.0",
       "resolved": "https://registry.npmjs.org/is-number/-/is-number-7.0.0.tgz",
@@ -5917,6 +6585,17 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/lz-string": {
+      "version": "1.5.0",
+      "resolved": "https://registry.npmjs.org/lz-string/-/lz-string-1.5.0.tgz",
+      "integrity": "sha512-h5bgJWpxJNswbU7qCrV0tIKQCaS3blPDrqKWx+QxzuzL1zGUzij9XCWLrSLsJPu5t+eWA/ycetzYAO5IOMcWAQ==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true,
+      "bin": {
+        "lz-string": "bin/bin.js"
+      }
+    },
     "node_modules/magic-string": {
       "version": "0.30.21",
       "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.30.21.tgz",
@@ -5955,6 +6634,13 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/make-error": {
+      "version": "1.3.6",
+      "resolved": "https://registry.npmjs.org/make-error/-/make-error-1.3.6.tgz",
+      "integrity": "sha512-s8UhlNe7vPKomQhC1qFelMokr/Sc3AgNbso3n74mVPA5LTZwkB9NlXf4XPamLxJE8h0gh73rM94xvwRT2CVInw==",
+      "dev": true,
+      "license": "ISC"
+    },
     "node_modules/mark.js": {
       "version": "8.11.1",
       "resolved": "https://registry.npmjs.org/mark.js/-/mark.js-8.11.1.tgz",
@@ -6439,6 +7125,135 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/msw": {
+      "version": "2.15.0",
+      "resolved": "https://registry.npmjs.org/msw/-/msw-2.15.0.tgz",
+      "integrity": "sha512-2wQAmKkQKxRuXvYJxVhPGG0wZNBQyD06oJvxqw90XqLvptdqxdlHrFUfEteKkpaNORX3Xzc+HtEl/q0nfmN2wQ==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "dependencies": {
+        "@inquirer/confirm": "^6.0.11",
+        "@mswjs/interceptors": "^0.41.3",
+        "@open-draft/deferred-promise": "^3.0.0",
+        "@types/statuses": "^2.0.6",
+        "cookie": "^1.1.1",
+        "graphql": "^16.13.2",
+        "headers-polyfill": "^5.0.1",
+        "is-node-process": "^1.2.0",
+        "outvariant": "^1.4.3",
+        "path-to-regexp": "^6.3.0",
+        "picocolors": "^1.1.1",
+        "rettime": "^0.11.11",
+        "statuses": "^2.0.2",
+        "strict-event-emitter": "^0.5.1",
+        "tough-cookie": "^6.0.1",
+        "type-fest": "^5.5.0",
+        "until-async": "^3.0.2",
+        "yargs": "^17.7.2"
+      },
+      "bin": {
+        "msw": "cli/index.js"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/mswjs"
+      },
+      "peerDependencies": {
+        "typescript": ">= 4.8.x"
+      },
+      "peerDependenciesMeta": {
+        "typescript": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/msw/node_modules/cliui": {
+      "version": "8.0.1",
+      "resolved": "https://registry.npmjs.org/cliui/-/cliui-8.0.1.tgz",
+      "integrity": "sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "string-width": "^4.2.0",
+        "strip-ansi": "^6.0.1",
+        "wrap-ansi": "^7.0.0"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/msw/node_modules/cookie": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/cookie/-/cookie-1.1.1.tgz",
+      "integrity": "sha512-ei8Aos7ja0weRpFzJnEA9UHJ/7XQmqglbRwnf2ATjcB9Wq874VKH9kfjjirM6UhU2/E5fFYadylyhFldcqSidQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/express"
+      }
+    },
+    "node_modules/msw/node_modules/type-fest": {
+      "version": "5.8.0",
+      "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-5.8.0.tgz",
+      "integrity": "sha512-YGYEVz3Fm5iy/AybuA0oyNFq7H4CgQNfRp/qfe8nurE1kuCeNm3/vfm9X4Mtl+qLyaKJUh5xrFZwogr41SMjYA==",
+      "dev": true,
+      "license": "(MIT OR CC0-1.0)",
+      "dependencies": {
+        "tagged-tag": "^1.0.0"
+      },
+      "engines": {
+        "node": ">=20"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/msw/node_modules/yargs": {
+      "version": "17.7.3",
+      "resolved": "https://registry.npmjs.org/yargs/-/yargs-17.7.3.tgz",
+      "integrity": "sha512-GZtjxm/J/4TSxuL3FNYjCmLktBTnIw/rVmKSIyKeYAZpmJB2ig9VauCC5xsa82GNKVKDAqpOn3KVzNt0zmrU0g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "cliui": "^8.0.1",
+        "escalade": "^3.1.1",
+        "get-caller-file": "^2.0.5",
+        "require-directory": "^2.1.1",
+        "string-width": "^4.2.3",
+        "y18n": "^5.0.5",
+        "yargs-parser": "^21.1.1"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/msw/node_modules/yargs-parser": {
+      "version": "21.1.1",
+      "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-21.1.1.tgz",
+      "integrity": "sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==",
+      "dev": true,
+      "license": "ISC",
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/mute-stream": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/mute-stream/-/mute-stream-3.0.0.tgz",
+      "integrity": "sha512-dkEJPVvun4FryqBmZ5KhDo0K9iDXAwn08tMLDinNdRBNPcYEDiWYysLcc6k3mjTMlbP9KyylvRpd4wFtwrT9rw==",
+      "dev": true,
+      "license": "ISC",
+      "engines": {
+        "node": "^20.17.0 || >=22.9.0"
+      }
+    },
     "node_modules/nanoid": {
       "version": "3.3.12",
       "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.12.tgz",
@@ -6671,13 +7486,13 @@
       }
     },
     "node_modules/openapi-sampler": {
-      "version": "1.7.1",
-      "resolved": "https://registry.npmjs.org/openapi-sampler/-/openapi-sampler-1.7.1.tgz",
-      "integrity": "sha512-pKFRROcYyxRt9GIn0NmS+GkWPS19l0CLQRYAnHk4m1Qp+G43ssVNcfRMs1sLkGrVMuFWO4P4F6YMXeXnfyFGuQ==",
+      "version": "1.7.4",
+      "resolved": "https://registry.npmjs.org/openapi-sampler/-/openapi-sampler-1.7.4.tgz",
+      "integrity": "sha512-CKS/rd5ucPCuEDbJnjGDXZTsuGWcmv53aCmQx7soZlPEONUGN4af0/dY5+THRFZraSEjeA78nlfzdFswC/N5SA==",
       "license": "MIT",
       "dependencies": {
         "@types/json-schema": "^7.0.7",
-        "fast-xml-parser": "^5.3.8",
+        "fast-xml-parser": "^5.5.1",
         "json-pointer": "0.6.2"
       }
     },
@@ -6687,6 +7502,13 @@
       "integrity": "sha512-VjIzdUHunL74DdhcwMDt5FhNDQ8NYmTkuW0B+usIV2afS9aWT/1c9z1TsnFW349TP3nxmYeUl7Z++XpJRByvgg==",
       "dev": true
     },
+    "node_modules/outvariant": {
+      "version": "1.4.3",
+      "resolved": "https://registry.npmjs.org/outvariant/-/outvariant-1.4.3.tgz",
+      "integrity": "sha512-+Sl2UErvtsoajRDKCE5/dBz4DIvHXQQnAxtQTF04OJxY0+DyZXSo5P5Bb7XYWOh81syohlYL24hbDwxedPUJCA==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/oxfmt": {
       "version": "0.33.0",
       "resolved": "https://registry.npmjs.org/oxfmt/-/oxfmt-0.33.0.tgz",
@@ -6922,6 +7744,13 @@
         "node": ">=8"
       }
     },
+    "node_modules/path-to-regexp": {
+      "version": "6.3.0",
+      "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-6.3.0.tgz",
+      "integrity": "sha512-Yhpw4T9C6hPpgPeA28us07OJeqZ5EzQTkbfwuhsUg0c237RomFoETJgmp2sa3F/41gfLE6G5cqcYwznmeEeOlQ==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/path-type": {
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/path-type/-/path-type-4.0.0.tgz",
@@ -7072,6 +7901,44 @@
         "url": "https://github.com/prettier/prettier?sponsor=1"
       }
     },
+    "node_modules/pretty-format": {
+      "version": "27.5.1",
+      "resolved": "https://registry.npmjs.org/pretty-format/-/pretty-format-27.5.1.tgz",
+      "integrity": "sha512-Qb1gy5OrP5+zDf2Bvnzdl3jsTf1qXVMazbvCoKhtKqVs4/YK4ozX4gKQJJVyNe+cajNPn0KoC0MC3FUmaHWEmQ==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "ansi-regex": "^5.0.1",
+        "ansi-styles": "^5.0.0",
+        "react-is": "^17.0.1"
+      },
+      "engines": {
+        "node": "^10.13.0 || ^12.13.0 || ^14.15.0 || >=15.0.0"
+      }
+    },
+    "node_modules/pretty-format/node_modules/ansi-styles": {
+      "version": "5.2.0",
+      "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-5.2.0.tgz",
+      "integrity": "sha512-Cxwpt2SfTzTtXcfOlzGEee8O+c+MmUgGrNiBcXnuWxuFJHe6a5Hz7qwhwe5OgaSYI0IJvkLqWX1ASG+cJOkEiA==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true,
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/ansi-styles?sponsor=1"
+      }
+    },
+    "node_modules/pretty-format/node_modules/react-is": {
+      "version": "17.0.2",
+      "resolved": "https://registry.npmjs.org/react-is/-/react-is-17.0.2.tgz",
+      "integrity": "sha512-w2GsyukL62IJnlaff/nRegPQR94C/XXamvMWmSHRJ4y7Ts/4ocGRmTHvOs8PSE6pB3dWOrD/nueuU5sduBsQ4w==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true
+    },
     "node_modules/prismjs": {
       "version": "1.30.0",
       "resolved": "https://registry.npmjs.org/prismjs/-/prismjs-1.30.0.tgz",
@@ -7435,6 +8302,13 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/rettime": {
+      "version": "0.11.11",
+      "resolved": "https://registry.npmjs.org/rettime/-/rettime-0.11.11.tgz",
+      "integrity": "sha512-ILJRqVWBCTlg9r42fFgwVZx1gnFAcQF8mRoMkbgQfIrjEDf9nbBFDFx00oloOa+Q869FUtaYDXZvEfnecQSCoQ==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/reusify": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/reusify/-/reusify-1.1.0.tgz",
@@ -7811,6 +8685,16 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/statuses": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/statuses/-/statuses-2.0.2.tgz",
+      "integrity": "sha512-DvEy55V3DB7uknRo+4iOGT5fP1slR8wQohVdknigZPMpMstaKJQWhwiYBACJE3Ul2pTnATihhBYnRhZQHGBiRw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.8"
+      }
+    },
     "node_modules/std-env": {
       "version": "4.1.0",
       "resolved": "https://registry.npmjs.org/std-env/-/std-env-4.1.0.tgz",
@@ -7837,6 +8721,13 @@
       "integrity": "sha512-GCp7vHAfpao+Qh/3Flh9DXEJ/qSi0KJwJw6zYlZOtRYXWUIpMM6mC2rIep/dK8RQqwW0KxGJIllmjPIBOGN8AA==",
       "dev": true
     },
+    "node_modules/strict-event-emitter": {
+      "version": "0.5.1",
+      "resolved": "https://registry.npmjs.org/strict-event-emitter/-/strict-event-emitter-0.5.1.tgz",
+      "integrity": "sha512-vMgjE/GGEPEFnhFub6pa4FmJBRBVOLpIII2hvCZ8Kzb7K0hlHo7mQv6xYrBvCL2LtAIBwFUK8wvuJgTVSQ5MFQ==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/string-argv": {
       "version": "0.3.2",
       "resolved": "https://registry.npmjs.org/string-argv/-/string-argv-0.3.2.tgz",
@@ -7988,6 +8879,20 @@
         "node": ">= 6"
       }
     },
+    "node_modules/swr": {
+      "version": "2.4.2",
+      "resolved": "https://registry.npmjs.org/swr/-/swr-2.4.2.tgz",
+      "integrity": "sha512-ej644Y2bvkIajfR32KGeSSdBXQW+ScjGjkybZgSE7kFpk9eGnV44XY9FJylXi+W75pavSX1PVNB57W5EbhGIYw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "dequal": "^2.0.3",
+        "use-sync-external-store": "^1.6.0"
+      },
+      "peerDependencies": {
+        "react": "^16.11.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+      }
+    },
     "node_modules/symbol-tree": {
       "version": "3.2.4",
       "resolved": "https://registry.npmjs.org/symbol-tree/-/symbol-tree-3.2.4.tgz",
@@ -7995,6 +8900,19 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/tagged-tag": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/tagged-tag/-/tagged-tag-1.0.0.tgz",
+      "integrity": "sha512-yEFYrVhod+hdNyx7g5Bnkkb0G6si8HJurOoOEgC8B/O0uXLHlaey/65KRv6cuWBNhBgHKAROVpc7QyYqE5gFng==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=20"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/term-size": {
       "version": "2.2.1",
       "resolved": "https://registry.npmjs.org/term-size/-/term-size-2.2.1.tgz",
@@ -8125,9 +9043,9 @@
       }
     },
     "node_modules/tough-cookie": {
-      "version": "6.0.0",
-      "resolved": "https://registry.npmjs.org/tough-cookie/-/tough-cookie-6.0.0.tgz",
-      "integrity": "sha512-kXuRi1mtaKMrsLUxz3sQYvVl37B0Ns6MzfrtV5DvJceE9bPyspOqk9xxv7XbZWcfLWbFmm997vl83qUWVJA64w==",
+      "version": "6.0.2",
+      "resolved": "https://registry.npmjs.org/tough-cookie/-/tough-cookie-6.0.2.tgz",
+      "integrity": "sha512-exgYmnmL/sJpR3upZfXG5PoatXQii55xAiXGXzY+sROLZ/Y+SLcp9PgJNI9Vz37HpQ74WvDcLT8eqm+kV3FzrA==",
       "dev": true,
       "license": "BSD-3-Clause",
       "dependencies": {
@@ -8160,6 +9078,50 @@
       "integrity": "sha512-FPAhNPFMrkwz76P7cdjdmiShwMynZYN6SgOujD1urY4oNm80Ou9oMdmbR45LotcKOXoy7wSmHkRFE6Mxbrhefw==",
       "dev": true
     },
+    "node_modules/ts-node": {
+      "version": "10.9.2",
+      "resolved": "https://registry.npmjs.org/ts-node/-/ts-node-10.9.2.tgz",
+      "integrity": "sha512-f0FFpIdcHgn8zcPSbf1dRevwt047YMnaiJM3u2w2RewrB+fob/zePZcrOyQoLMMO7aBIddLcQIEK5dYjkLnGrQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@cspotcode/source-map-support": "^0.8.0",
+        "@tsconfig/node10": "^1.0.7",
+        "@tsconfig/node12": "^1.0.7",
+        "@tsconfig/node14": "^1.0.0",
+        "@tsconfig/node16": "^1.0.2",
+        "acorn": "^8.4.1",
+        "acorn-walk": "^8.1.1",
+        "arg": "^4.1.0",
+        "create-require": "^1.1.0",
+        "diff": "^4.0.1",
+        "make-error": "^1.1.1",
+        "v8-compile-cache-lib": "^3.0.1",
+        "yn": "3.1.1"
+      },
+      "bin": {
+        "ts-node": "dist/bin.js",
+        "ts-node-cwd": "dist/bin-cwd.js",
+        "ts-node-esm": "dist/bin-esm.js",
+        "ts-node-script": "dist/bin-script.js",
+        "ts-node-transpile-only": "dist/bin-transpile.js",
+        "ts-script": "dist/bin-script-deprecated.js"
+      },
+      "peerDependencies": {
+        "@swc/core": ">=1.2.50",
+        "@swc/wasm": ">=1.2.50",
+        "@types/node": "*",
+        "typescript": ">=2.7"
+      },
+      "peerDependenciesMeta": {
+        "@swc/core": {
+          "optional": true
+        },
+        "@swc/wasm": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/tslib": {
       "version": "2.8.1",
       "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz",
@@ -8356,6 +9318,16 @@
         "node": ">= 4.0.0"
       }
     },
+    "node_modules/until-async": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/until-async/-/until-async-3.0.2.tgz",
+      "integrity": "sha512-IiSk4HlzAMqTUseHHe3VhIGyuFmN90zMTpD3Z3y8jeQbzLIq500MVM7Jq2vUAnTKAFPJrqwkzr6PoTcPhGcOiw==",
+      "dev": true,
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/kettanaito"
+      }
+    },
     "node_modules/update-browserslist-db": {
       "version": "1.2.3",
       "resolved": "https://registry.npmjs.org/update-browserslist-db/-/update-browserslist-db-1.2.3.tgz",
@@ -8411,6 +9383,13 @@
         "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
       }
     },
+    "node_modules/v8-compile-cache-lib": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/v8-compile-cache-lib/-/v8-compile-cache-lib-3.0.1.tgz",
+      "integrity": "sha512-wa7YjyUGfNZngI/vtK0UHAN+lgDCxBPCylVXGp0zu59Fz5aiGtNXaq3DhIov063MorB+VfufLh3JlF2KdTK3xg==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/vfile": {
       "version": "4.2.1",
       "resolved": "https://registry.npmjs.org/vfile/-/vfile-4.2.1.tgz",
@@ -8854,6 +9833,26 @@
         "node": ">=10"
       }
     },
+    "node_modules/yn": {
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/yn/-/yn-3.1.1.tgz",
+      "integrity": "sha512-Ux4ygGWsu2c7isFWe8Yu1YluJmqVhxqK2cLXNQA5AcC3QfbGNpM7fu0Y8b/z16pXLnFxZYvWhd3fhBY9DLmC6Q==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/zod": {
+      "version": "4.4.3",
+      "resolved": "https://registry.npmjs.org/zod/-/zod-4.4.3.tgz",
+      "integrity": "sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ==",
+      "dev": true,
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/colinhacks"
+      }
+    },
     "node_modules/zwitch": {
       "version": "1.0.5",
       "resolved": "https://registry.npmjs.org/zwitch/-/zwitch-1.0.5.tgz",
@@ -8878,6 +9877,7 @@
         "@opentelemetry/sdk-trace-node": "2.8.0",
         "@opentelemetry/semantic-conventions": "1.41.1",
         "@redocly/cli-otel": "0.3.4",
+        "@redocly/client-generator": "0.1.0",
         "@redocly/openapi-core": "2.39.0",
         "@redocly/respect-core": "2.39.0",
         "@types/cookie": "0.6.0",
@@ -8910,6 +9910,24 @@
         "npm": ">=10"
       }
     },
+    "packages/client-generator": {
+      "name": "@redocly/client-generator",
+      "version": "0.1.0",
+      "license": "MIT",
+      "dependencies": {
+        "@redocly/openapi-core": "2.39.0"
+      },
+      "devDependencies": {
+        "typescript": "6.0.2"
+      },
+      "engines": {
+        "node": ">=22.12.0 || >=20.19.0 <21.0.0",
+        "npm": ">=10"
+      },
+      "peerDependencies": {
+        "typescript": ">=5.5.0"
+      }
+    },
     "packages/core": {
       "name": "@redocly/openapi-core",
       "version": "2.39.0",
@@ -8997,6 +10015,16 @@
         "npm": ">=10"
       }
     },
+    "packages/respect-core/node_modules/@faker-js/faker": {
+      "version": "7.6.0",
+      "resolved": "https://registry.npmjs.org/@faker-js/faker/-/faker-7.6.0.tgz",
+      "integrity": "sha512-XK6BTq1NDMo9Xqw/YkYyGjSsg44fbNwYRx7QK2CuoQgyy+f1rrTDHoExVM5PsyXCtfl2vs2vVJ0MN0yN6LppRw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=14.0.0",
+        "npm": ">=6.0.0"
+      }
+    },
     "packages/respect-core/node_modules/ajv": {
       "name": "@redocly/ajv",
       "version": "8.18.1",
diff --git a/package.json b/package.json
index dc33dc0d94..2d29f921af 100644
--- a/package.json
+++ b/package.json
@@ -53,21 +53,32 @@
   "license": "MIT",
   "devDependencies": {
     "@changesets/cli": "^2.26.2",
+    "@faker-js/faker": "^9.9.0",
+    "@redocly/mock-server": "^0.7.0",
+    "@tanstack/react-query": "^5.0.0",
+    "@testing-library/react": "^16.0.0",
     "@types/node": "^22.15.3",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
     "@vitest/coverage-istanbul": "^4.1.8",
     "husky": "^9.1.7",
     "jsdom": "^27.2.0",
     "json-schema-to-ts": "^3.0.0",
     "json-server": "1.0.0-beta.3",
     "lint-staged": "^15.4.3",
+    "msw": "^2.14.6",
     "outdent": "^0.7.1",
     "oxfmt": "^0.33.0",
     "oxlint": "^1.48.0",
     "pegjs": "0.11.0-master.b7b87ea",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
     "slackify-markdown": "^4.3.1",
+    "swr": "^2.4.1",
     "tsx": "^4.19.3",
     "typescript": "6.0.2",
-    "vitest": "^4.1.8"
+    "vitest": "^4.1.8",
+    "zod": "^4.0.0"
   },
   "lint-staged": {
     "**/*.{ts,js,yaml,yml,json,md}": [
diff --git a/packages/cli/package.json b/packages/cli/package.json
index 144e44a6ea..8d9f250223 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -45,6 +45,7 @@
     "@opentelemetry/sdk-trace-node": "2.8.0",
     "@opentelemetry/semantic-conventions": "1.41.1",
     "@redocly/cli-otel": "0.3.4",
+    "@redocly/client-generator": "0.1.0",
     "@redocly/openapi-core": "2.39.0",
     "@redocly/respect-core": "2.39.0",
     "@types/cookie": "0.6.0",
diff --git a/packages/cli/scripts/build.mjs b/packages/cli/scripts/build.mjs
index 43881a1565..0948c78637 100644
--- a/packages/cli/scripts/build.mjs
+++ b/packages/cli/scripts/build.mjs
@@ -20,7 +20,14 @@ const result = await build({
   metafile: true,
   // Avoid errors when external dependencies use CJS syntax.
   banner: {
-    js: "import { createRequire as __createRequire } from 'node:module';\nconst require = __createRequire(import.meta.url);",
+    js: [
+      "import { createRequire as __createRequire } from 'node:module';",
+      "import { fileURLToPath as __fileURLToPath } from 'node:url';",
+      "import { dirname as __pathDirname } from 'node:path';",
+      'const require = __createRequire(import.meta.url);',
+      'var __filename = __fileURLToPath(import.meta.url);',
+      'var __dirname = __pathDirname(__filename);',
+    ].join('\n'),
   },
   logLevel: 'info',
 });
diff --git a/packages/cli/src/commands/generate-client.ts b/packages/cli/src/commands/generate-client.ts
new file mode 100644
index 0000000000..8fa4721e2f
--- /dev/null
+++ b/packages/cli/src/commands/generate-client.ts
@@ -0,0 +1,187 @@
+import { type Config as OpenApiTsConfig } from '@redocly/client-generator';
+import { type Config, HandledError, isPlainObject, logger, pluralize } from '@redocly/openapi-core';
+import { blue, gray, yellow } from 'colorette';
+import { basename, dirname, extname, isAbsolute, resolve as resolvePath } from 'node:path';
+
+import { getFallbackApisOrExit } from '../utils/miscellaneous.js';
+import { type CommandArgs } from '../wrapper.js';
+
+export type GenerateClientCommandArgv = {
+  api?: string;
+  output?: string;
+  config?: string;
+  'server-url'?: string;
+  'enum-style'?: 'union' | 'const-object';
+  'output-mode'?: 'single' | 'split';
+  runtime?: 'inline' | 'package';
+  'import-ext'?: 'js' | 'ts';
+  'args-style'?: 'flat' | 'grouped';
+  'error-mode'?: 'throw' | 'result';
+  'date-type'?: 'string' | 'Date';
+  'query-framework'?: 'react' | 'vue' | 'svelte' | 'solid';
+  'mock-data'?: 'baked' | 'faker';
+  'mock-seed'?: number;
+  generator?: string[];
+  setup?: string;
+};
+
+type ClientConfig = Partial<OpenApiTsConfig>;
+
+type Job = {
+  name: string;
+  api: string;
+  aliasConfig: Config;
+  clientOutput?: string;
+  client: ClientConfig;
+};
+
+// Two+ letter scheme, so Windows drive paths (`C:\...`) don't match.
+const URL_SCHEME = /^[a-z][a-z0-9+.-]+:/i;
+
+function resolveSetup(client: ClientConfig, configDir: string): ClientConfig {
+  const { setup } = client;
+  if (typeof setup !== 'string') return client;
+  if (URL_SCHEME.test(setup)) {
+    throw new HandledError(
+      `\n❌  \`client.setup\` must be a local file path — remote setup modules are not supported.\n   Got: ${setup}\n`
+    );
+  }
+  if (!isAbsolute(setup)) {
+    return { ...client, setup: resolvePath(configDir, setup) };
+  }
+  return client;
+}
+
+function fileNameFor(name: string): string {
+  return `${name.replace(/[\\/]/g, '_')}.client.ts`;
+}
+
+// Accepts an absolute http(s) URL or a root-relative path; rejects bare hostnames,
+// protocol-relative `//host`, and non-http(s) schemes.
+function isValidServerUrl(value: string): boolean {
+  if (value.startsWith('//')) return false;
+  if (value.startsWith('/')) return true;
+  try {
+    const url = new URL(value);
+    return url.protocol === 'http:' || url.protocol === 'https:';
+  } catch {
+    return false;
+  }
+}
+
+export async function handleGenerateClient({
+  argv,
+  config,
+}: CommandArgs<GenerateClientCommandArgv>) {
+  const { generateClient, mergeConfig } = await import('@redocly/client-generator');
+
+  const configDir = config.configPath ? dirname(config.configPath) : process.cwd();
+  const apisCfg = config.resolvedConfig.apis ?? {};
+
+  const cliFlags: ClientConfig = {
+    serverUrl: argv['server-url'],
+    enumStyle: argv['enum-style'],
+    outputMode: argv['output-mode'],
+    runtime: argv.runtime,
+    importExt: argv['import-ext'],
+    argsStyle: argv['args-style'],
+    errorMode: argv['error-mode'],
+    dateType: argv['date-type'],
+    queryFramework: argv['query-framework'],
+    mockData: argv['mock-data'],
+    mockSeed: argv['mock-seed'],
+    // Like `setup` below: flag paths resolve against the cwd, while config-file entries
+    // resolve against the config dir (in `resolveGenerators`). Package specifiers and
+    // built-in names pass through.
+    generators: argv.generator?.map((specifier) =>
+      specifier.startsWith('.') ? resolvePath(specifier) : specifier
+    ),
+    setup:
+      argv.setup === undefined
+        ? undefined
+        : resolveSetup({ setup: argv.setup }, process.cwd()).setup,
+  };
+
+  const optedIn = Object.keys(apisCfg).filter(
+    (name) => isPlainObject(apisCfg[name].client) || apisCfg[name].clientOutput !== undefined
+  );
+  if (argv.api === undefined) {
+    if (argv.output) {
+      throw new HandledError(
+        `\n❌  --output can't target multiple APIs. Set \`clientOutput\` under each api in redocly.yaml, or pass a single <api>.\n`
+      );
+    }
+    if (optedIn.length === 0) {
+      throw new HandledError(
+        `\n❌  No API to generate. Add a \`client\` block or \`clientOutput\` under an \`apis:\` entry, or pass <api> (a file/URL or an \`apis:\` alias).\n`
+      );
+    }
+  }
+  const entrypoints = await getFallbackApisOrExit(
+    argv.api === undefined ? optedIn : [argv.api],
+    config
+  );
+
+  const jobs: Job[] = entrypoints.map(({ path, alias }) => {
+    const aliasConfig = config.forAlias(alias);
+    const { client } = aliasConfig.resolvedConfig;
+    return {
+      name: alias ?? basename(path, extname(path)),
+      api: path,
+      aliasConfig,
+      clientOutput: alias === undefined ? undefined : apisCfg[alias]?.clientOutput,
+      client: resolveSetup((isPlainObject(client) ? client : {}) as ClientConfig, configDir),
+    };
+  });
+
+  const seenOutputs = new Set<string>();
+
+  for (const job of jobs) {
+    const merged = mergeConfig(job.client, cliFlags);
+
+    const outputPath =
+      argv.output !== undefined
+        ? resolvePath(argv.output)
+        : job.clientOutput !== undefined
+          ? resolvePath(configDir, job.clientOutput)
+          : resolvePath(configDir, fileNameFor(job.name));
+
+    if (!outputPath.endsWith('.ts')) {
+      throw new HandledError(
+        `\n❌  output must point at a TypeScript file (ending in .ts).\n   Got: ${outputPath}\n`
+      );
+    }
+    if (seenOutputs.has(outputPath)) {
+      throw new HandledError(
+        `\n❌  Two APIs resolve to the same output path: ${outputPath}.\n   Give each api a distinct \`clientOutput\`.\n`
+      );
+    }
+    seenOutputs.add(outputPath);
+    if (merged.serverUrl !== undefined && !isValidServerUrl(merged.serverUrl)) {
+      throw new HandledError(
+        `\n❌  --server-url must be an absolute URL (https://api.example.com) or a root-relative path (/v1).\n   Got: ${merged.serverUrl}\n`
+      );
+    }
+
+    try {
+      logger.info(gray(`\n  Generating TypeScript client for ${job.name}... \n`));
+      const result = await generateClient({
+        ...merged,
+        api: job.api,
+        output: outputPath,
+        config: job.aliasConfig,
+        configDir,
+      });
+      const fileCount = `${result.files.length} ${pluralize('file', result.files.length)}`;
+      const summary = `TypeScript client successfully generated: ${fileCount} (${
+        result.bytes
+      } bytes) at ${yellow(result.outputPath)}.`;
+      logger.info('\n' + blue(summary) + '\n');
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new HandledError(
+        `\n❌  Failed to generate TypeScript client for ${job.name}.\n   ${message}\n`
+      );
+    }
+  }
+}
diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts
index 7fe6cffefc..aebaa2b953 100644
--- a/packages/cli/src/index.ts
+++ b/packages/cli/src/index.ts
@@ -23,6 +23,10 @@ import {
   handleGenerateArazzo,
   type GenerateArazzoCommandArgv,
 } from './commands/generate-arazzo.js';
+import {
+  handleGenerateClient,
+  type GenerateClientCommandArgv,
+} from './commands/generate-client.js';
 import { handleJoin } from './commands/join/index.js';
 import { handleLint } from './commands/lint.js';
 import { PRODUCT_PLANS } from './commands/preview-project/constants.js';
@@ -855,6 +859,113 @@ yargs(hideBin(process.argv))
       commandWrapper(handleGenerateArazzo)(argv as Arguments<GenerateArazzoCommandArgv>);
     }
   )
+  .command(
+    'generate-client [api]',
+    'Generate a TypeScript client from an OpenAPI description [experimental].',
+    (yargs) => {
+      return yargs
+        .env('REDOCLY_CLI_GENERATE_CLIENT')
+        .positional('api', {
+          describe: 'OpenAPI description file path (or alias from redocly.yaml `apis:`).',
+          type: 'string',
+        })
+        .options({
+          output: {
+            alias: 'o',
+            describe: 'Output file path for the generated client (must end in .ts).',
+            type: 'string',
+            requiresArg: true,
+          },
+          'server-url': {
+            describe:
+              'Override the server URL inlined into the generated runtime. Defaults to `servers[0].url`.',
+            type: 'string',
+            requiresArg: true,
+          },
+          'enum-style': {
+            describe:
+              'How named string enums are emitted: `const-object` (default) emits a runtime `as const` object alongside the union type; `union` emits only the union.',
+            choices: ['union', 'const-object'] as const,
+            requiresArg: true,
+          },
+          'output-mode': {
+            describe:
+              'How the client is split across files: `single` (default, one file) or `split` (schema types and guards in a sibling `<name>.schemas.ts` the entry re-exports).',
+            choices: ['single', 'split'] as const,
+            requiresArg: true,
+          },
+          runtime: {
+            describe:
+              "Runtime distribution: 'inline' (default) embeds the runtime in the generated file; 'package' imports it from @redocly/client-generator.",
+            choices: ['inline', 'package'] as const,
+            requiresArg: true,
+          },
+          'import-ext': {
+            describe:
+              "Extension in generated relative imports: 'js' (default) suits tsc and bundlers; 'ts' suits runtimes that resolve specifiers literally, like Node's built-in type stripping (node client.ts).",
+            choices: ['js', 'ts'] as const,
+            requiresArg: true,
+          },
+          setup: {
+            describe:
+              'Path to a publisher setup module (export default defineClientSetup({ config, middleware })) baked into the generated client, so a published SDK ships its request/response defaults built in. Works across all output modes.',
+            type: 'string',
+            requiresArg: true,
+          },
+          'args-style': {
+            describe:
+              'How operation inputs are passed: `flat` (default) spreads path params as positional arguments followed by `params`/`body`/`headers`; `grouped` bundles every input into a single `args` object (the per-call request `init` stays a separate trailing argument).',
+            choices: ['flat', 'grouped'] as const,
+            requiresArg: true,
+          },
+          'error-mode': {
+            describe:
+              "Error handling: 'throw' (default) throws ApiError on non-2xx; 'result' returns { data, error, response }.",
+            choices: ['throw', 'result'] as const,
+            requiresArg: true,
+          },
+          'date-type': {
+            describe:
+              "How `date-time`/`date` string fields are typed: 'string' (default) keeps the ISO wire shape; 'Date' emits a `Date` (pair with --generator transformers so the runtime value matches).",
+            choices: ['string', 'Date'] as const,
+            requiresArg: true,
+          },
+          'query-framework': {
+            describe:
+              'TanStack Query adapter the `tanstack-query` generator imports from: `react` (default), `vue`, `svelte`, or `solid`. Only the import specifier changes — the emitted factory module is byte-identical across frameworks.',
+            choices: ['react', 'vue', 'svelte', 'solid'] as const,
+            requiresArg: true,
+          },
+          'mock-data': {
+            describe:
+              "How the `mock` generator produces data: 'baked' (default) inlines deterministic literals (zero-dep); 'faker' emits @faker-js/faker calls for realistic data (install @faker-js/faker as a dev dependency).",
+            choices: ['baked', 'faker'] as const,
+            requiresArg: true,
+          },
+          'mock-seed': {
+            describe:
+              'Seed for faker-mode mocks: emits a top-level `faker.seed(<n>)` so generated data is reproducible across runs. Ignored in baked mode.',
+            type: 'number',
+            requiresArg: true,
+          },
+          generator: {
+            describe:
+              'Generator to run; repeat the flag to run several (default: sdk). A built-in name (sdk, zod, tanstack-query, swr, transformers, mock) or a custom-generator path/package specifier. Example: --generator sdk --generator zod',
+            type: 'string',
+            array: true,
+            requiresArg: true,
+          },
+          config: {
+            describe: 'Path to the config file.',
+            type: 'string',
+            requiresArg: true,
+          },
+        });
+    },
+    async (argv) => {
+      commandWrapper(handleGenerateClient)(argv as Arguments<GenerateClientCommandArgv>);
+    }
+  )
   .command(
     'scorecard-classic [api]',
     'Run quality scorecards with multiple rule levels to validate and maintain API description standards.',
diff --git a/packages/cli/tsconfig.json b/packages/cli/tsconfig.json
index cb2d2b020e..c63ceea4c5 100644
--- a/packages/cli/tsconfig.json
+++ b/packages/cli/tsconfig.json
@@ -4,7 +4,11 @@
     "rootDir": "src",
     "outDir": "lib"
   },
-  "references": [{ "path": "../core" }, { "path": "../respect-core" }],
+  "references": [
+    { "path": "../core" },
+    { "path": "../respect-core" },
+    { "path": "../client-generator" }
+  ],
   "include": ["src/**/*.ts"],
   "exclude": ["lib", "**/__tests__", "**/*.test.ts"]
 }
diff --git a/packages/client-generator/ARCHITECTURE.md b/packages/client-generator/ARCHITECTURE.md
new file mode 100644
index 0000000000..91b20cb844
--- /dev/null
+++ b/packages/client-generator/ARCHITECTURE.md
@@ -0,0 +1,141 @@
+# Client Generator — Architecture
+
+How `@redocly/client-generator` is built.
+This is a **descriptive** map of the current shape — the pipeline, the modules, and the seams.
+It says _what is_; the **why** (the significant decisions and their trade-offs) lives in the Architecture Decision Records under [`docs/adr/`](./docs/adr/), linked inline below.
+For the vocabulary used here (IR, emitter, writer, runtime, output mode, …), see [CONTEXT.md](./CONTEXT.md).
+This is not a roadmap; planned refactors live in their own specs.
+
+## Overview
+
+The package turns an OpenAPI description into a typed TypeScript client with **zero runtime dependencies** — the generated code uses only web-standard APIs (`fetch`, `AbortController`, `URLSearchParams`), so it runs in browsers, Node, Bun, Deno, and edge runtimes (see [ADR-0002](./docs/adr/0002-typescript-peer-dep.md)).
+It backs the `redocly generate-client` CLI command.
+
+## Codegen approach
+
+Generated TypeScript is built as a **TypeScript AST** (`ts.factory` nodes) and emitted by the compiler's own printer (`ts.createPrinter`), **not** by string interpolation — rationale and trade-offs in [ADR-0001](./docs/adr/0001-ast-codegen.md).
+The one generation-time dependency is `typescript` itself, declared as a **peer** ([ADR-0002](./docs/adr/0002-typescript-peer-dep.md)); it is never emitted, so the generated client stays dependency-free.
+
+A foundation module (`emitters/ts.ts`) wraps the ergonomics: re-exports `ts` (the `factory`), `printNodes(nodes)` over a shared printer, `parseStatements(source)` to parse hand-authored source (used by the inline assembler and the baked-setup emitter), and `jsdoc(node, text)`.
+Each emitter produces `ts.Statement[]` / `ts.TypeNode`s; the shared wiring emitter (`emitters/package-client.ts`) assembles the per-file content and prints **once**.
+The **runtime** is not emitter-built at all — it is real TypeScript under `src/runtime/`, imported (package mode) or embedded from a source snapshot (inline mode).
+Formatting is the printer's; a pretty-print pass is deferred to optional-formatter work (roadmap P7.3).
+
+## Pipeline
+
+```mermaid
+flowchart LR
+  spec[OpenAPI doc] --> load["loadSpec()"]
+  load --> build["buildApiModel()"]
+  build --> ir[("ApiModel / IR")]
+  ir --> gw["getWriter(outputMode)"]
+  gw --> writer["a Writer"]
+  writer --> emit["emitters"]
+  emit --> files[[".ts files"]]
+```
+
+1. **`loadSpec`** (`loader.ts`) — bundles the OpenAPI document via `@redocly/openapi-core`, resolving external `$ref`s while **preserving internal `$ref`s** (the IR builder relies on named references staying intact).
+   Also detects the spec version (`detectSpec`).
+   1.5. **`normalizeSwagger2`** (`intermediate-representation/normalize-swagger2.ts`) — when the detected version is `oas2`, converts the Swagger 2.0 document to the OpenAPI 3.x shape (definitions → components.schemas, host/basePath/schemes → servers, body/formData params → requestBody, `responses[].schema` → `responses[].content`, securityDefinitions → securitySchemes, `$ref` rewrite).
+   OAS 3.0/3.1/3.2 skip this step.
+2. **`buildApiModel`** (`intermediate-representation/build.ts`) — walks the OpenAPI document and produces the spec-agnostic **IR** (`intermediate-representation/model.ts`).
+   Everything downstream reads the IR, never the raw spec ([ADR-0003](./docs/adr/0003-spec-agnostic-ir.md)).
+3. **`getWriter(outputMode)`** (`writers/index.ts`) — selects the **Writer** for the chosen output mode.
+4. The **Writer** decides the file layout and fills each file by calling the **emitters**.
+5. The **emitters** (`emitters/`) build a **TypeScript AST** and print it via `emitters/ts.ts`.
+6. `generateClient` (`index.ts`) writes the files to disk.
+
+## Module map
+
+| Area       | Files                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Owns                                                                                                                                                                                                                                                                                                                                                         | Depth                                                                                                                                    |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| Entry      | `index.ts`, `types.ts`, `config.ts`, `config-file.ts`, `plugin.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `generateClient` orchestration; public option/result types; config loading; the experimental `@redocly/client-generator` entry (`defineGenerator` + IR types + codegen toolkit)                                                                                                                                                                              | thin orchestrator                                                                                                                        |
+| Load       | `loader.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | bundle + `$ref` resolution, preserving internal refs                                                                                                                                                                                                                                                                                                         | deep (hides `openapi-core`)                                                                                                              |
+| IR         | `intermediate-representation/build.ts`, `intermediate-representation/model.ts`, `intermediate-representation/refs.ts`, `intermediate-representation/normalize-swagger2.ts`, `intermediate-representation/sanitize-identifiers.ts`                                                                                                                                                                                                                                                                                                                                                                                              | OpenAPI → IR; the IR type model; ref collection; Swagger 2.0 → 3.x normalization; coerce document-derived names to safe unique identifiers (security boundary)                                                                                                                                                                                               | deep (`buildApiModel` + `normalizeSwagger2` each one interface over a whole walk)                                                        |
+| Writers    | `writers/index.ts`, `single-file-writer.ts`, `split-writer.ts`, `util.ts`, `types.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | file layout per output mode (`single`, `split`) over the shared wiring emitter                                                                                                                                                                                                                                                                               | thin adapters at the `getWriter` seam                                                                                                    |
+| Generators | `generators/index.ts` (registry + `validateGenerators`), `resolve.ts` (built-in / inline / specifier resolution), `types.ts`, `sdk.ts`, `zod.ts`, `tanstack-query.ts`, `swr.ts`, `transformers.ts`, `mock.ts`                                                                                                                                                                                                                                                                                                                                                                                                                  | the generator registry seam: each descriptor declares its requires/errorModes/dateTypes/runtimes and produces `GeneratedFile[]` by calling an emitter; `resolve.ts` turns a selection (built-in names, inline `customGenerators`, or plugin import specifiers) into a name→descriptor registry                                                               | thin adapters at the `getGenerator` seam ([ADR-0004](./docs/adr/0004-registry-seams.md), [ADR-0012](./docs/adr/0012-plugin-api.md))      |
+| Runtime    | `runtime/types.ts`, `errors.ts`, `url.ts`, `parse.ts`, `retry.ts`, `multipart.ts`, `auth.ts`, `setup.ts`, `send.ts`, `sse.ts`, `create-client.ts`, `index.ts` (the package barrel)                                                                                                                                                                                                                                                                                                                                                                                                                                             | the client engine as real, unit-testable TypeScript modules: `createClient` builds a typed instance client over operation descriptors, dispatching optional behaviors (multipart, auth, SSE) through a capability seam; the barrel wires the full capability set for package-mode consumers                                                                  | deep (`createClient` is one interface over the whole engine)                                                                             |
+| Emitters   | sdk wiring: `emitters/package-client.ts` (the shared wiring emitter), `descriptor.ts` (OPERATIONS + `Ops`), `inline-runtime.ts` (the inline assembler) + generated `runtime-sources.ts`, `client.ts` (options + banners), `types.ts`, `type-guards.ts`, `auth.ts` (setter names), `operations.ts` (+ `operation-aliases.ts`, `operation-types.ts`), `sse.ts`, `setup-bake.ts`; satellite: `zod.ts`, `transformers.ts`, `tanstack-query.ts`, `swr.ts` (+ shared `wrapper-support.ts`), `mock.ts`/`faker.ts`/`sample.ts`; foundation `ts.ts`; shared `operation-signature.ts`; private `support.ts`, `jsdoc.ts`, `identifier.ts` | IR → TypeScript AST (`ts.factory` nodes, printed via `ts.ts`); `descriptor.ts` emits the pure-data operation descriptors and the `Ops` type; `sse.ts` is the SSE detection seam; `operation-signature.ts` is the single source of an operation’s calling convention; `wrapper-support.ts` is the shared eligibility/param model for `swr` + `tanstack-query` | each emitter is deep (one entry point builds nodes over hidden bulk); `package-client.ts` assembles the per-file content and prints once |
+| Errors     | `errors.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `NotSupportedError`                                                                                                                                                                                                                                                                                                                                          | trivial                                                                                                                                  |
+
+The IR (`intermediate-representation/model.ts`) is a **pure type model** — no runtime code. It is the contract between the
+builder and the emitters ([ADR-0003](./docs/adr/0003-spec-agnostic-ir.md)).
+
+## Seams
+
+Places where behavior varies without editing in place:
+
+- **The `getGenerator` seam** — a generator is `(input) => GeneratedFile[]` (`generators/types.ts`).
+  `generateClient` resolves the configured selection (default `['sdk']`) via `resolveGenerators` (`generators/resolve.ts`) into a name→descriptor registry, then runs them through `collectGeneratedFiles` and merges their files (duplicate output paths throw).
+  A selection entry is a built-in name, the `name` of an inline `customGenerators` entry, or a **plugin import specifier** (path or package, dynamically imported and validated).
+  This is the public, **experimental** extension point — authored with `defineGenerator` from `@redocly/client-generator`, which also re-exports the IR types and the codegen toolkit.
+  Where new capabilities (zod, framework hooks) plug in.
+  See [ADR-0004](./docs/adr/0004-registry-seams.md) and [ADR-0012](./docs/adr/0012-plugin-api.md).
+- **The `getWriter` seam** — `getWriter(outputMode)` maps an output mode to a `Writer`.
+  Two adapters: `single` (the whole client in one file) and `split` (schema types + type guards carved out into a sibling `<stem>.schemas.ts` the entry re-exports).
+  Both delegate to the shared wiring emitter (`emitClientSingleFile` / `emitClientSplit`); where a new file layout plugs in.
+  See [ADR-0004](./docs/adr/0004-registry-seams.md).
+- **The runtime seam** — the client engine is real TypeScript under `src/runtime/`, and the generated wiring (descriptors + `createClient` call + sugar) is identical for both distributions; only the runtime block differs.
+  `runtime: 'package'` emits an import of `createClient` from `@redocly/client-generator` (the barrel, `runtime/index.ts`, wires every capability); `runtime: 'inline'` (default) embeds the runtime sources in its place — a build step (`scripts/generate-runtime-sources.mjs`) snapshots `src/runtime/*.ts` into the tracked, generated `emitters/runtime-sources.ts` (drift-tested), and `emitters/inline-runtime.ts` walks the import graph in dependency order, strips module syntax via the TS AST, and appends a local `createClient` factory wiring **only** the capabilities the API needs.
+- **The capability seam** — `createClient` dispatches optional behaviors through a `Capabilities` object (`runtime/create-client.ts`): `serializeMultipart` (typed multipart bodies), `resolveAuth` (credential injection), `sse` (event streaming).
+  The core never statically imports them, so an inline client embeds only what its spec uses, and a package client gets the full set from the barrel.
+- **Error mode is config, not codegen** — `--error-mode` is baked into the client's initial config; the runtime's `execute` branches on it (throw `ApiError` vs return `Result`), and `configure()` ignores runtime attempts to flip it (the static types are fixed at generate time).
+  See [ADR-0005](./docs/adr/0005-error-mode-terminals.md) for the original decision (the terminals mechanism it describes is superseded).
+- **Response decoding is a runtime concern** — `runtime/parse.ts` decodes the body; the inferred kind comes from the operation descriptor's `responseKind` (a generate-time hint).
+  The per-call `RequestOptions.parseAs` overrides it (e.g. `'stream'` for the raw `ReadableStream`); the static return type is **not** narrowed by `parseAs`, keeping operation signatures stable.
+- **The SSE seam** — an operation whose 2xx response declares `text/event-stream` is a **derived response kind**, detected by `emitters/sse.ts` (`responseKind: 'sse'` on the descriptor) and surfaced as a typed async-generator client method plus the matching free function; the `sse` capability is wired only when a spec streams.
+- **The async-auth seam** — credentials are **per instance** (`ClientConfig.auth`), resolved per request by the `resolveAuth` capability (`runtime/auth.ts`); operations without declared `security` trigger no auth work.
+  The generated `set*` setters are instance-bound sugar over `client.auth.*`.
+  See [ADR-0007](./docs/adr/0007-call-site-auth.md) and [ADR-0009](./docs/adr/0009-per-instance-auth.md).
+
+## Configuration
+
+`generate-client` reads its options from a `client` block in `redocly.yaml`: top-level shared defaults plus per-API overrides under `apis.<name>.client`, with the input as `apis.<name>.root` and the output as `apis.<name>.clientOutput`. CLI flags layer over the config (top-level `client` → per-API `client` → flags).
+The extraction lives in the CLI command, not this package's core.
+See [ADR-0008](./docs/adr/0008-redocly-yaml-config.md).
+
+## What varies
+
+Three orthogonal knobs combine freely:
+
+- **Output mode** (`--output-mode`): `single` · `split` — file layout.
+- **Runtime** (`--runtime`): `inline` · `package` — where the client engine lives.
+- **Args style** (`--args-style`): `flat` · `grouped` — how inputs reach the free functions (the `client` instance's methods are always grouped).
+
+Plus **enum style** (`--enum-style`: `union` · `const-object`), **error mode** (`--error-mode`: `throw` · `result`), **date type** (`--date-type`: `string` · `Date`), and the `--server-url` / `--setup` modifiers.
+Every client exports **both call styles** — the instance and the free functions; args style only shapes the free-function sugar.
+
+Orthogonally, **`--generator`** selects which generators run (default `sdk`; plus `zod`, `tanstack-query`, `swr`, `transformers`, `mock`, and custom plugins), with per-generator knobs: `--query-framework` (`react` · `vue` · `svelte` · `solid`, for `tanstack-query`) and `--mock-data` (`baked` · `faker`) / `--mock-seed` (for `mock`).
+
+## Test architeture
+
+- **Unit tests** (`VITEST_SUITE=unit`) live in `__tests__/` beside source.
+  This package is held to **100% per-file coverage**.
+  The IR builder, ref collection, writers, and each emitter are tested directly through their interfaces, sharing `__tests__/fixtures.ts`; the emitters are largely covered by output-string assertions.
+- **E2E tests** (`VITEST_SUITE=e2e`, under `tests/e2e/generate-client/`) generate a client, type-check it under strict `tsc` (`--noUnusedLocals`), and — for behavioral cases — run it against a local mock server.
+- **The runtime** is real modules (`src/runtime/`) with direct unit tests; its end-to-end behavior (retry, abort, body serialization, query building, SSE reconnection) is also exercised through the e2e path, and a drift test keeps the generated `emitters/runtime-sources.ts` snapshot in lockstep with the sources.
+
+Tests run from a single root `vitest.config.ts`; there are no per-package vitest configs.
+Compile (`npm run compile`) before running tests — they run against built output.
+
+## How to add things
+
+- **A new output mode** — add the literal to `OutputMode` (`writers/types.ts`), write a `Writer` over the shared wiring emitter, and register it in the `WRITERS` map (`writers/index.ts`).
+  Wire the CLI choice in the `generate-client` command.
+- **A new schema kind** — add the variant to `SchemaModel` (`intermediate-representation/model.ts`), produce it in `intermediate-representation/build.ts`, and build its `ts.TypeNode` in `schemaToTypeNode` (`emitters/types.ts`).
+- **A new runtime capability** — add a module under `src/runtime/`, thread it through the `Capabilities` seam (`runtime/create-client.ts`), wire it in the barrel (`runtime/index.ts`), list it in `scripts/generate-runtime-sources.mjs`, and teach `emitters/inline-runtime.ts` when to embed it (a new `InlineRuntimeNeeds` flag).
+  Run `npm run compile` to regenerate the `runtime-sources.ts` snapshot.
+- **A new wrapper generator** (a framework adapter that forwards to the sdk functions) — reuse `emitters/wrapper-support.ts` for operation eligibility (SSE / `<Op>Variables`-collision skips) and the `vars`/`init` parameter shape, and derive the forwarding call's argument order and `<Op>Variables` naming from `operationSignature` (`emitters/operation-signature.ts`), the same source the sdk's parameter list uses, so the wrappers cannot drift.
+  Declare its compatibility contract (`requires`/`errorModes`/`dateTypes`/`runtimes`) in the generator registry (`generators/index.ts`).
+  See [ADR-0011](./docs/adr/0011-wrapper-generators.md).
+- **A new mock data source** — the `mock` generator's data comes from `emitters/sample.ts` (baked literals) or `emitters/faker.ts` (faker calls), selected by `--mock-data`; both walk the IR with the same cycle semantics.
+  See [ADR-0010](./docs/adr/0010-mock-data-baked-vs-faker.md).
+- **A custom generator (plugin, experimental)** — author `{ name, run }` with `defineGenerator` from the `@redocly/client-generator` entry (it also exports the IR types and the codegen toolkit); select it in `generators` by inline `customGenerators` name or by import specifier.
+  No core change is needed — `resolve.ts` loads and validates it.
+  See [ADR-0012](./docs/adr/0012-plugin-api.md).
+
+## Keep this current
+
+Update this file when the **pipeline** stages, the **seams**, or the **module map** change — not for routine feature work within an existing module.
+Keep it **descriptive**.
+When you make a significant, hard-to-reverse decision, record it as a new ADR in [`docs/adr/`](./docs/adr/) (don't rewrite an existing ADR — supersede it), and link the relevant seam here to it.
diff --git a/packages/client-generator/CONTEXT.md b/packages/client-generator/CONTEXT.md
new file mode 100644
index 0000000000..702d4501bd
--- /dev/null
+++ b/packages/client-generator/CONTEXT.md
@@ -0,0 +1,189 @@
+# Client Generator — Context
+
+The domain language of `@redocly/client-generator`: the package that turns an OpenAPI description into a typed, zero-dependency TypeScript client.
+Use these terms exactly — in code, comments, commits, and reviews — so the vocabulary stays consistent.
+For _how the pieces fit together_, see [ARCHITECTURE.md](./ARCHITECTURE.md).
+
+## Language
+
+### The model
+
+**IR** (Intermediate Representation):
+The spec-agnostic model the generator works against, produced from an OpenAPI document by `buildApiModel`.
+Everything downstream reads the IR, never the raw OpenAPI.
+The root node is the **ApiModel**.
+Inputs are accepted as OpenAPI 3.0/3.1/3.2 directly; **Swagger 2.0** is converted to the 3.x shape by `normalizeSwagger2` before `buildApiModel`, so the builder stays 3.x-only.
+_Avoid_: AST, schema graph, DOM.
+
+**ApiModel**:
+The root of the IR — title, version, base URL, services, schemas, security schemes.
+Has many **ServiceModel**s; each has many **OperationModel**s.
+_Avoid_: spec, document (those are the raw OpenAPI input).
+
+**SchemaModel**:
+A normalized type node in the IR — one of a fixed set of kinds (scalar, object, array, record, ref, literal, enum, union, intersection, null, unknown).
+The emitter turns it into a TypeScript type.
+_Avoid_: type, schema (unqualified "schema" means the raw OpenAPI schema, not this).
+
+**OperationModel**:
+One API operation in the IR — method, path, parameters (split into path/query/header), request body, success responses, **error responses** (`errorResponses`: the declared 4xx/5xx bodies, plus `default` when a 2xx success also exists — consumed only by `errorMode: 'result'` to type the result's `error`), security.
+Its `name` is the spec's `operationId`, or — when absent — a synthesized `<method><PascalCasePath>` made unique across the document (declared `operationId`s always win).
+Distinct from an **endpoint**, which is the _emitted_ function/file.
+_Avoid_: route, handler.
+
+**ResponseBodyModel** (`itemSchema`):
+A success/error response body in the IR — its `contentType`, the decoded `schema`, and (OpenAPI 3.2 only) an optional `itemSchema`: the per-item type of a streaming media type.
+For a `text/event-stream` response, `itemSchema` is the type of each event's `data` payload; the emitter prefers it over the response `schema` when typing **SSE** events.
+_Avoid_: streamSchema, eventSchema (in code identifiers — `itemSchema` mirrors the OpenAPI key).
+
+### Emission
+
+**Emitter**:
+Builds a TypeScript **AST** (`ts.factory` nodes) from the IR.
+Lives in `emitters/`.
+Each emitter is deep — one narrow entry point over hidden node-building bulk — and owns a single concern: `types.ts` (`typesStatements`/`schemaToTypeNode`), `type-guards.ts` (`typeGuardStatements`), `descriptor.ts` (the `OPERATIONS` descriptor map + the `Ops` type), `operation-aliases.ts`/`operation-types.ts` (the `<Op>*` aliases and their type builders), `sse.ts` (the **SSE** detection seam: `isSseOp`/`partitionOps`/`sseEventType`/`sseDataKind`), and `inline-runtime.ts` (the **inline assembler**).
+The foundation module `ts.ts` owns the shared printer and ergonomics: `printNodes` (nodes → source), `parseStatements` (parse hand-authored source into nodes), and `jsdoc` (attach a block comment).
+`package-client.ts` is the shared _wiring_ emitter: it assembles each file's content — identical for both runtimes except the runtime block (import vs embed) — and prints **once**, exposing `emitClientSingleFile` / `emitClientSplit`.
+Low-level text helpers (`pascalCase`, `splitLines`, `joinSections`) stay private in `support.ts`, and the JSDoc-body builder in `jsdoc.ts` — consumed only by the deep emitters, never by writers.
+_Avoid_: renderer, codegen.
+
+**Writer**:
+Chooses the _file layout_ from the IR and emit options, then fills each file by calling the emitter.
+Lives in `writers/`.
+One **Writer** per **output mode**, selected by `getWriter`.
+A Writer is an implementation detail of the `sdk` **Generator**.
+_Avoid_: formatter, builder.
+
+**Generator**:
+A deep module that turns the IR into a set of files for one concern, selected by name through `getGenerator(name)` (mirrors the `getWriter(outputMode)` seam).
+Lives in `generators/`.
+The `sdk` generator is the typed client (it delegates to the output-mode **Writer**).
+The `zod` generator emits a standalone `<stem>.zod.ts` **schema module** (one `export const <Name>Schema` per IR named schema) beside the client.
+The `tanstack-query` generator emits a TanStack Query v5 (React) module (`<stem>.tanstack.ts`) wrapping the sdk — per query op a `<op>QueryKey`/`<op>Options` (`queryOptions`) factory + query key, per mutation a `<op>Mutation` (`mutationKey`/`mutationFn`) factory (requires the `sdk` generator; the consumer installs `@tanstack/react-query`).
+The `transformers` generator emits a standalone `<stem>.transformers.ts` of `transform<Name>(data: <Name>): <Name>` functions — one per IR named schema that (recursively) carries a `date-time`/`date` field — that walk the value and rewrite wire ISO strings to `new Date(...)` in place, composing across refs (`transformPet` calls `transformOwner`); pair it with the **dateType** knob (`--date-type Date`) so the parsed value matches the type (it imports only the schema TYPES, so the client stays zero-dep).
+`generateClient` runs the configured generators (default `['sdk']`, selected via `--generator sdk --generator zod`) and merges their files.
+Custom generators are authored with `defineGenerator` and selected inline or by import specifier (the experimental **plugin** API, ADR-0012).
+_Avoid_: middleware (that's a runtime concept).
+
+**Schema module** (`zod` generator):
+The `<stem>.zod.ts` file the `zod` generator emits — `import { z } from 'zod'` plus one `export const <Name>Schema = z.object(…)` per IR named schema.
+Output-mode-agnostic in phase 1 (one module regardless of how the sdk partitions its files); refs become `z.lazy(() => …)`.
+Only the metadata refinements stable across zod `3.23 || 4` are emitted (`.min`/`.max`/`.int`/`.gt`/`.lt`/`.regex`); format methods (`.email`/`.uuid`/`.url`) are skipped.
+The generated **sdk** client never imports zod — `zod` is the _consumer's_ peer (`^3.23 || ^4`), installed only when validating (`PetSchema.parse(data)`) or deriving types (`z.infer<typeof PetSchema>`).
+_Avoid_: validation runtime, zod runtime (the sdk has no zod dependency).
+
+**Runtime**:
+The zero-dependency client engine — real TypeScript modules under `src/runtime/` (`send`, `url`, `parse`, `retry`, `errors`, `multipart`, `auth`, `setup`, `sse`, `create-client`), not emitter-built code.
+Uses only web-standard APIs.
+`createClient(operations, config)` builds a typed **instance client** over the operation descriptors: one bound method per operation plus the core members `configure` / `use` / `auth`; optional behaviors (multipart serialization, auth injection, SSE streaming) are dispatched through the **capability seam** (`Capabilities`, `runtime/create-client.ts`) and never statically imported by the core.
+Package mode imports the barrel (`runtime/index.ts`, all capabilities wired); inline mode embeds the same sources — snapshotted into the generated `emitters/runtime-sources.ts` and assembled per the API's needs by `emitters/inline-runtime.ts`, which appends a local `createClient` factory wiring only the needed capabilities.
+`parse` decodes a success body into the requested kind — `json` / `text` / `blob` / `arrayBuffer` / `formData` / `stream` (raw `ReadableStream` via `response.body`) / `auto` (content-type sniff, the default); the per-call `RequestOptions` (the trailing `init` arg) carries `parseAs?: ParseAs` — a runtime escape hatch that overrides the inferred decode kind (static return type unchanged) — alongside the `retry` override.
+**Error mode** lives in the instance config (fixed at generate time; `configure()` ignores attempts to flip it): throw mode throws `ApiError` on non-2xx, result mode returns the discriminated `Result<TData, TError>`.
+For **SSE** operations `runtime/sse.ts` provides `sse<T>` — an `async function*` that parses `text/event-stream` frames into `ServerSentEvent<T>` (`{ event?, data, id?, retry? }`) and auto-reconnects (resuming with `Last-Event-ID`; backoff = server `retry:` → `reconnectDelay` → 1000ms, exponential + jitter, 30s cap).
+`SseOptions` (`RequestInit & { reconnect?; reconnectDelay? }`) is the per-call init; aborting via `AbortSignal` or `break`ing the loop completes the iterator cleanly (no throw).
+The `sse` capability (and module, in inline mode) is **gated** — wired only when a model declares a streaming op.
+_Avoid_: helpers, lib, sdk-core.
+
+**SSE**:
+An operation whose 2xx response declares `text/event-stream` is an **SSE** operation.
+It is detection-driven — no flag — and marked `responseKind: 'sse'` on its descriptor: the client exposes it as a typed async-generator method (plus the matching free function) returning `AsyncGenerator<ServerSentEvent<T>>`, where `T` comes from the response **`itemSchema`** → media `schema` → `string`.
+SSE ops are error-mode-agnostic (they always throw on an initial non-2xx; never return the `Result` shape).
+_Avoid_: sse namespace (removed), stream namespace, events client, subscribe.
+
+**Descriptor** / **Wiring** / **Sugar**:
+The **descriptor** (`OperationDescriptor`) is the frozen data contract between generated code and the runtime — one operation's wire shape (`id`, `method`, `path`, `params`, `body`, `responseKind`, `security`), emitted into the `OPERATIONS` map (`as const satisfies Record<string, OperationDescriptor>`, which doubles as the version-skew guard in package mode).
+The **wiring** is the generated glue around it: schema types, `<Op>*` aliases, the `Ops` type, `OPERATIONS`, and the `export const client = createClient<Ops>(OPERATIONS, …)` instance — identical across both runtimes.
+The **sugar** is the derived conveniences bound to that instance: `export const { configure, use } = client`, the free-function operations (arrow consts in `flat` style, a destructure in `grouped`), and the auth setters (`export const setBearer = client.auth.bearer`).
+_Avoid_: fragments, ClientModules, barrel, endpoints (pre-runtime-module vocabulary).
+
+**Entry file** / **Schemas module**:
+The **entry file** is the `--output` file — the whole client in `single` mode; in `split` mode the **schemas module** (`<stem>.schemas.ts`: schema types, enums, const-objects, type guards) is carved out and the entry `export *`s it.
+_Avoid_: index, barrel.
+
+### Knobs
+
+**Output mode**:
+The file layout: `single` (one file) or `split` (the schemas module in a sibling `<stem>.schemas.ts` the entry re-exports).
+Selected by `--output-mode`; works with both **runtime** distributions.
+_Avoid_: format, layout (in prose), split (as a synonym for the whole concept), tags / tags-split (removed modes).
+
+**Runtime distribution** (`runtime` knob):
+Where the client engine lives: `inline` (default — the runtime sources embedded in the generated output, zero dependencies) or `package` (the generated file imports it from `@redocly/client-generator`, so engine fixes arrive via `npm update`).
+Selected by `--runtime`; the generated wiring and the app-facing surface are identical in both.
+_Avoid_: facade (removed knob — every client exports both the instance and the free functions), embedded mode (say inline).
+
+**Args style**:
+How an operation's inputs are passed: `flat` (path params then `params`/`body`/`headers` slots) or `grouped` (one **Variables** object).
+Selected by `--args-style`.
+_Avoid_: param style, calling convention.
+
+**Error mode**:
+The client's error-handling shape: `throw` (default — operations throw `ApiError` on non-2xx) or `result` (operations return a discriminated `Result<TData, TError>` = `{ data, error, response }`, with `error` typed from the spec's 4xx/5xx response bodies as the `<Op>Error` union).
+Selected by `--error-mode`.
+Transport/abort failures still throw in both modes; `onError` is a throw-mode hook.
+_Avoid_: throwOnError, errorHandling, result shape (in code identifiers).
+
+**dateType**:
+How `format: date-time`/`date` string fields are typed: `string` (default — byte-identical to the ISO wire shape) or `Date`.
+Selected by `--date-type`.
+Under `Date` the sdk emits `Date` for those scalar `string` schemas; the runtime conversion is opt-in and separate — pair it with the **`transformers` generator** (`--generator sdk --generator transformers`) so the parsed value matches the type.
+`int64` → `bigint` is deferred to a follow-up.
+_Avoid_: dateMode, parseDates (in code identifiers).
+
+**Variables** (`<Op>Variables`):
+The combined-inputs object type for an operation — path params + `params` + `body` + `headers`.
+It is the `vars` argument under `args-style grouped`, and the seam wrappers (React Query / SWR) consume it.
+_Avoid_: args, params, inputs (those mean narrower things — see below).
+
+**Params**:
+Query parameters, specifically.
+In a generated operation, `params` is always the query object; it never means "arguments in general".
+_Avoid_: arguments, inputs, query-string (in code identifiers).
+
+**Query serialization style**:
+How a query param's value is rendered onto the wire.
+The OpenAPI default is `form` + `explode: true` (arrays repeat the key; objects become `key[sub]=val`).
+`ParamModel` carries the spec's `style` / `explode` / `allowReserved` **only for query params**, and **only when present** — absence means the default, so the IR stays clean.
+The operation **descriptor** carries the hints the same way (only when the param deviates from the defaults); the runtime resolves them per request (`queryStyles`) and `buildUrl` (`runtime/url.ts`) serializes.
+`buildUrl` honors `form`+`explode:false` (`key=a,b`), `spaceDelimited` (`key=a%20b`), `pipeDelimited` (`key=a|b`) — literal delimiters, values encoded — and `deepObject` (the bracket form); `allowReserved` skips percent-encoding of RFC-3986 reserved chars (via `encodeReserved`).
+Known deviation: an **object** query param at the default `form` style still serializes as `key[sub]=val` (deepObject brackets), not the spec's `sub=val` spread.
+
+**Injectable security scheme**:
+A security scheme the **runtime** can auto-apply from the instance's credentials (`ClientConfig.auth`) — HTTP `bearer`, HTTP `basic`, and `apiKey` in header / query / cookie.
+OAuth2 / OpenID Connect normalize to `bearer`.
+Only `mutualTLS` is skipped.
+The generated setters (`setBearer`, `setBasicAuth`, `setApiKey…`) are instance-bound sugar over `client.auth.*`.
+Bearer/apiKey credentials are a **`TokenProvider`** — a string or a (possibly async) function `() => string | Promise<string>`, resolved per request.
+`resolveAuth` (`runtime/auth.ts`, the auth **capability**) is **async**, returning `{ headers, query }`; query-auth merges into the URL, cookie-auth folds into a combined `Cookie` header.
+_Avoid_: auth (unqualified), credential, global setters (credentials are per instance).
+
+## Flagged ambiguities
+
+**"module"** — two senses, keep them straight:
+
+- _Architecture sense_ (interface + implementation) — used when discussing depth/seams (e.g. the `src/runtime/` modules).
+- _Emitted-file sense_ — the entry file and (in `split` mode) the schemas module a client is split into.
+
+**`params` vs `Variables` vs `args style`** — easy to conflate:
+
+- `params` = the query object only.
+- `Variables` = the _whole_ combined-inputs object (path + params + body + headers).
+- `args style` = the _choice_ of how inputs reach the function (positional vs object).
+
+**operation vs endpoint** — `operation` is the IR/spec concept (an `OperationModel`); `endpoints` is the emitted code that realizes operations.
+
+## Example dialogue
+
+> **Dev:** I want the generated calls to take one object instead of positional args.
+>
+> **Maintainer:** That's the `grouped` **args style**. It bundles each operation's inputs
+> into its **Variables** type — so a call becomes `getPet({ id, params })` where `params`
+> is still the query object. The `client` instance's methods are always grouped;
+> **args style** only shapes the free-function **sugar**.
+>
+> **Dev:** Does that change the rest of the file?
+>
+> **Maintainer:** No. The **descriptors**, the **wiring**, and the embedded **runtime**
+> are byte-identical across args styles — in `flat` the sugar is per-operation arrow
+> consts, in `grouped` it's a destructure from the instance. The **writer** just lays
+> the same emitted content out per the **output mode**.
diff --git a/packages/client-generator/README.md b/packages/client-generator/README.md
new file mode 100644
index 0000000000..be41f4ae20
--- /dev/null
+++ b/packages/client-generator/README.md
@@ -0,0 +1,179 @@
+# @redocly/client-generator
+
+Generate a typed TypeScript client from an OpenAPI description.
+See https://github.com/Redocly/redocly-cli for the full project.
+
+> [!WARNING]
+> This package is experimental: the generated output, options, and the plugin API may change in any minor release until it is declared stable (see [ADR-0013](./docs/adr/0013-experimental-status.md)).
+> Pin your version if you depend on the output, and expect to regenerate when you upgrade.
+> Feedback is very welcome while we stabilize it.
+
+The generated client uses only web-standard APIs (`fetch`, `AbortController`, `URLSearchParams`), so by default it is a single self-contained file with zero runtime dependencies that runs in browsers, Node ≥ 18, Bun, Deno, and edge runtimes.
+(Running the generator itself requires the Node version in this package's `engines` field.)
+Code is produced through the TypeScript compiler AST, not string templates; `typescript` is the only peer dependency.
+
+This package is the engine behind the [`generate-client` command](https://redocly.com/docs/cli/commands/generate-client) — install [`@redocly/cli`](https://www.npmjs.com/package/@redocly/cli) to run it from the command line or `redocly.yaml`.
+How to use the generated client — auth, middleware, retries, pagination, Server-Sent Events, and the add-on generators (`zod`, `tanstack-query`, `swr`, `mock`, `transformers`) — is documented in [Use the generated client](https://redocly.com/docs/cli/guides/use-generated-client).
+This README covers using the package programmatically.
+
+## Basic usage
+
+### Generate a client
+
+```ts
+import { generateClient } from '@redocly/client-generator';
+
+const result = await generateClient({
+  api: './openapi.yaml', // file path or URL; OpenAPI 3.0/3.1/3.2 or Swagger 2.0
+  output: './src/api/client.ts',
+  generators: ['sdk', 'zod'],
+});
+
+console.log(`Wrote ${result.files.length} file(s), ${result.bytes} bytes.`);
+```
+
+Every `redocly.yaml` `client` option is accepted with the same name and default — see the [`client` configuration reference](https://redocly.com/docs/cli/configuration/reference/client).
+For type-safe authoring of a standalone options object, annotate it with `satisfies Config`.
+
+### Build extra client instances
+
+The generated module exports its operation descriptors, so an app can build additional instances with independent configuration and credentials over the same generated code:
+
+```ts
+import { createClient } from '@redocly/client-generator';
+import { OPERATIONS, type Ops } from './client.ts';
+
+const internal = createClient<Ops>(OPERATIONS, {
+  serverUrl: 'https://api.example.com',
+  auth: { basic: { username: 'svc', password: 's3cr3t' } },
+});
+```
+
+With `runtime: 'package'` the generated client also imports its whole engine from this package (instead of embedding it), so engine fixes arrive via `npm update` — install this package as a regular dependency of the consuming app.
+
+### Write a custom generator
+
+A custom generator reads the same spec-derived model the built-ins consume, runs in the same pass, and returns files:
+
+```ts
+// route-map-generator.ts
+import { defineGenerator } from '@redocly/client-generator';
+
+export default defineGenerator({
+  name: 'route-map',
+  requires: ['sdk'],
+  run({ model, outputPath }) {
+    const routes = model.services
+      .flatMap((service) => service.operations)
+      .map((op) => `  ${op.name}: '${op.method.toUpperCase()} ${op.path}',`)
+      .join('\n');
+    return [
+      {
+        path: outputPath.replace(/\.ts$/, '.routes.ts'),
+        content: `export const routes = {\n${routes}\n} as const;\n`,
+      },
+    ];
+  },
+});
+```
+
+Select it in `generators` by import specifier (a path or a package name), or register it inline via `customGenerators` and select it by `name`.
+A custom generator never adds dependencies to the generated client.
+
+### Bake defaults into a published SDK
+
+The `setup` option takes a module that default-exports `defineClientSetup({ config, middleware })`; its defaults are baked into the generated client so a published SDK ships them built in, and consumers can still override.
+See [Publisher defaults](https://redocly.com/docs/cli/guides/use-generated-client#publisher-defaults).
+
+## API
+
+### `generateClient`
+
+Loads the spec, builds the client, and writes the files.
+
+```ts
+async function generateClient(options: GenerateClientOptions): Promise<GenerateClientResult>;
+
+type GenerateClientResult = {
+  outputPath: string; // the `output` anchor path (the entry file in multi-file modes)
+  bytes: number; // total bytes written
+  files: Array<{ path: string; bytes: number }>; // every file written to disk
+};
+```
+
+`GenerateClientOptions` is the [`Config` type](./src/config.ts) (`api` and `output` required; `outputMode`, `runtime`, `argsStyle`, `errorMode`, `dateType`, `enumStyle`, `serverUrl`, `queryFramework`, `mockData`, `mockSeed`, `generators`, `customGenerators`, `setup`, `pagination` optional) plus an optional resolved Redocly `config` used for spec loading.
+
+### `collectGeneratedFiles`
+
+Runs the configured generators against a built model and returns the files in memory, without writing to disk.
+Imported from `@redocly/client-generator/codegen` — the codegen entry; the package root stays runtime-only so package-mode clients never load the generator stack:
+
+```ts
+function collectGeneratedFiles(
+  model: ApiModel,
+  options: {
+    outputPath: string;
+    outputMode: OutputMode;
+    emit: EmitOptions;
+    generators: string[];
+    registry?: Map<string, GeneratorDescriptor>; // defaults to the built-ins
+  }
+): GeneratedFile[];
+```
+
+### `defineGenerator`
+
+Authors a custom generator (`{ name, run }` plus optional `requires`/`errorModes`/`dateTypes`/`runtimes` compatibility metadata, validated up front):
+
+```ts
+function defineGenerator(generator: CustomGenerator): CustomGenerator;
+```
+
+The `@redocly/client-generator/codegen` entry also exports the codegen toolkit the built-ins use (`ts`, `printStatements`, `parseStatements`, `operationSignature`, `schemaToTypeNode`, `pascalCase`, …), and the package root exports the IR types, so a custom generator emits TypeScript exactly as the first-party ones do.
+
+### `defineClientSetup`
+
+Authors a publisher setup module for the `setup` option:
+
+```ts
+function defineClientSetup(setup: {
+  config?: ClientConfig;
+  middleware?: Middleware[];
+}): ClientSetup;
+```
+
+A setup module may import only from `@redocly/client-generator`, so it never adds a dependency to the client.
+
+### `createClient`
+
+The runtime factory that `runtime: 'package'` clients import, also usable directly to build extra instances over generated descriptors (see [Basic usage](#build-extra-client-instances)):
+
+```ts
+function createClient<Ops>(
+  operations: Record<string, OperationDescriptor>,
+  config?: ClientConfig
+): Client<Ops>;
+```
+
+## Examples
+
+Runnable examples — from a zero-install quickstart to middleware, baked setup, SSE streaming, pagination, custom generators, and the package runtime — live in [`tests/e2e/generate-client/examples`](https://github.com/Redocly/redocly-cli/tree/main/tests/e2e/generate-client/examples).
+Each is a standalone Vite app with a checked-in, drift-checked generated client.
+
+## Documentation
+
+- [`generate-client` command reference](https://redocly.com/docs/cli/commands/generate-client) — CLI usage, flags, and `redocly.yaml` configuration.
+- [Use the generated client](https://redocly.com/docs/cli/guides/use-generated-client) — the runtime API and the add-on generators.
+- [`ARCHITECTURE.md`](./ARCHITECTURE.md) and the [ADRs](./docs/adr/) — how the package is built and why.
+
+## Development
+
+This package is part of the Redocly CLI monorepo. Run all commands from the repo root:
+
+```sh
+npm run compile                 # build this package
+npm run unit                    # unit tests (this package is held at 100% coverage)
+VITEST_SUITE=e2e npx vitest run tests/e2e/generate-client/   # behavioral e2e
+```
+
+The client runtime lives in `src/runtime/` (real, unit-testable modules; package mode imports them, inline mode embeds them), the structural emitters in `src/emitters/`, the IR in `src/intermediate-representation/`, the generators in `src/generators/`, and the file-layout writers in `src/writers/`.
diff --git a/packages/client-generator/docs/adr/0001-ast-codegen.md b/packages/client-generator/docs/adr/0001-ast-codegen.md
new file mode 100644
index 0000000000..34f4825a3c
--- /dev/null
+++ b/packages/client-generator/docs/adr/0001-ast-codegen.md
@@ -0,0 +1,22 @@
+# ADR 0001: Generate TypeScript via the TS AST (`ts.factory`), not strings
+
+- Status: Accepted
+- Date: 2026-06-10
+
+## Context
+
+The generator must emit TypeScript across a growing matrix of options — output modes, facades, args-styles, error modes, auth breadth, `parseAs`, and a set of feature generators (zod, TanStack Query, transformers, SSE).
+String-template codegen makes the cross-cutting concerns (escaping, import/name coordination, indentation, dedup) brittle: every new axis multiplies the places a template can produce malformed or mis-formatted output.
+
+## Decision
+
+We build generated code as a **TypeScript AST** using `ts.factory` and emit it with the compiler's own printer (`ts.createPrinter`).
+A foundation module (`emitters/ts.ts`) wraps the ergonomics: a shared printer, `printNodes`, `parseStatements` (to embed hand-authored reference source — notably the runtime — as parsed nodes), and `jsdoc`.
+Each emitter returns `ts.Statement[]` / `ts.TypeNode`s; the composition (`client.ts`) assembles a per-file statement list and prints once.
+
+## Consequences
+
+- Structurally malformed output (mismatched braces, wrong nesting) is impossible; passes can compose/transform/dedupe nodes before printing; the option matrix scales without brittle template edits.
+- **The AST is not a sanitizer.** `ts.factory.createIdentifier` prints its text verbatim and synthetic comments are emitted as written — so a spec-supplied name or description still reaches the output unchecked. Those two channels are closed _before_ the printer, not by it: names are coerced to safe identifiers in the IR (`intermediate-representation/sanitize-identifiers.ts`, with an assert backstop) and all comment text is run through `escapeJsDoc` (`emitters/ts.ts`). Treat any new value that flows into an identifier slot or a comment as requiring the same handling.
+- Output formatting is the printer's (valid, but plainer than hand-formatting) — a pretty-print pass is deferred to optional-formatter work.
+- The cost is a dependency on `typescript` at generation time (see [ADR-0002](./0002-typescript-peer-dep.md)), and emitter code is more verbose than templates for trivial snippets — accepted for the correctness and composability gains.
diff --git a/packages/client-generator/docs/adr/0002-typescript-peer-dep.md b/packages/client-generator/docs/adr/0002-typescript-peer-dep.md
new file mode 100644
index 0000000000..c997b24929
--- /dev/null
+++ b/packages/client-generator/docs/adr/0002-typescript-peer-dep.md
@@ -0,0 +1,22 @@
+# ADR 0002: `typescript` as a peer dependency; zero-runtime-dependency output
+
+- Status: Accepted
+- Date: 2026-06-10
+
+## Context
+
+[ADR-0001](./0001-ast-codegen.md) makes `typescript` (for `ts.factory` + `ts.createPrinter`) a generation-time requirement.
+We must decide how the package depends on it without (a) bloating installs for consumers who already have `typescript`, or (b) compromising the headline property that the **generated client has no runtime dependencies**.
+
+## Decision
+
+We declare `typescript` (`>=5.5.0`) as a **`peerDependency`** of `@redocly/client-generator`.
+The only real runtime `dependency` is `@redocly/openapi-core` (the input/document side).
+Package-in-code consumers (`import { generateClient }`) already have `typescript`; `@redocly/cli` declares it as a real `dependency` so the CLI works standalone (and transitively satisfies the peer).
+The codegen uses only stable `factory` / `createPrinter` / `createSourceFile` / `SyntaxKind` APIs, so the wide peer range is safe.
+
+## Consequences
+
+- `typescript` is used **only at generation time** and never emitted, so the generated client stays dependency-free (web-standard APIs only: `fetch`, `AbortController`, `URLSearchParams`) and runs in browsers, Node, Bun, Deno, and edge runtimes.
+- `@redocly/openapi-core` must **not** grow a TS code-builder — its `yaml-ast-parser` is the input AST, not an output one.
+- Consumers in unusual setups may need to add `typescript` explicitly; the wide peer range keeps this rare.
diff --git a/packages/client-generator/docs/adr/0003-spec-agnostic-ir.md b/packages/client-generator/docs/adr/0003-spec-agnostic-ir.md
new file mode 100644
index 0000000000..ac1021699b
--- /dev/null
+++ b/packages/client-generator/docs/adr/0003-spec-agnostic-ir.md
@@ -0,0 +1,22 @@
+# ADR 0003: A spec-agnostic IR as the builder↔emitter contract
+
+- Status: Accepted
+- Date: 2026-06-10
+
+## Context
+
+The generator must support multiple input dialects (OpenAPI 3.0/3.1/3.2 and Swagger 2.0) and multiple output shapes.
+If emitters read the raw OpenAPI document directly, every emitter would have to handle every spec quirk and version difference, and adding a dialect or an output target would ripple across the whole codebase.
+
+## Decision
+
+We interpose a **spec-agnostic intermediate representation** (`intermediate-representation/model.ts`) between parsing and emission.
+`buildApiModel` (`intermediate-representation/build.ts`) walks the (bundled, ref-preserved) document once and produces the IR; Swagger 2.0 is first normalized to the 3.x shape (`intermediate-representation/normalize-swagger2.ts`) so the builder sees one shape.
+**Everything downstream reads the IR, never the raw spec.**
+The IR is a pure type model — no runtime code — and is the contract between the builder and the emitters.
+
+## Consequences
+
+- A new input dialect is absorbed in one place (normalize + build); emitters are untouched.
+- A new output target (e.g. another language) can be written against the IR without re-parsing specs — the IR is the seam that makes multi-language plausible.
+- The IR must stay genuinely spec-agnostic; leaking OpenAPI-isms into it would erode the boundary. New schema kinds are added to `SchemaModel` and produced in the builder, then consumed by emitters.
diff --git a/packages/client-generator/docs/adr/0004-registry-seams.md b/packages/client-generator/docs/adr/0004-registry-seams.md
new file mode 100644
index 0000000000..4dc4c562d0
--- /dev/null
+++ b/packages/client-generator/docs/adr/0004-registry-seams.md
@@ -0,0 +1,24 @@
+# ADR 0004: First-party `getGenerator` / `getWriter` registry seams
+
+- Status: Accepted
+- Date: 2026-06-10
+
+## Context
+
+The package needs to vary two things independently: **what** is generated (the SDK, plus optional feature outputs like zod schemas or framework hooks) and **how** files are laid out (single file, split, per-tag, …).
+We want these to be extensible internally without committing — yet — to a public plugin API and its long-term compatibility surface.
+
+## Decision
+
+We expose two internal **registry seams**, each mapping a name to an implementation:
+
+- **`getGenerator(name)`** → `Generator` (`(input) => GeneratedFile[]`). `generateClient` runs the configured generators (default `['sdk']`), merging their files (duplicate output paths throw). New capabilities (zod, tanstack-query, transformers, …) plug in here. The `sdk` generator delegates to the writer seam below.
+- **`getWriter(outputMode)`** → `Writer`. Adapters for `single` / `split` / `tags` / `tags-split` (the two tag layouts share `buildTaggedClient`). New file layouts plug in here.
+
+Both are **first-party only** — no public third-party plugin API yet.
+
+## Consequences
+
+- New generators and layouts are added by registering an implementation, not by editing call sites.
+- Writers consume the emitter only through the `emitModules(...) → ClientModules` seam, so they stay layout-only and the emitter's internal fragment breakdown never leaks.
+- Deferring a public plugin API keeps us free to change `Generator`/`Writer` internals; third-party extensibility is a deliberate later step, revisited once the first-party set stabilizes.
diff --git a/packages/client-generator/docs/adr/0005-error-mode-terminals.md b/packages/client-generator/docs/adr/0005-error-mode-terminals.md
new file mode 100644
index 0000000000..a02e6d9f47
--- /dev/null
+++ b/packages/client-generator/docs/adr/0005-error-mode-terminals.md
@@ -0,0 +1,28 @@
+# ADR 0005: Error handling as a generate-time mode (throw vs result)
+
+> **Note (2026-07):** The terminals mechanism described here (`__send`/`__request`/`__requestResult`, `renderRuntime`) is superseded by the runtime-module architecture — error mode is still fixed at generate time, but the runtime's `execute` now branches on the instance config; see [ADR-0017](./0017-runtime-module-and-descriptor-client.md).
+
+- Status: Accepted
+- Date: 2026-06-10
+
+## Context
+
+Consumers want different error-handling ergonomics: some prefer exceptions, others prefer a discriminated `{ data, error }` result they must inspect.
+Encoding this **per call** (à la a `throwOnError` flag) forces conditional-return overloads and complicates every operation signature.
+A codebase generally picks one convention anyway.
+
+## Decision
+
+Error handling is a **generate-time mode** (`--error-mode throw | result`, default `throw`).
+The fetch wrapper is factored into a shared core plus one of two terminals:
+
+- `__send` — payload/header build + the retry/fetch loop → a raw `Response`; `__parse` — success-body decode.
+- `__request` (**throw** mode — throws `ApiError` on non-2xx) **or** `__requestResult` (**result** mode — returns `Result<TData, TError>`).
+
+`renderRuntime(..., errorMode)` emits **only** the chosen terminal (so `noUnusedLocals` stays clean); `renderOperationsBlock(..., { errorMode })` emits matching call sites and the `<Op>Error` aliases.
+
+## Consequences
+
+- Operation signatures stay simple — no per-call conditional overloads; the mode is uniform across the client.
+- Throw mode is byte-identical to the pre-extraction behavior; result mode reuses the same `__send` core, so retry/abort/auth/decoding logic lives in one place.
+- Switching conventions requires regeneration (acceptable — it's a project-level choice, not a per-call one).
diff --git a/packages/client-generator/docs/adr/0006-sse-namespace.md b/packages/client-generator/docs/adr/0006-sse-namespace.md
new file mode 100644
index 0000000000..8bc6628c11
--- /dev/null
+++ b/packages/client-generator/docs/adr/0006-sse-namespace.md
@@ -0,0 +1,25 @@
+# ADR 0006: SSE as a derived response kind under an `sse.*` namespace
+
+> **Note (2026-07):** Superseded by [ADR-0017](./0017-runtime-module-and-descriptor-client.md) — the `sse.*` namespace is removed; SSE operations are now flat async-generator client methods/functions wired through the runtime's `sse` capability.
+
+- Status: Accepted
+- Date: 2026-06-10
+
+## Context
+
+Some operations stream Server-Sent Events (`text/event-stream`).
+These don't fit the one-shot request/response shape: they return an async iterator of typed events, need reconnection (`Last-Event-ID` + backoff), and are errorMode-agnostic.
+We must surface them without complicating ordinary operations or the default output.
+
+## Decision
+
+SSE is a **derived response kind**, detected (not flagged) by `emitters/sse.ts` (`isSseOp`/`partitionOps`): an operation whose 2xx response declares `text/event-stream` is emitted under a separate **`sse` namespace** instead of as a plain endpoint.
+The runtime gains a **gated** `__sse<T>` generator — an `async function*` that **reuses `__send`** for the initial request + retry/auth, then parses event frames and auto-reconnects via `Last-Event-ID`.
+The event payload type `T` comes from the response `itemSchema` → media `schema` → `string`.
+`client.ts` partitions each service's ops and exposes the SSE ones under `sse` (functions: `export const sse = { … }`; service-class: a bound `readonly sse = { … }`); in multi-file modes each tag/class contributes a `__sse_<Class>` fragment that the barrel merges.
+
+## Consequences
+
+- Streaming ops get an ergonomic, typed async-iterator surface without touching ordinary operations.
+- The whole `__sse`/`ServerSentEvent`/`SseOptions` block is **gated off** when no op streams, so non-SSE clients are byte-identical (no churn).
+- SSE bypasses the error-mode terminals ([ADR-0005](./0005-error-mode-terminals.md)) by design — it has no `Result` form.
diff --git a/packages/client-generator/docs/adr/0007-call-site-auth.md b/packages/client-generator/docs/adr/0007-call-site-auth.md
new file mode 100644
index 0000000000..b881cd0ff2
--- /dev/null
+++ b/packages/client-generator/docs/adr/0007-call-site-auth.md
@@ -0,0 +1,24 @@
+# ADR 0007: Auth resolved at the call site via async `__auth`
+
+> **Note (2026-07):** Superseded by [ADR-0017](./0017-runtime-module-and-descriptor-client.md) — the module-global credential slots and emitted `__auth` call sites are gone; credentials are per instance (`ClientConfig.auth`) and resolved by the runtime's `resolveAuth` capability.
+
+- Status: Accepted (extended by [ADR-0009](./0009-per-instance-auth.md))
+- Date: 2026-06-10
+
+## Context
+
+Security schemes vary (HTTP bearer/basic, apiKey in header/query/cookie) and credentials may be async (a token provider returning a `Promise`).
+We want all of this handled without bloating the shared runtime with auth branching, and without emitting auth code into operations that don't need it.
+
+## Decision
+
+Credentials are resolved **at the call site**, not inside the runtime fetch wrapper.
+`renderAuth` (`emitters/auth.ts`) emits module-scoped credential slots, the `set*` setters (accepting a `TokenProvider` = value-or-`(() => string | Promise<string>)` for bearer/apiKey; `setBasicAuth` stays sync), and an **async** `__auth(schemes): Promise<{ headers, query }>` that awaits each resolvable credential.
+Every authed operation emits `const __a = await __auth([...])`, spreads `...__a.headers`, and (for `apiKeyQuery` keys, threaded via `queryAuthKeys`) merges `...__a.query` into the URL builder.
+Non-authed operations emit **no** auth code at all.
+
+## Consequences
+
+- All auth — header/query/cookie, sync/async — lives in one place next to URL building, with zero churn to the runtime fetch wrapper.
+- Operations pay only for the auth they use; unauthenticated ops stay clean.
+- Auth resolution is per-call (awaited each request), which is the correct behavior for rotating/async tokens; the small overhead is acceptable.
diff --git a/packages/client-generator/docs/adr/0008-redocly-yaml-config.md b/packages/client-generator/docs/adr/0008-redocly-yaml-config.md
new file mode 100644
index 0000000000..6c4d931da0
--- /dev/null
+++ b/packages/client-generator/docs/adr/0008-redocly-yaml-config.md
@@ -0,0 +1,26 @@
+# ADR 0008: `generate-client` config via `redocly.yaml` `x-client-generator`
+
+- Status: Superseded by ADR-0019 — the `x-client-generator` extension and the `*.config.ts` /
+  `--config-file` layer were replaced by a first-class `client` block (top-level shared
+  defaults + per-API `apis.<name>.client`) with the output at `apis.<name>.clientOutput`.
+- Date: 2026-06-10
+
+## Context
+
+`generate-client` settings could live in a dedicated `defineConfig` file (`*.config.ts`), but Redocly users expect a single project config — `redocly.yaml`.
+First-class config keys belong in the `@redocly/config` package (a separate repo), which doesn't model client-gen settings yet.
+We want redocly.yaml-driven generation **now**, without blocking on that release.
+
+## Decision
+
+`generate-client` reads its options from an **`x-client-generator` extension block** in `redocly.yaml`.
+The `x-` prefix is the tolerated-extension convention, so no `@redocly/config` schema change is needed — and `@redocly/openapi-core` already preserves the block verbatim in `config.resolvedConfig`.
+The CLI extracts it, resolving relative `input`/`output` against the redocly.yaml directory.
+Precedence, low → high: **`redocly.yaml` block → `--config-file` (the `*.config.ts`, retained) → CLI flags**.
+Examples ship a `redocly.yaml` and run `redocly generate-client` with no flags.
+
+## Consequences
+
+- One project config; `redocly generate-client` works with no flags by auto-discovering `redocly.yaml`.
+- No core/`@redocly/config` change required yet; when first-class keys land, the `x-` block can be swapped for typed fields (a future ADR will supersede this).
+- The dedicated `*.config.ts` path stays available (via `--config-file`) for configs outside the project or in nested folders.
diff --git a/packages/client-generator/docs/adr/0009-per-instance-auth.md b/packages/client-generator/docs/adr/0009-per-instance-auth.md
new file mode 100644
index 0000000000..0f7ad25669
--- /dev/null
+++ b/packages/client-generator/docs/adr/0009-per-instance-auth.md
@@ -0,0 +1,27 @@
+# ADR 0009: Per-instance auth via `ClientConfig.auth`
+
+> **Note (2026-07):** The decision (per-instance `ClientConfig.auth`) stands, but the mechanism text is superseded by the runtime-module architecture — the module-global setter slots and `__auth` are gone; the generated `set*` setters are now sugar over `client.auth.*`; see [ADR-0017](./0017-runtime-module-and-descriptor-client.md).
+
+- Status: Accepted
+- Date: 2026-06-10
+
+## Context
+
+[ADR-0007](./0007-call-site-auth.md) resolves credentials at the call site, but from **module-global** slots (`setBearer`/`setBasicAuth`/`setApiKey*`).
+The `service-class` facade exists to run **multiple independent client instances** — yet global auth means every instance of a generated module shares one credential.
+Real adoption hit this: two clients of the _same_ generated module needing different HTTP Basic credentials (e.g. an internal vs. a public syncer client), which the globals cannot represent.
+The workaround — injecting `Authorization` via per-instance `config.headers` — bypasses the spec's per-operation `security`, sending the header even to endpoints that don't declare it.
+
+## Decision
+
+Add an optional **`auth?: AuthCredentials`** to `ClientConfig`, carrying per-instance credentials, and thread the config into the resolver: `__auth(schemes, config)`.
+Each scheme resolves from `config.auth?.<scheme> ?? <global slot>` — the per-instance value wins, the global setters remain the fallback.
+`AuthCredentials` mirrors the schemes the spec declares: `{ bearer?: TokenProvider; basic?: { username; password }; apiKey?: Record<string, TokenProvider> }`.
+It is emitted only when the client has injectable schemes (so non-auth clients are byte-identical), and works for both facades (the functions facade sets it once via `configure({ auth })`).
+
+## Consequences
+
+- The service-class facade can finally run independent instances with independent credentials — its reason to exist.
+- **Backward compatible:** the global setters are unchanged and remain the fallback; the functions facade is unchanged unless `auth` is set.
+- Unlike the header workaround, it still honors each operation's declared `security` (only declared schemes are sent).
+- **Extends** ADR-0007 rather than superseding it — credentials are still resolved at the call site; the source is now "config-then-global" instead of "global only".
diff --git a/packages/client-generator/docs/adr/0010-mock-data-baked-vs-faker.md b/packages/client-generator/docs/adr/0010-mock-data-baked-vs-faker.md
new file mode 100644
index 0000000000..bac2a0daf9
--- /dev/null
+++ b/packages/client-generator/docs/adr/0010-mock-data-baked-vs-faker.md
@@ -0,0 +1,32 @@
+# ADR 0010: Mock data — baked literals by default, faker opt-in
+
+- Status: Accepted
+- Date: 2026-06-13
+
+## Context
+
+The `mock` generator emits [MSW](https://mswjs.io) request handlers plus `create<Schema>` data factories.
+Those factories need values to return.
+Two sources are reasonable, and they pull in opposite directions:
+
+- **Baked literals** — deterministic values synthesized from the schema (preferring `example` / `default`). Zero runtime dependency, reproducible by construction, but unrealistic ("string", `0`, the same UUID every time).
+- **[`@faker-js/faker`](https://fakerjs.dev) calls** — realistic, varied data (names, emails, dates), at the cost of a dependency and (without a seed) non-determinism.
+
+A mock generator that hard-codes either choice is wrong for half its users: test suites want deterministic zero-dep fixtures; demos and Storybook want realistic data.
+The core constraint is that the generated **client stays dependency-free** ([ADR-0002](./0002-typescript-peer-dep.md)) — whatever mocks pull in must not leak into it.
+
+## Decision
+
+Make data source a knob — **`--mock-data baked` (default) | `faker`** — with **identical factory signatures** in both modes, so a consumer flips it without touching call sites.
+Baked mode lives in `emitters/sample.ts` (`sampleValue` → a JS value, printed as a literal); faker mode lives in `emitters/faker.ts` (`fakerExpression` → a `ts.Expression` of `@faker-js/faker` calls).
+Both walk the same IR with the same visited-set cycle guard, so they agree on shape; `--mock-seed <n>` emits `faker.seed(n)` for reproducible faker output.
+The `@faker-js/faker` import appears only in the `*.mocks.ts` module — never in the client.
+
+A `$ref` cycle terminates in the **type-correct empty value** for its position (array → `[]`, record → `{}`, optional property → omitted; only a required, non-container self-reference degrades to `null`), shared by both modes, so mock data always satisfies the generated non-nullable types.
+
+## Consequences
+
+- Default output is zero-dependency and deterministic — safe for CI fixtures with no install.
+- Realistic data is one flag away, and reproducible with `--mock-seed`, without changing how the factories are called.
+- Two walkers (`emitters/sample.ts`, `emitters/faker.ts`) must be kept structurally in lockstep; the shared cycle semantics and a parallel test suite are what hold them together. Both live under `emitters/` (a mock concern, not the IR layer).
+- `mock` requires the `sdk` generator (factories reference its types) and is validated by the generator contract ([ADR-0004](./0004-registry-seams.md)).
diff --git a/packages/client-generator/docs/adr/0011-wrapper-generators.md b/packages/client-generator/docs/adr/0011-wrapper-generators.md
new file mode 100644
index 0000000000..0cf69c1303
--- /dev/null
+++ b/packages/client-generator/docs/adr/0011-wrapper-generators.md
@@ -0,0 +1,30 @@
+# ADR 0011: Data-fetching wrapper generators (`swr`, `tanstack-query`)
+
+- Status: Accepted
+- Date: 2026-06-13
+
+## Context
+
+The sdk emits framework-agnostic `async function`s.
+Application code that uses [TanStack Query](https://tanstack.com/query) or [SWR](https://swr.vercel.app) then hand-writes the same glue per operation — query keys, `queryFn`/fetcher wrappers, mutation factories — which drifts from the spec and is exactly the boilerplate a generator should own.
+Two questions had to be answered without compromising the dependency-free client ([ADR-0002](./0002-typescript-peer-dep.md)): how the wrappers stay in step with the sdk's calling convention, and how to support multiple frameworks (TanStack ships `react`/`vue`/`svelte`/`solid` adapters) without four near-copies.
+
+## Decision
+
+Each wrapper is a **registry generator** ([ADR-0004](./0004-registry-seams.md)) emitting a separate `*.tanstack.ts` / `*.swr.ts` module that imports the framework peer and **forwards to the sdk's exported functions** — the client never imports the framework.
+Both wrappers derive their argument order from the shared `operation-signature.ts`, so a forwarding call lines up with the sdk by construction.
+
+Their cross-cutting agreement — which operations are wrappable (skip SSE; skip `<Op>Variables` name collisions) and the `vars`/`init` parameter shape — lives in one shared `wrapper-support.ts`, so the two emitters (and any third adapter) cannot diverge.
+
+For TanStack's multiple frameworks, the **emitted factory module is byte-identical across frameworks** — `queryOptions` and the mutation shape are framework-agnostic — so the only difference is the import specifier.
+`--query-framework` selects it (`@tanstack/<framework>-query`), rather than forking the generator per framework.
+
+Wrappers wrap the **throw-mode** sdk (TanStack/SWR expect the fetcher to throw), so they require `--error-mode throw` and the `functions` facade; the generator contract fails fast otherwise.
+
+## Consequences
+
+- Adding a third wrapper (e.g. another fetching library) reuses `wrapper-support.ts` and `operation-signature.ts` — only the per-operation factory bodies are new.
+- TanStack framework support costs one import-specifier switch, not a code path per framework.
+- The client stays dependency-free; the framework is a peer of the wrapper module only.
+- SSE operations and `<Op>Variables` schema collisions are skipped with a logged notice rather than emitting a module that won't compile.
+- Vercel/Next.js-specific data fetching is intentionally out of scope (SWR covers the React-Query alternative); revisit only if there is concrete demand.
diff --git a/packages/client-generator/docs/adr/0012-plugin-api.md b/packages/client-generator/docs/adr/0012-plugin-api.md
new file mode 100644
index 0000000000..c12a44b653
--- /dev/null
+++ b/packages/client-generator/docs/adr/0012-plugin-api.md
@@ -0,0 +1,33 @@
+# ADR 0012: Experimental custom-generator (plugin) API
+
+- Status: Accepted (experimental)
+- Date: 2026-06-13
+- Amended: the plugin surface is no longer a dedicated `@redocly/client-generator/plugin`
+  subpath — it is re-exported from the **package root** (`@redocly/client-generator`), the
+  package's single entry. The `defineConfig` / `*.config.ts` / `--config-file` mechanism was
+  also removed; inline `customGenerators` are passed via the programmatic `generateClient(...)`
+  API. The plugin API decision itself (below) is unchanged.
+
+## Context
+
+The built-in generators ([ADR-0004](./0004-registry-seams.md)) cover common targets (sdk, zod, tanstack-query, swr, transformers, mock).
+They cannot cover the long tail: outputs that are org-specific (a house-style SDK wrapper, a UI permissions map) or niche (validators in a library we don't ship, mocks in another test runner's format).
+Today a user's only options are forking the tool or writing a separate program that re-parses the spec.
+The registry seam is already shaped to admit more generators — the question was whether, and how, to open it to third parties without compromising the dependency-free client ([ADR-0002](./0002-typescript-peer-dep.md)) or locking the IR's shape prematurely.
+
+## Decision
+
+Open the `getGenerator` registry as a **public, experimental** API for **custom generators only** (not writers or AST hooks).
+A custom generator is the internal `GeneratorDescriptor` plus a `name`: `{ name, run, requires?, facades?, errorModes?, dateTypes? }`, where `run(input) => GeneratedFile[]` receives the same IR the built-ins do.
+
+- **Loading is dual.** A `generators` entry resolves as a built-in name, an inline `customGenerators` entry (from a `defineConfig` file — type-safe, no dynamic import), or an **import specifier** (a path resolved against the config dir, or an installed package) that is dynamically `import()`ed and default-exported (mirroring how config files load). A new `resolveGenerators` performs this before emission, producing a name→descriptor registry that `validateGenerators` and the run loop consume.
+- **Surface + stability.** The package root (`@redocly/client-generator`) exports `defineGenerator`, the IR types, and a curated codegen toolkit (`ts`, `printStatements`, `parseStatements`, `operationSignature`, `schemaToTypeNode`, `pascalCase`, `safeIdent`) — the same internals the built-in generators use, re-surfaced (no new logic). The whole surface is **`@experimental`**: it may change between minor versions until real plugins exercise it and it is stabilized.
+- **Fail fast.** Collisions (a custom name equal to a built-in or another custom), invalid exports, unloadable specifiers, and unmet `requires`/`facades`/`errorModes`/`dateTypes` all throw an actionable error before any file is written.
+
+## Consequences
+
+- The long tail is addressable without forking; a generator is a small module against a stable IR, and is a first-class peer of the built-ins (same model, same toolkit).
+- The generated client stays dependency-free — a generator's output is its own file, and its target libraries are peers of the consumer's app, not the client.
+- **Trust:** import-specifier generators execute arbitrary code at generation time — the same trust level as any installed dependency or `defineConfig` file. Not sandboxed (out of scope); documented.
+- **Commitment is deferred:** marking the surface experimental keeps the IR and toolkit free to evolve while the API is proven; graduating it to stable is future work.
+- **Out of scope (v1):** custom writers / output modes, emitter/AST hooks, per-plugin options passthrough, and a plugin marketplace.
diff --git a/packages/client-generator/docs/adr/0013-experimental-status.md b/packages/client-generator/docs/adr/0013-experimental-status.md
new file mode 100644
index 0000000000..1bbaf19b49
--- /dev/null
+++ b/packages/client-generator/docs/adr/0013-experimental-status.md
@@ -0,0 +1,42 @@
+# ADR 0013: Experimental release status & stabilization criteria
+
+- Status: Accepted
+- Date: 2026-06-13
+
+## Context
+
+`generate-client` (and `@redocly/client-generator`) ships a large public surface in one go: CLI flags, the **exact generated output**, the configuration schema, six generators, and a custom-generator plugin API that exposes the IR ([ADR-0012](./0012-plugin-api.md)).
+Several of these are hard to walk back once committed to:
+
+- **Generated output is the real lock-in** — consumers commit the generated client to their repos and depend on its exact shape; changing it is a breaking change.
+- **The IR is semi-public** through the plugin API (already `@experimental`), so freezing the surrounding feature while the IR moves would be incoherent.
+- There are **known deferrals** (`int64`→`bigint`, oauth2 token-flow helpers, a pretty-print pass, no built-in Angular/Valibot) and **little real-world adoption** yet to validate the design.
+
+Committing all of this to semver-stable on day one is a promise we can't yet keep.
+
+## Decision
+
+Release the **entire feature as experimental**.
+Its CLI flags, generated output, configuration, and the plugin API may change in any minor release until it is declared stable.
+
+- **Versioning:** `@redocly/client-generator` is versioned **independently, starting at `0.x`** — it is **not** in the monorepo's `fixed` lockstep group (which keeps `@redocly/cli` / `@redocly/openapi-core` / `@redocly/respect-core` in step). A `0.x` version is the semver-native signal that the API may change, and it decouples the experimental package's churn from the stable CLI's version (the CLI bundles it and pins the exact version it ships). It graduates to `1.0.0` when declared stable.
+- **Disclosure:** the `0.x` version, the README banner, the command-doc admonition, the changeset entry, and this ADR all state the experimental status and link here.
+
+### Stabilization criteria (what graduates it to stable)
+
+The feature stays experimental until all of the following hold:
+
+1. **Validated against real-world specs** — exercised on a representative set of production OpenAPI descriptions (incl. internal consumers) with no output-shape surprises.
+2. **Generated-output shape frozen** — no pending changes to the emitted client/types that would break a committed, generated client.
+3. **Plugin IR committed to** — the IR and codegen toolkit re-exported from `@redocly/client-generator` are reviewed and promoted from `@experimental` to stable.
+4. **Deferrals decided** — `int64`→`bigint`, oauth2 token-flow helpers, and the formatting/pretty-print pass are each either implemented or explicitly declared out of scope.
+5. **Soak period** — a defined window of no breaking changes to flags/output/config before the flag is flipped.
+
+Stabilization is tracked in a public issue linked from the docs; flipping to stable is itself a changelog-worthy change.
+
+## Consequences
+
+- We can refine flags, output, config, and the IR based on real adoption without breaking-change apologies — the experimental label sets that expectation up front.
+- The cost is the usual one: some teams defer adopting experimental tooling. For a _codegen_ tool the risk is low — the output lives in the consumer's repo and the version can be pinned.
+- "Experimental" must not become permanent: the criteria above are the explicit exit, and graduating to `1.0.0` (with the docs disclaimers dropped) is the signal that they have been met.
+- This ADR is the canonical record of the status; superseded when the feature is declared stable.
diff --git a/packages/client-generator/docs/adr/0014-request-response-customization.md b/packages/client-generator/docs/adr/0014-request-response-customization.md
new file mode 100644
index 0000000000..f439aa3e44
--- /dev/null
+++ b/packages/client-generator/docs/adr/0014-request-response-customization.md
@@ -0,0 +1,46 @@
+# ADR 0014: Request/response customization as a runtime contract
+
+- Status: Accepted
+- Date: 2026-06-26
+
+## Context
+
+Consumers need to shape requests and responses the generator cannot know about: add a header to some endpoints, attach a trace/idempotency key, swap the transport, retry differently, map errors to domain types, rewrite a URL behind a gateway, log and measure.
+The naive path — hand-editing the generated client — loses every change on the next regenerate, which defeats codegen.
+
+The generated client already ships a runtime extension surface for most of this ([ADR-0001](./0001-ast-codegen.md) emits it verbatim into every client):
+
+- `ClientConfig` — `baseUrl`, `headers` (static or per-request function), `fetch` (transport), `onRequest` / `onResponse` / `onError` hooks, a composable `middleware[]` onion, and `retry`.
+- `RequestContext` — `{ url, method, headers, body }` handed to `onRequest`; `url`/`method`/`headers` are mutable.
+- `RequestOptions` — the trailing per-call argument (`RequestInit & { retry, parseAs }`), merged over the global config.
+- `configure()` / `use()` for the functions facade; `new Client(config)` / `client.use()` per instance for the service-class facade.
+- Auth is its own resolved seam ([ADR-0007](./0007-call-site-auth.md), [ADR-0009](./0009-per-instance-auth.md)); response validation is the `zod` generator; framework glue is the wrapper generators ([ADR-0011](./0011-wrapper-generators.md)).
+
+The question this ADR settles is **where customization lives** — and which of the remaining gaps we close.
+The codegen-time alternatives considered (a dedicated plugin, extending the `transformers` generator, or an `--extension custom.ts` flag that stitches consumer code into the output) all push runtime, per-environment behavior into generate time and re-introduce the regenerate coupling we are trying to remove.
+
+Auditing the surface against real needs leaves three genuine gaps:
+
+1. **Targeting by operation identity.** Middleware can only match on `ctx.url` / `ctx.method`, so "all `admin`-tagged operations" or "the `createOrder` operation" can only be expressed as brittle URL regexes — `RequestContext` carries no `operationId`, `tags`, or path template.
+2. **Request body mutation is silently ignored.** The body is serialized into the fetch payload _before_ `onRequest` runs, and the fetch sends that payload — not `ctx.body`. So mutating `ctx.body` (case conversion, enveloping, signing) is a footgun: it type-checks and does nothing.
+3. **Typed-result enrichment.** Middleware sees only the raw `Response`, not the deserialized value, so enriching the typed result is impossible without reconstructing a `Response`.
+
+## Decision
+
+**Request/response customization is a runtime contract — the `ClientConfig` hooks, the `middleware[]` onion, and the per-call `RequestOptions` — never a codegen-time seam.** We will not add a customization plugin, extend `transformers` for it, or add a flag that merges consumer code into the generated output. The generated client stays a pure projection of the spec; everything spec-independent is composed from the outside by consumer-owned modules that survive regeneration.
+
+We close the prioritized gaps by **extending the same runtime contract**, additively:
+
+1. **Operation metadata in `RequestContext`.** Thread the operation's identity into the context the runtime builds — at minimum `operationId`, plus `tags` and the path template (the `path` before parameter interpolation). Middleware then targets requests semantically (`ctx.operationId === 'createOrder'`, `ctx.tags.includes('admin')`) instead of by URL shape. Emitted into every client; the existing `url`/`method`/`headers` fields are unchanged.
+2. **Make the request body mutable in `onRequest`.** Serialize the payload from `ctx.body` _after_ the `onRequest` chain runs, so body transforms take effect. The default behavior (JSON-encode a plain object, pass through `Blob`/`FormData`/string) is unchanged when no hook touches the body.
+
+We **defer typed-result enrichment** (gap 3): it weakens the contract's type safety and has no concrete demand — the raw-`Response` `onResponse` hook covers the asked-for cases. Revisit only on a real need.
+
+## Consequences
+
+- The customization story is one consumer-owned setup module (`configure`/`use` or `new Client`), not a generator feature — no merge step, no regenerate loss, no new CLI surface.
+- Operation metadata makes "some requests" first-class and stable across path changes, and is purely additive — existing middleware keeps working.
+- Fixing body mutation removes a silent footgun and unlocks request-body transforms (case conversion, enveloping, signing) without a new hook.
+- Emitting operation metadata adds a small per-request object and slightly larger output; acceptable for the targeting it enables. It is always emitted (not gated), keeping the contract uniform across clients.
+- Deferring typed-result enrichment keeps the response hook honest (raw `Response` in, raw `Response` out) and leaves type safety intact; consumers needing a derived field compute it at the call site for now.
+- Query serialization beyond OpenAPI `style`/`explode` remains out of scope — rewrite `ctx.url` in `onRequest` if needed; not worth a dedicated hook absent demand.
diff --git a/packages/client-generator/docs/adr/0015-publisher-setup-bake-in.md b/packages/client-generator/docs/adr/0015-publisher-setup-bake-in.md
new file mode 100644
index 0000000000..bc4fbf9326
--- /dev/null
+++ b/packages/client-generator/docs/adr/0015-publisher-setup-bake-in.md
@@ -0,0 +1,44 @@
+# ADR 0015: Publisher setup bake-in via `--setup`
+
+- Status: Accepted
+- Date: 2026-06-26
+
+## Context
+
+[ADR-0014](./0014-request-response-customization.md) settled request/response customization as a **runtime** contract a _consumer_ composes (`configure`/`use` from their own module), and deliberately ruled out stitching consumer code into the generated output.
+
+But an API provider **publishing an SDK on npm** has a different need: they want the generated client to ship with _their_ cross-cutting defaults already wired in — base URL, retry, a header injector, an idempotency-key middleware — so their downstream users `npm install` it and call operations with no `configure`/`use` of their own. Today only `baseUrl` can be baked (it is inlined); everything else is runtime-only.
+
+The obvious shape — a setup file that imports `configure`/`use` from `./client` and calls them — fails twice: the generated client does not exist when the setup is authored (the import will not resolve), and side-effecting calls against a per-client `configure`/`use` cannot be meaningfully unit-tested. The publisher actor is therefore a distinct, opt-in **build-time** concern, and must not break the zero-dependency guarantee ([ADR-0002](./0002-typescript-peer-dep.md)).
+
+## Decision
+
+Add a `--setup <file>` flag (config key `setup`) that **bakes a publisher setup module into the single-file client**.
+
+The setup module imports its contract — `defineClientSetup` plus the runtime types (`RequestContext`, `Middleware`, `ClientSetupConfig`, …) — from the package's main entry `@redocly/client-generator`, and **returns** an inspectable object rather than calling side-effecting functions:
+
+```ts
+export default defineClientSetup({ config: { baseUrl: '…', retry: { … } }, middleware: [ … ] });
+```
+
+This resolves the chicken-and-egg (the contract lives in the package, not the not-yet-generated client) and makes the setup **unit-testable in isolation** (its middleware are plain functions on an object). To support it, the package now exports a canonical, spec-independent **runtime-contract module**, kept in lockstep with the emitted runtime types by a test.
+
+The baker (`setup-bake.ts`) parses the module, **rejects any import other than `@redocly/client-generator`** (preserving zero-dep), strips the (type-only) package import, extracts the `defineClientSetup` argument, and emits a collision-safe `{ … }` block — `configure(config)` + `use(...middleware)` — appended to the single-file client after `configure`/`use` are defined. Baked calls run first on import; a consumer's own `configure`/`use` merge/append on top, so defaults stay overridable.
+
+`--setup` applies across **all output modes and both facades**, via a single source of truth — a module-scoped `__redoclySetup` object (emitted in the shared http module in multi-file layouts, exported so per-tag service classes can import it):
+
+- **Functions facade**: after `configure`/`use` are defined, the emitter applies `configure(__redoclySetup.config ?? {})` + `use(...(__redoclySetup.middleware ?? []))`. In multi-file this lives in the http module, which the entry imports, so it runs on load for every layout.
+- **Service-class facade**: the generated class constructor merges `__redoclySetup` into its per-instance `this.config` (`{ ...baked, ...passed }`, baked middleware first), so `new Client()` gets the defaults and `new Client(override)` merges on top.
+
+This **refines** ADR-0014 (it does not supersede it): ADR-0014's "no stitching consumer code" governs _consumer self-customization_; publisher bake-in is a separate, explicit build-time seam.
+
+**Override semantics.** The baked block runs first (at import). A consumer's own customization then layers on with two distinct rules: scalar `ClientConfig` fields (`fetch`/transport, `baseUrl`, `headers`, `retry`, the single hooks) are a single slot set via `configure` (`Object.assign`) — **last write wins, so the consumer overrides the baked default** (a consumer `config.fetch` _replaces_ a baked transport rather than wrapping it). Middleware registered via `use` **composes** — baked middleware appended first, consumer middleware after; both run (`onRequest` in order, `onResponse` reversed). A publisher who needs un-bypassable behavior should express it as middleware, not a baked `config.fetch`.
+
+## Consequences
+
+- A published SDK can ship its request/response defaults built in; downstream users get them with zero setup and can still override.
+- The package gains a real, documented home for the runtime contract types (`@redocly/client-generator` main entry) — overdue, and the basis for testable setup modules.
+- Zero-dependency output is preserved: the import allowlist forbids third-party imports in a setup file, and the `defineClientSetup` helper is stripped at bake time (never imported by the generated client).
+- The setup contract (`defineClientSetup` + the runtime types) is now public surface that must stay in lockstep with the emitted runtime; a unit test guards the spec-independent types against drift.
+- Works across all output modes and both facades from one `__redoclySetup` source of truth: in multi-file layouts it lives in the shared http module (exported for service-class so per-tag classes import it), so non-setup clients stay byte-identical.
+- Top-level `await` in a setup file is unsupported (the baked block is synchronous); revisit only on demand.
diff --git a/packages/client-generator/docs/adr/0016-msw-generator-vs-mock-server.md b/packages/client-generator/docs/adr/0016-msw-generator-vs-mock-server.md
new file mode 100644
index 0000000000..b517c323a2
--- /dev/null
+++ b/packages/client-generator/docs/adr/0016-msw-generator-vs-mock-server.md
@@ -0,0 +1,35 @@
+# ADR 0016: In-process MSW mocks (generated) coexist with the out-of-process mock server
+
+- Status: Accepted
+- Date: 2026-07-03
+
+## Context
+
+Two mocking mechanisms exist in this repo, and it recurs in review whether they are redundant — "why not use `@redocly/mock-server` for every mocking use case, and drop the generated [MSW](https://mswjs.io) handlers (and `faker`)?"
+
+They sit on **two orthogonal axes**, which the "redundant?" question conflates:
+
+1. **Where interception happens** — this ADR.
+   - **Generated MSW handlers** (`mock` generator, `*.mocks.ts`): run **in-process** and intercept the client's real `fetch` transparently. No change to where the client points; no port, no separate process. Work in a browser (service worker) and inside test workers (Vitest/jsdom, Storybook, Playwright-CT).
+   - **`@redocly/mock-server`**: a **separate HTTP process** on a port, serving spec-derived responses. The client must point its `baseUrl` at it. Language-agnostic and exercises the **real transport** (real `fetch` round-trip, real `AbortController`, real headers).
+2. **What data is returned** — already settled by [ADR-0010](./0010-mock-data-baked-vs-faker.md): `baked` deterministic literals (default) vs. `faker` realistic data; the mock server independently serves spec `example` values. This axis is _not_ the subject here.
+
+The dominant consumer of a generated TypeScript SDK is application code (React/Vue/…) whose testing and local-dev story is **in-process fetch interception** — which is precisely what MSW is, and what comparable generators emit, because it is the ecosystem norm. Booting a Node HTTP server inside each frontend test worker is heavier, flake-prone (port lifecycle), impossible in a browser worker, and loses transparent interception (the client's `baseUrl` must be redirected).
+
+The mock server's strengths are the mirror image: real transport (why this repo's own runtime-tier tests — `tests/e2e/generate-client/base.test.ts` / `cafe.test.ts` — run the generated client against it), a shared team/staging-like instance, and cross-language clients. Using the _generated_ mock as the harness for the _sdk_ generator's own runtime test would also be circular — a mock-generator bug could mask or cause an sdk-test failure — so the independent, spec-driven server is the trustworthy double there.
+
+## Decision
+
+Keep **both**, as complementary tools for different interception points; do not fold one into the other.
+
+- The **`mock` generator** owns **in-process** mocking: type-safe MSW handlers + data factories, co-located in the consumer's repo, overridable per test (`server.use(...)`), zero infra, browser- and test-worker-capable. It stays dependency-free for the client itself — `msw`/`@faker-js/faker` appear only in the emitted `*.mocks.ts`, never in the client ([ADR-0002](./0002-typescript-peer-dep.md), [ADR-0010](./0010-mock-data-baked-vs-faker.md)).
+- **`@redocly/mock-server`** owns **out-of-process** mocking: real-transport, language-agnostic, shared-instance scenarios — and is the independent double for this repo's runtime test tier.
+
+Neither mechanism can cover the other's primary use case well, so neither is dropped.
+
+## Consequences
+
+- The SDK's primary audience (frontend app + test code) gets the mocking mode it actually reaches for, with no running process.
+- Two mocking stories must be documented and maintained; this ADR is the reference for _why_, so the "just use the server" question does not get re-litigated per PR.
+- The genuine trim lever, if surface must shrink, is the **data axis, not the mechanism axis**: `faker` (an extra opt-in mode + peer dep) is the most marginal piece — `baked` already covers the deterministic-test case, and realistic data is mostly a demo/Storybook nicety. Dropping `faker` would be defensible; dropping the MSW generator in favor of the server would remove the one mode the primary audience needs. Revisit `faker` only if its maintenance cost outweighs demand.
+- The runtime test tier deliberately uses the independent mock server (not the generated mock) to keep sdk-failure blame unambiguous.
diff --git a/packages/client-generator/docs/adr/0017-runtime-module-and-descriptor-client.md b/packages/client-generator/docs/adr/0017-runtime-module-and-descriptor-client.md
new file mode 100644
index 0000000000..b6ec1e5cda
--- /dev/null
+++ b/packages/client-generator/docs/adr/0017-runtime-module-and-descriptor-client.md
@@ -0,0 +1,39 @@
+# ADR 0017: Hand-written runtime module + descriptor-driven generated clients
+
+- Status: Accepted
+- Date: 2026-07-06
+
+## Context
+
+Until now the generated client's behavior — URL building, auth, retry, middleware, body serialization, SSE — lived in a 700+-line source-string template (`emitters/runtime.ts`) stamped verbatim into every output. That delivered the zero-dependency, self-contained file [ADR-0002](./0002-typescript-peer-dep.md) promised, at three compounding costs:
+
+1. **Fix distribution.** A runtime-behavior bug required every consumer to regenerate every API. Empirically, all of this branch's customer-visible fixes (body-after-`onRequest`, multipart-after-`onRequest`, retry body drain, SSE final-frame/reconnect) were runtime-behavior fixes — each would have shipped via a `^` semver range had the runtime been installable.
+2. **Testability.** The behavior existed only as an emitted string — unit-testable only through generated output and e2e suites, never directly.
+3. **Surface sprawl.** Two facades (`--facade functions|service-class` plus `--name`), four output modes (`single|split|tags|tags-split`), an `sse.*` namespace ([ADR-0006](./0006-sse-namespace.md)), module-global auth slots ([ADR-0007](./0007-call-site-auth.md)), and `setServerUrl` multiplied the emit paths the template had to serve.
+
+The market's two reference designs each fail one side of the trade. The leading OSS generator ran a separate-runtime-packages model and abandoned it (its stated reasons: slower onboarding, painful upgrades, bundling issues — failure modes of version pairing across six client packages with no frozen contract). The leading commercial platform inlines everything and distributes fixes by republishing whole SDKs. Neither offers both.
+
+Nothing is published (the package sits at `0.0.0`), so reshaping the output is free-breaking — and [ADR-0013](./0013-experimental-status.md)'s stabilization criteria require the generated-output shape frozen before that changes, which forces the decision now.
+
+## Decision
+
+**The runtime is a hand-written module; the generated client is data.**
+
+1. **One package, no separate runtime package.** The runtime lives at `packages/client-generator/src/runtime/` — eleven internally dependency-free source modules (`types`, `errors`, `url`, `parse`, `retry`, `multipart`, `auth`, `setup`, `send`, `sse`, `create-client`) behind an `index.ts` barrel, re-exported from the package's main entry and directly unit-tested at 100% per-file coverage. Package-mode clients import `@redocly/client-generator` itself; setup files ([ADR-0015](./0015-publisher-setup-bake-in.md)) keep their existing import, and the runtime-contract types become re-exports of `runtime/types.ts` (single source of truth). This avoids the version-pairing failure mode of a second package; extraction remains possible later at the cost of one regeneration.
+2. **The descriptor is the frozen seam.** Generated clients carry per-operation wire shapes as pure data — `OPERATIONS = { … } as const satisfies Record<string, OperationDescriptor>` — plus an `Ops` interface (per-op `args`/`result`, `kind: 'sse'` for streams) and `export const client = createClient<Ops, …>(OPERATIONS, { … })`. `createClient` attaches one real bound method per operation in a construction-time loop (no Proxy); `configure`/`use`/`auth` are assigned after the loop so they win name collisions. Additions to `OperationDescriptor` must be optional (additive within a major).
+3. **`runtime: inline` stays the default; `runtime: package` is the opt-in.** Inline preserves ADR-0002's headline — a self-contained, zero-dependency file — via a build-time snapshot: `npm run compile` regenerates `emitters/runtime-sources.ts` from the real `src/runtime/` sources, and `emitters/inline-runtime.ts` embeds them in import-graph order, whole modules only, stripped of module syntax. One source of truth; the inline copy cannot drift. Package mode replaces the embedded block with `import { createClient, … } from '@redocly/client-generator'`, so runtime fixes reach the app via `npm update` with zero regeneration; regeneration then tracks only spec changes.
+4. **Capability-seam assembly.** The send core never statically imports the optional modules (`multipart`, `auth`, `sse`, `setup`); they plug in through a `Capabilities` object wired at `createClient` time. The package barrel wires the full set; the inline assembler wires — and embeds — only what the spec needs, so exclusion can never break the core, `noUnusedLocals` holds, and both modes execute identical code paths.
+5. **The `satisfies` clause is the version-skew guard.** No bespoke contract versioning: plain npm semver, with the generated `satisfies Record<string, OperationDescriptor>` failing the consumer's **build** on an incompatible generated/runtime pair (package mode's only new failure axis). Accepted caveat: plain-JS consumers who never typecheck lose the guard.
+6. **Facade and surface collapse.** Every generated module always exports both call styles — the `client` instance (grouped-args methods) and free-function one-liners (`--args-style` shapes only the sugar) — so `--facade` and `--name` are removed (no generated class to name). `--output-mode` reduces to `single` | `split` (entry + `<stem>.schemas.ts`; endpoints are one-liners now, so per-tag splitting lost its point). `setServerUrl` is removed (`configure({ serverUrl })` covers it). SSE operations become flat async-generator methods driven by `kind: 'sse'` in `Ops` — the `sse.*` namespace is gone.
+   Auth is per-instance only: the runtime's `resolveAuth` capability reads `ClientConfig.auth`, `client.auth.{bearer,basic,apiKey}` mutates it, and the generated `setBearer`/`setBasicAuth`/`setApiKey*` setters are sugar bound to the default instance — the module-global credential slots are gone.
+7. **Semantics carried over, not redesigned.** Error mode stays a generate-time knob ([ADR-0005](./0005-error-mode-terminals.md)): the generator writes `Result<…>` into `Ops` **and** bakes `errorMode: 'result'` into the `createClient` config; the runtime's `execute` branches on that flag, and `configure()` ignores `errorMode` (flipping it at runtime would desync the static types). Config layers lowest→highest as spec defaults → baked publisher setup (`mergeSetup`) → the app's `configure()`; `use()` appends, `configure({ middleware })` replaces. Middleware's `ctx.operation` keeps its literal-union typing (`OperationId`/`OperationPath`/`OperationTag`), now threaded through `createClient`'s type parameters.
+
+## Consequences
+
+- Runtime fixes finally have a `^`-range channel — for `runtime: package` users. Default (`inline`) users still fix by regenerating; one fan-out command covers a fleet. Both personas are served; the dual mode is a market unique.
+- The runtime gets direct unit tests (retry/backoff, middleware order, query styles, multipart, parse kinds, auth resolution, SSE framing/reconnect) instead of being reachable only through generated output.
+- The generator shrinks to emitting types + data + thin wiring; one emitter (`emitters/package-client.ts`) serves both runtimes and both output modes, and the wrapper generators' `facades: ['functions']` restriction is deleted (free functions always exist).
+- **Per-operation tree-shaking regresses** — the instance loop references the whole `OPERATIONS` map, so unused operations' descriptors ship. Accepted: descriptors are data-only (~100–200 B/op, gzips well; types never ship). If it bites, a per-op descriptor-export/client-subsetting mode restores shaking later — the pattern has commercial prior art and is on the roadmap, not in this change.
+- `satisfies` requires consumer TS >= 4.9 — well under the `>=5.5` peer floor.
+- The runtime module inherits the output's portability rule: web-standard APIs only (no Node builtins), ESM, `sideEffects: false` — enforced by the same strict-tsc e2e gates.
+- Relationship to earlier ADRs: **amends [ADR-0002](./0002-typescript-peer-dep.md)** (the zero-dep default is preserved; `package` mode is the documented opt-in that adds one dependency); **supersedes the mechanisms of [ADR-0005](./0005-error-mode-terminals.md)** (the `__send`/`__request`/`__requestResult` terminals are gone; the decision — error mode fixed at generate time — stands), **[ADR-0006](./0006-sse-namespace.md)** (namespace → flat methods), and **[ADR-0007](./0007-call-site-auth.md)/[ADR-0009](./0009-per-instance-auth.md)** (module-global slots and emitted `__auth` call sites → the runtime `resolveAuth` capability over per-instance `ClientConfig.auth`; 0009's per-instance decision stands and is now the only model).
diff --git a/packages/client-generator/docs/adr/0018-auto-pagination.md b/packages/client-generator/docs/adr/0018-auto-pagination.md
new file mode 100644
index 0000000000..6f43c9a20b
--- /dev/null
+++ b/packages/client-generator/docs/adr/0018-auto-pagination.md
@@ -0,0 +1,33 @@
+# ADR 0018: Auto-pagination as declared, statically verified configuration
+
+- Status: Accepted
+- Date: 2026-07-08
+
+## Context
+
+Iterating a paginated list endpoint by hand is boilerplate every consumer rewrites: call, extract the items, read the cursor (or bump the offset), loop, and get the stop condition right. Generators in the ecosystem attack this two ways, and both have a failure mode we refuse:
+
+1. **Heuristics** — sniff parameter names (`cursor`, `page`, `offset`, `next…`) and response shapes, and paginate whatever looks paginated. Cross-API naming variance makes this wrong silently: a lookalike param produces an iterator that loops forever or skips data, and nothing tells the user the guess happened.
+2. **Vendor extensions only** — require annotating every operation in the spec. Correct but tedious for the common case where one convention covers the whole API, and unavailable when the spec isn't yours to edit.
+
+Additional forces: the descriptor contract is frozen ([ADR-0017](./0017-runtime-module-and-descriptor-client.md) — additions must be optional); the send core assembles optional behavior through the capability seam, and non-paginated output must stay byte-identical; SSE already set a precedent that iterator-shaped surfaces bypass the error-mode terminals ([ADR-0005](./0005-error-mode-terminals.md), [ADR-0006](./0006-sse-namespace.md)); and the generator owns a resolved response-schema IR ([ADR-0003](./0003-spec-agnostic-ir.md)), so item types can be computed at generate time instead of guessed at runtime.
+
+## Decision
+
+**Pagination is declared, then statically verified against the spec — never guessed.**
+
+1. **Config-first declaration with a verified convention.** The `pagination` option (`redocly.yaml` `client.pagination`) carries one convention rule (`style: cursor | offset | page`, the style's advance param, `nextCursor`/`items` JSON pointers, optional `limitParam`) plus `operations` per-op overrides and an `exclude` list; the `x-pagination` operation extension takes the same rule fields inline in the spec. Precedence per operation: `operations[id]` > `x-pagination` > convention, with `exclude` killing all sources.
+   The convention applies only to operations it **structurally fits** — the advance param is a declared query parameter whose schema accepts what the runtime sends (string-ish for `cursor`, numeric for `offset`/`page`), and the pointers resolve over the JSON success-response schema with `items` landing on an array. A convention misfit silently skips the operation; an **explicit** rule that doesn't fit — and a malformed rule from any source — fails generation with per-operation errors aggregated into one throw. No name sniffing, no shape guessing.
+2. **Item typing is static, from the IR.** `emitters/pagination.ts` resolves the `items` pointer against the success-response `SchemaModel` (value-shape walking, `ref`s resolved through the model's named schemas) and writes the element type into the operation's `Ops` entry as `item`. `.items()` yields that type with zero runtime reflection; the same resolution is what verification rides on, so a type that emits is a pointer that resolves.
+3. **Capability-seam placement.** The runtime logic is one module, `runtime/paginate.ts` (`pages`/`items` generators + RFC 6901 `resolvePointer`), wired through `Capabilities.paginate` exactly like SSE: the send core never statically imports it, inline output embeds it only when some descriptor paginates, and an unwired capability throws descriptively. The descriptor gains an optional `pagination` field (normalized: `style`, `param`, `nextCursor?`, `limitParam?`, `items`) — optional, so the frozen contract holds and non-paginated package-mode output stays byte-identical; `runtime: package` clients pick up pagination fixes via `npm update`.
+4. **Method-attached surface, not a namespace.** A paginated operation keeps its one-shot call and gains `.pages(args?, init?)` / `.items(args?, init?)` via `Object.assign` on the bound method; the flat free function preserves them the same way. ADR-0017 already collapsed the `sse.*` namespace into flat methods — reintroducing a `paginated.*` namespace would fork the surface again, and a standalone helper (`paginate(client.listX, …)`) loses the per-operation static typing the `Ops` entry provides. Accepted asymmetry: the flat function stays positional while its attached iterators take the grouped args shape (they are the client method's iterators, and iterator args must round-trip into per-page calls).
+5. **Iteration is error-mode-agnostic** (the SSE precedent). On a result-mode client each page's envelope is unwrapped before it reaches the iterator: `.pages()` yields raw pages (an optional `page` field in the Ops entry carries that type), and a failed page aborts iteration by throwing `ApiError` in both modes — a mid-stream `{ data, error }` page would force every consumer to branch inside the loop and re-derive the page type. The throw-mode-only `onError` middleware hook is not invoked. The one-shot call keeps its mode's shape untouched.
+6. **Styles v1: `cursor`, `offset`, `page`; `Link` header deferred.** Cursor stops on an absent/`null`/empty next cursor and guards against non-advancing and non-scalar cursors (infinite-loop protection); offset advances by each page's item count, page by 1, both stopping on an empty page. Resume is free (the caller's own advance-param value seeds iteration); `init` is forwarded to every page call, so `AbortSignal` works. RFC 8288 `Link`-header pagination needs header (not body) extraction and URL-driven (not param-driven) advancement — a different descriptor shape, deferred until demanded rather than speculatively generalized.
+
+## Consequences
+
+- Paginated operations get `for await` ergonomics with statically typed items, in both runtimes, from one declaration — and a wrong declaration is a generate-time error naming the operation and the reason, not a runtime surprise.
+- Zero false positives by construction: no operation paginates unless a rule was declared for it and the spec structurally supports it. The trade: users must write the declaration — nothing is inferred, even for obviously paginated APIs.
+- Verification quality is bounded by spec quality: an undeclared query param or an untyped response schema blocks the convention from fitting (explicitly declaring it surfaces the reason as an error).
+- The descriptor and `OpsShape` grow optional fields only (`pagination`, `item`, `page`), so existing generated/runtime pairs stay compatible and non-paginated output is unchanged.
+- v1 strictness accepted: pointer walking over unions/intersections bails (the rule won't fit), and `Link`-header APIs aren't served yet; both can be added by extending the same rule schema and pointer walker.
diff --git a/packages/client-generator/docs/adr/0019-first-class-client-config.md b/packages/client-generator/docs/adr/0019-first-class-client-config.md
new file mode 100644
index 0000000000..e148c7b9ea
--- /dev/null
+++ b/packages/client-generator/docs/adr/0019-first-class-client-config.md
@@ -0,0 +1,22 @@
+# ADR 0019: `generate-client` config via a first-class `client` block
+
+- Status: Accepted — supersedes ADR-0008
+- Date: 2026-07-17
+
+## Context
+
+ADR-0008 parked `generate-client` settings in an `x-client-generator` extension block plus an optional `*.config.ts` (`--config-file`) layer, explicitly as a stopgap until first-class keys could land.
+Both layers existed only because the config schema didn't model client generation yet; keeping them meant two config dialects and an extension key users had to discover.
+
+## Decision
+
+`redocly.yaml` models client generation with **typed, first-class keys**: a top-level `client` block for shared defaults and a per-API `apis.<name>.client` block layered over it field by field (the `pagination` block merges additively), with the output path at `apis.<name>.clientOutput`.
+The schema lives in `@redocly/openapi-core`'s config types, so the config is linted like any other block.
+Precedence, low → high: **top-level `client` → `apis.<name>.client` → CLI flags**.
+The `x-client-generator` extension and the `*.config.ts` / `--config-file` layer are removed.
+
+## Consequences
+
+- One config dialect: everything is declared in `redocly.yaml` and validated by the config schema.
+- A no-arg `redocly generate-client` fans out over every API that declares a `client` block or `clientOutput`.
+- Programmatic use passes the same vocabulary to `generateClient(...)` directly; there is no separate config-file loader to maintain.
diff --git a/packages/client-generator/docs/adr/README.md b/packages/client-generator/docs/adr/README.md
new file mode 100644
index 0000000000..9df55a34de
--- /dev/null
+++ b/packages/client-generator/docs/adr/README.md
@@ -0,0 +1,53 @@
+# Architecture Decision Records
+
+Immutable, point-in-time records of the significant, hard-to-reverse decisions behind `@redocly/client-generator`.
+Each ADR captures the **context**, the **decision**, and its **consequences** at the time it was made.
+ADRs are not edited as the code evolves — when a decision is revisited, add a new ADR that supersedes the old one (and mark the old one `Superseded by ADR-NNNN`).
+
+For the **descriptive** map of how the package is built today (pipeline, module map, seams), see [`../../ARCHITECTURE.md`](../../ARCHITECTURE.md).
+ARCHITECTURE.md says _what is_; these ADRs say _why_.
+
+## Index
+
+| #                                                      | Decision                                                          | Status                  |
+| ------------------------------------------------------ | ----------------------------------------------------------------- | ----------------------- |
+| [0001](./0001-ast-codegen.md)                          | Generate TypeScript via the TS AST (`ts.factory`), not strings    | Accepted                |
+| [0002](./0002-typescript-peer-dep.md)                  | `typescript` as a peer dep; zero-runtime-dependency output        | Accepted                |
+| [0003](./0003-spec-agnostic-ir.md)                     | A spec-agnostic IR as the builder↔emitter contract                | Accepted                |
+| [0004](./0004-registry-seams.md)                       | First-party `getGenerator` / `getWriter` registry seams           | Accepted                |
+| [0005](./0005-error-mode-terminals.md)                 | Error handling as a generate-time mode (throw vs result)          | Amended by 0017         |
+| [0006](./0006-sse-namespace.md)                        | SSE as a derived response kind under an `sse.*` namespace         | Superseded by 0017      |
+| [0007](./0007-call-site-auth.md)                       | Auth resolved at the call site via async `__auth`                 | Superseded by 0017      |
+| [0008](./0008-redocly-yaml-config.md)                  | `generate-client` config via `redocly.yaml` `x-client-generator`  | Superseded by 0019      |
+| [0009](./0009-per-instance-auth.md)                    | Per-instance auth via `ClientConfig.auth`                         | Amended by 0017         |
+| [0010](./0010-mock-data-baked-vs-faker.md)             | Mock data: baked literals by default, faker opt-in                | Accepted                |
+| [0011](./0011-wrapper-generators.md)                   | Data-fetching wrapper generators (`swr`, `tanstack-query`)        | Accepted                |
+| [0012](./0012-plugin-api.md)                           | Experimental custom-generator (plugin) API                        | Accepted (experimental) |
+| [0013](./0013-experimental-status.md)                  | Experimental release status & stabilization criteria              | Accepted                |
+| [0014](./0014-request-response-customization.md)       | Request/response customization as a runtime contract              | Accepted                |
+| [0015](./0015-publisher-setup-bake-in.md)              | Publisher setup bake-in via `--setup`                             | Accepted                |
+| [0016](./0016-msw-generator-vs-mock-server.md)         | In-process MSW mocks coexist with the out-of-process mock server  | Accepted                |
+| [0017](./0017-runtime-module-and-descriptor-client.md) | Hand-written runtime module + descriptor-driven generated clients | Accepted                |
+| [0018](./0018-auto-pagination.md)                      | Auto-pagination as declared, statically verified configuration    | Accepted                |
+| [0019](./0019-first-class-client-config.md)            | `generate-client` config via a first-class `client` block         | Accepted                |
+
+## Template
+
+```md
+# ADR NNNN: <short decision title>
+
+- Status: Proposed | Accepted | Superseded by ADR-XXXX
+- Date: YYYY-MM-DD
+
+## Context
+
+What forces are at play — the problem, constraints, and alternatives considered.
+
+## Decision
+
+The choice made, stated in active voice ("We will …").
+
+## Consequences
+
+What becomes easier and what becomes harder as a result. Include the trade-offs accepted.
+```
diff --git a/packages/client-generator/package.json b/packages/client-generator/package.json
new file mode 100644
index 0000000000..6feea5e032
--- /dev/null
+++ b/packages/client-generator/package.json
@@ -0,0 +1,64 @@
+{
+  "name": "@redocly/client-generator",
+  "version": "0.1.0",
+  "description": "Generate typed, zero-dependency TypeScript clients (fetch, auth, retries, middleware, SSE) from OpenAPI descriptions.",
+  "type": "module",
+  "types": "lib/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js",
+      "default": "./lib/index.js"
+    },
+    "./codegen": {
+      "types": "./lib/codegen.d.ts",
+      "import": "./lib/codegen.js",
+      "default": "./lib/codegen.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=22.12.0 || >=20.19.0 <21.0.0",
+    "npm": ">=10"
+  },
+  "engineStrict": true,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "examples:regen": "node scripts/regenerate-examples.mjs",
+    "prepare": "node scripts/generate-runtime-sources.mjs",
+    "typecheck:examples": "node scripts/typecheck-examples.mjs"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Redocly/redocly-cli.git"
+  },
+  "homepage": "https://github.com/Redocly/redocly-cli",
+  "keywords": [
+    "OpenAPI",
+    "Swagger",
+    "TypeScript",
+    "client",
+    "generator",
+    "codegen",
+    "fetch"
+  ],
+  "contributors": [
+    "Roman Marshevskyi <roman.marshevskyy@redocly.com> (https://redocly.com/)"
+  ],
+  "dependencies": {
+    "@redocly/openapi-core": "2.39.0"
+  },
+  "peerDependencies": {
+    "typescript": ">=5.5.0"
+  },
+  "devDependencies": {
+    "typescript": "6.0.2"
+  },
+  "files": [
+    "lib"
+  ]
+}
diff --git a/packages/client-generator/scripts/generate-runtime-sources.mjs b/packages/client-generator/scripts/generate-runtime-sources.mjs
new file mode 100644
index 0000000000..4516820f20
--- /dev/null
+++ b/packages/client-generator/scripts/generate-runtime-sources.mjs
@@ -0,0 +1,58 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Snapshot src/runtime/*.ts source text into a tracked TS module so the inline assembler
+// can embed the real runtime (a readFileSync asset would not survive the CLI's esbuild
+// bundling). Order is the assembler's fixed dependency order; the barrel (index.ts) is
+// not embedded — the assembler emits its own local createClient wiring.
+const MODULES = [
+  'types',
+  'errors',
+  'url',
+  'parse',
+  'retry',
+  'multipart',
+  'auth',
+  'setup',
+  'send',
+  'sse',
+  'create-client',
+  'paginate',
+];
+
+const pkgRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
+const runtimeDir = join(pkgRoot, 'src', 'runtime');
+const outFile = join(pkgRoot, 'src', 'emitters', 'runtime-sources.ts');
+
+// Emit the literal exactly as oxfmt (singleQuote: true) would format it, so that
+// compile → format is a no-op: prefer single quotes unless that needs more escapes.
+function toStringLiteral(source) {
+  const singles = (source.match(/'/g) ?? []).length;
+  const doubles = (source.match(/"/g) ?? []).length;
+  const json = JSON.stringify(source); // handles all escaping, double-quoted
+  if (singles > doubles) return json;
+  const inner = json
+    .slice(1, -1)
+    .replace(/\\\\|\\"|'/g, (m) => (m === '\\\\' ? m : m === '\\"' ? '"' : "\\'"));
+  return `'${inner}'`;
+}
+
+const entries = MODULES.map((name) => {
+  const source = readFileSync(join(runtimeDir, `${name}.ts`), 'utf-8');
+  const line = `  '${name}.ts': ${toStringLiteral(source)},`;
+  // oxfmt (printWidth: 100) breaks an over-width property onto a continuation line.
+  return line.length <= 100 ? line : `  '${name}.ts':\n    ${toStringLiteral(source)},`;
+});
+
+const content = [
+  '// GENERATED by scripts/generate-runtime-sources.mjs — do not edit. Regenerated on install (`prepare`); manually: `npm run prepare -w @redocly/client-generator`.',
+  'export const RUNTIME_SOURCES = {',
+  ...entries,
+  '} as const;',
+  '',
+  'export type RuntimeModuleName = keyof typeof RUNTIME_SOURCES;',
+  '',
+].join('\n');
+
+writeFileSync(outFile, content);
diff --git a/packages/client-generator/scripts/regenerate-examples.mjs b/packages/client-generator/scripts/regenerate-examples.mjs
new file mode 100644
index 0000000000..9b7a1f42f9
--- /dev/null
+++ b/packages/client-generator/scripts/regenerate-examples.mjs
@@ -0,0 +1,25 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Regenerate each example's client in place. A `redocly.yaml` example uses the CLI
+// (a no-arg run fans out over its `apis:` entry's `client` block); the programmatic
+// example runs its own `generate.ts`.
+const pkgRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
+const repoRoot = join(pkgRoot, '..', '..');
+const cli = join(repoRoot, 'packages/cli/lib/index.js');
+const tsx = join(repoRoot, 'node_modules/.bin/tsx');
+const examplesDir = join(repoRoot, 'tests/e2e/generate-client/examples');
+const examples = readdirSync(examplesDir, { withFileTypes: true })
+  .filter((entry) => entry.isDirectory() && entry.name !== '_shared')
+  .map((entry) => entry.name)
+  .sort();
+
+for (const name of examples) {
+  const cwd = join(examplesDir, name);
+  const res = existsSync(join(cwd, 'redocly.yaml'))
+    ? spawnSync('node', [cli, 'generate-client'], { cwd, stdio: 'inherit' })
+    : spawnSync(tsx, [join(cwd, 'generate.ts')], { cwd, stdio: 'inherit' });
+  if (res.status !== 0) process.exit(res.status ?? 1);
+}
diff --git a/packages/client-generator/scripts/typecheck-examples.mjs b/packages/client-generator/scripts/typecheck-examples.mjs
new file mode 100644
index 0000000000..f2dc49f12f
--- /dev/null
+++ b/packages/client-generator/scripts/typecheck-examples.mjs
@@ -0,0 +1,27 @@
+import { spawnSync } from 'node:child_process';
+import { readdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Type-check each example against its own (strict, browser-targeted) tsconfig. The
+// root `npm run typecheck` is a single Node-targeted pass and excludes `examples/`
+// (they are Vite/React apps needing DOM + JSX + bundler resolution), so they are
+// verified here instead — same rigor, the right compiler options per project.
+// Run `examples:regen` first: the gitignored clients must exist to type-check against.
+const pkgRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
+const repoRoot = join(pkgRoot, '..', '..');
+const tsc = join(repoRoot, 'node_modules/.bin/tsc');
+const examplesDir = join(repoRoot, 'tests/e2e/generate-client/examples');
+const examples = readdirSync(examplesDir, { withFileTypes: true })
+  .filter((entry) => entry.isDirectory() && entry.name !== '_shared')
+  .map((entry) => entry.name)
+  .sort();
+
+let failed = false;
+for (const name of examples) {
+  const res = spawnSync(tsc, ['--noEmit', '-p', join(examplesDir, name, 'tsconfig.json')], {
+    stdio: 'inherit',
+  });
+  if (res.status !== 0) failed = true;
+}
+if (failed) process.exit(1);
diff --git a/packages/client-generator/src/__tests__/config-file.test.ts b/packages/client-generator/src/__tests__/config-file.test.ts
new file mode 100644
index 0000000000..30c754f052
--- /dev/null
+++ b/packages/client-generator/src/__tests__/config-file.test.ts
@@ -0,0 +1,53 @@
+import { mergeConfig } from '../config-file.js';
+
+describe('mergeConfig', () => {
+  it('CLI overrides win over base values; undefined overrides are ignored', () => {
+    const merged = mergeConfig(
+      { api: 'spec.yaml', output: 'a.ts', outputMode: 'single' },
+      { output: 'b.ts', outputMode: undefined, argsStyle: 'grouped' }
+    );
+    expect(merged).toEqual({
+      api: 'spec.yaml',
+      output: 'b.ts',
+      outputMode: 'single',
+      argsStyle: 'grouped',
+    });
+  });
+
+  it('layers a partial pagination override onto the shared convention instead of replacing it', () => {
+    const merged = mergeConfig(
+      {
+        pagination: {
+          style: 'cursor',
+          cursorParam: 'cursor',
+          items: '/items',
+          operations: { listA: { style: 'cursor', cursorParam: 'a', items: '/a' } },
+        },
+      },
+      {
+        pagination: {
+          limitParam: 'perPage',
+          operations: { listB: { style: 'offset', offsetParam: 'b', items: '/b' } },
+        },
+      }
+    );
+    expect(merged.pagination).toEqual({
+      style: 'cursor',
+      cursorParam: 'cursor',
+      items: '/items',
+      limitParam: 'perPage',
+      operations: {
+        listA: { style: 'cursor', cursorParam: 'a', items: '/a' },
+        listB: { style: 'offset', offsetParam: 'b', items: '/b' },
+      },
+    });
+  });
+
+  it('unions pagination `exclude` (a per-API exclude adds to the shared one, never replaces it)', () => {
+    const merged = mergeConfig(
+      { pagination: { style: 'cursor', cursorParam: 'c', items: '/i', exclude: ['a', 'shared'] } },
+      { pagination: { exclude: ['b', 'shared'] } }
+    );
+    expect(merged.pagination?.exclude).toEqual(['a', 'shared', 'b']);
+  });
+});
diff --git a/packages/client-generator/src/__tests__/entry-weight.test.ts b/packages/client-generator/src/__tests__/entry-weight.test.ts
new file mode 100644
index 0000000000..670490cbb7
--- /dev/null
+++ b/packages/client-generator/src/__tests__/entry-weight.test.ts
@@ -0,0 +1,41 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Package-mode clients import the package ROOT at app runtime, and native ESM loads
+// every static import eagerly — so the root entry's static graph must stay free of the
+// codegen stack (`typescript`, `@redocly/openapi-core`, Node builtins). Codegen is
+// reached only through the dynamic `import('./codegen.js')` inside `generateClient`,
+// which this walk deliberately does not follow.
+const libDir = resolve(dirname(fileURLToPath(import.meta.url)), '../../lib');
+
+const STATIC_IMPORT = /(?:^|\n)(?:import|export)\s[^'"]*?from\s+['"]([^'"]+)['"]/g;
+
+function staticGraph(entry: string): { files: Set<string>; externals: Set<string> } {
+  const files = new Set<string>();
+  const externals = new Set<string>();
+  const queue = [entry];
+  while (queue.length > 0) {
+    const file = queue.pop()!;
+    if (files.has(file)) continue;
+    files.add(file);
+    const source = readFileSync(file, 'utf-8');
+    for (const match of source.matchAll(STATIC_IMPORT)) {
+      const specifier = match[1];
+      if (specifier.startsWith('.')) queue.push(join(dirname(file), specifier));
+      else externals.add(specifier);
+    }
+  }
+  return { files, externals };
+}
+
+describe('package root entry (lib/index.js)', () => {
+  it('statically loads only the runtime — no typescript, openapi-core, or Node builtins', () => {
+    const { files, externals } = staticGraph(join(libDir, 'index.js'));
+    expect([...externals]).toEqual([]);
+    const outsideRuntime = [...files].filter(
+      (file) => file.includes('/emitters/') || file.includes('/intermediate-representation/')
+    );
+    expect(outsideRuntime).toEqual([]);
+  });
+});
diff --git a/packages/client-generator/src/__tests__/errors.test.ts b/packages/client-generator/src/__tests__/errors.test.ts
new file mode 100644
index 0000000000..65dabe3c7f
--- /dev/null
+++ b/packages/client-generator/src/__tests__/errors.test.ts
@@ -0,0 +1,15 @@
+import { NotSupportedError } from '../errors.js';
+
+describe('NotSupportedError', () => {
+  it('is an instance of Error and exposes the given message', () => {
+    const err = new NotSupportedError('boom');
+    expect(err).toBeInstanceOf(Error);
+    expect(err).toBeInstanceOf(NotSupportedError);
+    expect(err.message).toBe('boom');
+  });
+
+  it('sets name to "NotSupportedError"', () => {
+    const err = new NotSupportedError('x');
+    expect(err.name).toBe('NotSupportedError');
+  });
+});
diff --git a/packages/client-generator/src/__tests__/index.test.ts b/packages/client-generator/src/__tests__/index.test.ts
new file mode 100644
index 0000000000..e25e9056d6
--- /dev/null
+++ b/packages/client-generator/src/__tests__/index.test.ts
@@ -0,0 +1,267 @@
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { outdent } from 'outdent';
+
+import { collectGeneratedFiles } from '../codegen.js';
+import { generateClient } from '../index.js';
+import type { ApiModel } from '../intermediate-representation/model.js';
+
+function model(): ApiModel {
+  return {
+    title: 'T',
+    version: '1',
+    serverUrl: 'https://x',
+    services: [{ name: 'Default', operations: [] }],
+    schemas: [],
+    securitySchemes: [],
+  };
+}
+
+describe('generateClient output validation', () => {
+  it("rejects output paths with a literal 'undefined' or 'null' segment (interpolation-bug telltale)", async () => {
+    const { generateClient } = await import('../index.js');
+    for (const output of ['undefined/api.ts', 'out/null/api.ts', 'undefined']) {
+      await expect(generateClient({ api: 'unused.yaml', output })).rejects.toThrow(
+        /looks like an interpolation bug/
+      );
+    }
+    // A file merely NAMED undefined.* is legitimate — only exact segments are rejected.
+    await expect(
+      generateClient({ api: 'unused.yaml', output: 'out/undefined.ts' })
+    ).rejects.not.toThrow(/interpolation/);
+  });
+});
+
+describe('generateClient setup validation', () => {
+  it('rejects a URL setup specifier upfront (local file paths only)', async () => {
+    const { generateClient } = await import('../index.js');
+    for (const url of ['https://cdn.example.com/setup.ts', 'file:///tmp/setup.ts']) {
+      await expect(
+        generateClient({ api: 'unused.yaml', output: '/tmp/never.ts', setup: url })
+      ).rejects.toThrow(/local file path/);
+    }
+    // A Windows-style drive path must NOT be mistaken for a URL scheme (it fails
+    // later on file reading, not on the scheme guard).
+    await expect(
+      generateClient({ api: 'unused.yaml', output: '/tmp/never.ts', setup: 'C:\\team\\setup.ts' })
+    ).rejects.not.toThrow(/local file path/);
+  });
+});
+
+describe('collectGeneratedFiles', () => {
+  it('runs the given generators and concatenates their files', () => {
+    const files = collectGeneratedFiles(model(), {
+      outputPath: '/out/api.ts',
+      outputMode: 'single',
+      emit: {},
+      generators: ['sdk'],
+    });
+    expect(files.length).toBe(1);
+    expect(files[0].path).toBe('/out/api.ts');
+  });
+
+  it('throws when two generators emit the same path', () => {
+    expect(() =>
+      collectGeneratedFiles(model(), {
+        outputPath: '/out/api.ts',
+        outputMode: 'single',
+        emit: {},
+        generators: ['sdk', 'sdk'],
+      })
+    ).toThrow(/already emitted/);
+  });
+
+  it('supports runtime: package with outputMode: split (the shared emitter serves both)', () => {
+    const files = collectGeneratedFiles(model(), {
+      outputPath: '/out/api.ts',
+      outputMode: 'split',
+      emit: { runtime: 'package' },
+      generators: ['sdk'],
+    });
+    // No schemas in the model → only the entry file.
+    expect(files.map((f) => f.path)).toEqual(['/out/api.ts']);
+    expect(files[0].content).toContain("from '@redocly/client-generator'");
+  });
+});
+
+describe('generateClient — end-to-end orchestration', () => {
+  let workDir: string;
+
+  beforeEach(async () => {
+    workDir = await mkdtemp(join(tmpdir(), 'client-gen-index-'));
+  });
+
+  afterEach(async () => {
+    await rm(workDir, { recursive: true, force: true });
+  });
+
+  it('writes the generated file to disk and reports its size', async () => {
+    const api = join(workDir, 'spec.yaml');
+    await writeFile(
+      api,
+      outdent`
+        openapi: 3.0.3
+        info:
+          title: Tiny
+          version: 1.0.0
+        paths:
+          /ping:
+            get:
+              operationId: ping
+              responses:
+                '200':
+                  description: OK
+                  content:
+                    application/json:
+                      schema: { type: string }
+      `,
+      'utf-8'
+    );
+
+    const output = join(workDir, 'nested/dir/api.ts');
+    const result = await generateClient({ api, output });
+
+    expect(result.outputPath).toBe(output);
+    expect(result.bytes).toBeGreaterThan(0);
+
+    const contents = await readFile(output, 'utf-8');
+    expect(contents).toContain(
+      'export const ping = (init: RequestOptions = {}) => client.ping({}, init);'
+    );
+    expect(contents).toContain('// Generated by @redocly/client-generator');
+    // bytes should match what we wrote.
+    expect(result.bytes).toBe(Buffer.byteLength(contents, 'utf-8'));
+  });
+
+  it('emits the result shape when errorMode is `result`', async () => {
+    const api = join(workDir, 'errmode.yaml');
+    await writeFile(
+      api,
+      outdent`
+        openapi: 3.0.3
+        info:
+          title: Tiny
+          version: 1.0.0
+        paths:
+          /ping:
+            get:
+              operationId: ping
+              responses:
+                '200':
+                  description: OK
+                  content:
+                    application/json:
+                      schema: { type: string }
+      `,
+      'utf-8'
+    );
+
+    const resultOutput = join(workDir, 'result.ts');
+    await generateClient({ api, output: resultOutput, errorMode: 'result' });
+    const resultContents = await readFile(resultOutput, 'utf-8');
+    expect(resultContents).toContain('errorMode: "result"');
+    expect(resultContents).toContain('result: Result<PingResult, unknown>;');
+
+    const throwOutput = join(workDir, 'throw.ts');
+    await generateClient({ api, output: throwOutput });
+    const throwContents = await readFile(throwOutput, 'utf-8');
+    expect(throwContents).not.toContain('errorMode: "result"');
+    expect(throwContents).toContain('result: PingResult;');
+  });
+
+  it('passes the pagination config through to the emitter', async () => {
+    const api = join(workDir, 'paginated.yaml');
+    await writeFile(
+      api,
+      outdent`
+        openapi: 3.0.3
+        info:
+          title: Cafe
+          version: 1.0.0
+        paths:
+          /orders:
+            get:
+              operationId: listOrders
+              parameters:
+                - { name: cursor, in: query, schema: { type: string } }
+              responses:
+                '200':
+                  description: OK
+                  content:
+                    application/json:
+                      schema:
+                        type: object
+                        properties:
+                          orders:
+                            type: array
+                            items: { type: string }
+                          nextCursor: { type: string }
+      `,
+      'utf-8'
+    );
+
+    const output = join(workDir, 'paginated.ts');
+    await generateClient({
+      api,
+      output,
+      pagination: {
+        style: 'cursor',
+        cursorParam: 'cursor',
+        nextCursor: '/nextCursor',
+        items: '/orders',
+      },
+    });
+    const contents = await readFile(output, 'utf-8');
+    expect(contents).toContain(
+      'pagination: { style: "cursor", param: "cursor", nextCursor: "/nextCursor", items: "/orders" }'
+    );
+    expect(contents).toContain('item: string;');
+    expect(contents).toContain(
+      '{ pages: client.listOrders.pages, items: client.listOrders.items });'
+    );
+  });
+
+  it('normalizes a Swagger 2.0 document before generating', async () => {
+    const api = join(workDir, 'swagger2.yaml');
+    await writeFile(
+      api,
+      outdent`
+        swagger: '2.0'
+        info:
+          title: Tiny2
+          version: 1.0.0
+        host: api.example.com
+        basePath: /v1
+        schemes: [https]
+        consumes: [application/json]
+        produces: [application/json]
+        paths:
+          /items:
+            get:
+              operationId: listItems
+              parameters:
+                - { name: page, in: query, required: false, type: integer }
+              responses:
+                '200':
+                  description: ok
+                  schema: { $ref: '#/definitions/Item' }
+        definitions:
+          Item:
+            type: object
+            properties:
+              id: { type: integer }
+      `,
+      'utf-8'
+    );
+
+    const output = join(workDir, 'api2.ts');
+    const result = await generateClient({ api, output });
+
+    expect(result.bytes).toBeGreaterThan(0);
+    const contents = await readFile(output, 'utf-8');
+    expect(contents).toContain('export const listItems = (');
+    expect(contents).toContain('export type Item');
+    expect(contents).toContain('serverUrl: "https://api.example.com/v1"');
+  });
+});
diff --git a/packages/client-generator/src/__tests__/loader.test.ts b/packages/client-generator/src/__tests__/loader.test.ts
new file mode 100644
index 0000000000..46c565caeb
--- /dev/null
+++ b/packages/client-generator/src/__tests__/loader.test.ts
@@ -0,0 +1,94 @@
+import { createConfig } from '@redocly/openapi-core';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { outdent } from 'outdent';
+
+import { loadSpec } from '../loader.js';
+
+describe('loadSpec', () => {
+  let workDir: string;
+
+  beforeEach(async () => {
+    workDir = await mkdtemp(join(tmpdir(), 'client-gen-loader-'));
+  });
+
+  afterEach(async () => {
+    await rm(workDir, { recursive: true, force: true });
+  });
+
+  async function write(name: string, contents: string): Promise<string> {
+    const file = join(workDir, name);
+    await writeFile(file, contents, 'utf-8');
+    return file;
+  }
+
+  it('loads a valid OpenAPI document and returns the parsed bundle', async () => {
+    const file = await write(
+      'minimal.yaml',
+      outdent`
+        openapi: 3.0.3
+        info:
+          title: Minimal
+          version: 1.0.0
+        paths: {}
+      `
+    );
+
+    const { document } = await loadSpec(file);
+    expect(document.openapi).toBe('3.0.3');
+    expect(document.info?.title).toBe('Minimal');
+  });
+
+  it('uses a caller-supplied Config instead of building a fresh one', async () => {
+    const file = await write(
+      'with-config.yaml',
+      outdent`
+        openapi: 3.0.3
+        info:
+          title: Minimal
+          version: 1.0.0
+        paths: {}
+      `
+    );
+    const config = await createConfig({});
+    const { document } = await loadSpec(file, config);
+    expect(document.openapi).toBe('3.0.3');
+  });
+
+  // The underlying `bundle()` already validates document shape and OpenAPI version, so
+  // these failure paths are exercised by openapi-core itself. We re-assert that the loader
+  // surfaces those errors instead of swallowing them.
+  it('detects the spec version (oas3_0)', async () => {
+    const file = await write(
+      'oas3_0.yaml',
+      outdent`
+        openapi: 3.0.3
+        info:
+          title: Minimal
+          version: 1.0.0
+        paths: {}
+      `
+    );
+    const result = await loadSpec(file);
+    expect(result.version).toBe('oas3_0');
+  });
+
+  it('propagates errors from bundle() for null/empty documents', async () => {
+    const file = await write('null.yaml', 'null\n');
+    await expect(loadSpec(file)).rejects.toThrow();
+  });
+
+  it('propagates errors from bundle() for documents missing "openapi"', async () => {
+    const file = await write('no-openapi.yaml', 'foo: bar\n');
+    await expect(loadSpec(file)).rejects.toThrow();
+  });
+
+  it('propagates errors from bundle() for non-string "openapi" values', async () => {
+    const file = await write(
+      'numeric-openapi.yaml',
+      'openapi: 3\ninfo:\n  title: x\n  version: y\npaths: {}\n'
+    );
+    await expect(loadSpec(file)).rejects.toThrow();
+  });
+});
diff --git a/packages/client-generator/src/__tests__/plugin.test.ts b/packages/client-generator/src/__tests__/plugin.test.ts
new file mode 100644
index 0000000000..745976ce23
--- /dev/null
+++ b/packages/client-generator/src/__tests__/plugin.test.ts
@@ -0,0 +1,26 @@
+import {
+  operationSignature,
+  pascalCase,
+  printStatements,
+  safeIdent,
+  schemaToTypeNode,
+  ts,
+} from '../codegen.js';
+import { type CustomGenerator, defineGenerator } from '../plugin.js';
+
+describe('plugin entry', () => {
+  it('defineGenerator returns its argument unchanged', () => {
+    const gen: CustomGenerator = { name: 'route-map', requires: ['sdk'], run: () => [] };
+    expect(defineGenerator(gen)).toBe(gen);
+  });
+
+  it('re-exports the codegen toolkit the built-in generators use', () => {
+    // Value re-exports are reachable and usable from the public entry.
+    expect(typeof ts.factory).toBe('object');
+    expect(typeof printStatements).toBe('function');
+    expect(typeof operationSignature).toBe('function');
+    expect(typeof schemaToTypeNode).toBe('function');
+    expect(pascalCase('pet')).toBe('Pet');
+    expect(safeIdent('123')).not.toBe('123');
+  });
+});
diff --git a/packages/client-generator/src/codegen.ts b/packages/client-generator/src/codegen.ts
new file mode 100644
index 0000000000..e7ec6c38ed
--- /dev/null
+++ b/packages/client-generator/src/codegen.ts
@@ -0,0 +1,163 @@
+// The codegen entry (`@redocly/client-generator/codegen`): everything that runs at
+// GENERATION time — `generateClient`, `collectGeneratedFiles`, and the TypeScript-emitting
+// toolkit for custom generators. It loads `typescript` and `@redocly/openapi-core`, so it
+// must never be reached statically from the package root: package-mode clients import the
+// root at app runtime, and the root reaches this module only through the dynamic import
+// inside its `generateClient` facade.
+
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+
+import type { EmitOptions } from './emitters/emit-options.js';
+import { bakeSetup } from './emitters/setup-bake.js';
+import { NotSupportedError } from './errors.js';
+import { builtinGenerators, validateGenerators } from './generators/index.js';
+import { resolveGenerators } from './generators/resolve.js';
+import type { GeneratedFile, GeneratorDescriptor, OutputMode } from './generators/types.js';
+import { buildApiModel } from './intermediate-representation/build.js';
+import type { ApiModel } from './intermediate-representation/model.js';
+import { normalizeSwagger2 } from './intermediate-representation/normalize-swagger2.js';
+import { loadSpec } from './loader.js';
+import type { GenerateClientOptions, GenerateClientResult } from './types.js';
+
+// --- Codegen toolkit: build TypeScript the same way the built-in generators do -----------------
+export {
+  arrow,
+  constArray,
+  exportConstStatement,
+  jsdoc,
+  parseStatements,
+  printNodes,
+  printStatements,
+  ts,
+} from './emitters/ts.js';
+export { operationSignature } from './emitters/operation-signature.js';
+export type { OperationSignature } from './emitters/operation-signature.js';
+export { schemaToTypeNode } from './emitters/types.js';
+export { pascalCase } from './emitters/support.js';
+export { safeIdent } from './emitters/identifier.js';
+
+/**
+ * Validate the generator selection (see `validateGenerators`), then run each
+ * configured generator against the IR and concatenate their files. Throws on a
+ * duplicate output path so two generators can't silently clobber each other.
+ */
+export function collectGeneratedFiles(
+  model: ApiModel,
+  options: {
+    outputPath: string;
+    outputMode: OutputMode;
+    emit: EmitOptions;
+    generators: string[];
+    /** The resolved registry (built-ins + custom). Defaults to the built-ins. */
+    registry?: Map<string, GeneratorDescriptor>;
+  }
+): GeneratedFile[] {
+  const registry = options.registry ?? builtinGenerators();
+  // Fail fast on an incompatible selection (missing prerequisite, unsupported
+  // error-mode/date-type/runtime) before producing any file.
+  validateGenerators(options.generators, options.emit, registry);
+  const files: GeneratedFile[] = [];
+  const seen = new Set<string>();
+  for (const name of options.generators) {
+    const generator = registry.get(name)!;
+    for (const file of generator.run({
+      model,
+      outputPath: options.outputPath,
+      outputMode: options.outputMode,
+      emit: options.emit,
+    })) {
+      if (seen.has(file.path)) {
+        throw new Error(`Generator conflict: ${file.path} already emitted by an earlier generator`);
+      }
+      seen.add(file.path);
+      files.push(file);
+    }
+  }
+  return files;
+}
+
+export async function generateClient(
+  options: GenerateClientOptions
+): Promise<GenerateClientResult> {
+  // A path segment that is literally "undefined"/"null" is the telltale of an
+  // interpolation bug in the caller (`\`${dir}/client.ts\`` with `dir` unset) — reject
+  // it instead of silently creating an `undefined/` directory.
+  if (
+    options.output.split(/[\\/]/).some((segment) => segment === 'undefined' || segment === 'null')
+  ) {
+    throw new Error(
+      `output path "${options.output}" contains a literal "undefined" or "null" segment — this looks like an interpolation bug in the caller`
+    );
+  }
+  // Setup is a LOCAL module (its code is baked into the generated client) — reject
+  // URL-ish specifiers upfront, before any spec loading, instead of failing later as
+  // an unreadable file path. Two+ letter scheme, so Windows drive paths don't match.
+  if (options.setup && /^[a-z][a-z0-9+.-]+:/i.test(options.setup)) {
+    throw new NotSupportedError(
+      `setup must be a local file path — remote setup modules are not supported (got: ${options.setup})`
+    );
+  }
+  const outputPath = resolve(options.output);
+  const { document, version } = await loadSpec(options.api, options.config);
+  const normalized =
+    version === 'oas2'
+      ? normalizeSwagger2(document as unknown as Record<string, unknown>)
+      : document;
+  const model = buildApiModel(normalized);
+
+  // A publisher `--setup` module is read, validated, and transformed into the neutral setup
+  // expression baked into the client. Applied across all output modes by the emitter.
+  let setupBlock: string | undefined;
+  if (options.setup) {
+    // Resolve a relative setup path against the cwd, consistent with `output` above.
+    // The CLI pre-resolves it (relative to cwd, like --output) and a config-file
+    // `setup` is pre-resolved against the config dir, so both arrive absolute here.
+    const setupPath = resolve(options.setup);
+    setupBlock = bakeSetup(await readFile(setupPath, 'utf-8'));
+  }
+
+  // Resolve the selection into a registry: built-in names pass through, inline `customGenerators`
+  // register, and any other entry is imported as a plugin specifier (path/package).
+  // An empty list (e.g. `generators: []` in config, or no `--generator` flags) means
+  // "unspecified" — fall back to the default sdk client rather than emitting nothing.
+  const requested = options.generators?.length ? options.generators : ['sdk'];
+  const { selected, registry } = await resolveGenerators(requested, {
+    customGenerators: options.customGenerators,
+    configDir: options.configDir,
+  });
+
+  const files = collectGeneratedFiles(model, {
+    outputPath,
+    outputMode: options.outputMode ?? 'single',
+    emit: {
+      serverUrl: options.serverUrl,
+      enumStyle: options.enumStyle,
+      argsStyle: options.argsStyle,
+      errorMode: options.errorMode,
+      dateType: options.dateType,
+      queryFramework: options.queryFramework,
+      mockData: options.mockData,
+      mockSeed: options.mockSeed,
+      setup: setupBlock,
+      runtime: options.runtime,
+      importExt: options.importExt,
+      pagination: options.pagination,
+    },
+    generators: selected,
+    registry,
+  });
+
+  const written: GenerateClientResult['files'] = [];
+  for (const file of files) {
+    await mkdir(dirname(file.path), { recursive: true });
+    await writeFile(file.path, file.content, 'utf-8');
+    written.push({ path: file.path, bytes: Buffer.byteLength(file.content, 'utf-8') });
+  }
+
+  return {
+    outputPath,
+    bytes: written.reduce((sum, file) => sum + file.bytes, 0),
+    files: written,
+  };
+}
diff --git a/packages/client-generator/src/config-file.ts b/packages/client-generator/src/config-file.ts
new file mode 100644
index 0000000000..ec04c06933
--- /dev/null
+++ b/packages/client-generator/src/config-file.ts
@@ -0,0 +1,33 @@
+// packages/client-generator/src/config-file.ts
+import type { Config } from './config.js';
+
+/**
+ * Merge a base config (a `redocly.yaml` `client` block) with CLI overrides.
+ * Defined keys in `overrides` win; `undefined` override values are ignored
+ * so absent flags don't clobber the base values.
+ */
+export function mergeConfig(base: Partial<Config>, overrides: Partial<Config>): Partial<Config> {
+  const merged: Partial<Config> = { ...base };
+  for (const [key, value] of Object.entries(overrides)) {
+    if (value !== undefined) (merged as Record<string, unknown>)[key] = value;
+  }
+  // `pagination` is the one nested block: a partial override (e.g. a per-API `operations`
+  // map alone) must layer onto the shared convention fields, not replace the whole object.
+  // `operations` merge by id and `exclude` unions — both additive, so a per-API block
+  // extends the shared exclusions/overrides rather than dropping them.
+  if (base.pagination && overrides.pagination) {
+    merged.pagination = { ...base.pagination, ...overrides.pagination };
+    if (base.pagination.operations || overrides.pagination.operations) {
+      merged.pagination.operations = {
+        ...base.pagination.operations,
+        ...overrides.pagination.operations,
+      };
+    }
+    if (base.pagination.exclude || overrides.pagination.exclude) {
+      merged.pagination.exclude = [
+        ...new Set([...(base.pagination.exclude ?? []), ...(overrides.pagination.exclude ?? [])]),
+      ];
+    }
+  }
+  return merged;
+}
diff --git a/packages/client-generator/src/config.ts b/packages/client-generator/src/config.ts
new file mode 100644
index 0000000000..91741c5197
--- /dev/null
+++ b/packages/client-generator/src/config.ts
@@ -0,0 +1,68 @@
+import type { ArgsStyle } from './emitters/emit-options.js';
+// packages/client-generator/src/config.ts
+import type { PaginationConfig } from './emitters/pagination.js';
+import type { CustomGenerator, OutputMode } from './generators/types.js';
+
+/**
+ * The user-facing generation config: the options `generateClient()` accepts, plus the
+ * `generators` list. Annotate a standalone config object with `satisfies Config` for
+ * type-safe authoring. The CLI merges a `redocly.yaml` `client` block into this shape
+ * via `mergeConfig` (see config-file.ts).
+ */
+export type Config = {
+  /** Path or URL to the OpenAPI document (or an `apis:` alias from `redocly.yaml`). */
+  api: string;
+  /** Output anchor path (a `.ts` file; multi-file modes derive siblings from it). */
+  output: string;
+  /** File partitioning. Defaults to `single`. */
+  outputMode?: OutputMode;
+  /** How inputs are passed. Defaults to `flat`. */
+  argsStyle?: ArgsStyle;
+  /** Override the inlined base URL (else derived from `servers[0].url`). */
+  serverUrl?: string;
+  /** Named-enum emission. Defaults to `const-object`. */
+  enumStyle?: 'union' | 'const-object';
+  /** Error-handling shape of the generated client. `'throw'` (default) throws `ApiError`
+   * on non-2xx; `'result'` returns a discriminated `{ data, error, response }`. */
+  errorMode?: 'throw' | 'result';
+  /** How `date-time`/`date` string fields are typed. `'string'` (default) keeps the
+   * ISO wire shape; `'Date'` emits a `Date` reference (pair with the `transformers`
+   * generator so the runtime value matches). */
+  dateType?: 'string' | 'Date';
+  /** TanStack Query adapter the `tanstack-query` generator imports from
+   * (`@tanstack/${queryFramework}-query`). Defaults to `react`; only the import
+   * specifier changes. */
+  queryFramework?: 'react' | 'vue' | 'svelte' | 'solid';
+  /** How the `mock` generator produces data. `'baked'` (default) inlines deterministic
+   * literals (zero-dep); `'faker'` emits `@faker-js/faker` calls for realistic data
+   * (the consumer adds `@faker-js/faker` as a dev-dep). */
+  mockData?: 'baked' | 'faker';
+  /** Seed for faker-mode mocks: emits `faker.seed(<n>)` so runs reproduce. Baked mode ignores it. */
+  mockSeed?: number;
+  /**
+   * Generators to run, in order. Defaults to `['sdk']`. Each entry is a built-in name, the `name`
+   * of an inline `customGenerators` entry, or an import specifier (path or package) for a plugin.
+   */
+  generators?: string[];
+  /**
+   * Inline custom generators (the experimental plugin API), registered so they can be selected in
+   * `generators` by `name`. Authored with `defineGenerator` from `@redocly/client-generator`.
+   */
+  customGenerators?: CustomGenerator[];
+  /**
+   * Path to a publisher setup module (`export default defineClientSetup({ config, middleware })`)
+   * baked into the generated client, so a published SDK ships its request/response defaults built
+   * in. Resolved against the config dir. Works across all output modes.
+   */
+  setup?: string;
+  /** Runtime distribution: 'inline' (default, self-contained) | 'package' (imports @redocly/client-generator). */
+  runtime?: 'inline' | 'package';
+  /** Extension in generated relative imports. `'js'` (default) suits tsc and bundlers;
+   * `'ts'` suits runtimes that resolve specifiers literally, like Node's built-in
+   * type stripping (`node client.ts`). */
+  importExt?: 'js' | 'ts';
+  /** Auto-pagination rules (convention + per-operation overrides + `exclude`), resolved
+   * together with each operation's `x-pagination` extension. Explicit rules that don't
+   * fit their operation fail generation. */
+  pagination?: PaginationConfig;
+};
diff --git a/packages/client-generator/src/emitters/__tests__/__snapshots__/client-assembly.test.ts.snap b/packages/client-generator/src/emitters/__tests__/__snapshots__/client-assembly.test.ts.snap
new file mode 100644
index 0000000000..f249406058
--- /dev/null
+++ b/packages/client-generator/src/emitters/__tests__/__snapshots__/client-assembly.test.ts.snap
@@ -0,0 +1,286 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`emitClientSingleFile (package arm) > matches the golden output for a small model 1`] = `
+"// Generated by @redocly/client-generator — do not edit by hand.
+// Source: OpenAPI document. Re-run \`redocly generate-client\` to update.
+
+/**
+ * T (v1.0.0)
+ */
+
+import { createClient, type OperationDescriptor, type RequestOptions, type SseOptions } from '@redocly/client-generator';
+
+export type Order = {
+    id: string;
+};
+
+export type Problem = {};
+
+export type Pet = {};
+
+export type OrderEvent = {};
+
+export type GetOrderResult = Order;
+
+export type GetOrderParams = {
+    expand?: string;
+};
+
+export type GetOrderVariables = {
+    orderId: string;
+    params?: GetOrderParams;
+};
+
+/**
+ * Per-operation \`args\`/\`result\` shapes (plus \`kind: 'sse'\` for event streams) — the
+ * type-level companion of \`OPERATIONS\` that gives \`createClient<Ops>\` its typed methods.
+ */
+export type Ops = {
+    getOrder: {
+        args: {
+            orderId: string;
+            params?: GetOrderParams;
+        };
+        result: GetOrderResult;
+    };
+    streamEvents: {
+        args: {};
+        result: OrderEvent;
+        kind: "sse";
+    };
+};
+
+/**
+ * The wire-shape descriptor for every operation, keyed by operationId — the data the
+ * runtime routes requests by. Also minification-safe static metadata (method, path,
+ * tags) for cache keys, tracing span names, and request logging.
+ */
+export const OPERATIONS = {
+    getOrder: { id: "getOrder", method: "GET", path: "/orders/{orderId}", tags: ["Orders"], params: [{ name: "orderId", in: "path" }, { name: "expand", in: "query" }], security: [[{ scheme: "bearerAuth", kind: "bearer" }]] },
+    streamEvents: { id: "streamEvents", method: "GET", path: "/events", responseKind: "sse", sseDataKind: "json" }
+} as const satisfies Record<string, OperationDescriptor>;
+
+export type OperationId = keyof typeof OPERATIONS;
+
+export type OperationPath = (typeof OPERATIONS)[OperationId]["path"];
+
+export type OperationTag = Extract<(typeof OPERATIONS)[OperationId], {
+    tags: readonly string[];
+}>["tags"][number];
+
+export const client = createClient<Ops, OperationId, OperationPath, OperationTag>(OPERATIONS, { serverUrl: "https://cafe.example.com" });
+
+export const { configure, use } = client;
+export const setBearer = client.auth.bearer;
+export const getOrder = (orderId: string, params: {
+    expand?: string;
+} = {}, init: RequestOptions = {}) => client.getOrder({ orderId, params }, init);
+export const streamEvents = (init: SseOptions = {}) => client.streamEvents({}, init);
+
+export { ApiError, createClient } from '@redocly/client-generator';
+export type { ClientConfig, Middleware, RequestOptions, ServerSentEvent, SseOptions } from '@redocly/client-generator';
+"
+`;
+
+exports[`emitClientSingleFile — pagination > matches the golden output for a paginated package client 1`] = `
+"// Generated by @redocly/client-generator — do not edit by hand.
+// Source: OpenAPI document. Re-run \`redocly generate-client\` to update.
+
+/**
+ * T (v1.0.0)
+ */
+
+import { createClient, type OperationDescriptor, type RequestOptions } from '@redocly/client-generator';
+
+export type Order = {};
+
+export type Problem = {};
+
+export type Pet = {};
+
+export type OrderEvent = {};
+
+export type OrderPage = {
+    orders: Order[];
+    nextCursor?: string;
+};
+
+export type ListOrdersResult = OrderPage;
+
+export type ListOrdersParams = {
+    cursor?: string;
+    limit?: string;
+};
+
+export type ListOrdersVariables = {
+    params?: ListOrdersParams;
+};
+
+export type GetOrderResult = Order;
+
+export type GetOrderParams = {
+    expand?: string;
+};
+
+export type GetOrderVariables = {
+    orderId: string;
+    params?: GetOrderParams;
+};
+
+/**
+ * Per-operation \`args\`/\`result\` shapes (plus \`kind: 'sse'\` for event streams) — the
+ * type-level companion of \`OPERATIONS\` that gives \`createClient<Ops>\` its typed methods.
+ */
+export type Ops = {
+    listOrders: {
+        args: {
+            params?: ListOrdersParams;
+        };
+        result: ListOrdersResult;
+        item: Order;
+    };
+    getOrder: {
+        args: {
+            orderId: string;
+            params?: GetOrderParams;
+        };
+        result: GetOrderResult;
+    };
+};
+
+/**
+ * The wire-shape descriptor for every operation, keyed by operationId — the data the
+ * runtime routes requests by. Also minification-safe static metadata (method, path,
+ * tags) for cache keys, tracing span names, and request logging.
+ */
+export const OPERATIONS = {
+    listOrders: { id: "listOrders", method: "GET", path: "/orders", params: [{ name: "cursor", in: "query" }, { name: "limit", in: "query" }], pagination: { style: "cursor", param: "cursor", nextCursor: "/nextCursor", items: "/orders" } },
+    getOrder: { id: "getOrder", method: "GET", path: "/orders/{orderId}", tags: ["Orders"], params: [{ name: "orderId", in: "path" }, { name: "expand", in: "query" }] }
+} as const satisfies Record<string, OperationDescriptor>;
+
+export type OperationId = keyof typeof OPERATIONS;
+
+export type OperationPath = (typeof OPERATIONS)[OperationId]["path"];
+
+export type OperationTag = Extract<(typeof OPERATIONS)[OperationId], {
+    tags: readonly string[];
+}>["tags"][number];
+
+export const client = createClient<Ops, OperationId, OperationPath, OperationTag>(OPERATIONS, { serverUrl: "https://api.example.com" });
+
+export const { configure, use } = client;
+export const listOrders = Object.assign((params: {
+    cursor?: string;
+    limit?: string;
+} = {}, init: RequestOptions = {}) => client.listOrders({ params }, init), { pages: client.listOrders.pages, items: client.listOrders.items });
+export const getOrder = (orderId: string, params: {
+    expand?: string;
+} = {}, init: RequestOptions = {}) => client.getOrder({ orderId, params }, init);
+
+export { ApiError, createClient } from '@redocly/client-generator';
+export type { ClientConfig, Middleware, RequestOptions } from '@redocly/client-generator';
+"
+`;
+
+exports[`emitClientSingleFile — pagination > matches the golden output for a result-mode paginated package client 1`] = `
+"// Generated by @redocly/client-generator — do not edit by hand.
+// Source: OpenAPI document. Re-run \`redocly generate-client\` to update.
+
+/**
+ * T (v1.0.0)
+ */
+
+import { createClient, type OperationDescriptor, type RequestOptions, type Result } from '@redocly/client-generator';
+
+export type Order = {};
+
+export type Problem = {};
+
+export type Pet = {};
+
+export type OrderEvent = {};
+
+export type OrderPage = {
+    orders: Order[];
+    nextCursor?: string;
+};
+
+export type ListOrdersResult = OrderPage;
+
+export type ListOrdersParams = {
+    cursor?: string;
+    limit?: string;
+};
+
+export type ListOrdersVariables = {
+    params?: ListOrdersParams;
+};
+
+export type GetOrderResult = Order;
+
+export type GetOrderError = Problem;
+
+export type GetOrderParams = {
+    expand?: string;
+};
+
+export type GetOrderVariables = {
+    orderId: string;
+    params?: GetOrderParams;
+};
+
+/**
+ * Per-operation \`args\`/\`result\` shapes (plus \`kind: 'sse'\` for event streams) — the
+ * type-level companion of \`OPERATIONS\` that gives \`createClient<Ops>\` its typed methods.
+ */
+export type Ops = {
+    listOrders: {
+        args: {
+            params?: ListOrdersParams;
+        };
+        result: Result<ListOrdersResult, unknown>;
+        item: Order;
+        page: ListOrdersResult;
+    };
+    getOrder: {
+        args: {
+            orderId: string;
+            params?: GetOrderParams;
+        };
+        result: Result<GetOrderResult, GetOrderError>;
+    };
+};
+
+/**
+ * The wire-shape descriptor for every operation, keyed by operationId — the data the
+ * runtime routes requests by. Also minification-safe static metadata (method, path,
+ * tags) for cache keys, tracing span names, and request logging.
+ */
+export const OPERATIONS = {
+    listOrders: { id: "listOrders", method: "GET", path: "/orders", params: [{ name: "cursor", in: "query" }, { name: "limit", in: "query" }], pagination: { style: "cursor", param: "cursor", nextCursor: "/nextCursor", items: "/orders" } },
+    getOrder: { id: "getOrder", method: "GET", path: "/orders/{orderId}", tags: ["Orders"], params: [{ name: "orderId", in: "path" }, { name: "expand", in: "query" }] }
+} as const satisfies Record<string, OperationDescriptor>;
+
+export type OperationId = keyof typeof OPERATIONS;
+
+export type OperationPath = (typeof OPERATIONS)[OperationId]["path"];
+
+export type OperationTag = Extract<(typeof OPERATIONS)[OperationId], {
+    tags: readonly string[];
+}>["tags"][number];
+
+export const client = createClient<Ops, OperationId, OperationPath, OperationTag>(OPERATIONS, { serverUrl: "https://api.example.com", errorMode: "result" });
+
+export const { configure, use } = client;
+export const listOrders = Object.assign((params: {
+    cursor?: string;
+    limit?: string;
+} = {}, init: RequestOptions = {}) => client.listOrders({ params }, init), { pages: client.listOrders.pages, items: client.listOrders.items });
+export const getOrder = (orderId: string, params: {
+    expand?: string;
+} = {}, init: RequestOptions = {}) => client.getOrder({ orderId, params }, init);
+
+export { ApiError, createClient } from '@redocly/client-generator';
+export type { ClientConfig, Middleware, RequestOptions, Result } from '@redocly/client-generator';
+"
+`;
diff --git a/packages/client-generator/src/emitters/__tests__/auth.test.ts b/packages/client-generator/src/emitters/__tests__/auth.test.ts
new file mode 100644
index 0000000000..8c89800339
--- /dev/null
+++ b/packages/client-generator/src/emitters/__tests__/auth.test.ts
@@ -0,0 +1,66 @@
+import type { SecuritySchemeModel } from '../../intermediate-representation/model.js';
+import { apiKeySetterName, authSetterNames } from '../auth.js';
+
+/** A spec exercising all five injectable kinds at once. */
+const allKinds: SecuritySchemeModel[] = [
+  { kind: 'bearer', key: 'OAuth2' },
+  { kind: 'basic', key: 'Basic' },
+  { kind: 'apiKeyHeader', key: 'HeaderKey', headerName: 'X-API-Key' },
+  { kind: 'apiKeyQuery', key: 'QueryKey', paramName: 'api_key' },
+  { kind: 'apiKeyCookie', key: 'CookieKey', cookieName: 'sid' },
+];
+
+describe('apiKeySetterName', () => {
+  it('is the bare setApiKey for a sole apiKey scheme', () => {
+    expect(apiKeySetterName('anything', true)).toBe('setApiKey');
+  });
+
+  it('suffixes the PascalCased scheme key when several apiKey schemes exist', () => {
+    expect(apiKeySetterName('cookieAuth', false)).toBe('setApiKeyCookieAuth');
+    expect(apiKeySetterName('QueryKey', false)).toBe('setApiKeyQueryKey');
+  });
+});
+
+describe('authSetterNames', () => {
+  it('returns no names when there are no schemes', () => {
+    expect(authSetterNames([])).toEqual([]);
+  });
+
+  it('emits setBearer once for any number of bearer schemes', () => {
+    expect(
+      authSetterNames([
+        { kind: 'bearer', key: 'OAuth2' },
+        { kind: 'bearer', key: 'BearerHttp' },
+      ])
+    ).toEqual(['setBearer']);
+  });
+
+  it('emits setBasicAuth for basic schemes', () => {
+    expect(authSetterNames([{ kind: 'basic', key: 'Basic' }])).toEqual(['setBasicAuth']);
+  });
+
+  it('names a sole apiKey scheme setApiKey regardless of its `in`', () => {
+    expect(
+      authSetterNames([{ kind: 'apiKeyCookie', key: 'CookieKey', cookieName: 'sid' }])
+    ).toEqual(['setApiKey']);
+  });
+
+  it('disambiguates several apiKey schemes with the PascalCased key', () => {
+    expect(
+      authSetterNames([
+        { kind: 'apiKeyHeader', key: 'HeaderKey', headerName: 'X-API-Key' },
+        { kind: 'apiKeyQuery', key: 'QueryKey', paramName: 'api_key' },
+      ])
+    ).toEqual(['setApiKeyHeaderKey', 'setApiKeyQueryKey']);
+  });
+
+  it('orders the full surface bearer → basic → apiKey (emission order)', () => {
+    expect(authSetterNames(allKinds)).toEqual([
+      'setBearer',
+      'setBasicAuth',
+      'setApiKeyHeaderKey',
+      'setApiKeyQueryKey',
+      'setApiKeyCookieKey',
+    ]);
+  });
+});
diff --git a/packages/client-generator/src/emitters/__tests__/client-assembly.test.ts b/packages/client-generator/src/emitters/__tests__/client-assembly.test.ts
new file mode 100644
index 0000000000..2678a33502
--- /dev/null
+++ b/packages/client-generator/src/emitters/__tests__/client-assembly.test.ts
@@ -0,0 +1,542 @@
+import type { ApiModel } from '../../intermediate-representation/model.js';
+import { emitClientSingleFile } from '../client-assembly.js';
+import type { EmitOptions } from '../emit-options.js';
+import { ts } from '../ts.js';
+import { modelWith, namedSchema, operation, param, response, SCALAR } from './fixtures.js';
+
+/** The package arm of the shared emitter. */
+function emit(model: ApiModel, options: EmitOptions = {}): string {
+  return emitClientSingleFile(model, { ...options, runtime: 'package' });
+}
+
+const getOrder = operation({
+  name: 'getOrder',
+  path: '/orders/{orderId}',
+  pathParams: [param('orderId', 'path', true)],
+  queryParams: [param('expand', 'query', false)],
+  successResponses: [response({ schema: { kind: 'ref', name: 'Order' } })],
+  errorResponses: [response({ status: 400, schema: { kind: 'ref', name: 'Problem' } })],
+  security: [['bearerAuth']],
+  tags: ['Orders'],
+});
+const createPet = operation({
+  name: 'createPet',
+  method: 'post',
+  path: '/pets',
+  requestBody: {
+    contentType: 'application/json',
+    schema: { kind: 'ref', name: 'Pet' },
+    required: true,
+  },
+  successResponses: [response({ schema: { kind: 'ref', name: 'Pet' } })],
+});
+const upload = operation({
+  name: 'upload',
+  method: 'post',
+  path: '/upload',
+  requestBody: {
+    contentType: 'multipart/form-data',
+    schema: { kind: 'object', properties: [] },
+    required: true,
+  },
+});
+const streamEvents = operation({
+  name: 'streamEvents',
+  path: '/events',
+  successResponses: [
+    response({ contentType: 'text/event-stream', schema: { kind: 'ref', name: 'OrderEvent' } }),
+  ],
+});
+const configureOp = operation({ name: 'configure', path: '/configure-op' });
+const listOrders = operation({
+  name: 'listOrders',
+  path: '/orders',
+  queryParams: [param('cursor', 'query', false), param('limit', 'query', false)],
+  successResponses: [response({ schema: { kind: 'ref', name: 'OrderPage' } })],
+});
+const CURSOR_RULE = {
+  style: 'cursor' as const,
+  cursorParam: 'cursor',
+  nextCursor: '/nextCursor',
+  items: '/orders',
+};
+const ORDER_PAGE = namedSchema('OrderPage', {
+  kind: 'object',
+  properties: [
+    {
+      name: 'orders',
+      schema: { kind: 'array', items: { kind: 'ref', name: 'Order' } },
+      required: true,
+    },
+    { name: 'nextCursor', schema: SCALAR, required: false },
+  ],
+});
+
+const SCHEMAS = [
+  namedSchema('Order', { kind: 'object', properties: [] }),
+  namedSchema('Problem', { kind: 'object', properties: [] }),
+  namedSchema('Pet', { kind: 'object', properties: [] }),
+  namedSchema('OrderEvent', { kind: 'object', properties: [] }),
+];
+const CAFE = modelWith([getOrder, createPet, upload, streamEvents, configureOp], {
+  schemas: SCHEMAS,
+  securitySchemes: [
+    { kind: 'bearer', key: 'bearerAuth' },
+    { kind: 'apiKeyCookie', key: 'cookieAuth', cookieName: 'sid' },
+  ],
+});
+
+describe('emitClientSingleFile (package arm)', () => {
+  const output = emit(CAFE, { serverUrl: 'https://x' });
+
+  it('imports from the package instead of inlining the runtime template', () => {
+    expect(output).toContain(
+      "import { createClient, type OperationDescriptor, type RequestOptions, type SseOptions, type TokenProvider } from '@redocly/client-generator';"
+    );
+    expect(output).not.toContain('__send');
+    expect(output).not.toContain('__buildUrl');
+    expect(output).not.toContain('let BASE');
+  });
+
+  it('escapes U+2028/U+2029 in generated string literals (code-shape hardening)', () => {
+    const out = emit(
+      modelWith([getOrder], {
+        schemas: SCHEMAS,
+        securitySchemes: [{ kind: 'apiKeyHeader', key: 'k\u2028evil', headerName: 'X-K' }],
+      }),
+      { serverUrl: 'https://x/\u2029path' }
+    );
+    expect(out).toContain('serverUrl: "https://x/\\u2029path"');
+    expect(out).toContain('client.auth.apiKey("k\\u2028evil", value)');
+    expect(out).not.toContain('\u2028');
+    expect(out).not.toContain('\u2029');
+  });
+
+  it('bakes the serverUrl into the createClient config and narrows ctx.operation', () => {
+    expect(output).toContain(
+      'export const client = createClient<Ops, OperationId, OperationPath, OperationTag>(OPERATIONS, { serverUrl: "https://x" });'
+    );
+  });
+
+  it('emits schema types, type guards, aliases, Ops, and OPERATIONS', () => {
+    expect(output).toContain('export type Order =');
+    expect(output).toContain('export type GetOrderResult = Order;');
+    expect(output).toContain('export type Ops = {');
+    expect(output).toContain('as const satisfies Record<string, OperationDescriptor>;');
+  });
+
+  it('emits type guards for discriminated unions', () => {
+    const model = modelWith([getOrder], {
+      schemas: [
+        namedSchema('Cat', {
+          kind: 'object',
+          properties: [{ name: 'type', schema: { kind: 'literal', value: 'cat' }, required: true }],
+        }),
+        namedSchema('Dog', {
+          kind: 'object',
+          properties: [{ name: 'type', schema: { kind: 'literal', value: 'dog' }, required: true }],
+        }),
+        namedSchema('Animal', {
+          kind: 'union',
+          members: [
+            { kind: 'ref', name: 'Cat' },
+            { kind: 'ref', name: 'Dog' },
+          ],
+        }),
+        ...SCHEMAS,
+      ],
+    });
+    expect(emit(model)).toContain('export function isCat(');
+  });
+
+  it('emits core destructure and auth sugar bound to the instance', () => {
+    expect(output).toContain('export const { configure, use } = client;');
+    expect(output).toContain('export const setBearer = client.auth.bearer;');
+    // Sole apiKey scheme → unsuffixed setter, scheme key baked into the closure.
+    expect(output).toContain(
+      'export const setApiKey = (value: TokenProvider) => client.auth.apiKey("cookieAuth", value);'
+    );
+    expect(output).not.toContain('setBasicAuth');
+  });
+
+  it('emits flat sugar one-liners forwarding to the grouped client methods', () => {
+    // Same positional signature style as inline flat mode (`renderArgList`): inline
+    // param object types with `= {}` defaults, trailing `init: … = {}`.
+    expect(output).toContain('export const getOrder = (orderId: string, params: {');
+    expect(output).toContain('=> client.getOrder({ orderId, params }, init);');
+    expect(output).toContain(
+      'export const createPet = (body: Pet, init: RequestOptions = {}) => client.createPet({ body }, init);'
+    );
+    // SSE sugar takes SseOptions and returns the generator directly.
+    expect(output).toContain(
+      'export const streamEvents = (init: SseOptions = {}) => client.streamEvents({}, init);'
+    );
+  });
+
+  it('renames the colliding operation everywhere while the core members keep their names', () => {
+    expect(output).toContain('configure_2: {');
+    expect(output).toContain('id: "configure"'); // descriptor id stays the spec operationId
+    expect(output).toContain(
+      'export const configure_2 = (init: RequestOptions = {}) => client.configure_2({}, init);'
+    );
+  });
+
+  it('re-exports the public surface', () => {
+    expect(output).toContain("export { ApiError, createClient } from '@redocly/client-generator';");
+    expect(output).toContain(
+      "export type { ClientConfig, Middleware, RequestOptions, ServerSentEvent, SseOptions } from '@redocly/client-generator';"
+    );
+  });
+
+  it('keys flat-sugar path values by WIRE name when it differs from the ident', () => {
+    const model = modelWith([
+      operation({
+        name: 'getPet',
+        path: '/pets/{pet-id}',
+        pathParams: [param('pet-id', 'path', true)],
+        successResponses: [response()],
+      }),
+    ]);
+    // No options at all — the emitter's own defaults apply.
+    const out = emit(model);
+    expect(out).toContain(
+      'export const getPet = (pet_id: string, init: RequestOptions = {}) => client.getPet({ "pet-id": pet_id }, init);'
+    );
+    expect(out).toContain('"pet-id": string;'); // Ops args + Variables alias, wire-keyed
+  });
+
+  it('keeps sanitizer-collapsed path params distinct: identifier-safe wire name, renamed ident', () => {
+    const model = modelWith([
+      operation({
+        name: 'compare',
+        path: '/x/{a-b}/{a_b}',
+        pathParams: [param('a-b', 'path', true), param('a_b', 'path', true)],
+        successResponses: [response()],
+      }),
+    ]);
+    // `a-b` sanitizes to `a_b`, so the literal `a_b` param is deduped to `a_b_2` —
+    // but both forward under their wire names.
+    expect(emit(model)).toContain('client.compare({ "a-b": a_b, a_b: a_b_2 }, init);');
+  });
+
+  it('layers a baked setup OVER the spec defaults and imports the contract types', () => {
+    const out = emit(modelWith([getOrder], { schemas: SCHEMAS }), {
+      serverUrl: 'https://x',
+      setup: '{ config: { retry: { retries: 2 } } }',
+    });
+    expect(out).toContain(
+      "import { createClient, mergeSetup, type ClientConfig, type Middleware, type OperationDescriptor, type RequestOptions } from '@redocly/client-generator';"
+    );
+    expect(out).toContain(
+      'const __redoclySetup: { config?: ClientConfig; middleware?: Middleware[] } = { config: { retry: { retries: 2 } } };'
+    );
+    // Precedence lowest→highest: spec default → baked setup (→ app configure()).
+    expect(out).toContain(
+      'export const client = createClient<Ops, OperationId, OperationPath, OperationTag>(OPERATIONS, mergeSetup({ config: { serverUrl: "https://x" } }, mergeSetup(__redoclySetup, {})));'
+    );
+  });
+
+  it('result mode with an SSE-only spec does not import the (unreferenced) Result type', () => {
+    const out = emit(modelWith([streamEvents], { schemas: SCHEMAS }), { errorMode: 'result' });
+    expect(out).not.toContain('type Result');
+    // The SSE member stays unwrapped, and the re-export list still offers Result.
+    expect(out).toContain('kind: "sse"');
+    expect(out).toContain(
+      "export type { ClientConfig, Middleware, RequestOptions, Result, ServerSentEvent, SseOptions } from '@redocly/client-generator';"
+    );
+  });
+
+  it('bakes errorMode: result into the config and wraps Ops results', () => {
+    const out = emit(modelWith([getOrder], { schemas: SCHEMAS }), {
+      serverUrl: 'https://x',
+      errorMode: 'result',
+    });
+    expect(out).toContain('{ serverUrl: "https://x", errorMode: "result" }');
+    expect(out).toContain('result: Result<GetOrderResult, GetOrderError>;');
+    expect(out).toContain('type Result');
+  });
+
+  it('grouped argsStyle destructures the client methods instead of flat one-liners', () => {
+    const out = emit(CAFE, { serverUrl: 'https://x', argsStyle: 'grouped' });
+    expect(out).toContain(
+      'export const { getOrder, createPet, upload, streamEvents, configure_2 } = client;'
+    );
+    expect(out).not.toContain('=> client.getOrder(');
+    // No flat sugar → the per-call option types are not imported (only re-exported).
+    expect(out).toContain(
+      "import { createClient, type OperationDescriptor, type TokenProvider } from '@redocly/client-generator';"
+    );
+  });
+
+  it('threads one schemaNames set: a suppressed alias is inlined in Ops, never referenced', () => {
+    const model = modelWith(
+      [
+        operation({
+          name: 'search',
+          path: '/search',
+          successResponses: [response({ schema: { kind: 'ref', name: 'SearchResult' } })],
+        }),
+      ],
+      { schemas: [namedSchema('SearchResult', { kind: 'object', properties: [] })] }
+    );
+    const out = emit(model);
+    expect(out).not.toContain('export type SearchResult = SearchResult;');
+    expect(out).toContain('result: SearchResult;'); // the schema type, inlined
+  });
+
+  it('suffixes apiKey setters when several apiKey schemes exist; emits setBasicAuth for basic', () => {
+    const out = emit(
+      modelWith([getOrder], {
+        schemas: SCHEMAS,
+        securitySchemes: [
+          { kind: 'basic', key: 'basicAuth' },
+          { kind: 'apiKeyHeader', key: 'keyA', headerName: 'X-A' },
+          { kind: 'apiKeyQuery', key: 'keyB', paramName: 'b' },
+        ],
+      })
+    );
+    expect(out).toContain('export const setBasicAuth = client.auth.basic;');
+    expect(out).toContain(
+      'export const setApiKeyKeyA = (value: TokenProvider) => client.auth.apiKey("keyA", value);'
+    );
+    expect(out).toContain(
+      'export const setApiKeyKeyB = (value: TokenProvider) => client.auth.apiKey("keyB", value);'
+    );
+  });
+
+  it('handles a spec with no operations: uniform wiring over empty maps', () => {
+    const out = emit(modelWith([]), {});
+    expect(out).toContain('export type Ops = Record<string, never>;');
+    expect(out).toContain(
+      'export const OPERATIONS = {} as const satisfies Record<string, OperationDescriptor>;'
+    );
+    // model fixture has a serverUrl — still baked.
+    expect(out).toContain(
+      'export const client = createClient<Ops>(OPERATIONS, { serverUrl: "https://api.example.com" });'
+    );
+    expect(out).toContain('export const { configure, use } = client;');
+  });
+
+  it('emits an empty config object when neither options nor the document set a serverUrl', () => {
+    const out = emit(modelWith([getOrder], { serverUrl: undefined, schemas: SCHEMAS }));
+    expect(out).toContain(
+      'export const client = createClient<Ops, OperationId, OperationPath, OperationTag>(OPERATIONS, {});'
+    );
+  });
+
+  it('forwards the headers slot for operations with header params', () => {
+    const out = emit(
+      modelWith([
+        operation({
+          name: 'ping',
+          path: '/ping',
+          headerParams: [param('X-Trace', 'header', false)],
+          successResponses: [response()],
+        }),
+      ])
+    );
+    expect(out).toContain('=> client.ping({ headers }, init);');
+  });
+
+  it('matches the golden output for a small model', () => {
+    const model = modelWith([getOrder, streamEvents], {
+      schemas: [
+        namedSchema('Order', {
+          kind: 'object',
+          properties: [{ name: 'id', schema: SCALAR, required: true }],
+        }),
+        ...SCHEMAS.slice(1),
+      ],
+      securitySchemes: [{ kind: 'bearer', key: 'bearerAuth' }],
+    });
+    expect(emit(model, { serverUrl: 'https://cafe.example.com' })).toMatchSnapshot();
+  });
+});
+
+describe('emitClientSingleFile (embed arm)', () => {
+  const output = emitClientSingleFile(CAFE, { serverUrl: 'https://x' });
+
+  it('embeds the runtime block instead of importing the package', () => {
+    expect(output).toContain('// ─── Embedded runtime');
+    expect(output).toContain('export class ApiError');
+    expect(output).toContain('export function createClient<\n  Ops extends OpsShape,');
+    expect(output).not.toContain("from '@redocly/client-generator'");
+  });
+
+  it('emits no re-export section — the embedded surface is already exported in place', () => {
+    expect(output).not.toContain('export { ApiError }');
+    expect(output).not.toContain('export type {');
+    expect(output).toContain('export type ClientConfig'); // from the embedded types.ts
+  });
+
+  it('embeds every capability CAFE needs: multipart, auth, and sse', () => {
+    expect(output).toContain('function toFormData');
+    expect(output).toContain('async function resolveAuth');
+    expect(output).toContain('async function* sse');
+    expect(output).toContain(
+      'createClientCore<Ops, Id, Path, Tag>(operations, config, { serializeMultipart: toFormData, resolveAuth, sse })'
+    );
+  });
+
+  it('embeds no capability module a plain model does not need', () => {
+    const out = emitClientSingleFile(modelWith([createPet], { schemas: SCHEMAS }));
+    expect(out).not.toContain('toFormData');
+    // The auth MODULE is absent; `resolveAuth` as a bare word still names the
+    // (unwired) property in create-client.ts's `Capabilities` seam type.
+    expect(out).not.toContain('async function resolveAuth');
+    expect(out).not.toContain('async function* sse');
+    expect(out).toContain('createClientCore<Ops, Id, Path, Tag>(operations, config, {})');
+  });
+
+  it('embeds resolveAuth when a descriptor carries security even without declared schemes', () => {
+    const out = emitClientSingleFile(modelWith([getOrder], { schemas: SCHEMAS }));
+    expect(out).toContain('async function resolveAuth');
+    expect(out).toContain(
+      'createClientCore<Ops, Id, Path, Tag>(operations, config, { resolveAuth })'
+    );
+  });
+
+  it('embeds mergeSetup and bakes the setup const when --setup is given', () => {
+    const out = emitClientSingleFile(modelWith([createPet], { schemas: SCHEMAS }), {
+      serverUrl: 'https://x',
+      setup: '{ config: { retry: { retries: 2 } } }',
+    });
+    expect(out).toContain('export function mergeSetup');
+    expect(out).toContain(
+      'const __redoclySetup: { config?: ClientConfig; middleware?: Middleware[] } = { config: { retry: { retries: 2 } } };'
+    );
+    // Precedence lowest→highest: spec default → baked setup (→ app configure()).
+    expect(out).toContain(
+      'export const client = createClient<Ops, OperationId, OperationPath, string>(OPERATIONS, mergeSetup({ config: { serverUrl: "https://x" } }, mergeSetup(__redoclySetup, {})));'
+    );
+  });
+
+  it('survives a spec schema named Error: runtime type positions use globalThis.Error', () => {
+    const model = modelWith([getOrder], {
+      schemas: [
+        namedSchema('Error', {
+          kind: 'object',
+          properties: [{ name: 'code', schema: SCALAR, required: true }],
+        }),
+        ...SCHEMAS,
+      ],
+    });
+    const out = emitClientSingleFile(model, { serverUrl: 'https://x' });
+    // The schema type is emitted alongside the embedded runtime in one module…
+    expect(out).toContain('export type Error =');
+    // …so every runtime TYPE-position reference to Error must be shadow-proof.
+    expect(out).toContain('export type ApiErrorLike = globalThis.Error & {');
+    expect(out).toContain('=> globalThis.Error | Promise<globalThis.Error>;');
+    expect(out).toContain('let error: globalThis.Error');
+    expect(out).toContain('function abortError(signal: AbortSignal): globalThis.Error {');
+    // VALUE positions stay bare — `globalThis.Error === Error` at runtime anyway.
+    expect(out).toContain('class ApiError extends Error');
+    // Cheap semantic gate: the assembled module parses clean.
+    const sourceFile = ts.createSourceFile('client.ts', out, ts.ScriptTarget.Latest, true);
+    expect((sourceFile as unknown as { parseDiagnostics: unknown[] }).parseDiagnostics).toEqual([]);
+  });
+
+  it('emits wiring (Ops → OPERATIONS, client → sugar) byte-identical to the package arm', () => {
+    const packaged = emit(CAFE, { serverUrl: 'https://x' });
+    // `'export type Ops ='` — the trailing `=` skips the embedded `export type OpsShape`.
+    // In embed mode the runtime block sits between OPERATIONS and `client`, so the
+    // wiring is compared as its two contiguous segments around it.
+    const slice = (out: string, from: string, to: number) => out.slice(out.indexOf(from), to);
+    expect(
+      slice(output, 'export type Ops =', output.indexOf('// ─── Embedded runtime')).trim()
+    ).toBe(slice(packaged, 'export type Ops =', packaged.indexOf('export const client')).trim());
+    expect(slice(output, 'export const client', output.length).trim()).toBe(
+      slice(packaged, 'export const client', packaged.indexOf('export { ApiError,')).trim()
+    );
+  });
+
+  // The full inline output is not snapshotted here: the runtime bytes are pinned by
+  // runtime-sources.test.ts, the wiring by the byte-identity test above, and a real
+  // full inline client by the e2e cafe.snapshot.ts.
+});
+
+describe('emitClientSingleFile — pagination', () => {
+  const PAGINATED = modelWith([listOrders, getOrder], { schemas: [...SCHEMAS, ORDER_PAGE] });
+  const config = { operations: { listOrders: CURSOR_RULE } };
+
+  it('threads a config rule into the descriptor and the Ops item member (package arm)', () => {
+    const out = emit(PAGINATED, { pagination: config });
+    expect(out).toContain(
+      'pagination: { style: "cursor", param: "cursor", nextCursor: "/nextCursor", items: "/orders" }'
+    );
+    expect(out).toMatch(
+      /listOrders: \{\n\s+args: \{\n\s+params\?: ListOrdersParams;\n\s+\};\n\s+result: ListOrdersResult;\n\s+item: Order;\n\s+\};/
+    );
+  });
+
+  it('resolves the x-pagination extension without any config', () => {
+    const model = modelWith([{ ...listOrders, paginationExtension: CURSOR_RULE }, getOrder], {
+      schemas: [...SCHEMAS, ORDER_PAGE],
+    });
+    const out = emit(model);
+    expect(out).toContain('item: Order;');
+    expect(out).toContain('pagination: { style: "cursor", param: "cursor",');
+  });
+
+  it('wraps the flat sugar in Object.assign, preserving .pages/.items', () => {
+    const out = emit(PAGINATED, { pagination: config });
+    expect(out).toContain('export const listOrders = Object.assign((params: {');
+    expect(out).toContain(
+      '} = {}, init: RequestOptions = {}) => client.listOrders({ params }, init), { pages: client.listOrders.pages, items: client.listOrders.items });'
+    );
+    // Non-paginated siblings keep the plain arrow.
+    expect(out).toContain('export const getOrder = (orderId: string, params: {');
+    expect(out).not.toContain('Object.assign((orderId');
+  });
+
+  it('grouped argsStyle needs no wrapper — properties ride along on the destructure', () => {
+    const out = emit(PAGINATED, { pagination: config, argsStyle: 'grouped' });
+    expect(out).toContain('export const { listOrders, getOrder } = client;');
+    expect(out).not.toContain('Object.assign');
+  });
+
+  it('embeds the paginate capability in inline mode only when a descriptor paginates', () => {
+    // A security-free model, so paginate is the ONLY capability in the factory wiring.
+    const model = modelWith([listOrders], { schemas: [SCHEMAS[0], ORDER_PAGE] });
+    const paginated = emitClientSingleFile(model, { pagination: config });
+    expect(paginated).toContain('async function* pages');
+    expect(paginated).toContain(
+      'createClientCore<Ops, Id, Path, Tag>(operations, config, { paginate: { pages, items } })'
+    );
+    const plain = emitClientSingleFile(model);
+    expect(plain).not.toContain('async function* pages');
+    expect(plain).toContain('createClientCore<Ops, Id, Path, Tag>(operations, config, {})');
+  });
+
+  it('throws one aggregated error for explicit rules that do not fit', () => {
+    const model = modelWith(
+      [
+        { ...listOrders, paginationExtension: { ...CURSOR_RULE, cursorParam: 'after' } },
+        {
+          ...listOrders,
+          name: 'listRefunds',
+          path: '/refunds',
+          paginationExtension: { ...CURSOR_RULE, items: '/refunds' },
+        },
+      ],
+      { schemas: [...SCHEMAS, ORDER_PAGE] }
+    );
+    expect(() => emitClientSingleFile(model)).toThrow(
+      'Invalid pagination configuration:\n' +
+        '  - Pagination for operation "listOrders" (x-pagination): ' +
+        'query parameter "after" is not declared on the operation\n' +
+        '  - Pagination for operation "listRefunds" (x-pagination): ' +
+        'the "items" pointer "/refunds" does not resolve in the success response schema'
+    );
+  });
+
+  it('matches the golden output for a paginated package client', () => {
+    expect(emit(PAGINATED, { pagination: config })).toMatchSnapshot();
+  });
+
+  it('matches the golden output for a result-mode paginated package client', () => {
+    // Result mode: the Ops entry gains `page` (the raw page `.pages()` yields) next to
+    // the envelope-wrapped `result`.
+    expect(emit(PAGINATED, { pagination: config, errorMode: 'result' })).toMatchSnapshot();
+  });
+});
diff --git a/packages/client-generator/src/emitters/__tests__/descriptor.test.ts b/packages/client-generator/src/emitters/__tests__/descriptor.test.ts
new file mode 100644
index 0000000000..dc88b5e657
--- /dev/null
+++ b/packages/client-generator/src/emitters/__tests__/descriptor.test.ts
@@ -0,0 +1,606 @@
+import type {
+  ApiModel,
+  OperationModel,
+  ResponseBodyModel,
+} from '../../intermediate-representation/model.js';
+import { descriptorStatements, opsInterfaceStatements, packageIdents } from '../descriptor.js';
+import type { EmitContext } from '../operations.js';
+import type { ModelPagination } from '../pagination.js';
+import { printStatements } from '../ts.js';
+import { apiModel, modelWith, operation, param } from './fixtures.js';
+
+function emitDescriptors(model: ApiModel): string {
+  return printStatements(descriptorStatements(model, packageIdents(model), 'string'));
+}
+
+/** A JSON 200 response — keeps `responseKind` at its omitted `'json'` default. */
+const JSON_OK: ResponseBodyModel = {
+  contentType: 'application/json',
+  schema: { kind: 'ref', name: 'Pong' },
+  status: 200,
+};
+
+describe('packageIdents', () => {
+  it('renames colliding operation ids deterministically', () => {
+    const model = modelWith(
+      [
+        operation({ name: 'configure' }),
+        operation({ name: 'createClient' }),
+        operation({ name: 'setBearer' }),
+      ],
+      {
+        securitySchemes: [{ kind: 'bearer', key: 'bearerAuth' }],
+      }
+    );
+    const idents = packageIdents(model);
+    expect(idents.get('configure')).toBe('configure_2');
+    expect(idents.get('createClient')).toBe('createClient_2');
+    expect(idents.get('setBearer')).toBe('setBearer_2'); // auth sugar seeded first
+  });
+
+  it('keeps non-colliding names and sanitizes non-identifier ones', () => {
+    const idents = packageIdents(
+      modelWith([operation({ name: 'ping' }), operation({ name: 'get-thing' })])
+    );
+    expect(idents.get('ping')).toBe('ping');
+    expect(idents.get('get-thing')).toBe('get_thing');
+  });
+
+  it('reserves the TokenProvider import and the __redoclySetup const', () => {
+    const idents = packageIdents(
+      modelWith([operation({ name: 'TokenProvider' }), operation({ name: '__redoclySetup' })])
+    );
+    expect(idents.get('TokenProvider')).toBe('TokenProvider_2');
+    expect(idents.get('__redoclySetup')).toBe('__redoclySetup_2');
+  });
+});
+
+describe('descriptorStatements', () => {
+  it('returns no statements for a model with no operations', () => {
+    expect(descriptorStatements(apiModel(), new Map(), 'string')).toEqual([]);
+  });
+
+  it('emits a minimal descriptor with only the non-default fields', () => {
+    const out = emitDescriptors(
+      modelWith([operation({ name: 'ping', path: '/ping', successResponses: [JSON_OK] })])
+    );
+    expect(out).toContain('ping: { id: "ping", method: "GET", path: "/ping" }');
+    expect(out).toContain('as const satisfies Record<string, OperationDescriptor>;');
+    expect(out).not.toContain('tags:');
+    expect(out).not.toContain('params:');
+    expect(out).not.toContain('responseKind:');
+  });
+
+  it('matches the full minimal output', () => {
+    expect(
+      emitDescriptors(
+        modelWith([operation({ name: 'ping', path: '/ping', successResponses: [JSON_OK] })])
+      )
+    ).toMatchInlineSnapshot(`
+        "/**
+         * The wire-shape descriptor for every operation, keyed by operationId — the data the
+         * runtime routes requests by. Also minification-safe static metadata (method, path,
+         * tags) for cache keys, tracing span names, and request logging.
+         */
+        export const OPERATIONS = {
+            ping: { id: "ping", method: "GET", path: "/ping" }
+        } as const satisfies Record<string, OperationDescriptor>;
+
+        export type OperationId = keyof typeof OPERATIONS;
+
+        export type OperationPath = (typeof OPERATIONS)[OperationId]["path"];"
+      `);
+  });
+
+  it('keys a renamed operation by its emitted identifier but ids it by the spec operationId', () => {
+    // `id` drives middleware targeting (`ctx.operation.id`), so it stays the spec's
+    // operationId — matching inline mode's `operationMetaExpr` — even when the key is renamed.
+    const out = emitDescriptors(
+      modelWith([operation({ name: 'configure', path: '/c', successResponses: [JSON_OK] })])
+    );
+    expect(out).toContain('configure_2: { id: "configure", method: "GET", path: "/c" }');
+  });
+
+  it('keeps id/params/security intact on a renamed operation', () => {
+    const out = emitDescriptors(
+      modelWith(
+        [
+          operation({
+            name: 'use',
+            path: '/u/{id}',
+            pathParams: [param('id', 'path', true)],
+            security: [['bearerAuth']],
+            successResponses: [JSON_OK],
+          }),
+        ],
+        { securitySchemes: [{ kind: 'bearer', key: 'bearerAuth' }] }
+      )
+    );
+    expect(out).toContain(
+      'use_2: { id: "use", method: "GET", path: "/u/{id}", params: [{ name: "id", in: "path" }], security: [[{ scheme: "bearerAuth", kind: "bearer" }]] }'
+    );
+  });
+
+  it('records a non-identifier path param by its quoted wire name', () => {
+    const out = emitDescriptors(
+      modelWith([
+        operation({
+          name: 'getPet',
+          path: '/pets/{pet-id}',
+          pathParams: [param('pet-id', 'path', true)],
+          successResponses: [JSON_OK],
+        }),
+      ])
+    );
+    expect(out).toContain('params: [{ name: "pet-id", in: "path" }]');
+    expect(out).not.toContain('pet_id');
+  });
+
+  it('emits params with in/style/explode/allowReserved only when present', () => {
+    const out = emitDescriptors(
+      modelWith([
+        operation({
+          name: 'getOrder',
+          path: '/orders/{orderId}',
+          pathParams: [param('orderId', 'path', true)],
+          queryParams: [
+            { ...param('tags', 'query', false), style: 'pipeDelimited', explode: false },
+            { ...param('q', 'query', false), allowReserved: true },
+            param('limit', 'query', false),
+          ],
+          headerParams: [param('X-Trace', 'header', false)],
+        }),
+      ])
+    );
+    expect(out).toContain('{ name: "orderId", in: "path" }');
+    expect(out).toContain('{ name: "tags", in: "query", style: "pipeDelimited", explode: false }');
+    expect(out).toContain('{ name: "q", in: "query", allowReserved: true }');
+    expect(out).toContain('{ name: "limit", in: "query" }');
+    expect(out).toContain('{ name: "X-Trace", in: "header" }');
+  });
+
+  it('derives body.multipart, responseKind, and sseDataKind', () => {
+    const multipart = emitDescriptors(
+      modelWith([
+        operation({
+          name: 'upload',
+          method: 'post',
+          requestBody: {
+            contentType: 'multipart/form-data',
+            required: true,
+            schema: { kind: 'object', properties: [] },
+          },
+        }),
+      ])
+    );
+    expect(multipart).toContain('body: { contentType: "multipart/form-data", multipart: true }');
+
+    const json = emitDescriptors(
+      modelWith([
+        operation({
+          name: 'create',
+          method: 'post',
+          requestBody: {
+            contentType: 'application/json',
+            required: true,
+            schema: { kind: 'ref', name: 'Pet' },
+          },
+          successResponses: [
+            { contentType: 'application/json', schema: { kind: 'ref', name: 'Pet' }, status: 200 },
+          ],
+        }),
+      ])
+    );
+    expect(json).toContain('body: { contentType: "application/json" }');
+    expect(json).not.toContain('multipart');
+    expect(json).not.toContain('responseKind'); // json is the default
+
+    const text = emitDescriptors(
+      modelWith([
+        operation({
+          name: 'readme',
+          successResponses: [
+            {
+              contentType: 'text/plain',
+              schema: { kind: 'scalar', scalar: 'string' },
+              status: 200,
+            },
+          ],
+        }),
+      ])
+    );
+    expect(text).toContain('responseKind: "text"');
+
+    const none = emitDescriptors(modelWith([operation({ name: 'drop', method: 'delete' })]));
+    expect(none).toContain('responseKind: "void"');
+
+    const blob = emitDescriptors(
+      modelWith([
+        operation({
+          name: 'getPhoto',
+          successResponses: [
+            { contentType: 'image/png', schema: { kind: 'unknown' }, status: 200 },
+          ],
+        }),
+      ])
+    );
+    expect(blob).toContain('responseKind: "blob"');
+
+    const sse = emitDescriptors(
+      modelWith([
+        operation({
+          name: 'streamEvents',
+          successResponses: [
+            {
+              contentType: 'text/event-stream',
+              schema: { kind: 'object', properties: [] },
+              status: 200,
+            },
+          ],
+        }),
+      ])
+    );
+    expect(sse).toContain('responseKind: "sse"');
+    expect(sse).toContain('sseDataKind: "json"');
+  });
+
+  it('denormalizes security from the model schemes, skipping unknown keys', () => {
+    const out = emitDescriptors(
+      modelWith(
+        [operation({ name: 'getOrder', security: [['bearerAuth', 'apiCookie', 'ghost']] })],
+        {
+          securitySchemes: [
+            { kind: 'bearer', key: 'bearerAuth' },
+            { kind: 'apiKeyCookie', key: 'apiCookie', cookieName: 'sid' },
+          ],
+        }
+      )
+    );
+    expect(out).toContain(
+      'security: [[{ scheme: "bearerAuth", kind: "bearer" }, { scheme: "apiCookie", kind: "apiKey", name: "sid", in: "cookie" }]]'
+    );
+    expect(out).not.toContain('ghost');
+  });
+
+  it('covers basic, apiKey header, and apiKey query schemes', () => {
+    const out = emitDescriptors(
+      modelWith(
+        [operation({ name: 'getOrder', security: [['basicAuth', 'apiHeader', 'apiQuery']] })],
+        {
+          securitySchemes: [
+            { kind: 'basic', key: 'basicAuth' },
+            { kind: 'apiKeyHeader', key: 'apiHeader', headerName: 'X-Key' },
+            { kind: 'apiKeyQuery', key: 'apiQuery', paramName: 'api_key' },
+          ],
+        }
+      )
+    );
+    expect(out).toContain('{ scheme: "basicAuth", kind: "basic" }');
+    expect(out).toContain('{ scheme: "apiHeader", kind: "apiKey", name: "X-Key", in: "header" }');
+    expect(out).toContain('{ scheme: "apiQuery", kind: "apiKey", name: "api_key", in: "query" }');
+  });
+
+  it('emits tags and the derived OperationId/OperationPath/OperationTag unions', () => {
+    const out = emitDescriptors(
+      modelWith([
+        operation({ name: 'listPets', path: '/pets', tags: ['Pets'] }),
+        operation({ name: 'ping', path: '/ping' }),
+      ])
+    );
+    expect(out).toContain('tags: ["Pets"]');
+    expect(out).toContain('export type OperationId = keyof typeof OPERATIONS;');
+    expect(out).toContain('export type OperationPath = (typeof OPERATIONS)[OperationId]["path"];');
+    // `tags` is present only on tagged entries, so the union is derived via Extract —
+    // a plain ["tags"] index would not compile against the untagged entries.
+    expect(out).toContain(
+      'export type OperationTag = Extract<(typeof OPERATIONS)[OperationId], {\n' +
+        '    tags: readonly string[];\n' +
+        '}>["tags"][number];'
+    );
+  });
+
+  it('omits OperationTag when no operation has a tag (avoids never)', () => {
+    const out = emitDescriptors(modelWith([operation({ name: 'ping' })]));
+    expect(out).toContain('export type OperationId');
+    expect(out).toContain('export type OperationPath');
+    expect(out).not.toContain('OperationTag');
+  });
+
+  it('emits the resolved pagination spec with stable key order, only on resolved ops', () => {
+    const model = modelWith([
+      operation({
+        name: 'listOrders',
+        path: '/orders',
+        queryParams: [param('cursor', 'query', false)],
+        successResponses: [JSON_OK],
+      }),
+      operation({ name: 'ping', path: '/ping', successResponses: [JSON_OK] }),
+    ]);
+    const pagination: ModelPagination = new Map([
+      [
+        'listOrders',
+        {
+          spec: {
+            style: 'cursor',
+            param: 'cursor',
+            limitParam: 'limit',
+            nextCursor: '/nextCursor',
+            items: '/orders',
+          },
+          itemSchema: { kind: 'ref', name: 'Order' },
+        },
+      ],
+    ]);
+    const out = printStatements(
+      descriptorStatements(model, packageIdents(model), 'string', pagination)
+    );
+    expect(out).toContain(
+      'pagination: { style: "cursor", param: "cursor", limitParam: "limit", nextCursor: "/nextCursor", items: "/orders" }'
+    );
+    // Non-paginated entries carry no pagination field.
+    expect(out).toContain('ping: { id: "ping", method: "GET", path: "/ping" }');
+  });
+});
+
+describe('opsInterfaceStatements', () => {
+  function emitOps(model: ApiModel, extra: Partial<EmitContext> = {}): string {
+    const ctx: EmitContext = {
+      argsStyle: 'flat',
+      errorMode: 'throw',
+      dateType: 'string',
+      schemaNames: new Set(),
+      ...extra,
+    };
+    return printStatements(opsInterfaceStatements(model, packageIdents(model), ctx));
+  }
+
+  const getOrder = operation({
+    name: 'getOrder',
+    path: '/orders/{orderId}',
+    pathParams: [param('orderId', 'path', true)],
+    successResponses: [
+      { contentType: 'application/json', schema: { kind: 'ref', name: 'Order' }, status: 200 },
+    ],
+  });
+  const streamOrders = operation({
+    name: 'streamOrders',
+    path: '/orders/stream',
+    successResponses: [
+      {
+        contentType: 'text/event-stream',
+        schema: { kind: 'ref', name: 'OrderEvent' },
+        status: 200,
+      },
+    ],
+  });
+
+  it('returns no statements for a model with no operations', () => {
+    expect(emitOps(modelWith([]))).toBe('');
+  });
+
+  it('emits per-operation args (via the Variables shape) and result members', () => {
+    const out = emitOps(
+      modelWith([
+        operation({
+          name: 'getOrder',
+          path: '/orders/{orderId}',
+          pathParams: [param('orderId', 'path', true)],
+          queryParams: [param('include', 'query', false)],
+          successResponses: [
+            {
+              contentType: 'application/json',
+              schema: { kind: 'ref', name: 'Order' },
+              status: 200,
+            },
+          ],
+        }),
+      ])
+    );
+    expect(out).toContain('export type Ops = {');
+    expect(out).toMatch(
+      /getOrder: \{\n {8}args: \{\n {12}orderId: string;\n {12}params\?: GetOrderParams;\n {8}\};\n {8}result: GetOrderResult;\n {4}\};/
+    );
+    expect(out).not.toContain('kind: "sse"');
+  });
+
+  it('keys args path params by wire name, quoted when not identifier-safe', () => {
+    // The runtime routes path values by wire name (`splitArgs` reads `args[param.name]`),
+    // so the args type must key them the same way — never by the sanitized ident.
+    const out = emitOps(
+      modelWith([
+        operation({
+          name: 'getPet',
+          path: '/pets/{pet-id}',
+          pathParams: [param('pet-id', 'path', true)],
+        }),
+      ])
+    );
+    expect(out).toContain('"pet-id": string;');
+    expect(out).not.toContain('pet_id');
+  });
+
+  it('keeps path params that sanitize to the same ident distinct via their wire names', () => {
+    const out = emitOps(
+      modelWith([
+        operation({
+          name: 'compare',
+          path: '/x/{a-b}/{a.b}',
+          pathParams: [param('a-b', 'path', true), param('a.b', 'path', true)],
+        }),
+      ])
+    );
+    expect(out).toContain('"a-b": string;');
+    expect(out).toContain('"a.b": string;');
+    expect(out).not.toContain('a_b');
+  });
+
+  it('emits args: {} for a no-input operation', () => {
+    const out = emitOps(modelWith([operation({ name: 'ping' })]));
+    expect(out).toContain('ping: {\n        args: {};');
+    expect(out).toContain('result: PingResult;');
+  });
+
+  it('inlines the response type when the <Op>Result alias collides with a schema', () => {
+    const out = emitOps(modelWith([getOrder]), { schemaNames: new Set(['GetOrderResult']) });
+    expect(out).toContain('result: Order;');
+    expect(out).not.toContain('GetOrderResult');
+  });
+
+  it('keys members by the collision-renamed identifier', () => {
+    const out = emitOps(modelWith([operation({ name: 'configure' })]));
+    expect(out).toContain('configure_2: {');
+  });
+
+  it('wraps the result in Result<…, <Op>Error> in result mode', () => {
+    const out = emitOps(
+      modelWith([
+        operation({
+          ...getOrder,
+          errorResponses: [
+            {
+              contentType: 'application/json',
+              schema: { kind: 'ref', name: 'Problem' },
+              status: 404,
+            },
+          ],
+        }),
+      ]),
+      { errorMode: 'result' }
+    );
+    expect(out).toContain('result: Result<GetOrderResult, GetOrderError>;');
+  });
+
+  it('falls back to unknown in result mode when the op declares no error responses', () => {
+    const out = emitOps(modelWith([getOrder]), { errorMode: 'result' });
+    expect(out).toContain('result: Result<GetOrderResult, unknown>;');
+  });
+
+  it('inlines the error type when the <Op>Error alias collides with a schema', () => {
+    const errored = (errorResponses: OperationModel['errorResponses']) =>
+      operation({ ...getOrder, errorResponses });
+    const single = emitOps(
+      modelWith([
+        errored([
+          { contentType: 'application/json', schema: { kind: 'ref', name: 'E1' }, status: 400 },
+        ]),
+      ]),
+      { errorMode: 'result', schemaNames: new Set(['GetOrderError']) }
+    );
+    expect(single).toContain('result: Result<GetOrderResult, E1>;');
+
+    const union = emitOps(
+      modelWith([
+        errored([
+          { contentType: 'application/json', schema: { kind: 'ref', name: 'E1' }, status: 400 },
+          { contentType: 'application/json', schema: { kind: 'ref', name: 'E2' }, status: 500 },
+        ]),
+      ]),
+      { errorMode: 'result', schemaNames: new Set(['GetOrderError']) }
+    );
+    expect(union).toContain('result: Result<GetOrderResult, E1 | E2>;');
+  });
+
+  it('types an SSE op with the event payload and kind: "sse", never a Result wrapper', () => {
+    const out = emitOps(modelWith([streamOrders]), { errorMode: 'result' });
+    expect(out).toMatch(
+      /streamOrders: \{\n {8}args: \{\};\n {8}result: OrderEvent;\n {8}kind: "sse";\n {4}\};/
+    );
+    expect(out).not.toContain('Result<');
+  });
+
+  it('adds an item member (the page element type) only to paginated operations', () => {
+    const listOrders = operation({
+      name: 'listOrders',
+      path: '/orders',
+      queryParams: [param('cursor', 'query', false)],
+      successResponses: [
+        {
+          contentType: 'application/json',
+          schema: { kind: 'ref', name: 'OrderPage' },
+          status: 200,
+        },
+      ],
+    });
+    const pagination: ModelPagination = new Map([
+      [
+        'listOrders',
+        {
+          spec: { style: 'cursor', param: 'cursor', nextCursor: '/nextCursor', items: '/orders' },
+          itemSchema: { kind: 'ref', name: 'Order' },
+        },
+      ],
+    ]);
+    const out = emitOps(modelWith([listOrders, getOrder]), { pagination });
+    expect(out).toMatch(
+      /listOrders: \{\n {8}args: \{\n {12}params\?: ListOrdersParams;\n {8}\};\n {8}result: ListOrdersResult;\n {8}item: Order;\n {4}\};/
+    );
+    // The non-paginated sibling stays untouched.
+    expect(out).toMatch(
+      /getOrder: \{\n {8}args: \{\n {12}orderId: string;\n {8}\};\n {8}result: GetOrderResult;\n {4}\};/
+    );
+  });
+
+  it('adds a page member (the RAW page type) to paginated operations in result mode only', () => {
+    const listOrders = operation({
+      name: 'listOrders',
+      path: '/orders',
+      queryParams: [param('cursor', 'query', false)],
+      successResponses: [
+        {
+          contentType: 'application/json',
+          schema: { kind: 'ref', name: 'OrderPage' },
+          status: 200,
+        },
+      ],
+    });
+    const pagination: ModelPagination = new Map([
+      [
+        'listOrders',
+        {
+          spec: { style: 'cursor', param: 'cursor', nextCursor: '/nextCursor', items: '/orders' },
+          itemSchema: { kind: 'ref', name: 'Order' },
+        },
+      ],
+    ]);
+    // Result mode: `result` is the envelope, so `page` carries the raw page for `.pages()`.
+    const out = emitOps(modelWith([listOrders]), { pagination, errorMode: 'result' });
+    expect(out).toMatch(
+      /listOrders: \{\n {8}args: \{\n {12}params\?: ListOrdersParams;\n {8}\};\n {8}result: Result<ListOrdersResult, unknown>;\n {8}item: Order;\n {8}page: ListOrdersResult;\n {4}\};/
+    );
+    // Throw mode emits no page member — `result` already IS the raw page.
+    expect(emitOps(modelWith([listOrders]), { pagination })).not.toContain('page:');
+    // The page member reuses the suppression-aware alias reference: a colliding
+    // `<Op>Result` alias inlines the raw response type instead.
+    const suppressed = emitOps(modelWith([listOrders]), {
+      pagination,
+      errorMode: 'result',
+      schemaNames: new Set(['ListOrdersResult']),
+    });
+    expect(suppressed).toContain('result: Result<OrderPage, unknown>;');
+    expect(suppressed).toContain('page: OrderPage;');
+  });
+
+  it('types item with the shared dateType handling', () => {
+    const listOrders = operation({
+      name: 'listOrders',
+      path: '/orders',
+      queryParams: [param('page', 'query', false)],
+      successResponses: [JSON_OK],
+    });
+    const pagination: ModelPagination = new Map([
+      [
+        'listOrders',
+        {
+          spec: { style: 'page', param: 'page', items: '/orders' },
+          itemSchema: {
+            kind: 'scalar',
+            scalar: 'string',
+            metadata: { format: 'date-time' },
+          },
+        },
+      ],
+    ]);
+    const out = emitOps(modelWith([listOrders]), { pagination, dateType: 'Date' });
+    expect(out).toContain('item: Date;');
+  });
+});
diff --git a/packages/client-generator/src/emitters/__tests__/emit-options.test.ts b/packages/client-generator/src/emitters/__tests__/emit-options.test.ts
new file mode 100644
index 0000000000..1e2cae931f
--- /dev/null
+++ b/packages/client-generator/src/emitters/__tests__/emit-options.test.ts
@@ -0,0 +1,40 @@
+import { banner, HEADER, renderTitleComment } from '../emit-options.js';
+import { apiModel } from './fixtures.js';
+
+describe('banner', () => {
+  it('joins non-empty sections with blank lines and appends a trailing newline', () => {
+    expect(banner(['a', 'b'])).toBe('a\n\nb\n');
+  });
+
+  it('drops empty sections so no double separators appear', () => {
+    expect(banner(['a', '', 'b'])).toBe('a\n\nb\n');
+  });
+});
+
+describe('HEADER', () => {
+  it('names the generator and the regeneration command', () => {
+    expect(HEADER).toContain('Generated by @redocly/client-generator');
+    expect(HEADER).toContain('redocly generate-client');
+  });
+});
+
+describe('renderTitleComment', () => {
+  it('emits a JSDoc block with the title and version', () => {
+    const out = renderTitleComment(apiModel({ title: 'My API', version: '2.0.0' }));
+    expect(out).toBe('/**\n * My API (v2.0.0)\n */');
+  });
+
+  it('appends multi-line descriptions in the block', () => {
+    const out = renderTitleComment(apiModel({ title: 'D', description: 'line one\nline two' }));
+    expect(out).toContain(' * line one');
+    expect(out).toContain(' * line two');
+  });
+
+  it('escapes `*/` in attacker-controllable title/description text', () => {
+    const out = renderTitleComment(
+      apiModel({ title: 'X */ alert(1) /*', description: 'desc */ boom' })
+    );
+    // The comment must not be closable from inside.
+    expect(out.slice(3, -2)).not.toContain('*/');
+  });
+});
diff --git a/packages/client-generator/src/emitters/__tests__/faker.test.ts b/packages/client-generator/src/emitters/__tests__/faker.test.ts
new file mode 100644
index 0000000000..c84229dfab
--- /dev/null
+++ b/packages/client-generator/src/emitters/__tests__/faker.test.ts
@@ -0,0 +1,333 @@
+import type { NamedSchemaModel, SchemaModel } from '../../intermediate-representation/model.js';
+import { fakerExpression } from '../faker.js';
+import { printNodes } from '../ts.js';
+
+/** Emit `schema`'s faker expression and print it to source for substring assertions. */
+function emit(
+  schema: SchemaModel,
+  schemas: NamedSchemaModel[] = [],
+  dateType?: 'string' | 'Date'
+): string {
+  return printNodes([fakerExpression(schema, schemas, { dateType })]);
+}
+
+describe('fakerExpression', () => {
+  it('maps a boolean scalar to faker.datatype.boolean()', () => {
+    expect(emit({ kind: 'scalar', scalar: 'boolean' })).toContain('faker.datatype.boolean()');
+  });
+
+  it('maps an integer scalar to faker.number.int()', () => {
+    expect(emit({ kind: 'scalar', scalar: 'integer' })).toBe('faker.number.int()');
+  });
+
+  it('passes { min, max } to faker.number.int when bounds are present', () => {
+    const out = emit({ kind: 'scalar', scalar: 'integer', metadata: { minimum: 1, maximum: 9 } });
+    expect(out).toContain('faker.number.int(');
+    expect(out).toContain('min: 1');
+    expect(out).toContain('max: 9');
+  });
+
+  it('maps a number scalar to faker.number.float(), respecting bounds', () => {
+    expect(emit({ kind: 'scalar', scalar: 'number' })).toBe('faker.number.float()');
+    const out = emit({ kind: 'scalar', scalar: 'number', metadata: { minimum: 0, maximum: 1 } });
+    expect(out).toContain('faker.number.float(');
+    expect(out).toContain('min: 0');
+    expect(out).toContain('max: 1');
+  });
+
+  it('maps string formats to the matching faker call', () => {
+    const str = (format: string) =>
+      emit({ kind: 'scalar', scalar: 'string', metadata: { format } });
+    expect(str('email')).toBe('faker.internet.email()');
+    expect(str('uuid')).toBe('faker.string.uuid()');
+    expect(str('uri')).toBe('faker.internet.url()');
+    expect(str('url')).toBe('faker.internet.url()');
+    expect(str('hostname')).toBe('faker.internet.domainName()');
+    expect(str('ipv4')).toBe('faker.internet.ipv4()');
+  });
+
+  it('maps date-time/date to faker.date.recent() honoring dateType', () => {
+    const dt = { kind: 'scalar', scalar: 'string', metadata: { format: 'date-time' } } as const;
+    const d = { kind: 'scalar', scalar: 'string', metadata: { format: 'date' } } as const;
+    expect(emit(dt, [], 'Date')).toBe('faker.date.recent()');
+    expect(emit(dt, [], 'string')).toBe('faker.date.recent().toISOString()');
+    expect(emit(d, [], 'Date')).toBe('faker.date.recent()');
+    expect(emit(d, [], 'string')).toBe('faker.date.recent().toISOString().slice(0, 10)');
+  });
+
+  it('maps a binary field to new Blob([]) (faker cannot make a Blob)', () => {
+    expect(emit({ kind: 'scalar', scalar: 'string', metadata: { format: 'binary' } })).toBe(
+      'new Blob([])'
+    );
+  });
+
+  it('falls back to faker.lorem.word() for a plain string', () => {
+    expect(emit({ kind: 'scalar', scalar: 'string' })).toBe('faker.lorem.word()');
+  });
+
+  it('maps an enum to faker.helpers.arrayElement([...] as const)', () => {
+    const out = emit({ kind: 'enum', scalar: 'string', values: ['a', 'b'] });
+    expect(out).toContain('faker.helpers.arrayElement(');
+    expect(out).toContain('"a"');
+    expect(out).toContain('"b"');
+    expect(out).toContain('as const');
+  });
+
+  it('emits a literal value as-is (a const cannot be randomized)', () => {
+    expect(emit({ kind: 'literal', value: 'fixed' })).toBe('"fixed"');
+    expect(emit({ kind: 'literal', value: 42 })).toBe('42');
+    expect(emit({ kind: 'literal', value: -3 })).toBe('-3');
+    expect(emit({ kind: 'literal', value: true })).toBe('true');
+  });
+
+  it('maps an array to faker.helpers.multiple(() => <item>, { count: 1 })', () => {
+    const out = emit({ kind: 'array', items: { kind: 'scalar', scalar: 'boolean' } });
+    expect(out).toContain('faker.helpers.multiple(');
+    expect(out).toContain('faker.datatype.boolean()');
+    expect(out).toContain('count: 1');
+  });
+
+  it('maps an object to an object literal of per-property faker exprs', () => {
+    const out = emit({
+      kind: 'object',
+      properties: [
+        { name: 'id', schema: { kind: 'scalar', scalar: 'integer' }, required: true },
+        { name: 'x-h', schema: { kind: 'scalar', scalar: 'string' }, required: true },
+      ],
+    });
+    expect(out).toContain('id: faker.number.int()');
+    expect(out).toContain('"x-h": faker.lorem.word()');
+  });
+
+  it('maps a record to { key: <value expr> }', () => {
+    const out = emit({ kind: 'record', value: { kind: 'scalar', scalar: 'boolean' } });
+    expect(out).toContain('key: faker.datatype.boolean()');
+  });
+
+  it('uses the first member of a union', () => {
+    const out = emit({
+      kind: 'union',
+      members: [
+        { kind: 'scalar', scalar: 'boolean' },
+        { kind: 'scalar', scalar: 'integer' },
+      ],
+    });
+    expect(out).toBe('faker.datatype.boolean()');
+  });
+
+  it('emits null for an empty union', () => {
+    expect(emit({ kind: 'union', members: [] })).toBe('null');
+  });
+
+  it('merges object members of an intersection', () => {
+    const out = emit({
+      kind: 'intersection',
+      members: [
+        {
+          kind: 'object',
+          properties: [
+            { name: 'a', schema: { kind: 'scalar', scalar: 'boolean' }, required: true },
+          ],
+        },
+        {
+          kind: 'object',
+          properties: [
+            { name: 'b', schema: { kind: 'scalar', scalar: 'integer' }, required: true },
+          ],
+        },
+        // a non-object member contributes nothing
+        { kind: 'scalar', scalar: 'string' },
+      ],
+    });
+    expect(out).toContain('a: faker.datatype.boolean()');
+    expect(out).toContain('b: faker.number.int()');
+    expect(out).not.toContain('faker.lorem.word()');
+  });
+
+  it('resolves a ref and inlines its faker expr', () => {
+    const schemas: NamedSchemaModel[] = [
+      {
+        name: 'Pet',
+        schema: {
+          kind: 'object',
+          properties: [
+            { name: 'id', schema: { kind: 'scalar', scalar: 'integer' }, required: true },
+          ],
+        },
+      },
+    ];
+    const out = emit({ kind: 'ref', name: 'Pet' }, schemas);
+    expect(out).toContain('id: faker.number.int()');
+    // Inlined — NOT a createPet() factory call (that would infinitely recurse on cycles).
+    expect(out).not.toContain('createPet');
+  });
+
+  it('emits null for an unresolvable ref', () => {
+    expect(emit({ kind: 'ref', name: 'Missing' }, [])).toBe('null');
+  });
+
+  it('terminates a cyclic ref with null', () => {
+    const schemas: NamedSchemaModel[] = [
+      {
+        name: 'Node',
+        schema: {
+          kind: 'object',
+          properties: [
+            { name: 'value', schema: { kind: 'scalar', scalar: 'integer' }, required: true },
+            { name: 'next', schema: { kind: 'ref', name: 'Node' }, required: true },
+          ],
+        },
+      },
+    ];
+    const out = emit({ kind: 'ref', name: 'Node' }, schemas);
+    expect(out).toContain('value: faker.number.int()');
+    expect(out).toContain('next: null');
+  });
+
+  it('terminates a cyclic ref behind an ARRAY with an empty array (a valid `T[]`, not `[null]`)', () => {
+    const schemas: NamedSchemaModel[] = [
+      {
+        name: 'Category',
+        schema: {
+          kind: 'object',
+          properties: [
+            { name: 'id', schema: { kind: 'scalar', scalar: 'integer' }, required: true },
+            {
+              name: 'children',
+              schema: { kind: 'array', items: { kind: 'ref', name: 'Category' } },
+              required: true,
+            },
+          ],
+        },
+      },
+    ];
+    const out = emit({ kind: 'ref', name: 'Category' }, schemas);
+    expect(out).toContain('children: []');
+    expect(out).not.toContain('null');
+  });
+
+  it('terminates a cyclic ref behind an OPTIONAL property by omitting it', () => {
+    const schemas: NamedSchemaModel[] = [
+      {
+        name: 'Node',
+        schema: {
+          kind: 'object',
+          properties: [
+            { name: 'value', schema: { kind: 'scalar', scalar: 'integer' }, required: true },
+            { name: 'next', schema: { kind: 'ref', name: 'Node' }, required: false },
+          ],
+        },
+      },
+    ];
+    const out = emit({ kind: 'ref', name: 'Node' }, schemas);
+    expect(out).toContain('value: faker.number.int()');
+    expect(out).not.toContain('next');
+  });
+
+  it('terminates a cyclic ref behind a RECORD with an empty object', () => {
+    const schemas: NamedSchemaModel[] = [
+      {
+        name: 'Tree',
+        schema: {
+          kind: 'object',
+          properties: [
+            {
+              name: 'nodes',
+              schema: { kind: 'record', value: { kind: 'ref', name: 'Tree' } },
+              required: true,
+            },
+          ],
+        },
+      },
+    ];
+    const out = emit({ kind: 'ref', name: 'Tree' }, schemas);
+    expect(out).toContain('nodes: {}');
+    expect(out).not.toContain('null');
+  });
+
+  it('resolves a self-referential union with no inhabitable member to null', () => {
+    const schemas: NamedSchemaModel[] = [
+      { name: 'A', schema: { kind: 'union', members: [{ kind: 'ref', name: 'A' }] } },
+    ];
+    expect(emit({ kind: 'ref', name: 'A' }, schemas)).toBe('null');
+  });
+
+  it('builds an omit as the base faker expr minus the dropped keys', () => {
+    const schemas: NamedSchemaModel[] = [
+      {
+        name: 'Pet',
+        schema: {
+          kind: 'object',
+          properties: [
+            { name: 'id', schema: { kind: 'scalar', scalar: 'integer' }, required: true },
+            { name: 'name', schema: { kind: 'scalar', scalar: 'string' }, required: true },
+          ],
+        },
+      },
+    ];
+    const out = emit({ kind: 'omit', base: 'Pet', keys: ['id'] }, schemas);
+    expect(out).toContain('name: faker.lorem.word()');
+    expect(out).not.toContain('id:');
+  });
+
+  it('emits null for an omit whose base is unresolvable', () => {
+    expect(emit({ kind: 'omit', base: 'Missing', keys: [] }, [])).toBe('null');
+  });
+
+  it('emits the base expr unchanged for an omit whose base is not an object', () => {
+    const schemas: NamedSchemaModel[] = [
+      { name: 'Name', schema: { kind: 'scalar', scalar: 'string' } },
+    ];
+    expect(emit({ kind: 'omit', base: 'Name', keys: ['x'] }, schemas)).toBe('faker.lorem.word()');
+  });
+
+  it('emits null for null and unknown schemas', () => {
+    expect(emit({ kind: 'null' })).toBe('null');
+    expect(emit({ kind: 'unknown' })).toBe('null');
+  });
+
+  it('ignores example/default (faker mode generates data)', () => {
+    const out = emit({ kind: 'scalar', scalar: 'string', metadata: { example: 'ignored' } });
+    expect(out).toBe('faker.lorem.word()');
+  });
+
+  it('defaults dateType to string when opts is omitted', () => {
+    const out = printNodes([
+      fakerExpression({ kind: 'scalar', scalar: 'string', metadata: { format: 'date-time' } }, []),
+    ]);
+    expect(out).toBe('faker.date.recent().toISOString()');
+  });
+
+  it('renders boolean enum values as literals', () => {
+    const out = emit({ kind: 'enum', scalar: 'boolean', values: [true, false] });
+    expect(out).toContain('true');
+    expect(out).toContain('false');
+  });
+
+  it('drops a quoted (non-identifier) key from an omit', () => {
+    const schemas: NamedSchemaModel[] = [
+      {
+        name: 'Trace',
+        schema: {
+          kind: 'object',
+          properties: [
+            { name: 'x-id', schema: { kind: 'scalar', scalar: 'string' }, required: true },
+            { name: 'ok', schema: { kind: 'scalar', scalar: 'boolean' }, required: true },
+          ],
+        },
+      },
+    ];
+    const out = emit({ kind: 'omit', base: 'Trace', keys: ['x-id'] }, schemas);
+    expect(out).not.toContain('x-id');
+    expect(out).toContain('ok: faker.datatype.boolean()');
+  });
+
+  it('still honors a binary type-demand over an example', () => {
+    const out = emit({
+      kind: 'scalar',
+      scalar: 'string',
+      metadata: { format: 'binary', example: 'ignored' },
+    });
+    expect(out).toBe('new Blob([])');
+  });
+});
diff --git a/packages/client-generator/src/emitters/__tests__/fixtures.ts b/packages/client-generator/src/emitters/__tests__/fixtures.ts
new file mode 100644
index 0000000000..6e57e09f58
--- /dev/null
+++ b/packages/client-generator/src/emitters/__tests__/fixtures.ts
@@ -0,0 +1,77 @@
+import type {
+  ApiModel,
+  NamedSchemaModel,
+  OperationModel,
+  ParamModel,
+  ResponseBodyModel,
+  SchemaModel,
+} from '../../intermediate-representation/model.js';
+import { emitClientSingleFile } from '../client-assembly.js';
+
+/** A plain `string` scalar — the default schema for params and the most-reused leaf. */
+export const SCALAR: SchemaModel = { kind: 'scalar', scalar: 'string' };
+
+/** A minimal valid `ApiModel`; spread `overrides` to vary one facet per test. */
+export function apiModel(overrides: Partial<ApiModel> = {}): ApiModel {
+  return {
+    title: 'T',
+    version: '1.0.0',
+    serverUrl: 'https://api.example.com',
+    services: [{ name: 'Default', operations: [] }],
+    schemas: [],
+    securitySchemes: [],
+    ...overrides,
+  };
+}
+
+export function namedSchema(
+  name: string,
+  schema: SchemaModel,
+  description?: string
+): NamedSchemaModel {
+  return { name, schema, description };
+}
+
+/** A minimal `GET /p` operation; spread `overrides` to add params, a body, responses, etc. */
+export function operation(overrides: Partial<OperationModel> = {}): OperationModel {
+  return {
+    name: 'op',
+    method: 'get',
+    path: '/p',
+    pathParams: [],
+    queryParams: [],
+    headerParams: [],
+    cookieParams: [],
+    successResponses: [],
+    errorResponses: [],
+    security: [],
+    tags: [],
+    ...overrides,
+  };
+}
+
+export function param(
+  name: string,
+  loc: ParamModel['in'],
+  required: boolean,
+  schema: SchemaModel = SCALAR
+): ParamModel {
+  return { name, in: loc, schema, required };
+}
+
+/** An `ApiModel` with a single `Default` service holding `ops`; spread `extra` to vary. */
+export function modelWith(ops: OperationModel[], extra: Partial<ApiModel> = {}): ApiModel {
+  return apiModel({ services: [{ name: 'Default', operations: ops }], ...extra });
+}
+
+/** A JSON `ResponseBodyModel`, defaulting to `status: 200`; spread to vary status/schema. */
+export function response(overrides: Partial<ResponseBodyModel> = {}): ResponseBodyModel {
+  return { contentType: 'application/json', schema: SCALAR, status: 200, ...overrides };
+}
+
+/** Emit a single-file (inline-runtime) client whose only operation is `operation(op)`. */
+export function emitWithOp(op: Partial<OperationModel>): string {
+  return emitClientSingleFile(
+    apiModel({ services: [{ name: 'Default', operations: [operation(op)] }] })
+  );
+}
diff --git a/packages/client-generator/src/emitters/__tests__/identifier.test.ts b/packages/client-generator/src/emitters/__tests__/identifier.test.ts
new file mode 100644
index 0000000000..0aeee91550
--- /dev/null
+++ b/packages/client-generator/src/emitters/__tests__/identifier.test.ts
@@ -0,0 +1,58 @@
+import { isIdentifier, safeIdent, uniqueIdent } from '../identifier.js';
+
+describe('isIdentifier', () => {
+  it('accepts valid identifiers (letters, _, $, digits after the first char)', () => {
+    expect(isIdentifier('foo')).toBe(true);
+    expect(isIdentifier('_foo')).toBe(true);
+    expect(isIdentifier('$foo')).toBe(true);
+    expect(isIdentifier('foo123')).toBe(true);
+  });
+
+  it('rejects names that are not valid identifiers', () => {
+    expect(isIdentifier('foo-bar')).toBe(false);
+    expect(isIdentifier('2fa')).toBe(false);
+    expect(isIdentifier('has space')).toBe(false);
+    expect(isIdentifier('')).toBe(false);
+  });
+});
+
+describe('safeIdent', () => {
+  it('returns a valid, non-reserved name bare', () => {
+    expect(safeIdent('limit')).toBe('limit');
+  });
+
+  it('quotes a reserved word (a bare reserved word would not be a usable key)', () => {
+    expect(safeIdent('default')).toBe('"default"');
+  });
+
+  it('quotes a name that is not a valid identifier', () => {
+    expect(safeIdent('X-Request-Id')).toBe('"X-Request-Id"');
+  });
+});
+
+describe('uniqueIdent', () => {
+  it('keeps a clean identifier unchanged and records it', () => {
+    const used = new Set<string>();
+    expect(uniqueIdent('orderId', used)).toBe('orderId');
+    expect(used.has('orderId')).toBe(true);
+  });
+
+  it('replaces non-identifier characters with underscores', () => {
+    expect(uniqueIdent('pet-id', new Set())).toBe('pet_id');
+  });
+
+  it('prefixes a leading digit with an underscore', () => {
+    expect(uniqueIdent('2fa', new Set())).toBe('_2fa');
+  });
+
+  it('prefixes a reserved word with an underscore', () => {
+    expect(uniqueIdent('new', new Set())).toBe('_new');
+  });
+
+  it('suffixes collisions with an incrementing counter', () => {
+    const used = new Set<string>();
+    expect(uniqueIdent('a.b', used)).toBe('a_b');
+    expect(uniqueIdent('a-b', used)).toBe('a_b_2');
+    expect(uniqueIdent('a b', used)).toBe('a_b_3');
+  });
+});
diff --git a/packages/client-generator/src/emitters/__tests__/inline-runtime.test.ts b/packages/client-generator/src/emitters/__tests__/inline-runtime.test.ts
new file mode 100644
index 0000000000..2963d9c3a1
--- /dev/null
+++ b/packages/client-generator/src/emitters/__tests__/inline-runtime.test.ts
@@ -0,0 +1,213 @@
+import { assembleInlineRuntime } from '../inline-runtime.js';
+import { ts } from '../ts.js';
+
+const NONE = { multipart: false, auth: false, sse: false, setup: false, paginate: false };
+const ALL = { multipart: true, auth: true, sse: true, setup: true, paginate: true };
+
+/** Positions of `markers` in `text`; asserts each is present and they appear in order. */
+function expectOrder(text: string, markers: string[]): void {
+  const positions = markers.map((marker) => {
+    const at = text.indexOf(marker);
+    expect(at, `missing marker: ${marker}`).toBeGreaterThanOrEqual(0);
+    return at;
+  });
+  expect(positions, `markers out of order: ${markers.join(' < ')}`).toEqual(
+    [...positions].sort((a, b) => a - b)
+  );
+}
+
+// Syntax-validity gate: `ts.createSourceFile` + its parse diagnostics. Pragmatic by
+// design — a full in-memory `ts.createProgram` typecheck is stage T3+'s e2e strict-tsc
+// job; here we assert the assembled text is at least syntactically sound TypeScript.
+function parseErrors(source: string): readonly unknown[] {
+  const file = ts.createSourceFile(
+    'inline.ts',
+    source,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TS
+  );
+  return (file as unknown as { parseDiagnostics: readonly unknown[] }).parseDiagnostics;
+}
+
+describe('assembleInlineRuntime', () => {
+  describe('core-only', () => {
+    const out = assembleInlineRuntime(NONE);
+
+    it('keeps export on the public surface and strips it from internals', () => {
+      expect(out).toContain('export class ApiError');
+      expect(out).toContain('function buildUrl');
+      expect(out).not.toContain('export function buildUrl');
+      // The factory IS exported — the generated module's multi-instance surface
+      // (spec: it re-exports `createClient`/`OPERATIONS`/`Ops`).
+      expect(out).toContain('export function createClient<\n  Ops extends OpsShape,');
+      expect(out).toContain('Tag extends string = string,');
+    });
+
+    it('wires an empty capability object', () => {
+      expect(out).toContain('createClientCore<Ops, Id, Path, Tag>(operations, config, {})');
+    });
+
+    it('embeds no capability module', () => {
+      // The auth MODULE is absent (its function bodies); `resolveAuth` as a bare word
+      // still appears in create-client.ts's `Capabilities` seam type — that is expected.
+      expect(out).not.toContain('toFormData');
+      expect(out).not.toContain('async function resolveAuth');
+      expect(out).not.toContain('resolveToken');
+      expect(out).not.toContain('async function* sse');
+      expect(out).not.toContain('mergeSetup');
+      expect(out).not.toContain('function resolvePointer');
+      expect(out).not.toContain('async function* pages');
+    });
+
+    it('contains no import statements or package references', () => {
+      expect(out).not.toContain("from './");
+      expect(out).not.toContain("from '@redocly");
+      expect(out).not.toContain('import ');
+    });
+
+    it('starts with the embedded-runtime header and orders modules by dependency', () => {
+      expect(
+        out.startsWith(
+          "// ─── Embedded runtime (@redocly/client-generator, assembled per this API's needs) ───\n\n"
+        )
+      ).toBe(true);
+      expectOrder(out, [
+        'export type ParamSpec',
+        'export class ApiError',
+        'function buildUrl',
+        'async function parse',
+        'function defaultRetryOn',
+        'async function send',
+        'function createClientCore',
+        'function createClient<\n  Ops extends OpsShape,',
+      ]);
+    });
+  });
+
+  describe('full capabilities', () => {
+    const out = assembleInlineRuntime(ALL);
+
+    it('wires all capabilities into the factory', () => {
+      expect(out).toContain('serializeMultipart: toFormData');
+      expect(out).toContain(
+        'createClientCore<Ops, Id, Path, Tag>(operations, config, { serializeMultipart: toFormData, resolveAuth, sse, paginate: { pages, items } })'
+      );
+    });
+
+    it('embeds the capability modules module-local, mergeSetup exported', () => {
+      expect(out).toContain('function toFormData');
+      expect(out).not.toContain('export function toFormData');
+      expect(out).toContain('async function resolveAuth');
+      expect(out).not.toContain('export async function resolveAuth');
+      expect(out).toContain('async function* sse');
+      expect(out).not.toContain('export async function* sse');
+      expect(out).toContain('async function* pages');
+      expect(out).not.toContain('export async function* pages');
+      expect(out).toContain('export function mergeSetup');
+    });
+
+    it('slots capability modules into the dependency order', () => {
+      expectOrder(out, [
+        'function defaultRetryOn',
+        'function toFormData',
+        'async function resolveAuth',
+        'export function mergeSetup',
+        'function resolvePointer',
+        'async function send',
+        'async function* sse',
+        'function createClientCore',
+      ]);
+    });
+  });
+
+  describe('each capability alone pulls exactly its module', () => {
+    it('multipart', () => {
+      const out = assembleInlineRuntime({ ...NONE, multipart: true });
+      expect(out).toContain('function toFormData');
+      expect(out).toContain(
+        'createClientCore<Ops, Id, Path, Tag>(operations, config, { serializeMultipart: toFormData })'
+      );
+      expect(out).not.toContain('resolveToken');
+      expect(out).not.toContain('parseSseFrame');
+      expect(out).not.toContain('mergeSetup');
+    });
+
+    it('auth', () => {
+      const out = assembleInlineRuntime({ ...NONE, auth: true });
+      expect(out).toContain('async function resolveAuth');
+      expect(out).toContain('resolveToken');
+      expect(out).toContain(
+        'createClientCore<Ops, Id, Path, Tag>(operations, config, { resolveAuth })'
+      );
+      expect(out).not.toContain('toFormData');
+      expect(out).not.toContain('parseSseFrame');
+      expect(out).not.toContain('mergeSetup');
+    });
+
+    it('sse', () => {
+      const out = assembleInlineRuntime({ ...NONE, sse: true });
+      expect(out).toContain('async function* sse');
+      expect(out).toContain('parseSseFrame');
+      expect(out).toContain('createClientCore<Ops, Id, Path, Tag>(operations, config, { sse })');
+      expect(out).not.toContain('toFormData');
+      expect(out).not.toContain('resolveToken');
+      expect(out).not.toContain('mergeSetup');
+    });
+
+    it('setup (exported for the wiring, not a factory capability)', () => {
+      const out = assembleInlineRuntime({ ...NONE, setup: true });
+      expect(out).toContain('export function mergeSetup');
+      expect(out).toContain('createClientCore<Ops, Id, Path, Tag>(operations, config, {})');
+      expect(out).not.toContain('toFormData');
+      expect(out).not.toContain('resolveToken');
+      expect(out).not.toContain('parseSseFrame');
+    });
+
+    it('paginate', () => {
+      const out = assembleInlineRuntime({ ...NONE, paginate: true });
+      expect(out).toContain('function resolvePointer');
+      expect(out).toContain('async function* pages');
+      expect(out).toContain('async function* items');
+      expect(out).toContain(
+        'createClientCore<Ops, Id, Path, Tag>(operations, config, { paginate: { pages, items } })'
+      );
+      expect(out).not.toContain('toFormData');
+      expect(out).not.toContain('resolveToken');
+      expect(out).not.toContain('parseSseFrame');
+      expect(out).not.toContain('mergeSetup');
+    });
+  });
+
+  describe('embedded type surface', () => {
+    const out = assembleInlineRuntime(NONE);
+
+    it('keeps every types.ts export (they replace package-mode type imports)', () => {
+      expect(out).toContain('export type ClientConfig');
+      expect(out).toContain('export type RequestOptions');
+      expect(out).toContain('export type OperationDescriptor');
+      expect(out).toContain(
+        'export type Client<Ops extends OpsShape, Op extends OperationContext = OperationContext>'
+      );
+    });
+
+    it('strips exports from internal types in non-types modules', () => {
+      expect(out).toContain('type QueryStyle');
+      expect(out).not.toContain('export type QueryStyle');
+      expect(out).toContain('type SendCapabilities');
+      expect(out).not.toContain('export type SendCapabilities');
+      expect(out).toContain('type Capabilities');
+      expect(out).not.toContain('export type Capabilities');
+    });
+  });
+
+  it('is deterministic', () => {
+    expect(assembleInlineRuntime(ALL)).toBe(assembleInlineRuntime(ALL));
+    expect(assembleInlineRuntime(NONE)).toBe(assembleInlineRuntime(NONE));
+  });
+
+  it('assembles syntactically valid TypeScript (core-only and full)', () => {
+    expect(parseErrors(assembleInlineRuntime(NONE))).toEqual([]);
+    expect(parseErrors(assembleInlineRuntime(ALL))).toEqual([]);
+  });
+});
diff --git a/packages/client-generator/src/emitters/__tests__/mock.test.ts b/packages/client-generator/src/emitters/__tests__/mock.test.ts
new file mode 100644
index 0000000000..b656b9a395
--- /dev/null
+++ b/packages/client-generator/src/emitters/__tests__/mock.test.ts
@@ -0,0 +1,623 @@
+import { renderMockModule } from '../mock.js';
+import { apiModel, namedSchema, operation, param } from './fixtures.js';
+
+describe('renderMockModule', () => {
+  it('emits the msw import, a factory per named schema, and a handlers array', () => {
+    const model = apiModel({
+      schemas: [
+        namedSchema('Pet', {
+          kind: 'object',
+          properties: [
+            { name: 'id', schema: { kind: 'scalar', scalar: 'integer' }, required: true },
+          ],
+        }),
+      ],
+      services: [
+        {
+          name: 'Default',
+          operations: [
+            operation({
+              name: 'getPet',
+              method: 'get',
+              path: '/pets/{petId}',
+              pathParams: [param('petId', 'path', true)],
+              successResponses: [
+                {
+                  contentType: 'application/json',
+                  schema: { kind: 'ref', name: 'Pet' },
+                  status: 200,
+                },
+              ],
+            }),
+          ],
+        },
+      ],
+    });
+    const out = renderMockModule(model, { sdkModule: './client.js' });
+    // The `msw` import is the one hand-written line (single-quoted); everything
+    // else is printer output, which double-quotes strings. A downstream formatter
+    // normalizes both, so assertions track each source's raw form.
+    expect(out).toContain("import { http, HttpResponse } from 'msw';");
+    // The factories reference the generated schema types, so the module type-imports
+    // them from the sdk entry (printer double-quotes the specifier).
+    expect(out).toContain('import type { Pet } from "./client.js";');
+    expect(out).toContain('export function createPet(overrides?: Partial<Pet>): Pet {');
+    expect(out).toContain('id: 0');
+    expect(out).toContain('...overrides');
+    expect(out).toContain('http.get("*/pets/:petId",');
+    expect(out).toContain('HttpResponse.json(createPet(override))');
+    expect(out).toContain('export const handlers = [getPetHandler()];');
+  });
+
+  it('emits a body-less handler for a success response with no content', () => {
+    const model = apiModel({
+      schemas: [],
+      services: [
+        {
+          name: 'Default',
+          operations: [
+            operation({ name: 'ping', method: 'get', path: '/ping', successResponses: [] }),
+          ],
+        },
+      ],
+    });
+    const out = renderMockModule(model, { sdkModule: './client.js' });
+    expect(out).toContain('http.get("*/ping",');
+    expect(out).toContain('new HttpResponse(null, { status: 200 })');
+    expect(out).not.toContain('HttpResponse.json');
+  });
+
+  it('samples an inline (unnamed) success body in place', () => {
+    const model = apiModel({
+      schemas: [],
+      services: [
+        {
+          name: 'Default',
+          operations: [
+            operation({
+              name: 'health',
+              method: 'get',
+              path: '/health',
+              successResponses: [
+                {
+                  contentType: 'application/json',
+                  status: 200,
+                  schema: {
+                    kind: 'object',
+                    properties: [
+                      { name: 'ok', schema: { kind: 'scalar', scalar: 'boolean' }, required: true },
+                    ],
+                  },
+                },
+              ],
+            }),
+          ],
+        },
+      ],
+    });
+    const out = renderMockModule(model, { sdkModule: './client.js' });
+    expect(out).toContain('ok: true');
+    expect(out).not.toContain('create'); // no named factory for an inline body
+    expect(out).toContain('...override');
+  });
+
+  it('prints string, negative-number, array, and null defaults as literals', () => {
+    const model = apiModel({
+      schemas: [
+        namedSchema('Mixed', {
+          kind: 'object',
+          properties: [
+            { name: 'label', schema: { kind: 'scalar', scalar: 'string' }, required: true },
+            {
+              name: 'offset',
+              schema: { kind: 'scalar', scalar: 'integer', metadata: { default: -1 } },
+              required: true,
+            },
+            {
+              name: 'tags',
+              schema: { kind: 'array', items: { kind: 'scalar', scalar: 'string' } },
+              required: true,
+            },
+            { name: 'nothing', schema: { kind: 'null' }, required: true },
+            {
+              name: 'disabled',
+              schema: { kind: 'scalar', scalar: 'boolean', metadata: { example: false } },
+              required: true,
+            },
+          ],
+        }),
+      ],
+      services: [
+        {
+          name: 'Default',
+          operations: [
+            operation({
+              name: 'getMixed',
+              method: 'get',
+              path: '/mixed',
+              successResponses: [
+                {
+                  contentType: 'application/json',
+                  schema: { kind: 'ref', name: 'Mixed' },
+                  status: 200,
+                },
+              ],
+            }),
+          ],
+        },
+      ],
+    });
+    const out = renderMockModule(model, { sdkModule: './client.js' });
+    expect(out).toContain('label: "string"');
+    expect(out).toContain('offset: -1');
+    expect(out).toContain('tags: [');
+    expect(out).toContain('"string"');
+    expect(out).toContain('nothing: null');
+    expect(out).toContain('disabled: false');
+  });
+
+  it('passes a non-object inline body through without an override spread', () => {
+    const model = apiModel({
+      schemas: [],
+      services: [
+        {
+          name: 'Default',
+          operations: [
+            operation({
+              name: 'count',
+              method: 'get',
+              path: '/count',
+              successResponses: [
+                {
+                  contentType: 'application/json',
+                  schema: { kind: 'scalar', scalar: 'integer' },
+                  status: 200,
+                },
+              ],
+            }),
+          ],
+        },
+      ],
+    });
+    const out = renderMockModule(model, { sdkModule: './client.js' });
+    // `HttpResponse.json(x)` defaults to 200, so no `{ status }` init is emitted either.
+    expect(out).toContain('HttpResponse.json(0)');
+    expect(out).not.toContain('...override');
+    expect(out).not.toContain('{ status:');
+  });
+
+  it('quotes non-identifier object keys', () => {
+    const model = apiModel({
+      schemas: [
+        namedSchema('Trace', {
+          kind: 'object',
+          properties: [
+            { name: 'x-trace-id', schema: { kind: 'scalar', scalar: 'string' }, required: true },
+          ],
+        }),
+      ],
+      services: [
+        {
+          name: 'Default',
+          operations: [
+            operation({
+              name: 'getTrace',
+              method: 'get',
+              path: '/trace',
+              successResponses: [
+                {
+                  contentType: 'application/json',
+                  schema: { kind: 'ref', name: 'Trace' },
+                  status: 200,
+                },
+              ],
+            }),
+          ],
+        },
+      ],
+    });
+    const out = renderMockModule(model, { sdkModule: './client.js' });
+    expect(out).toContain('"x-trace-id": "string"');
+  });
+
+  it('casts a union-schema factory body `as <Type>` so the `Partial<Union>` override spread keeps narrowing', () => {
+    const model = apiModel({
+      schemas: [
+        namedSchema('Shape', {
+          kind: 'union',
+          members: [
+            {
+              kind: 'object',
+              properties: [
+                { name: 'kind', schema: { kind: 'literal', value: 'circle' }, required: true },
+                { name: 'r', schema: { kind: 'scalar', scalar: 'number' }, required: true },
+              ],
+            },
+            {
+              kind: 'object',
+              properties: [
+                { name: 'kind', schema: { kind: 'literal', value: 'square' }, required: true },
+                { name: 'side', schema: { kind: 'scalar', scalar: 'number' }, required: true },
+              ],
+            },
+          ],
+        }),
+      ],
+      services: [
+        {
+          name: 'Default',
+          operations: [
+            operation({
+              name: 'getShape',
+              method: 'get',
+              path: '/shape',
+              successResponses: [
+                {
+                  contentType: 'application/json',
+                  schema: { kind: 'ref', name: 'Shape' },
+                  status: 200,
+                },
+              ],
+            }),
+          ],
+        },
+      ],
+    });
+    const out = renderMockModule(model, { sdkModule: './client.js' });
+    expect(out).toContain('export function createShape(overrides?: Partial<Shape>): Shape {');
+    expect(out).toMatch(/\.\.\.overrides\s*\} as Shape/);
+  });
+
+  it('bakes a `format: date-time` field as `new Date(...)` under dateType `Date`', () => {
+    const model = apiModel({
+      schemas: [
+        namedSchema('Event', {
+          kind: 'object',
+          properties: [
+            {
+              name: 'at',
+              schema: { kind: 'scalar', scalar: 'string', metadata: { format: 'date-time' } },
+              required: true,
+            },
+          ],
+        }),
+      ],
+      services: [
+        {
+          name: 'Default',
+          operations: [
+            operation({
+              name: 'getEvent',
+              method: 'get',
+              path: '/event',
+              successResponses: [
+                {
+                  contentType: 'application/json',
+                  schema: { kind: 'ref', name: 'Event' },
+                  status: 200,
+                },
+              ],
+            }),
+          ],
+        },
+      ],
+    });
+    const out = renderMockModule(model, { sdkModule: './client.js', dateType: 'Date' });
+    expect(out).toContain('at: new Date(');
+    expect(out).not.toContain('at: "2024-01-01T00:00:00Z"');
+  });
+
+  it('passes { status: 201 } to HttpResponse.json for a non-200 success', () => {
+    const model = apiModel({
+      schemas: [],
+      services: [
+        {
+          name: 'Default',
+          operations: [
+            operation({
+              name: 'create',
+              method: 'post',
+              path: '/things',
+              successResponses: [
+                {
+                  contentType: 'application/json',
+                  schema: { kind: 'scalar', scalar: 'integer' },
+                  status: 201,
+                },
+              ],
+            }),
+          ],
+        },
+      ],
+    });
+    const out = renderMockModule(model, { sdkModule: './client.js' });
+    expect(out).toContain('HttpResponse.json(0, { status: 201 })');
+  });
+
+  it('emits a body-less response carrying the success status (204)', () => {
+    const model = apiModel({
+      schemas: [],
+      services: [
+        {
+          name: 'Default',
+          operations: [
+            operation({
+              name: 'remove',
+              method: 'delete',
+              path: '/things/{id}',
+              pathParams: [param('id', 'path', true)],
+              successResponses: [
+                { contentType: 'application/json', schema: { kind: 'unknown' }, status: 204 },
+              ],
+            }),
+          ],
+        },
+      ],
+    });
+    const out = renderMockModule(model, { sdkModule: './client.js' });
+    expect(out).toContain('new HttpResponse(null, { status: 204 })');
+    expect(out).not.toContain('HttpResponse.json');
+  });
+
+  it('emits an opt-in error handler typed with the declared status, kept out of `handlers`', () => {
+    const model = apiModel({
+      schemas: [
+        namedSchema('Problem', {
+          kind: 'object',
+          properties: [
+            { name: 'message', schema: { kind: 'scalar', scalar: 'string' }, required: true },
+          ],
+        }),
+      ],
+      services: [
+        {
+          name: 'Default',
+          operations: [
+            operation({
+              name: 'getPet',
+              method: 'get',
+              path: '/pets/{petId}',
+              pathParams: [param('petId', 'path', true)],
+              successResponses: [
+                {
+                  contentType: 'application/json',
+                  schema: { kind: 'ref', name: 'Problem' },
+                  status: 200,
+                },
+              ],
+              errorResponses: [
+                {
+                  contentType: 'application/json',
+                  schema: { kind: 'ref', name: 'Problem' },
+                  status: 404,
+                },
+              ],
+            }),
+          ],
+        },
+      ],
+    });
+    const out = renderMockModule(model, { sdkModule: './client.js' });
+    expect(out).toContain('export const getPetErrorHandler = (status: 404, body?: Problem) =>');
+    expect(out).toContain('http.get("*/pets/:petId", () => HttpResponse.json(body ?? {');
+    expect(out).toContain('{ status })');
+    // The error handler stays opt-in: only the success handler is in the array.
+    expect(out).toContain('export const handlers = [getPetHandler()];');
+    expect(out).not.toContain('getPetErrorHandler()');
+  });
+
+  it('unions multiple declared error statuses', () => {
+    const model = apiModel({
+      schemas: [],
+      services: [
+        {
+          name: 'Default',
+          operations: [
+            operation({
+              name: 'submit',
+              method: 'post',
+              path: '/submit',
+              errorResponses: [
+                {
+                  contentType: 'application/json',
+                  schema: { kind: 'scalar', scalar: 'string' },
+                  status: 404,
+                },
+                {
+                  contentType: 'application/json',
+                  schema: { kind: 'scalar', scalar: 'string' },
+                  status: 422,
+                },
+              ],
+            }),
+          ],
+        },
+      ],
+    });
+    const out = renderMockModule(model, { sdkModule: './client.js' });
+    expect(out).toContain('submitErrorHandler = (status: 404 | 422,');
+  });
+
+  it('widens the error-status union with `number` for a `default` error', () => {
+    const model = apiModel({
+      schemas: [],
+      services: [
+        {
+          name: 'Default',
+          operations: [
+            operation({
+              name: 'submit',
+              method: 'post',
+              path: '/submit',
+              errorResponses: [
+                {
+                  contentType: 'application/json',
+                  schema: { kind: 'scalar', scalar: 'string' },
+                  status: 404,
+                },
+                {
+                  contentType: 'application/json',
+                  schema: { kind: 'scalar', scalar: 'string' },
+                  status: 'default',
+                },
+              ],
+            }),
+          ],
+        },
+      ],
+    });
+    const out = renderMockModule(model, { sdkModule: './client.js' });
+    expect(out).toContain('status: 404 | number');
+  });
+
+  it('unions distinct error body types', () => {
+    const model = apiModel({
+      schemas: [
+        namedSchema('NotFound', {
+          kind: 'object',
+          properties: [
+            { name: 'message', schema: { kind: 'scalar', scalar: 'string' }, required: true },
+          ],
+        }),
+        namedSchema('Invalid', {
+          kind: 'object',
+          properties: [
+            { name: 'field', schema: { kind: 'scalar', scalar: 'string' }, required: true },
+          ],
+        }),
+      ],
+      services: [
+        {
+          name: 'Default',
+          operations: [
+            operation({
+              name: 'submit',
+              method: 'post',
+              path: '/submit',
+              errorResponses: [
+                {
+                  contentType: 'application/json',
+                  schema: { kind: 'ref', name: 'NotFound' },
+                  status: 404,
+                },
+                {
+                  contentType: 'application/json',
+                  schema: { kind: 'ref', name: 'Invalid' },
+                  status: 422,
+                },
+              ],
+            }),
+          ],
+        },
+      ],
+    });
+    const out = renderMockModule(model, { sdkModule: './client.js' });
+    expect(out).toContain('body?: NotFound | Invalid)');
+  });
+
+  it('emits no error handler for an op without error responses', () => {
+    const model = apiModel({
+      schemas: [],
+      services: [
+        {
+          name: 'Default',
+          operations: [
+            operation({
+              name: 'ping',
+              method: 'get',
+              path: '/ping',
+              successResponses: [
+                {
+                  contentType: 'application/json',
+                  schema: { kind: 'scalar', scalar: 'integer' },
+                  status: 200,
+                },
+              ],
+            }),
+          ],
+        },
+      ],
+    });
+    const out = renderMockModule(model, { sdkModule: './client.js' });
+    expect(out).not.toContain('ErrorHandler');
+  });
+
+  it('returns empty string when there are no operations', () => {
+    const model = apiModel({ schemas: [], services: [{ name: 'Default', operations: [] }] });
+    expect(renderMockModule(model, { sdkModule: './client.js' })).toBe('');
+  });
+
+  describe('faker mode', () => {
+    const fakerModel = () =>
+      apiModel({
+        schemas: [
+          namedSchema('Pet', {
+            kind: 'object',
+            properties: [
+              { name: 'id', schema: { kind: 'scalar', scalar: 'integer' }, required: true },
+              { name: 'name', schema: { kind: 'scalar', scalar: 'string' }, required: true },
+            ],
+          }),
+        ],
+        services: [
+          {
+            name: 'Default',
+            operations: [
+              operation({
+                name: 'getPet',
+                method: 'get',
+                path: '/pets/{petId}',
+                pathParams: [param('petId', 'path', true)],
+                successResponses: [
+                  {
+                    contentType: 'application/json',
+                    schema: { kind: 'ref', name: 'Pet' },
+                    status: 200,
+                  },
+                ],
+                errorResponses: [
+                  {
+                    contentType: 'application/json',
+                    schema: { kind: 'ref', name: 'Pet' },
+                    status: 404,
+                  },
+                ],
+              }),
+            ],
+          },
+        ],
+      });
+
+    it('imports faker and uses faker calls in factory bodies', () => {
+      const out = renderMockModule(fakerModel(), { sdkModule: './client.js', mockData: 'faker' });
+      expect(out).toContain("import { faker } from '@faker-js/faker';");
+      expect(out).toContain('id: faker.number.int()');
+      expect(out).toContain('name: faker.lorem.word()');
+      // No baked literals leaked in.
+      expect(out).not.toContain('id: 0');
+      expect(out).not.toContain('name: "string"');
+    });
+
+    it('emits faker.seed(n) once when mockSeed is set', () => {
+      const out = renderMockModule(fakerModel(), {
+        sdkModule: './client.js',
+        mockData: 'faker',
+        mockSeed: 42,
+      });
+      expect(out).toContain('faker.seed(42);');
+      expect(out.match(/faker\.seed\(/g)).toHaveLength(1);
+    });
+
+    it('emits no seed call when mockSeed is absent', () => {
+      const out = renderMockModule(fakerModel(), { sdkModule: './client.js', mockData: 'faker' });
+      expect(out).not.toContain('faker.seed(');
+    });
+
+    it('baked mode (default) emits no faker import or seed call', () => {
+      const out = renderMockModule(fakerModel(), { sdkModule: './client.js' });
+      expect(out).not.toContain('@faker-js/faker');
+      expect(out).not.toContain('faker.');
+      expect(out).toContain('id: 0');
+    });
+  });
+});
diff --git a/packages/client-generator/src/emitters/__tests__/operation-signature.test.ts b/packages/client-generator/src/emitters/__tests__/operation-signature.test.ts
new file mode 100644
index 0000000000..a0cd82f8b3
--- /dev/null
+++ b/packages/client-generator/src/emitters/__tests__/operation-signature.test.ts
@@ -0,0 +1,59 @@
+import { operationSignature } from '../operation-signature.js';
+import { operation, param } from './fixtures.js';
+
+describe('operationSignature', () => {
+  it('orders path params by URL-template position and assigns unique identifiers', () => {
+    // Declared out of order; the path dictates order. `a-b` sanitizes to `a_b`.
+    const sig = operationSignature(
+      operation({
+        path: '/x/{second}/y/{a-b}',
+        pathParams: [param('a-b', 'path', true), param('second', 'path', true)],
+      })
+    );
+    expect(sig.pathParams.map((p) => p.param.name)).toEqual(['second', 'a-b']);
+    expect(sig.pathParams.map((p) => p.ident)).toEqual(['second', 'a_b']);
+  });
+
+  it('reports slot presence and hasInputs', () => {
+    const none = operationSignature(operation({ path: '/x', method: 'get' }));
+    expect(none).toMatchObject({
+      hasQuery: false,
+      hasBody: false,
+      hasHeaders: false,
+      hasInputs: false,
+    });
+
+    const all = operationSignature(
+      operation({
+        path: '/x/{id}',
+        pathParams: [param('id', 'path', true)],
+        queryParams: [param('q', 'query', false)],
+        headerParams: [param('h', 'header', false)],
+        requestBody: {
+          contentType: 'application/json',
+          schema: { kind: 'ref', name: 'Body' },
+          required: false,
+        },
+      })
+    );
+    expect(all).toMatchObject({ hasQuery: true, hasBody: true, hasHeaders: true, hasInputs: true });
+  });
+
+  it('marks vars required when any input is required', () => {
+    const required = operationSignature(
+      operation({ path: '/x', queryParams: [param('q', 'query', true)] })
+    );
+    expect(required.varsRequired).toBe(true);
+
+    const optional = operationSignature(
+      operation({ path: '/x', queryParams: [param('q', 'query', false)] })
+    );
+    expect(optional).toMatchObject({ hasInputs: true, varsRequired: false });
+  });
+
+  it('derives the <Op>Variables type name from the (PascalCased) operation name', () => {
+    expect(operationSignature(operation({ name: 'getPet' })).variablesTypeName).toBe(
+      'GetPetVariables'
+    );
+  });
+});
diff --git a/packages/client-generator/src/emitters/__tests__/operations.test.ts b/packages/client-generator/src/emitters/__tests__/operations.test.ts
new file mode 100644
index 0000000000..bfaf613152
--- /dev/null
+++ b/packages/client-generator/src/emitters/__tests__/operations.test.ts
@@ -0,0 +1,445 @@
+// The flat sugar signatures (`renderArgList`) and the `<Op>*` operation aliases as
+// they appear in the descriptor-wired single-file client. The wiring itself (Ops,
+// OPERATIONS, client, auth sugar) is covered in client-assembly.test.ts; here the
+// focus is one operation's developer-facing surface.
+import type { OperationModel, RequestBodyModel } from '../../intermediate-representation/model.js';
+import { emitClientSingleFile } from '../client-assembly.js';
+import { SCALAR, apiModel, emitWithOp, namedSchema, operation, param } from './fixtures.js';
+
+/** Emit a result-mode single-file client whose only operation is `operation(op)`. */
+function emitResult(op: Partial<OperationModel>, schemas: string[] = []): string {
+  return emitClientSingleFile(
+    apiModel({
+      schemas: schemas.map((name) => namedSchema(name, { kind: 'object', properties: [] })),
+      services: [{ name: 'Default', operations: [operation(op)] }],
+    }),
+    { errorMode: 'result' }
+  );
+}
+
+describe('flat sugar — argument-list permutations (renderArgList)', () => {
+  it('renders an operation with no inputs: only the trailing init, forwarding empty args', () => {
+    const out = emitWithOp({});
+    expect(out).toContain('export const op = (init: RequestOptions = {}) => client.op({}, init);');
+  });
+
+  it('orders path params by their position in the URL template, not in pathParams[]', () => {
+    const out = emitWithOp({
+      name: 'getNested',
+      path: '/x/{first}/y/{second}',
+      pathParams: [
+        param('second', 'path', true, { kind: 'scalar', scalar: 'number' }),
+        param('first', 'path', true, { kind: 'scalar', scalar: 'string' }),
+      ],
+    });
+    expect(out).toContain(
+      'export const getNested = (first: string, second: number, init: RequestOptions = {}) => client.getNested({ first, second }, init);'
+    );
+  });
+
+  it('skips path params that are declared but missing from the URL template', () => {
+    const out = emitWithOp({ path: '/x', pathParams: [param('ghost', 'path', true)] });
+    expect(out).not.toContain('ghost: string');
+  });
+
+  it('sanitizes a non-identifier path param name into a safe argument, keyed by wire name', () => {
+    const out = emitWithOp({
+      name: 'getPet',
+      path: '/pets/{pet-id}',
+      pathParams: [param('pet-id', 'path', true)],
+    });
+    expect(out).toContain(
+      'export const getPet = (pet_id: string, init: RequestOptions = {}) => client.getPet({ "pet-id": pet_id }, init);'
+    );
+  });
+
+  it('prefixes digit-leading and reserved-word path param names with `_`', () => {
+    expect(emitWithOp({ path: '/x/{2fa}', pathParams: [param('2fa', 'path', true)] })).toContain(
+      '_2fa: string'
+    );
+    expect(emitWithOp({ path: '/x/{new}', pathParams: [param('new', 'path', true)] })).toContain(
+      '_new: string'
+    );
+  });
+
+  it('disambiguates path param names that sanitize to the same identifier', () => {
+    const out = emitWithOp({
+      path: '/x/{a-b}/{a.b}',
+      pathParams: [param('a-b', 'path', true), param('a.b', 'path', true)],
+    });
+    expect(out).toContain('a_b: string');
+    expect(out).toContain('a_b_2: string');
+  });
+
+  it('emits `params = {}` default when all query params are optional', () => {
+    const out = emitWithOp({
+      queryParams: [param('q', 'query', false), param('r', 'query', false)],
+    });
+    expect(out).toMatch(/params: \{\n {4}q\?: string;\n {4}r\?: string;\n\} = \{\}/);
+  });
+
+  it('makes `params` required when at least one query param is required', () => {
+    const out = emitWithOp({
+      queryParams: [param('q', 'query', true), param('r', 'query', false)],
+    });
+    expect(out).toMatch(/params: \{\n {4}q: string;\n {4}r\?: string;\n\}, init/);
+  });
+
+  it('produces `body: T` for required JSON bodies and `body?: T` for optional ones', () => {
+    const required: RequestBodyModel = {
+      contentType: 'application/json',
+      schema: { kind: 'ref', name: 'Pet' },
+      required: true,
+    };
+    expect(emitWithOp({ requestBody: required })).toContain('body: Pet');
+    const optional: RequestBodyModel = {
+      contentType: 'application/json',
+      schema: SCALAR,
+      required: false,
+    };
+    expect(emitWithOp({ requestBody: optional })).toContain('body?: string');
+  });
+
+  it('uses raw `FormData` for a non-object multipart body', () => {
+    const body: RequestBodyModel = {
+      contentType: 'multipart/form-data',
+      schema: { kind: 'unknown' },
+      required: true,
+    };
+    expect(emitWithOp({ requestBody: body })).toContain('body: FormData');
+  });
+
+  it('uses `URLSearchParams` for urlencoded bodies', () => {
+    const body: RequestBodyModel = {
+      contentType: 'application/x-www-form-urlencoded',
+      schema: { kind: 'object', properties: [] },
+      required: true,
+    };
+    expect(emitWithOp({ requestBody: body })).toContain('body: URLSearchParams');
+  });
+
+  it('uses `Blob | ArrayBuffer` for octet-stream bodies', () => {
+    const body: RequestBodyModel = {
+      contentType: 'application/octet-stream',
+      schema: SCALAR,
+      required: true,
+    };
+    expect(emitWithOp({ requestBody: body })).toContain('body: Blob | ArrayBuffer');
+  });
+
+  it('emits header params as a typed `headers` slot, forwarded to the client method', () => {
+    const out = emitWithOp({
+      name: 'getThing',
+      headerParams: [param('X-Api-Version', 'header', true)],
+    });
+    expect(out).toMatch(/headers: \{\n {4}"X-Api-Version": string;\n\}, init/);
+    expect(out).toContain('=> client.getThing({ headers }, init);');
+  });
+
+  it('defaults the `headers` slot to `= {}` when all header params are optional', () => {
+    const out = emitWithOp({
+      name: 'getThing',
+      headerParams: [param('X-Trace', 'header', false)],
+    });
+    expect(out).toMatch(/headers: \{\n {4}"X-Trace"\?: string;\n\} = \{\}/);
+  });
+
+  it('renders per-param JSDoc (description + schema metadata) above sugar params', () => {
+    const out = emitWithOp({
+      name: 'listPets',
+      queryParams: [
+        {
+          name: 'limit',
+          in: 'query',
+          required: false,
+          description: 'Page size.',
+          schema: { kind: 'scalar', scalar: 'integer', metadata: { minimum: 1, maximum: 100 } },
+        },
+      ],
+    });
+    expect(out).toMatch(/Page size\.[\s\S]*@minimum 1[\s\S]*@maximum 100[\s\S]*limit\?: number;/);
+  });
+
+  it('the SSE sugar takes `SseOptions`; regular ops take `RequestOptions`', () => {
+    const out = emitClientSingleFile(
+      apiModel({
+        services: [
+          {
+            name: 'Default',
+            operations: [
+              operation({
+                name: 'streamMessages',
+                path: '/stream',
+                successResponses: [
+                  { contentType: 'text/event-stream', status: 200, schema: { kind: 'unknown' } },
+                ],
+              }),
+              operation({ name: 'listThings', path: '/things' }),
+            ],
+          },
+        ],
+      })
+    );
+    expect(out).toContain(
+      'export const streamMessages = (init: SseOptions = {}) => client.streamMessages({}, init);'
+    );
+    expect(out).toContain(
+      'export const listThings = (init: RequestOptions = {}) => client.listThings({}, init);'
+    );
+  });
+});
+
+describe('operation type aliases (*Result / *Params / *Body / *Headers / *Variables)', () => {
+  it('emits <PascalCaseOpName>Result for every operation, even the trivial void ones', () => {
+    expect(emitWithOp({ name: 'ping' })).toContain('export type PingResult = void;');
+  });
+
+  it('uses the response type and PascalCases a lowercase operationId', () => {
+    const out = emitWithOp({
+      name: 'getPet',
+      successResponses: [
+        { contentType: 'application/json', status: 200, schema: { kind: 'ref', name: 'Pet' } },
+      ],
+    });
+    expect(out).toContain('export type GetPetResult = Pet;');
+  });
+
+  it('emits *Params/*Body/*Headers/*Variables per input kind, in a stable order', () => {
+    const out = emitWithOp({
+      name: 'updateOrder',
+      path: '/orders/{orderId}',
+      pathParams: [param('orderId', 'path', true)],
+      queryParams: [param('include', 'query', false)],
+      headerParams: [param('X-Trace', 'header', false)],
+      requestBody: {
+        contentType: 'application/json',
+        schema: { kind: 'ref', name: 'Order' },
+        required: true,
+      },
+      successResponses: [
+        { contentType: 'application/json', status: 200, schema: { kind: 'ref', name: 'Order' } },
+      ],
+    });
+    const names = [
+      'UpdateOrderResult',
+      'UpdateOrderParams',
+      'UpdateOrderBody',
+      'UpdateOrderHeaders',
+      'UpdateOrderVariables',
+    ];
+    let last = -1;
+    for (const name of names) {
+      const idx = out.indexOf(`export type ${name}`);
+      expect(idx, `${name} should appear after its predecessor`).toBeGreaterThan(last);
+      last = idx;
+    }
+    expect(out).toMatch(
+      /export type UpdateOrderVariables = \{[\s\S]*orderId: string;[\s\S]*params\?: UpdateOrderParams;[\s\S]*body: UpdateOrderBody;[\s\S]*headers\?: UpdateOrderHeaders;[\s\S]*\};/
+    );
+  });
+
+  it('omits *Params/*Body/*Variables for operations without those inputs', () => {
+    const out = emitWithOp({ name: 'ping' });
+    expect(out).not.toContain('PingParams');
+    expect(out).not.toContain('PingBody');
+    expect(out).not.toContain('PingVariables');
+  });
+
+  it('types a typed multipart body as an object (binary→Blob), not FormData', () => {
+    const out = emitWithOp({
+      name: 'upload',
+      method: 'post',
+      requestBody: {
+        contentType: 'multipart/form-data',
+        required: true,
+        schema: {
+          kind: 'object',
+          properties: [
+            {
+              name: 'file',
+              schema: { kind: 'scalar', scalar: 'string', metadata: { format: 'binary' } },
+              required: true,
+            },
+          ],
+        },
+      },
+    });
+    expect(out).toContain('export type UploadBody = {');
+    expect(out).toContain('file: Blob;');
+    expect(out).not.toContain('UploadBody = FormData');
+  });
+});
+
+describe('<Op>* alias collision suppression', () => {
+  it('suppresses the *Result alias when it collides with the response schema name', () => {
+    const out = emitClientSingleFile(
+      apiModel({
+        schemas: [namedSchema('SearchResult', { kind: 'object', properties: [] })],
+        services: [
+          {
+            name: 'Default',
+            operations: [
+              operation({
+                name: 'search',
+                method: 'post',
+                successResponses: [
+                  {
+                    contentType: 'application/json',
+                    status: 200,
+                    schema: { kind: 'ref', name: 'SearchResult' },
+                  },
+                ],
+              }),
+            ],
+          },
+        ],
+      })
+    );
+    expect(out).not.toContain('export type SearchResult = SearchResult;');
+    // Exactly one `SearchResult` declaration — the schema, not a colliding alias.
+    expect(out.match(/export type SearchResult\b/g)).toHaveLength(1);
+    // The Ops member references the schema type directly.
+    expect(out).toContain('result: SearchResult;');
+  });
+
+  it('suppresses *Error and references the error schema directly in result mode', () => {
+    const out = emitResult(
+      {
+        name: 'login',
+        method: 'post',
+        successResponses: [
+          {
+            contentType: 'application/json',
+            status: 200,
+            schema: { kind: 'ref', name: 'Session' },
+          },
+        ],
+        errorResponses: [
+          {
+            contentType: 'application/json',
+            status: 400,
+            schema: { kind: 'ref', name: 'Problem' },
+          },
+        ],
+      },
+      ['Session', 'Problem', 'LoginError']
+    );
+    // `LoginError` names the SCHEMA type only — no `<Op>Error` alias shadows it.
+    expect(out).not.toContain('export type LoginError = Problem');
+    expect(out).toContain('Result<LoginResult, Problem>');
+  });
+});
+
+describe("errorMode: 'result' — typed error aliases", () => {
+  const okResponse = {
+    contentType: 'application/json',
+    status: 200,
+    schema: { kind: 'ref', name: 'Pet' },
+  } as const;
+
+  it('emits a *Error alias and wraps the Ops result when the op declares an error response', () => {
+    const out = emitResult(
+      {
+        name: 'getPet',
+        successResponses: [okResponse],
+        errorResponses: [
+          {
+            contentType: 'application/json',
+            status: 400,
+            schema: { kind: 'ref', name: 'Problem' },
+          },
+        ],
+      },
+      ['Pet', 'Problem']
+    );
+    expect(out).toContain('export type GetPetError = Problem;');
+    expect(out).toContain('result: Result<GetPetResult, GetPetError>;');
+  });
+
+  it('falls back to `unknown` (and emits no *Error alias) when the op has no error responses', () => {
+    const out = emitResult({ name: 'getPet', successResponses: [okResponse] }, ['Pet']);
+    expect(out).not.toContain('GetPetError');
+    expect(out).toContain('result: Result<GetPetResult, unknown>;');
+  });
+
+  it('unions and dedupes error-response body types in the *Error alias', () => {
+    const out = emitResult(
+      {
+        name: 'getPet',
+        successResponses: [okResponse],
+        errorResponses: [
+          { contentType: 'application/json', status: 400, schema: { kind: 'ref', name: 'A' } },
+          { contentType: 'application/json', status: 500, schema: { kind: 'ref', name: 'B' } },
+          {
+            contentType: 'application/problem+json',
+            status: 502,
+            schema: { kind: 'ref', name: 'B' },
+          },
+        ],
+      },
+      ['Pet', 'A', 'B']
+    );
+    expect(out).toContain('export type GetPetError = A | B;');
+    expect(out).not.toContain('B | B');
+  });
+
+  it('throw mode (the default) emits no Result wrapping and no *Error alias', () => {
+    const out = emitWithOp({
+      name: 'getPet',
+      successResponses: [okResponse],
+      errorResponses: [
+        { contentType: 'application/json', status: 400, schema: { kind: 'ref', name: 'Problem' } },
+      ],
+    });
+    expect(out).not.toContain('GetPetError');
+    // The Ops member holds the bare result type (the embedded runtime still
+    // declares the unused-in-throw-mode `Result` helper type).
+    expect(out).toContain('result: GetPetResult;');
+    expect(out).not.toContain('result: Result<');
+  });
+});
+
+describe('response type discovery (computeResponse through *Result)', () => {
+  it('void when there are no responses', () => {
+    expect(emitWithOp({ name: 'ping' })).toContain('export type PingResult = void;');
+  });
+
+  it('binary-only responses → Blob; text-only → string', () => {
+    expect(
+      emitWithOp({
+        name: 'getPhoto',
+        successResponses: [{ contentType: 'image/png', schema: { kind: 'unknown' }, status: 200 }],
+      })
+    ).toContain('export type GetPhotoResult = Blob;');
+    expect(
+      emitWithOp({
+        name: 'getText',
+        successResponses: [{ contentType: 'text/plain', schema: { kind: 'unknown' }, status: 200 }],
+      })
+    ).toContain('export type GetTextResult = string;');
+  });
+
+  it('unions mixed binary + text responses and dedupes identical types', () => {
+    const out = emitWithOp({
+      name: 'getPhoto',
+      successResponses: [
+        { contentType: 'image/png', schema: { kind: 'unknown' }, status: 200 },
+        { contentType: 'image/jpeg', schema: { kind: 'unknown' }, status: 200 },
+        { contentType: 'text/plain', schema: { kind: 'unknown' }, status: 200 },
+      ],
+    });
+    expect(out).toContain('export type GetPhotoResult = Blob | string;');
+    expect(out).not.toContain('Blob | Blob');
+  });
+
+  it('picks JSON when both JSON and non-JSON content types coexist', () => {
+    const out = emitWithOp({
+      name: 'get',
+      successResponses: [
+        { contentType: 'application/xml', schema: { kind: 'ref', name: 'X' }, status: 200 },
+        { contentType: 'application/json', schema: { kind: 'ref', name: 'J' }, status: 200 },
+      ],
+    });
+    expect(out).toContain('export type GetResult = J;');
+  });
+});
diff --git a/packages/client-generator/src/emitters/__tests__/pagination.test.ts b/packages/client-generator/src/emitters/__tests__/pagination.test.ts
new file mode 100644
index 0000000000..ff72604509
--- /dev/null
+++ b/packages/client-generator/src/emitters/__tests__/pagination.test.ts
@@ -0,0 +1,647 @@
+import type {
+  ApiModel,
+  OperationModel,
+  SchemaModel,
+} from '../../intermediate-representation/model.js';
+import {
+  type PaginationRule,
+  resolveModelPagination,
+  resolveOperationPagination,
+  resolveSchemaPointer,
+} from '../pagination.js';
+import { apiModel, namedSchema, operation, param, response, SCALAR } from './fixtures.js';
+
+const ORDER: SchemaModel = {
+  kind: 'object',
+  properties: [{ name: 'id', schema: SCALAR, required: true }],
+};
+const ORDER_LIST: SchemaModel = { kind: 'array', items: { kind: 'ref', name: 'Order' } };
+/** A cursor page: `{ orders: Order[]; nextCursor?: string }`. */
+const ORDER_PAGE: SchemaModel = {
+  kind: 'object',
+  properties: [
+    { name: 'orders', schema: ORDER_LIST, required: true },
+    { name: 'nextCursor', schema: SCALAR, required: false },
+  ],
+};
+
+function modelWith(ops: OperationModel[], extra: Partial<ApiModel> = {}): ApiModel {
+  return apiModel({
+    services: [{ name: 'Default', operations: ops }],
+    schemas: [namedSchema('Order', ORDER), namedSchema('OrderPage', ORDER_PAGE)],
+    ...extra,
+  });
+}
+
+/** `GET /orders` returning an `OrderPage` ref, with the standard advance/limit params. */
+function listOrders(extra: Partial<OperationModel> = {}): OperationModel {
+  return operation({
+    name: 'listOrders',
+    path: '/orders',
+    queryParams: [
+      param('cursor', 'query', false),
+      param('offset', 'query', false, { kind: 'scalar', scalar: 'integer' }),
+      param('page', 'query', false, { kind: 'scalar', scalar: 'number' }),
+      param('limit', 'query', false),
+    ],
+    successResponses: [response({ schema: { kind: 'ref', name: 'OrderPage' } })],
+    ...extra,
+  });
+}
+
+const CURSOR_RULE: PaginationRule = {
+  style: 'cursor',
+  cursorParam: 'cursor',
+  nextCursor: '/nextCursor',
+  items: '/orders',
+};
+const OFFSET_RULE: PaginationRule = { style: 'offset', offsetParam: 'offset', items: '/orders' };
+const PAGE_RULE: PaginationRule = { style: 'page', offsetParam: 'page', items: '/orders' };
+
+describe('resolveSchemaPointer', () => {
+  const model = modelWith([]);
+
+  it('returns the (dereferenced) schema itself for the empty pointer', () => {
+    expect(resolveSchemaPointer({ kind: 'ref', name: 'Order' }, '', model)).toBe(ORDER);
+  });
+
+  it('returns undefined for a pointer that does not start with "/"', () => {
+    expect(resolveSchemaPointer(ORDER_PAGE, 'orders', model)).toBeUndefined();
+  });
+
+  it('walks object properties by name, resolving refs at each step', () => {
+    const root: SchemaModel = {
+      kind: 'object',
+      properties: [{ name: 'data', schema: { kind: 'ref', name: 'OrderPage' }, required: true }],
+    };
+    expect(resolveSchemaPointer(root, '/data/orders', model)).toBe(ORDER_LIST);
+  });
+
+  it('returns undefined for a missing property', () => {
+    expect(resolveSchemaPointer(ORDER_PAGE, '/missing', model)).toBeUndefined();
+  });
+
+  it('steps into a record value for any token', () => {
+    const root: SchemaModel = { kind: 'record', value: { kind: 'ref', name: 'Order' } };
+    expect(resolveSchemaPointer(root, '/anything', model)).toBe(ORDER);
+  });
+
+  it('steps into array items only for a numeric token', () => {
+    expect(resolveSchemaPointer(ORDER_LIST, '/0', model)).toBe(ORDER);
+    expect(resolveSchemaPointer(ORDER_LIST, '/12', model)).toBe(ORDER);
+    expect(resolveSchemaPointer(ORDER_LIST, '/first', model)).toBeUndefined();
+    expect(resolveSchemaPointer(ORDER_LIST, '/01', model)).toBeUndefined();
+  });
+
+  it('bails on unions and intersections (v1 is strict)', () => {
+    const union: SchemaModel = { kind: 'union', members: [ORDER_PAGE, { kind: 'null' }] };
+    expect(resolveSchemaPointer(union, '/orders', model)).toBeUndefined();
+    const intersection: SchemaModel = { kind: 'intersection', members: [ORDER_PAGE] };
+    expect(resolveSchemaPointer(intersection, '/orders', model)).toBeUndefined();
+  });
+
+  it('bails when a step lands on a scalar', () => {
+    expect(resolveSchemaPointer(ORDER_PAGE, '/nextCursor/deeper', model)).toBeUndefined();
+  });
+
+  it('follows a ref chain through the named schemas', () => {
+    const chained = modelWith([], {
+      schemas: [
+        namedSchema('A', { kind: 'ref', name: 'B' }),
+        namedSchema('B', ORDER_PAGE),
+        namedSchema('Order', ORDER),
+      ],
+    });
+    expect(resolveSchemaPointer({ kind: 'ref', name: 'A' }, '/orders', chained)).toBe(ORDER_LIST);
+  });
+
+  it('returns undefined for a ref cycle', () => {
+    const cyclic = modelWith([], {
+      schemas: [
+        namedSchema('A', { kind: 'ref', name: 'B' }),
+        namedSchema('B', { kind: 'ref', name: 'A' }),
+      ],
+    });
+    expect(resolveSchemaPointer({ kind: 'ref', name: 'A' }, '/x', cyclic)).toBeUndefined();
+  });
+
+  it('returns undefined for an unknown ref, at the root and mid-walk', () => {
+    expect(resolveSchemaPointer({ kind: 'ref', name: 'Ghost' }, '/x', model)).toBeUndefined();
+    const root: SchemaModel = {
+      kind: 'object',
+      properties: [{ name: 'data', schema: { kind: 'ref', name: 'Ghost' }, required: true }],
+    };
+    expect(resolveSchemaPointer(root, '/data/x', model)).toBeUndefined();
+  });
+
+  it('unescapes ~1 and ~0 tokens per RFC 6901', () => {
+    const root: SchemaModel = {
+      kind: 'object',
+      properties: [{ name: 'a/b~c', schema: ORDER_LIST, required: true }],
+    };
+    expect(resolveSchemaPointer(root, '/a~1b~0c', model)).toBe(ORDER_LIST);
+  });
+});
+
+describe('resolveOperationPagination — sources and precedence', () => {
+  it('resolves nothing when no source declares pagination', () => {
+    expect(resolveOperationPagination(listOrders(), modelWith([listOrders()]), undefined)).toEqual(
+      {}
+    );
+    expect(resolveOperationPagination(listOrders(), modelWith([listOrders()]), {})).toEqual({});
+  });
+
+  it('applies a per-operation config rule', () => {
+    const result = resolveOperationPagination(listOrders(), modelWith([listOrders()]), {
+      operations: { listOrders: CURSOR_RULE },
+    });
+    expect(result.error).toBeUndefined();
+    expect(result.spec).toEqual({
+      style: 'cursor',
+      param: 'cursor',
+      nextCursor: '/nextCursor',
+      items: '/orders',
+    });
+    expect(result.itemSchema).toEqual({ kind: 'ref', name: 'Order' });
+  });
+
+  it('verifies an optional hasMore pointer (boolean) and carries it into the spec', () => {
+    const connectionPage: SchemaModel = {
+      kind: 'object',
+      properties: [
+        { name: 'orders', schema: ORDER_LIST, required: true },
+        { name: 'endCursor', schema: SCALAR, required: false },
+        {
+          name: 'pageInfo',
+          schema: {
+            kind: 'object',
+            properties: [
+              {
+                name: 'hasNextPage',
+                schema: { kind: 'scalar', scalar: 'boolean' },
+                required: true,
+              },
+            ],
+          },
+          required: true,
+        },
+      ],
+    };
+    const op = listOrders({ successResponses: [response({ schema: connectionPage })] });
+    const rule: PaginationRule = {
+      style: 'cursor',
+      cursorParam: 'cursor',
+      nextCursor: '/endCursor',
+      hasMore: '/pageInfo/hasNextPage',
+      items: '/orders',
+    };
+    const result = resolveOperationPagination(op, modelWith([op]), {
+      operations: { listOrders: rule },
+    });
+    expect(result.error).toBeUndefined();
+    expect(result.spec?.hasMore).toBe('/pageInfo/hasNextPage');
+
+    const missing = resolveOperationPagination(op, modelWith([op]), {
+      operations: { listOrders: { ...rule, hasMore: '/pageInfo/missing' } },
+    });
+    expect(missing.error).toContain('"hasMore" pointer "/pageInfo/missing" does not resolve');
+
+    const notBoolean = resolveOperationPagination(op, modelWith([op]), {
+      operations: { listOrders: { ...rule, hasMore: '/endCursor' } },
+    });
+    expect(notBoolean.error).toContain('must point at a boolean');
+  });
+
+  it('applies the x-pagination extension when no per-op rule exists', () => {
+    const op = listOrders({ paginationExtension: OFFSET_RULE });
+    const result = resolveOperationPagination(op, modelWith([op]), undefined);
+    expect(result.spec).toEqual({ style: 'offset', param: 'offset', items: '/orders' });
+  });
+
+  it('applies the convention rule when config.style is set', () => {
+    const result = resolveOperationPagination(listOrders(), modelWith([listOrders()]), {
+      ...PAGE_RULE,
+      exclude: ['otherOp'],
+    });
+    expect(result.spec).toEqual({ style: 'page', param: 'page', items: '/orders' });
+  });
+
+  it('per-op config beats the extension, which beats the convention', () => {
+    const op = listOrders({ paginationExtension: OFFSET_RULE });
+    const model = modelWith([op]);
+    const perOpWins = resolveOperationPagination(op, model, {
+      ...PAGE_RULE,
+      operations: { listOrders: CURSOR_RULE },
+    });
+    expect(perOpWins.spec?.style).toBe('cursor');
+    const extensionWins = resolveOperationPagination(op, model, { ...PAGE_RULE });
+    expect(extensionWins.spec?.style).toBe('offset');
+  });
+
+  it('matches exclude and operations keys against the spec operationId of a renamed op', () => {
+    const op = listOrders({ name: 'list_orders', specName: 'list-orders' });
+    expect(
+      resolveOperationPagination(op, modelWith([op]), { ...PAGE_RULE, exclude: ['list-orders'] })
+    ).toEqual({});
+    const result = resolveOperationPagination(op, modelWith([op]), {
+      operations: { 'list-orders': CURSOR_RULE },
+    });
+    expect(result.error).toBeUndefined();
+    expect(result.spec?.style).toBe('cursor');
+  });
+
+  it('exclude kills every source for the operation', () => {
+    const op = listOrders({ paginationExtension: OFFSET_RULE });
+    const result = resolveOperationPagination(op, modelWith([op]), {
+      ...PAGE_RULE,
+      exclude: ['listOrders'],
+      operations: { listOrders: CURSOR_RULE },
+    });
+    expect(result).toEqual({});
+  });
+
+  it('carries limitParam into the spec when set', () => {
+    const result = resolveOperationPagination(listOrders(), modelWith([listOrders()]), {
+      operations: { listOrders: { ...OFFSET_RULE, limitParam: 'limit' } },
+    });
+    expect(result.spec).toEqual({
+      style: 'offset',
+      param: 'offset',
+      limitParam: 'limit',
+      items: '/orders',
+    });
+  });
+});
+
+describe('resolveOperationPagination — rule-shape validation (any source)', () => {
+  const model = () => modelWith([listOrders()]);
+
+  it.each([
+    ['a non-object rule', 'nonsense', 'the rule must be an object'],
+    [
+      'an unknown style',
+      { ...CURSOR_RULE, style: 'link' },
+      '"style" must be one of "cursor" | "offset" | "page" (got "link")',
+    ],
+    [
+      'a missing style',
+      { items: '/orders' },
+      '"style" must be one of "cursor" | "offset" | "page" (got undefined)',
+    ],
+    [
+      'missing items',
+      { style: 'cursor', cursorParam: 'cursor', nextCursor: '/nextCursor' },
+      '"items" must be a JSON pointer starting with "/"',
+    ],
+    [
+      'an items pointer without the leading slash',
+      { ...OFFSET_RULE, items: 'orders' },
+      '"items" must be a JSON pointer starting with "/"',
+    ],
+    [
+      'cursor style without cursorParam',
+      { style: 'cursor', nextCursor: '/nextCursor', items: '/orders' },
+      'cursor style requires a "cursorParam" query parameter name',
+    ],
+    [
+      'cursor style without nextCursor',
+      { style: 'cursor', cursorParam: 'cursor', items: '/orders' },
+      'cursor style requires a "nextCursor" JSON pointer starting with "/"',
+    ],
+    [
+      'a nextCursor pointer without the leading slash',
+      { ...CURSOR_RULE, nextCursor: 'nextCursor' },
+      'cursor style requires a "nextCursor" JSON pointer starting with "/"',
+    ],
+    [
+      'offset style without offsetParam',
+      { style: 'offset', items: '/orders' },
+      'offset style requires an "offsetParam" query parameter name',
+    ],
+    [
+      'page style with an empty offsetParam',
+      { style: 'page', offsetParam: '', items: '/orders' },
+      'page style requires an "offsetParam" query parameter name',
+    ],
+    [
+      'a non-string limitParam',
+      { ...OFFSET_RULE, limitParam: 25 },
+      '"limitParam" must be a query parameter name',
+    ],
+  ])('rejects %s from the extension with the x-pagination source', (_case, rule, problem) => {
+    const op = listOrders({ paginationExtension: rule });
+    const { spec, error } = resolveOperationPagination(op, model(), undefined);
+    expect(spec).toBeUndefined();
+    expect(error).toBe(`Pagination for operation "listOrders" (x-pagination): ${problem}`);
+  });
+
+  it('names the per-operation config source in shape errors', () => {
+    const { error } = resolveOperationPagination(listOrders(), model(), {
+      operations: { listOrders: { style: 'offset', items: '/orders' } as PaginationRule },
+    });
+    expect(error).toBe(
+      'Pagination for operation "listOrders" (pagination.operations["listOrders"]): ' +
+        'offset style requires an "offsetParam" query parameter name'
+    );
+  });
+
+  it('rejects a malformed convention too — a config bug, never silence', () => {
+    const { error } = resolveOperationPagination(listOrders(), model(), {
+      style: 'cursor',
+      items: '/orders',
+    });
+    expect(error).toBe(
+      'Pagination for operation "listOrders" (pagination convention): ' +
+        'cursor style requires a "cursorParam" query parameter name'
+    );
+  });
+});
+
+describe('resolveOperationPagination — fit verification', () => {
+  it.each([
+    [
+      'an advance param missing from the query params',
+      { ...CURSOR_RULE, cursorParam: 'after' },
+      'query parameter "after" is not declared on the operation',
+    ],
+    [
+      'an unresolvable items pointer',
+      { ...OFFSET_RULE, items: '/results' },
+      'the "items" pointer "/results" does not resolve in the success response schema',
+    ],
+    [
+      'an items pointer landing on a non-array',
+      { ...OFFSET_RULE, items: '/nextCursor' },
+      'the "items" pointer "/nextCursor" must point at an array (got scalar)',
+    ],
+    [
+      'an unresolvable nextCursor pointer',
+      { ...CURSOR_RULE, nextCursor: '/meta/next' },
+      'the "nextCursor" pointer "/meta/next" does not resolve in the success response schema',
+    ],
+  ])('explicit source: %s is an error', (_case, rule, problem) => {
+    const op = listOrders({ paginationExtension: rule });
+    const { spec, error } = resolveOperationPagination(op, modelWith([op]), undefined);
+    expect(spec).toBeUndefined();
+    expect(error).toBe(`Pagination for operation "listOrders" (x-pagination): ${problem}`);
+  });
+
+  it('convention that does not fit resolves to nothing, silently', () => {
+    const model = modelWith([listOrders()]);
+    for (const rule of [
+      { ...CURSOR_RULE, cursorParam: 'after' },
+      { ...OFFSET_RULE, items: '/results' },
+      { ...OFFSET_RULE, items: '/nextCursor' },
+      { ...CURSOR_RULE, nextCursor: '/meta/next' },
+    ]) {
+      expect(resolveOperationPagination(listOrders(), model, rule)).toEqual({});
+    }
+  });
+
+  it('requires a JSON success response', () => {
+    const op = listOrders({
+      paginationExtension: OFFSET_RULE,
+      successResponses: [response({ contentType: 'text/plain' })],
+    });
+    const { error } = resolveOperationPagination(op, modelWith([op]), undefined);
+    expect(error).toBe(
+      'Pagination for operation "listOrders" (x-pagination): ' +
+        'the operation has no JSON success response'
+    );
+    const conventionOnly = listOrders({
+      successResponses: [response({ contentType: 'text/plain' })],
+    });
+    expect(
+      resolveOperationPagination(conventionOnly, modelWith([conventionOnly]), { ...OFFSET_RULE })
+    ).toEqual({});
+  });
+
+  it('never paginates a Server-Sent Events operation (explicit source errors)', () => {
+    const sseOp = listOrders({
+      paginationExtension: OFFSET_RULE,
+      successResponses: [response({ contentType: 'text/event-stream' })],
+    });
+    const { error } = resolveOperationPagination(sseOp, modelWith([sseOp]), undefined);
+    expect(error).toBe(
+      'Pagination for operation "listOrders" (x-pagination): ' +
+        'the operation is a Server-Sent Events stream'
+    );
+    const conventionOnly = listOrders({
+      successResponses: [response({ contentType: 'text/event-stream' })],
+    });
+    expect(
+      resolveOperationPagination(conventionOnly, modelWith([conventionOnly]), OFFSET_RULE)
+    ).toEqual({});
+  });
+
+  it('resolves pointers over the JSON success response even when another response comes first', () => {
+    const op = listOrders({
+      paginationExtension: CURSOR_RULE,
+      successResponses: [
+        response({ contentType: 'text/plain' }),
+        response({ schema: { kind: 'ref', name: 'OrderPage' }, status: 200 }),
+      ],
+    });
+    const result = resolveOperationPagination(op, modelWith([op]), undefined);
+    expect(result.spec?.style).toBe('cursor');
+    expect(result.itemSchema).toEqual({ kind: 'ref', name: 'Order' });
+  });
+
+  describe('advance param schema fit', () => {
+    /** `listOrders` whose single query param carries the given schema. */
+    const withParamSchema = (name: string, schema: SchemaModel, rule: unknown): OperationModel =>
+      listOrders({ paginationExtension: rule, queryParams: [param(name, 'query', false, schema)] });
+
+    it.each<[string, PaginationRule, string, SchemaModel, string]>([
+      [
+        'a numeric cursor param',
+        CURSOR_RULE,
+        'cursor',
+        { kind: 'scalar', scalar: 'integer' },
+        'the "cursorParam" query parameter "cursor" must accept a string (got integer)',
+      ],
+      [
+        'an object cursor param',
+        CURSOR_RULE,
+        'cursor',
+        ORDER,
+        'the "cursorParam" query parameter "cursor" must accept a string (got object)',
+      ],
+      [
+        'a string offset param',
+        OFFSET_RULE,
+        'offset',
+        SCALAR,
+        'the "offsetParam" query parameter "offset" must accept a number (got string)',
+      ],
+      [
+        'a boolean offset param',
+        OFFSET_RULE,
+        'offset',
+        { kind: 'scalar', scalar: 'boolean' },
+        'the "offsetParam" query parameter "offset" must accept a number (got boolean)',
+      ],
+      [
+        'a numeric-enum page param (numbers must be plain scalars)',
+        PAGE_RULE,
+        'page',
+        { kind: 'enum', values: [1, 2], scalar: 'integer' },
+        'the "offsetParam" query parameter "page" must accept a number (got integer)',
+      ],
+      [
+        'an object page param',
+        PAGE_RULE,
+        'page',
+        ORDER,
+        'the "offsetParam" query parameter "page" must accept a number (got object)',
+      ],
+      [
+        'an unresolvable-ref offset param',
+        OFFSET_RULE,
+        'offset',
+        { kind: 'ref', name: 'Ghost' },
+        'the "offsetParam" query parameter "offset" must accept a number (got an unresolvable ref)',
+      ],
+    ])('explicit source: %s is an error', (_case, rule, name, schema, problem) => {
+      const op = withParamSchema(name, schema, rule);
+      const { spec, error } = resolveOperationPagination(op, modelWith([op]), undefined);
+      expect(spec).toBeUndefined();
+      expect(error).toBe(`Pagination for operation "listOrders" (x-pagination): ${problem}`);
+    });
+
+    it('convention with a misfitting advance param resolves to nothing, silently', () => {
+      for (const [rule, name, schema] of [
+        [CURSOR_RULE, 'cursor', { kind: 'scalar', scalar: 'integer' }],
+        [OFFSET_RULE, 'offset', SCALAR],
+        [PAGE_RULE, 'page', ORDER],
+      ] as Array<[PaginationRule, string, SchemaModel]>) {
+        const op = listOrders({ queryParams: [param(name, 'query', false, schema)] });
+        expect(resolveOperationPagination(op, modelWith([op]), rule)).toEqual({});
+      }
+    });
+
+    it('resolves the advance param schema through refs (string cursor, integer offset)', () => {
+      const schemas = [
+        namedSchema('Order', ORDER),
+        namedSchema('OrderPage', ORDER_PAGE),
+        namedSchema('Cursor', SCALAR),
+        namedSchema('Offset', { kind: 'scalar', scalar: 'integer' }),
+      ];
+      const cursorOp = withParamSchema('cursor', { kind: 'ref', name: 'Cursor' }, CURSOR_RULE);
+      expect(
+        resolveOperationPagination(cursorOp, modelWith([cursorOp], { schemas }), undefined).spec
+          ?.style
+      ).toBe('cursor');
+      const offsetOp = withParamSchema('offset', { kind: 'ref', name: 'Offset' }, OFFSET_RULE);
+      expect(
+        resolveOperationPagination(offsetOp, modelWith([offsetOp], { schemas }), undefined).spec
+          ?.style
+      ).toBe('offset');
+    });
+
+    it('tolerates a nullable string union on the cursor param (same predicate as nextCursor)', () => {
+      const op = withParamSchema(
+        'cursor',
+        { kind: 'union', members: [SCALAR, { kind: 'null' }] },
+        CURSOR_RULE
+      );
+      const result = resolveOperationPagination(op, modelWith([op]), undefined);
+      expect(result.error).toBeUndefined();
+      expect(result.spec?.param).toBe('cursor');
+    });
+  });
+
+  describe('nextCursor string-ish check', () => {
+    function cursorWith(nextCursorSchema: SchemaModel): {
+      op: OperationModel;
+      model: ApiModel;
+    } {
+      const page: SchemaModel = {
+        kind: 'object',
+        properties: [
+          { name: 'orders', schema: ORDER_LIST, required: true },
+          { name: 'nextCursor', schema: nextCursorSchema, required: false },
+        ],
+      };
+      const op = listOrders({
+        paginationExtension: CURSOR_RULE,
+        successResponses: [response({ schema: page })],
+      });
+      return { op, model: modelWith([op]) };
+    }
+
+    it.each<[string, SchemaModel]>([
+      ['a string scalar', SCALAR],
+      ['a string enum', { kind: 'enum', values: ['a', 'b'], scalar: 'string' }],
+      ['a string literal', { kind: 'literal', value: 'next' }],
+      ['a nullable string union', { kind: 'union', members: [SCALAR, { kind: 'null' }] }],
+      [
+        'a nullable string union through a ref',
+        { kind: 'union', members: [{ kind: 'ref', name: 'Cursor' }, { kind: 'null' }] },
+      ],
+    ])('accepts %s', (_label, schema) => {
+      const { op } = cursorWith(schema);
+      const model = modelWith([op], {
+        schemas: [namedSchema('Order', ORDER), namedSchema('Cursor', SCALAR)],
+      });
+      const result = resolveOperationPagination(op, model, undefined);
+      expect(result.error).toBeUndefined();
+      expect(result.spec?.nextCursor).toBe('/nextCursor');
+    });
+
+    it.each<[string, SchemaModel]>([
+      ['a number scalar', { kind: 'scalar', scalar: 'number' }],
+      ['a numeric enum', { kind: 'enum', values: [1, 2], scalar: 'number' }],
+      ['a numeric literal', { kind: 'literal', value: 7 }],
+      ['an object', ORDER],
+      ['a union with a non-string member', { kind: 'union', members: [SCALAR, ORDER] }],
+      [
+        'a union nesting another union',
+        { kind: 'union', members: [{ kind: 'union', members: [SCALAR] }, { kind: 'null' }] },
+      ],
+      [
+        'a union whose member ref is unresolvable',
+        { kind: 'union', members: [{ kind: 'ref', name: 'Ghost' }, { kind: 'null' }] },
+      ],
+    ])('rejects %s', (_label, schema) => {
+      const { op, model } = cursorWith(schema);
+      const { error } = resolveOperationPagination(op, model, undefined);
+      expect(error).toContain('the "nextCursor" pointer "/nextCursor" must point at a string');
+    });
+  });
+});
+
+describe('resolveModelPagination', () => {
+  it('maps only the operations that resolve, keyed by operation name', () => {
+    const paginated = listOrders({ paginationExtension: CURSOR_RULE });
+    const plain = operation({ name: 'getOrder', path: '/orders/{id}' });
+    const map = resolveModelPagination(modelWith([paginated, plain]), undefined);
+    expect([...map.keys()]).toEqual(['listOrders']);
+    expect(map.get('listOrders')).toEqual({
+      spec: { style: 'cursor', param: 'cursor', nextCursor: '/nextCursor', items: '/orders' },
+      itemSchema: { kind: 'ref', name: 'Order' },
+    });
+  });
+
+  it('aggregates every error into one throw, listing each operation', () => {
+    const bad1 = listOrders({
+      name: 'listOrders',
+      paginationExtension: { ...CURSOR_RULE, cursorParam: 'after' },
+    });
+    const bad2 = listOrders({
+      name: 'listRefunds',
+      paginationExtension: { style: 'nope' },
+    });
+    expect(() => resolveModelPagination(modelWith([bad1, bad2]), undefined)).toThrow(
+      'Invalid pagination configuration:\n' +
+        '  - Pagination for operation "listOrders" (x-pagination): ' +
+        'query parameter "after" is not declared on the operation\n' +
+        '  - Pagination for operation "listRefunds" (x-pagination): ' +
+        '"style" must be one of "cursor" | "offset" | "page" (got "nope")'
+    );
+  });
+
+  it('returns an empty map for a model with no pagination anywhere', () => {
+    expect(resolveModelPagination(modelWith([listOrders()]), undefined).size).toBe(0);
+  });
+});
diff --git a/packages/client-generator/src/emitters/__tests__/runtime-sources.test.ts b/packages/client-generator/src/emitters/__tests__/runtime-sources.test.ts
new file mode 100644
index 0000000000..8c304cd504
--- /dev/null
+++ b/packages/client-generator/src/emitters/__tests__/runtime-sources.test.ts
@@ -0,0 +1,21 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { RUNTIME_SOURCES } from '../runtime-sources.js';
+
+const runtimeDir = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'runtime');
+
+describe('runtime-sources', () => {
+  it('the generated snapshot matches src/runtime (every module except the barrel)', () => {
+    const expected = Object.fromEntries(
+      readdirSync(runtimeDir)
+        .filter((name) => name.endsWith('.ts') && name !== 'index.ts')
+        .map((name) => [name, readFileSync(join(runtimeDir, name), 'utf-8')])
+    );
+    expect(
+      { ...RUNTIME_SOURCES },
+      'emitters/runtime-sources.ts is stale — run `npm run prepare -w @redocly/client-generator`'
+    ).toEqual(expected);
+  });
+});
diff --git a/packages/client-generator/src/emitters/__tests__/sample.test.ts b/packages/client-generator/src/emitters/__tests__/sample.test.ts
new file mode 100644
index 0000000000..fcc21b2ad0
--- /dev/null
+++ b/packages/client-generator/src/emitters/__tests__/sample.test.ts
@@ -0,0 +1,356 @@
+import type { NamedSchemaModel, SchemaModel } from '../../intermediate-representation/model.js';
+import { sampleValue, SampleExpression } from '../sample.js';
+
+describe('sampleValue', () => {
+  it('samples scalars with deterministic, format-aware values', () => {
+    expect(sampleValue({ kind: 'scalar', scalar: 'string' }, [])).toBe('string');
+    expect(sampleValue({ kind: 'scalar', scalar: 'integer' }, [])).toBe(0);
+    expect(sampleValue({ kind: 'scalar', scalar: 'number' }, [])).toBe(0);
+    expect(sampleValue({ kind: 'scalar', scalar: 'boolean' }, [])).toBe(true);
+    expect(
+      sampleValue({ kind: 'scalar', scalar: 'string', metadata: { format: 'email' } }, [])
+    ).toBe('user@example.com');
+    expect(
+      sampleValue({ kind: 'scalar', scalar: 'string', metadata: { format: 'uuid' } }, [])
+    ).toBe('00000000-0000-4000-8000-000000000000');
+    expect(
+      sampleValue({ kind: 'scalar', scalar: 'string', metadata: { format: 'date-time' } }, [])
+    ).toBe('2024-01-01T00:00:00Z');
+    expect(
+      sampleValue({ kind: 'scalar', scalar: 'string', metadata: { format: 'date' } }, [])
+    ).toBe('2024-01-01');
+    expect(sampleValue({ kind: 'scalar', scalar: 'string', metadata: { format: 'uri' } }, [])).toBe(
+      'https://example.com'
+    );
+    expect(sampleValue({ kind: 'scalar', scalar: 'string', metadata: { format: 'url' } }, [])).toBe(
+      'https://example.com'
+    );
+  });
+
+  it('samples a `format: binary` field as a `new Blob([])` raw expression (not a JSON literal)', () => {
+    const sampled = sampleValue(
+      { kind: 'scalar', scalar: 'string', metadata: { format: 'binary' } },
+      []
+    );
+    expect(sampled).toBeInstanceOf(SampleExpression);
+    expect((sampled as SampleExpression).code).toBe('new Blob([])');
+  });
+
+  it('samples a `format: binary` field as `new Blob([])` even when an example is present', () => {
+    // The generated type is `Blob` regardless of any spec example, so baking the
+    // example string would not type-check — the type-demanded expression wins.
+    expect(
+      sampleValue(
+        { kind: 'scalar', scalar: 'string', metadata: { format: 'binary', example: 'AAAA' } },
+        []
+      )
+    ).toBeInstanceOf(SampleExpression);
+  });
+
+  it('samples date/date-time as `new Date(...)` when dateType is `Date`', () => {
+    const dt = sampleValue(
+      { kind: 'scalar', scalar: 'string', metadata: { format: 'date-time' } },
+      [],
+      { dateType: 'Date' }
+    );
+    expect(dt).toBeInstanceOf(SampleExpression);
+    expect((dt as SampleExpression).code).toBe('new Date("2024-01-01T00:00:00Z")');
+
+    const d = sampleValue({ kind: 'scalar', scalar: 'string', metadata: { format: 'date' } }, [], {
+      dateType: 'Date',
+    });
+    expect((d as SampleExpression).code).toBe('new Date("2024-01-01")');
+  });
+
+  it('samples date-time as `new Date(...)` even with an example when dateType is `Date`', () => {
+    expect(
+      sampleValue(
+        {
+          kind: 'scalar',
+          scalar: 'string',
+          metadata: { format: 'date-time', example: '2020-05-05T00:00:00Z' },
+        },
+        [],
+        { dateType: 'Date' }
+      )
+    ).toBeInstanceOf(SampleExpression);
+  });
+
+  it('under dateType `Date`, a non-date scalar still samples normally (no type demand)', () => {
+    expect(
+      sampleValue({ kind: 'scalar', scalar: 'string', metadata: { format: 'email' } }, [], {
+        dateType: 'Date',
+      })
+    ).toBe('user@example.com');
+  });
+
+  it('regression: default dateType `string` bakes the ISO string and still honors an example', () => {
+    expect(
+      sampleValue({ kind: 'scalar', scalar: 'string', metadata: { format: 'date-time' } }, [])
+    ).toBe('2024-01-01T00:00:00Z');
+    expect(
+      sampleValue(
+        {
+          kind: 'scalar',
+          scalar: 'string',
+          metadata: { format: 'date-time', example: '2020-01-01T00:00:00Z' },
+        },
+        []
+      )
+    ).toBe('2020-01-01T00:00:00Z');
+  });
+
+  it('prefers example then default over synthesis', () => {
+    expect(
+      sampleValue({ kind: 'scalar', scalar: 'string', metadata: { example: 'Ada' } }, [])
+    ).toBe('Ada');
+    expect(sampleValue({ kind: 'scalar', scalar: 'string', metadata: { default: 'D' } }, [])).toBe(
+      'D'
+    );
+    expect(
+      sampleValue(
+        { kind: 'scalar', scalar: 'string', metadata: { example: 'E', default: 'D' } },
+        []
+      )
+    ).toBe('E');
+  });
+
+  it('samples enum (first value) and literal (its value)', () => {
+    expect(sampleValue({ kind: 'enum', scalar: 'string', values: ['a', 'b'] }, [])).toBe('a');
+    expect(sampleValue({ kind: 'literal', value: 42 }, [])).toBe(42);
+  });
+
+  it('samples objects (all properties) and arrays (one item)', () => {
+    const obj: SchemaModel = {
+      kind: 'object',
+      properties: [
+        { name: 'id', schema: { kind: 'scalar', scalar: 'integer' }, required: true },
+        { name: 'tag', schema: { kind: 'scalar', scalar: 'string' }, required: false },
+      ],
+    };
+    expect(sampleValue(obj, [])).toEqual({ id: 0, tag: 'string' });
+    expect(
+      sampleValue({ kind: 'array', items: { kind: 'scalar', scalar: 'boolean' } }, [])
+    ).toEqual([true]);
+  });
+
+  it('resolves refs against the named-schema set', () => {
+    const schemas: NamedSchemaModel[] = [
+      {
+        name: 'Pet',
+        schema: {
+          kind: 'object',
+          properties: [
+            { name: 'name', schema: { kind: 'scalar', scalar: 'string' }, required: true },
+          ],
+        },
+      },
+    ];
+    expect(sampleValue({ kind: 'ref', name: 'Pet' }, schemas)).toEqual({ name: 'string' });
+  });
+
+  it('returns null for an unresolved ref', () => {
+    expect(sampleValue({ kind: 'ref', name: 'Missing' }, [])).toBeNull();
+  });
+
+  it('terminates a recursive ref behind an OPTIONAL property by omitting it (a null would not type-check)', () => {
+    // `next?: Node` is `Node | undefined`; a `null` there is a TS2322. Omitting the
+    // optional property is the type-correct way to break the cycle.
+    const schemas: NamedSchemaModel[] = [
+      {
+        name: 'Node',
+        schema: {
+          kind: 'object',
+          properties: [{ name: 'next', schema: { kind: 'ref', name: 'Node' }, required: false }],
+        },
+      },
+    ];
+    expect(sampleValue({ kind: 'ref', name: 'Node' }, schemas)).toEqual({});
+  });
+
+  it('terminates a recursive ref behind an ARRAY with an empty array (a valid `T[]`)', () => {
+    // A tree: `children: Category[]` (required). At the cycle the array must collapse to
+    // `[]` — which IS a valid `Category[]` — rather than `[null]` (TS2322).
+    const schemas: NamedSchemaModel[] = [
+      {
+        name: 'Category',
+        schema: {
+          kind: 'object',
+          properties: [
+            { name: 'id', schema: { kind: 'scalar', scalar: 'integer' }, required: true },
+            {
+              name: 'children',
+              schema: { kind: 'array', items: { kind: 'ref', name: 'Category' } },
+              required: true,
+            },
+          ],
+        },
+      },
+    ];
+    expect(sampleValue({ kind: 'ref', name: 'Category' }, schemas)).toEqual({
+      id: 0,
+      children: [],
+    });
+  });
+
+  it('terminates a recursive ref behind a RECORD with an empty record', () => {
+    const schemas: NamedSchemaModel[] = [
+      {
+        name: 'Tree',
+        schema: {
+          kind: 'object',
+          properties: [
+            {
+              name: 'nodes',
+              schema: { kind: 'record', value: { kind: 'ref', name: 'Tree' } },
+              required: true,
+            },
+          ],
+        },
+      },
+    ];
+    expect(sampleValue({ kind: 'ref', name: 'Tree' }, schemas)).toEqual({
+      nodes: {},
+    });
+  });
+
+  it('a REQUIRED direct self-ref is genuinely uninhabitable, so it falls back to null', () => {
+    // `self: Node` (required, not behind an array/optional) cannot be finitely constructed;
+    // null is the only available stand-in (and the schema itself is uninhabitable).
+    const schemas: NamedSchemaModel[] = [
+      {
+        name: 'Node',
+        schema: {
+          kind: 'object',
+          properties: [{ name: 'self', schema: { kind: 'ref', name: 'Node' }, required: true }],
+        },
+      },
+    ];
+    expect(sampleValue({ kind: 'ref', name: 'Node' }, schemas)).toEqual({ self: null });
+  });
+
+  it('a self-referential union with no inhabitable member resolves to null', () => {
+    const schemas: NamedSchemaModel[] = [
+      { name: 'A', schema: { kind: 'union', members: [{ kind: 'ref', name: 'A' }] } },
+    ];
+    expect(sampleValue({ kind: 'ref', name: 'A' }, schemas)).toBeNull();
+  });
+
+  it('samples union (first member), intersection (merged objects), null, unknown, record', () => {
+    expect(
+      sampleValue(
+        { kind: 'union', members: [{ kind: 'literal', value: 'x' }, { kind: 'null' }] },
+        []
+      )
+    ).toBe('x');
+    expect(
+      sampleValue(
+        {
+          kind: 'intersection',
+          members: [
+            {
+              kind: 'object',
+              properties: [
+                { name: 'a', schema: { kind: 'scalar', scalar: 'integer' }, required: true },
+              ],
+            },
+            {
+              kind: 'object',
+              properties: [
+                { name: 'b', schema: { kind: 'scalar', scalar: 'boolean' }, required: true },
+              ],
+            },
+          ],
+        },
+        []
+      )
+    ).toEqual({ a: 0, b: true });
+    expect(sampleValue({ kind: 'null' }, [])).toBeNull();
+    expect(sampleValue({ kind: 'unknown' }, [])).toBeNull();
+    expect(
+      sampleValue({ kind: 'record', value: { kind: 'scalar', scalar: 'string' } }, [])
+    ).toEqual({ key: 'string' });
+  });
+
+  it('samples omit by dropping the named keys from the base named schema', () => {
+    const schemas: NamedSchemaModel[] = [
+      {
+        name: 'Full',
+        schema: {
+          kind: 'object',
+          properties: [
+            { name: 'id', schema: { kind: 'scalar', scalar: 'integer' }, required: true },
+            { name: 'secret', schema: { kind: 'scalar', scalar: 'string' }, required: false },
+          ],
+        },
+      },
+    ];
+    // omit.base is a string (named schema reference), not a SchemaModel
+    expect(sampleValue({ kind: 'omit', base: 'Full', keys: ['secret'] }, schemas)).toEqual({
+      id: 0,
+    });
+  });
+
+  it('returns null for omit with an unresolved base', () => {
+    expect(sampleValue({ kind: 'omit', base: 'Missing', keys: ['x'] }, [])).toBeNull();
+  });
+
+  it('returns base value unchanged for omit when base resolves to a non-object', () => {
+    const schemas: NamedSchemaModel[] = [
+      { name: 'Scalar', schema: { kind: 'scalar', scalar: 'string' } },
+    ];
+    expect(sampleValue({ kind: 'omit', base: 'Scalar', keys: ['x'] }, schemas)).toBe('string');
+  });
+
+  it('omit does not mutate the base schema — sampling the same omit node twice yields independent objects', () => {
+    const schemas: NamedSchemaModel[] = [
+      {
+        name: 'Full',
+        schema: {
+          kind: 'object',
+          properties: [
+            { name: 'id', schema: { kind: 'scalar', scalar: 'integer' }, required: true },
+            { name: 'secret', schema: { kind: 'scalar', scalar: 'string' }, required: false },
+          ],
+        },
+      },
+    ];
+    const omitSchema: SchemaModel = { kind: 'omit', base: 'Full', keys: ['secret'] };
+    // First sample should drop 'secret'
+    const first = sampleValue(omitSchema, schemas) as Record<string, unknown>;
+    expect(first).toEqual({ id: 0 });
+    // The base named schema 'Full' must still produce both keys (no mutation leaked)
+    expect(sampleValue({ kind: 'ref', name: 'Full' }, schemas)).toEqual({
+      id: 0,
+      secret: 'string',
+    });
+    // Second omit sample must still work correctly
+    const second = sampleValue(omitSchema, schemas) as Record<string, unknown>;
+    expect(second).toEqual({ id: 0 });
+  });
+
+  it('returns null for a union with no members', () => {
+    expect(sampleValue({ kind: 'union', members: [] }, [])).toBeNull();
+  });
+
+  it('intersection skips non-object members', () => {
+    // A union member that resolves to a scalar (non-object) should be skipped in reduce
+    expect(
+      sampleValue(
+        {
+          kind: 'intersection',
+          members: [
+            { kind: 'scalar', scalar: 'string' },
+            {
+              kind: 'object',
+              properties: [
+                { name: 'a', schema: { kind: 'scalar', scalar: 'integer' }, required: true },
+              ],
+            },
+          ],
+        },
+        []
+      )
+    ).toEqual({ a: 0 });
+  });
+});
diff --git a/packages/client-generator/src/emitters/__tests__/setup-bake.test.ts b/packages/client-generator/src/emitters/__tests__/setup-bake.test.ts
new file mode 100644
index 0000000000..ffb1fea43e
--- /dev/null
+++ b/packages/client-generator/src/emitters/__tests__/setup-bake.test.ts
@@ -0,0 +1,61 @@
+import { outdent } from 'outdent';
+
+import { bakeSetup } from '../setup-bake.js';
+
+const FILE = outdent`
+  import { defineClientSetup, type RequestContext } from '@redocly/client-generator';
+  export default defineClientSetup({
+    config: { serverUrl: 'https://api.acme.com', retry: { retries: 3 } },
+    middleware: [{ onRequest: (ctx: RequestContext) => { ctx.headers['X-Acme'] = '1'; } }],
+  });
+`;
+
+describe('bakeSetup', () => {
+  it('returns the setup expression with the package import stripped', () => {
+    const out = bakeSetup(FILE);
+    expect(out).not.toContain("from '@redocly/client-generator'");
+    expect(out).not.toContain('defineClientSetup');
+    expect(out).toContain("serverUrl: 'https://api.acme.com'");
+    expect(out).toContain("ctx.headers['X-Acme'] = '1'");
+    // A neutral expression only — applying it (mergeSetup) is the emitter's job.
+    expect(out).not.toContain('configure(');
+    expect(out).not.toContain('use(');
+  });
+
+  it('rejects a setup file importing anything but @redocly/client-generator', () => {
+    expect(() => bakeSetup(`import x from 'axios';\nexport default x;`)).toThrow(
+      /may only import from "@redocly\/client-generator"/
+    );
+  });
+
+  it('errors when there is no default export', () => {
+    expect(() => bakeSetup(`const x = 1;`)).toThrow(/export default/);
+  });
+
+  it('accepts a bare default-exported object (no defineClientSetup wrapper)', () => {
+    const out = bakeSetup(`export default { config: { serverUrl: 'https://x' } };`);
+    expect(out).toBe("{ config: { serverUrl: 'https://x' } }");
+  });
+
+  it('unwraps a renamed (aliased) defineClientSetup import', () => {
+    const out = bakeSetup(outdent`
+      import { defineClientSetup as setup } from '@redocly/client-generator';
+      export default setup({ config: { serverUrl: 'https://x' } });
+    `);
+    // The alias is unwrapped to the bare argument — no dangling call to the dropped import.
+    expect(out).toBe("{ config: { serverUrl: 'https://x' } }");
+    expect(out).not.toContain('setup(');
+  });
+
+  it('wraps file-level helper declarations in an IIFE so they are preserved and scoped', () => {
+    const out = bakeSetup(outdent`
+      import { defineClientSetup } from '@redocly/client-generator';
+      const VERSION = '9.9';
+      export default defineClientSetup({ config: { headers: { 'X-V': VERSION } } });
+    `);
+    expect(out.startsWith('(() => {')).toBe(true);
+    expect(out).toContain("const VERSION = '9.9'");
+    expect(out).toContain("'X-V': VERSION");
+    expect(out).toContain('return ');
+  });
+});
diff --git a/packages/client-generator/src/emitters/__tests__/sse.test.ts b/packages/client-generator/src/emitters/__tests__/sse.test.ts
new file mode 100644
index 0000000000..fb66c99588
--- /dev/null
+++ b/packages/client-generator/src/emitters/__tests__/sse.test.ts
@@ -0,0 +1,107 @@
+import type { ResponseBodyModel, SchemaModel } from '../../intermediate-representation/model.js';
+import { isSseOp, sseDataKind, sseEventType } from '../sse.js';
+import { printNodes } from '../ts.js';
+import { operation } from './fixtures.js';
+
+/** An operation whose success response streams `text/event-stream`. */
+function sseOp(response: Partial<ResponseBodyModel>, name = 'streamMessages') {
+  return operation({
+    name,
+    successResponses: [
+      { contentType: 'text/event-stream', schema: { kind: 'unknown' }, ...response, status: 200 },
+    ],
+  });
+}
+
+describe('isSseOp', () => {
+  it('is true for a success response with the text/event-stream content type', () => {
+    expect(isSseOp(sseOp({}))).toBe(true);
+  });
+
+  it('matches with parameters and is case-insensitive', () => {
+    expect(isSseOp(sseOp({ contentType: 'text/event-stream; charset=utf-8' }))).toBe(true);
+    expect(isSseOp(sseOp({ contentType: 'Text/Event-Stream' }))).toBe(true);
+  });
+
+  it('is false for a plain JSON operation', () => {
+    expect(
+      isSseOp(
+        operation({
+          successResponses: [
+            { contentType: 'application/json', schema: { kind: 'ref', name: 'Pet' }, status: 200 },
+          ],
+        })
+      )
+    ).toBe(false);
+  });
+
+  it('is false for an operation with no responses', () => {
+    expect(isSseOp(operation({}))).toBe(false);
+  });
+});
+
+describe('sseEventType', () => {
+  it('uses the per-item schema when present (a ref → a Message reference)', () => {
+    const out = printNodes([
+      sseEventType(sseOp({ itemSchema: { kind: 'ref', name: 'Message' } }), 'string'),
+    ]);
+    expect(out).toContain('Message');
+  });
+
+  it('falls back to the response schema when it is meaningful', () => {
+    const out = printNodes([
+      sseEventType(sseOp({ schema: { kind: 'ref', name: 'Token' } }), 'string'),
+    ]);
+    expect(out).toContain('Token');
+  });
+
+  it('ignores a typeless `itemSchema` and falls back to the response schema', () => {
+    const out = printNodes([
+      sseEventType(
+        sseOp({ itemSchema: { kind: 'unknown' }, schema: { kind: 'ref', name: 'Token' } }),
+        'string'
+      ),
+    ]);
+    expect(out).toContain('Token');
+  });
+
+  it('falls back to the `string` keyword when no schema is declared', () => {
+    expect(printNodes([sseEventType(sseOp({}), 'string')])).toBe('string');
+  });
+
+  it('falls back to `string` when the op is not an SSE op at all', () => {
+    expect(printNodes([sseEventType(operation({}), 'string')])).toBe('string');
+  });
+});
+
+describe('sseDataKind', () => {
+  it("is 'json' for object/ref/array/record/union/intersection event types", () => {
+    const json: SchemaModel[] = [
+      { kind: 'object', properties: [] },
+      { kind: 'ref', name: 'Message' },
+      { kind: 'array', items: { kind: 'scalar', scalar: 'string' } },
+      { kind: 'record', value: { kind: 'scalar', scalar: 'string' } },
+      { kind: 'union', members: [{ kind: 'ref', name: 'A' }] },
+      { kind: 'intersection', members: [{ kind: 'ref', name: 'A' }] },
+    ];
+    for (const itemSchema of json) expect(sseDataKind(sseOp({ itemSchema }))).toBe('json');
+  });
+
+  it("is 'text' for the string fallback (no schema)", () => {
+    expect(sseDataKind(sseOp({}))).toBe('text');
+  });
+
+  it("is 'text' for a typeless `itemSchema` (no meaningful schema)", () => {
+    expect(sseDataKind(sseOp({ itemSchema: { kind: 'unknown' } }))).toBe('text');
+  });
+
+  it("is 'text' for scalar/literal/enum/null event types", () => {
+    const text: SchemaModel[] = [
+      { kind: 'scalar', scalar: 'string' },
+      { kind: 'literal', value: 'x' },
+      { kind: 'enum', values: ['a'], scalar: 'string' },
+      { kind: 'null' },
+    ];
+    for (const itemSchema of text) expect(sseDataKind(sseOp({ itemSchema }))).toBe('text');
+  });
+});
diff --git a/packages/client-generator/src/emitters/__tests__/swr.test.ts b/packages/client-generator/src/emitters/__tests__/swr.test.ts
new file mode 100644
index 0000000000..0004e0be7e
--- /dev/null
+++ b/packages/client-generator/src/emitters/__tests__/swr.test.ts
@@ -0,0 +1,214 @@
+import { renderSwrModule } from '../swr.js';
+import { apiModel, namedSchema, operation, param, SCALAR } from './fixtures.js';
+
+const SDK = './client.js';
+
+function render(ops: Parameters<typeof operation>[0][], argsStyle: 'flat' | 'grouped' = 'grouped') {
+  return renderSwrModule(
+    apiModel({ services: [{ name: 'Default', operations: ops.map(operation) }] }),
+    { sdkModule: SDK, argsStyle }
+  );
+}
+
+describe('renderSwrModule', () => {
+  it('returns empty string when the model has no operations', () => {
+    expect(renderSwrModule(apiModel(), { sdkModule: SDK, argsStyle: 'flat' })).toBe('');
+  });
+
+  it('skips SSE operations (not exported by the sdk) and wraps only the regular ones', () => {
+    const out = render([
+      {
+        name: 'getPet',
+        method: 'get',
+        path: '/pets/{id}',
+        pathParams: [param('id', 'path', true)],
+      },
+      {
+        name: 'streamEvents',
+        method: 'get',
+        path: '/events',
+        successResponses: [{ contentType: 'text/event-stream', schema: SCALAR, status: 200 }],
+      },
+    ]);
+    expect(out).toContain('useGetPet');
+    expect(out).not.toContain('streamEvents');
+  });
+
+  it('skips an op whose <Op>Variables name collides with a schema', () => {
+    const out = renderSwrModule(
+      apiModel({
+        schemas: [namedSchema('GetUserVariables', { kind: 'object', properties: [] })],
+        services: [
+          {
+            name: 'Default',
+            operations: [
+              operation({
+                name: 'getUser',
+                method: 'get',
+                path: '/u/{id}',
+                pathParams: [param('id', 'path', true)],
+              }),
+              operation({ name: 'listUsers', method: 'get' }),
+            ],
+          },
+        ],
+      }),
+      { sdkModule: SDK, argsStyle: 'grouped' }
+    );
+    expect(out).not.toContain('useGetUser');
+    expect(out).toContain('useListUsers');
+  });
+
+  it('returns empty string when every operation is SSE', () => {
+    const out = render([
+      {
+        name: 'streamEvents',
+        method: 'get',
+        path: '/events',
+        successResponses: [{ contentType: 'text/event-stream', schema: SCALAR, status: 200 }],
+      },
+    ]);
+    expect(out).toBe('');
+  });
+
+  describe('query operation (GET) with inputs', () => {
+    const getOp = {
+      name: 'getPet',
+      method: 'get' as const,
+      path: '/pets/{petId}',
+      pathParams: [param('petId', 'path', true)],
+      queryParams: [param('expand', 'query', false)],
+    };
+
+    it('emits a key factory + useSWR hook forwarding (vars, init)', () => {
+      const out = render([getOp]);
+      expect(out).toContain(
+        'export const getPetKey = (vars: GetPetVariables) => ["getPet", vars] as const;'
+      );
+      expect(out).toContain(
+        'export function useGetPet(vars: GetPetVariables, init?: RequestOptions) {'
+      );
+      expect(out).toContain('return useSWR(getPetKey(vars), () => getPet(vars, init));');
+    });
+  });
+
+  describe('no-input query operation', () => {
+    it('drops the vars param; key takes no args', () => {
+      const out = render([{ name: 'listPets', method: 'get', path: '/pets' }]);
+      expect(out).toContain('export const listPetsKey = () => ["listPets"] as const;');
+      expect(out).toContain('export function useListPets(init?: RequestOptions) {');
+      expect(out).toContain('return useSWR(listPetsKey(), () => listPets(init));');
+    });
+  });
+
+  describe('mutation operation (POST) with a body', () => {
+    const postOp = {
+      name: 'createPet',
+      method: 'post' as const,
+      path: '/pets',
+      requestBody: { contentType: 'application/json', schema: SCALAR, required: true },
+    };
+
+    it('emits a useSWRMutation hook with key + (key, { arg }) trigger', () => {
+      const out = render([postOp]);
+      expect(out).toContain('export function useCreatePet() {');
+      expect(out).toContain('return useSWRMutation("createPet", (_key: string, { arg }: {');
+      expect(out).toContain('arg: CreatePetVariables;');
+      expect(out).toContain('}) => createPet(arg));');
+    });
+  });
+
+  describe('no-input mutation operation', () => {
+    it('drops the arg; trigger takes no args', () => {
+      const out = render([{ name: 'ping', method: 'post', path: '/ping' }]);
+      expect(out).toContain('export function usePing() {');
+      expect(out).toContain('return useSWRMutation("ping", () => ping());');
+    });
+  });
+
+  describe('flat forwarding', () => {
+    it('query: spreads vars.<path>, vars.params, then init (URL-template order)', () => {
+      const out = render(
+        [
+          {
+            name: 'getPet',
+            method: 'get',
+            path: '/pets/{petId}',
+            pathParams: [param('petId', 'path', true)],
+            queryParams: [param('expand', 'query', false)],
+          },
+        ],
+        'flat'
+      );
+      expect(out).toContain('() => getPet(vars.petId, vars.params, init)');
+    });
+
+    it('mutation: spreads arg.<path> (URL-template order), then params, body, headers', () => {
+      const out = render(
+        [
+          {
+            name: 'replace',
+            method: 'put',
+            path: '/a/{a}/b/{b}',
+            pathParams: [param('b', 'path', true), param('a', 'path', true)],
+            queryParams: [param('q', 'query', false)],
+            requestBody: { contentType: 'application/json', schema: SCALAR, required: true },
+            headerParams: [param('X-Trace', 'header', false)],
+          },
+        ],
+        'flat'
+      );
+      expect(out).toContain('=> replace(arg.a, arg.b, arg.params, arg.body, arg.headers)');
+    });
+  });
+
+  describe('module header (imports)', () => {
+    it('imports useSWR only when a query op exists, useSWRMutation only when a mutation exists', () => {
+      const queryOnly = render([{ name: 'listPets', method: 'get', path: '/pets' }]);
+      expect(queryOnly).toContain('import useSWR from "swr";');
+      expect(queryOnly).not.toContain('swr/mutation');
+
+      const mutationOnly = render([{ name: 'ping', method: 'post', path: '/ping' }]);
+      expect(mutationOnly).toContain('import useSWRMutation from "swr/mutation";');
+      expect(mutationOnly).not.toContain('import useSWR from "swr";');
+    });
+
+    it('imports used opFns + Variables types + RequestOptions from the sdk module', () => {
+      const out = render([
+        {
+          name: 'getPet',
+          method: 'get',
+          path: '/pets/{petId}',
+          pathParams: [param('petId', 'path', true)],
+        },
+        {
+          name: 'createPet',
+          method: 'post',
+          path: '/pets',
+          requestBody: { contentType: 'application/json', schema: SCALAR, required: true },
+        },
+      ]);
+      expect(out).toContain(
+        'import { createPet, getPet, type CreatePetVariables, type GetPetVariables, type RequestOptions } from "./client.js";'
+      );
+    });
+
+    it('omits RequestOptions when there are only mutations (no query)', () => {
+      const out = render([
+        {
+          name: 'createPet',
+          method: 'post',
+          path: '/pets',
+          requestBody: { contentType: 'application/json', schema: SCALAR, required: true },
+        },
+      ]);
+      expect(out).toContain('import { createPet, type CreatePetVariables } from "./client.js";');
+      expect(out).not.toContain('RequestOptions');
+    });
+
+    it('imports only the opFn for a no-input op (no Variables type)', () => {
+      const out = render([{ name: 'ping', method: 'post', path: '/ping' }]);
+      expect(out).toContain('import { ping } from "./client.js";');
+    });
+  });
+});
diff --git a/packages/client-generator/src/emitters/__tests__/tanstack-query.test.ts b/packages/client-generator/src/emitters/__tests__/tanstack-query.test.ts
new file mode 100644
index 0000000000..9616094b88
--- /dev/null
+++ b/packages/client-generator/src/emitters/__tests__/tanstack-query.test.ts
@@ -0,0 +1,282 @@
+import { renderTanstackModule } from '../tanstack-query.js';
+import { apiModel, namedSchema, operation, param, SCALAR } from './fixtures.js';
+
+const SDK = './client.js';
+
+function render(
+  ops: Parameters<typeof operation>[0][],
+  argsStyle: 'flat' | 'grouped',
+  framework: 'react' | 'vue' | 'svelte' | 'solid' = 'react'
+) {
+  return renderTanstackModule(
+    apiModel({ services: [{ name: 'Default', operations: ops.map(operation) }] }),
+    { argsStyle, sdkModule: SDK, framework }
+  );
+}
+
+describe('renderTanstackModule', () => {
+  it('returns empty string when the model has no operations', () => {
+    expect(
+      renderTanstackModule(apiModel(), { argsStyle: 'flat', sdkModule: SDK, framework: 'react' })
+    ).toBe('');
+  });
+
+  it('skips SSE operations (not exported by the sdk) and wraps only the regular ones', () => {
+    const out = render(
+      [
+        {
+          name: 'getPet',
+          method: 'get',
+          path: '/pets/{id}',
+          pathParams: [param('id', 'path', true)],
+        },
+        {
+          name: 'streamEvents',
+          method: 'get',
+          path: '/events',
+          successResponses: [{ contentType: 'text/event-stream', schema: SCALAR, status: 200 }],
+        },
+      ],
+      'grouped'
+    );
+    expect(out).toContain('getPetOptions');
+    // The SSE op is neither imported nor wrapped.
+    expect(out).not.toContain('streamEvents');
+  });
+
+  it('skips an op whose <Op>Variables name collides with a schema (would import the wrong type)', () => {
+    const out = renderTanstackModule(
+      apiModel({
+        schemas: [namedSchema('GetUserVariables', { kind: 'object', properties: [] })],
+        services: [
+          {
+            name: 'Default',
+            operations: [
+              operation({
+                name: 'getUser',
+                method: 'get',
+                path: '/u/{id}',
+                pathParams: [param('id', 'path', true)],
+              }),
+              operation({ name: 'listUsers', method: 'get' }),
+            ].map((o) => o),
+          },
+        ],
+      }),
+      { argsStyle: 'grouped', sdkModule: SDK, framework: 'react' }
+    );
+    // The colliding op is skipped; the non-colliding one is still wrapped.
+    expect(out).not.toContain('getUserOptions');
+    expect(out).toContain('listUsersOptions');
+  });
+
+  it('returns empty string when every operation is SSE', () => {
+    const out = render(
+      [
+        {
+          name: 'streamEvents',
+          method: 'get',
+          path: '/events',
+          successResponses: [{ contentType: 'text/event-stream', schema: SCALAR, status: 200 }],
+        },
+      ],
+      'flat'
+    );
+    expect(out).toBe('');
+  });
+
+  describe('query operation (GET) with path + query params', () => {
+    const getOp = {
+      name: 'getPet',
+      method: 'get' as const,
+      path: '/pets/{petId}',
+      pathParams: [param('petId', 'path', true)],
+      queryParams: [param('expand', 'query', false)],
+    };
+
+    it('emits queryKey + Options factories with grouped forwarding', () => {
+      const out = render([getOp], 'grouped');
+      expect(out).toContain(
+        'export const getPetQueryKey = (vars: GetPetVariables) => ["getPet", vars] as const;'
+      );
+      expect(out).toContain('queryOptions({');
+      expect(out).toContain('queryKey: getPetQueryKey(vars)');
+      expect(out).toContain('queryFn: () => getPet(vars, init)');
+      expect(out).toContain(
+        'export const getPetOptions = (vars: GetPetVariables, init?: RequestOptions) =>'
+      );
+    });
+
+    it('emits flat positional forwarding (path ident, then params, then init)', () => {
+      const out = render([getOp], 'flat');
+      expect(out).toContain('queryFn: () => getPet(vars.petId, vars.params, init)');
+    });
+  });
+
+  describe('mutation operation (POST) with a body', () => {
+    const postOp = {
+      name: 'createPet',
+      method: 'post' as const,
+      path: '/pets',
+      requestBody: { contentType: 'application/json', schema: SCALAR, required: true },
+    };
+
+    it('emits a Mutation factory with mutationKey + mutationFn (grouped)', () => {
+      const out = render([postOp], 'grouped');
+      expect(out).toContain('export const createPetMutation = () => ({');
+      expect(out).toContain('mutationKey: ["createPet"] as const');
+      expect(out).toContain('mutationFn: (vars: CreatePetVariables) => createPet(vars)');
+    });
+
+    it('forwards the body positionally in flat mode (no trailing init)', () => {
+      const out = render([postOp], 'flat');
+      expect(out).toContain('mutationFn: (vars: CreatePetVariables) => createPet(vars.body)');
+    });
+  });
+
+  describe('flat forwarding ordering', () => {
+    it('orders path params (URL-template order), then params, body, headers', () => {
+      const op = {
+        name: 'replace',
+        method: 'put' as const,
+        path: '/a/{a}/b/{b}',
+        pathParams: [param('b', 'path', true), param('a', 'path', true)],
+        queryParams: [param('q', 'query', false)],
+        requestBody: { contentType: 'application/json', schema: SCALAR, required: true },
+        headerParams: [param('X-Trace', 'header', false)],
+      };
+      const out = render([op], 'flat');
+      expect(out).toContain(
+        'mutationFn: (vars: ReplaceVariables) => replace(vars.a, vars.b, vars.params, vars.body, vars.headers)'
+      );
+    });
+  });
+
+  describe('flat forwarding with an undeclared path placeholder', () => {
+    it('skips a `{placeholder}` that has no matching declared path param', () => {
+      const op = {
+        name: 'getThing',
+        method: 'get' as const,
+        path: '/things/{id}/{undeclared}',
+        pathParams: [param('id', 'path', true)],
+      };
+      const out = render([op], 'flat');
+      // Only `id` is forwarded; `{undeclared}` has no param, so it is dropped.
+      expect(out).toContain('queryFn: () => getThing(vars.id, init)');
+    });
+  });
+
+  describe('no-input operations', () => {
+    it('query: no vars param, queryKey without vars, forwards init', () => {
+      const out = render([{ name: 'listPets', method: 'get', path: '/pets' }], 'grouped');
+      expect(out).toContain('export const listPetsQueryKey = () => ["listPets"] as const;');
+      expect(out).toContain('export const listPetsOptions = (init?: RequestOptions) =>');
+      expect(out).toContain('queryKey: listPetsQueryKey()');
+      expect(out).toContain('queryFn: () => listPets(init)');
+    });
+
+    it('mutation: mutationFn takes no vars, calls with no args', () => {
+      const out = render([{ name: 'ping', method: 'post', path: '/ping' }], 'grouped');
+      expect(out).toContain('export const pingMutation = () => ({');
+      expect(out).toContain('mutationFn: () => ping()');
+    });
+
+    it('flat no-input query forwards init too', () => {
+      const out = render([{ name: 'listPets', method: 'get', path: '/pets' }], 'flat');
+      expect(out).toContain('queryFn: () => listPets(init)');
+    });
+  });
+
+  describe('module header (imports)', () => {
+    it('imports queryOptions only when a query op exists', () => {
+      const queryOnly = render([{ name: 'listPets', method: 'get', path: '/pets' }], 'grouped');
+      expect(queryOnly).toContain('import { queryOptions } from "@tanstack/react-query";');
+
+      const mutationOnly = render([{ name: 'ping', method: 'post', path: '/ping' }], 'grouped');
+      expect(mutationOnly).not.toContain('@tanstack/react-query');
+    });
+
+    it('imports used opFns + Variables types + RequestOptions from the sdk module', () => {
+      const out = render(
+        [
+          {
+            name: 'getPet',
+            method: 'get',
+            path: '/pets/{petId}',
+            pathParams: [param('petId', 'path', true)],
+          },
+          {
+            name: 'createPet',
+            method: 'post',
+            path: '/pets',
+            requestBody: { contentType: 'application/json', schema: SCALAR, required: true },
+          },
+        ],
+        'grouped'
+      );
+      expect(out).toContain(
+        'import { createPet, getPet, type CreatePetVariables, type GetPetVariables, type RequestOptions } from "./client.js";'
+      );
+    });
+
+    it('omits RequestOptions when there are only mutations (no query)', () => {
+      const out = render(
+        [
+          {
+            name: 'createPet',
+            method: 'post',
+            path: '/pets',
+            requestBody: { contentType: 'application/json', schema: SCALAR, required: true },
+          },
+        ],
+        'grouped'
+      );
+      expect(out).toContain('import { createPet, type CreatePetVariables } from "./client.js";');
+      expect(out).not.toContain('RequestOptions');
+    });
+
+    it('imports only the opFn for a no-input op (no Variables type)', () => {
+      const out = render([{ name: 'ping', method: 'post', path: '/ping' }], 'grouped');
+      expect(out).toContain('import { ping } from "./client.js";');
+    });
+  });
+
+  describe('queryFramework', () => {
+    const op = [{ name: 'listPets', method: 'get' as const, path: '/pets' }];
+
+    it('defaults to react: imports from @tanstack/react-query', () => {
+      expect(render(op, 'grouped')).toContain(
+        'import { queryOptions } from "@tanstack/react-query";'
+      );
+    });
+
+    it('imports from @tanstack/vue-query when framework is vue', () => {
+      expect(render(op, 'grouped', 'vue')).toContain(
+        'import { queryOptions } from "@tanstack/vue-query";'
+      );
+    });
+
+    it('changes only the import specifier — the rest of the body is byte-identical', () => {
+      const ops = [
+        {
+          name: 'getPet',
+          method: 'get' as const,
+          path: '/pets/{petId}',
+          pathParams: [param('petId', 'path', true)],
+        },
+        {
+          name: 'createPet',
+          method: 'post' as const,
+          path: '/pets',
+          requestBody: { contentType: 'application/json', schema: SCALAR, required: true },
+        },
+      ];
+      const react = render(ops, 'grouped', 'react');
+      const vue = render(ops, 'grouped', 'vue');
+      // Replace each rendering's import line with the other's; the documents must then match,
+      // proving the framework choice touches nothing but the `@tanstack/<framework>-query` string.
+      const importLine = (q: string) => `import { queryOptions } from "@tanstack/${q}-query";`;
+      expect(react.replace(importLine('react'), importLine('vue'))).toBe(vue);
+    });
+  });
+});
diff --git a/packages/client-generator/src/emitters/__tests__/transformers.test.ts b/packages/client-generator/src/emitters/__tests__/transformers.test.ts
new file mode 100644
index 0000000000..5e23e47325
--- /dev/null
+++ b/packages/client-generator/src/emitters/__tests__/transformers.test.ts
@@ -0,0 +1,798 @@
+import type {
+  ApiModel,
+  NamedSchemaModel,
+  PropertyModel,
+} from '../../intermediate-representation/model.js';
+import { renderTransformersModule } from '../transformers.js';
+
+const base: Omit<ApiModel, 'schemas'> = {
+  title: 'T',
+  version: '1',
+  serverUrl: 'https://x',
+  services: [],
+  securitySchemes: [],
+};
+
+function render(schemas: NamedSchemaModel[]): string {
+  return renderTransformersModule({ ...base, schemas }, { sdkModule: './client.js' });
+}
+
+describe('renderTransformersModule', () => {
+  it("returns '' when no schema has dates", () => {
+    expect(
+      render([
+        {
+          name: 'Plain',
+          schema: {
+            kind: 'object',
+            properties: [
+              { name: 'id', schema: { kind: 'scalar', scalar: 'integer' }, required: true },
+            ],
+          },
+        },
+      ])
+    ).toBe('');
+  });
+
+  it("returns '' for an empty model", () => {
+    expect(render([])).toBe('');
+  });
+
+  it('converts top-level `date-time` and `date` scalar fields, guarded', () => {
+    const out = render([
+      {
+        name: 'Event',
+        schema: {
+          kind: 'object',
+          properties: [
+            {
+              name: 'createdAt',
+              schema: { kind: 'scalar', scalar: 'string', metadata: { format: 'date-time' } },
+              required: true,
+            },
+            {
+              name: 'day',
+              schema: { kind: 'scalar', scalar: 'string', metadata: { format: 'date' } },
+              required: false,
+            },
+          ],
+        },
+      },
+    ]);
+    expect(out).toContain('export const transformEvent = (data: Event): Event =>');
+    expect(out).toContain('if (typeof data["createdAt"] === "string")');
+    expect(out).toContain('data["createdAt"] = new Date(data["createdAt"]);');
+    expect(out).toContain('data["day"] = new Date(data["day"]);');
+    expect(out).toContain('return data;');
+    expect(out).toContain('import type { Event } from "./client.js";');
+  });
+
+  it('converts an array of date scalars, guarded', () => {
+    const out = render([
+      {
+        name: 'Log',
+        schema: {
+          kind: 'object',
+          properties: [
+            {
+              name: 'timestamps',
+              schema: {
+                kind: 'array',
+                items: { kind: 'scalar', scalar: 'string', metadata: { format: 'date-time' } },
+              },
+              required: true,
+            },
+          ],
+        },
+      },
+    ]);
+    expect(out).toContain('if (Array.isArray(data["timestamps"]))');
+    expect(out).toContain('data["timestamps"] = data["timestamps"].map(v => new Date(v));');
+  });
+
+  it('composes via a ref to a date-bearing schema', () => {
+    const out = render([
+      {
+        name: 'Person',
+        schema: {
+          kind: 'object',
+          properties: [
+            {
+              name: 'born',
+              schema: { kind: 'scalar', scalar: 'string', metadata: { format: 'date' } },
+              required: true,
+            },
+          ],
+        },
+      },
+      {
+        name: 'Pet',
+        schema: {
+          kind: 'object',
+          properties: [{ name: 'owner', schema: { kind: 'ref', name: 'Person' }, required: false }],
+        },
+      },
+    ]);
+    expect(out).toContain('export const transformPerson = (data: Person): Person =>');
+    expect(out).toContain('export const transformPet = (data: Pet): Pet =>');
+    expect(out).toContain('if (data["owner"])');
+    expect(out).toContain('transformPerson(data["owner"]);');
+    expect(out).toContain('import type { Person, Pet } from "./client.js";');
+  });
+
+  // Each date-free shape exercises its own pruning bail-out: convertRef, the
+  // ref-items branch of convertArray, convertCollection, and convertProperty.
+  it.each<{ shape: string; property: PropertyModel; absent: string }>([
+    {
+      shape: 'ref to a date-free schema',
+      property: { name: 'tag', schema: { kind: 'ref', name: 'Plain' }, required: false },
+      absent: 'transformPlain',
+    },
+    {
+      shape: 'array of refs to a date-free schema',
+      property: {
+        name: 'list',
+        schema: { kind: 'array', items: { kind: 'ref', name: 'Plain' } },
+        required: true,
+      },
+      absent: 'data["list"]',
+    },
+    {
+      shape: 'record whose values bear no dates',
+      property: {
+        name: 'tags',
+        schema: { kind: 'record', value: { kind: 'scalar', scalar: 'string' } },
+        required: true,
+      },
+      absent: 'data["tags"]',
+    },
+    {
+      shape: 'nested inline object',
+      property: {
+        name: 'meta',
+        schema: {
+          kind: 'object',
+          properties: [
+            { name: 'title', schema: { kind: 'scalar', scalar: 'string' }, required: true },
+          ],
+        },
+        required: false,
+      },
+      absent: 'data["meta"]',
+    },
+  ])('skips a date-free $shape', ({ property, absent }) => {
+    const out = render([
+      {
+        name: 'Plain',
+        schema: {
+          kind: 'object',
+          properties: [
+            { name: 'id', schema: { kind: 'scalar', scalar: 'integer' }, required: true },
+          ],
+        },
+      },
+      {
+        name: 'Holder',
+        schema: {
+          kind: 'object',
+          properties: [
+            property,
+            {
+              name: 'at',
+              schema: { kind: 'scalar', scalar: 'string', metadata: { format: 'date-time' } },
+              required: true,
+            },
+          ],
+        },
+      },
+    ]);
+    expect(out).not.toContain(absent);
+    expect(out).toContain('data["at"] = new Date(data["at"]);');
+    // Date-free schemas are also left out of the type import.
+    expect(out).toContain('import type { Holder } from "./client.js";');
+  });
+
+  it('composes via an array of refs to a date-bearing schema', () => {
+    const out = render([
+      {
+        name: 'Visit',
+        schema: {
+          kind: 'object',
+          properties: [
+            {
+              name: 'on',
+              schema: { kind: 'scalar', scalar: 'string', metadata: { format: 'date' } },
+              required: true,
+            },
+          ],
+        },
+      },
+      {
+        name: 'History',
+        schema: {
+          kind: 'object',
+          properties: [
+            {
+              name: 'visits',
+              schema: { kind: 'array', items: { kind: 'ref', name: 'Visit' } },
+              required: true,
+            },
+          ],
+        },
+      },
+    ]);
+    expect(out).toContain('if (Array.isArray(data["visits"]))');
+    expect(out).toContain('data["visits"].forEach(transformVisit);');
+  });
+
+  it('recurses into a nested inline object with a date', () => {
+    const out = render([
+      {
+        name: 'Order',
+        schema: {
+          kind: 'object',
+          properties: [
+            {
+              name: 'meta',
+              required: false,
+              schema: {
+                kind: 'object',
+                properties: [
+                  {
+                    name: 'placedAt',
+                    schema: { kind: 'scalar', scalar: 'string', metadata: { format: 'date-time' } },
+                    required: true,
+                  },
+                ],
+              },
+            },
+          ],
+        },
+      },
+    ]);
+    expect(out).toContain('if (data["meta"])');
+    expect(out).toContain('if (typeof data["meta"]["placedAt"] === "string")');
+    expect(out).toContain('data["meta"]["placedAt"] = new Date(data["meta"]["placedAt"]);');
+  });
+
+  it('recurses into an array of inline objects with dates', () => {
+    const out = render([
+      {
+        name: 'Bundle',
+        schema: {
+          kind: 'object',
+          properties: [
+            {
+              name: 'items',
+              required: true,
+              schema: {
+                kind: 'array',
+                items: {
+                  kind: 'object',
+                  properties: [
+                    {
+                      name: 'shippedAt',
+                      schema: {
+                        kind: 'scalar',
+                        scalar: 'string',
+                        metadata: { format: 'date-time' },
+                      },
+                      required: true,
+                    },
+                  ],
+                },
+              },
+            },
+          ],
+        },
+      },
+    ]);
+    expect(out).toContain('data["items"].forEach(item =>');
+    expect(out).toContain('if (typeof item["shippedAt"] === "string")');
+    expect(out).toContain('item["shippedAt"] = new Date(item["shippedAt"]);');
+  });
+
+  it('handles a top-level array named schema of date scalars', () => {
+    const out = render([
+      {
+        name: 'Dates',
+        schema: {
+          kind: 'array',
+          items: { kind: 'scalar', scalar: 'string', metadata: { format: 'date-time' } },
+        },
+      },
+    ]);
+    expect(out).toContain('export const transformDates = (data: Dates): Dates =>');
+    expect(out).toContain('if (Array.isArray(data))');
+    expect(out).toContain('data = data.map(v => new Date(v));');
+  });
+
+  it('handles a top-level ref-to-date named schema', () => {
+    const out = render([
+      {
+        name: 'Inner',
+        schema: {
+          kind: 'object',
+          properties: [
+            {
+              name: 'at',
+              schema: { kind: 'scalar', scalar: 'string', metadata: { format: 'date-time' } },
+              required: true,
+            },
+          ],
+        },
+      },
+      {
+        name: 'Alias',
+        schema: { kind: 'ref', name: 'Inner' },
+      },
+    ]);
+    expect(out).toContain('export const transformAlias');
+    expect(out).toContain('transformInner(data)');
+  });
+
+  it('walks union members that bear dates', () => {
+    const out = render([
+      {
+        name: 'A',
+        schema: {
+          kind: 'object',
+          properties: [
+            {
+              name: 'when',
+              schema: { kind: 'scalar', scalar: 'string', metadata: { format: 'date-time' } },
+              required: true,
+            },
+          ],
+        },
+      },
+      {
+        name: 'Holder',
+        schema: {
+          kind: 'object',
+          properties: [
+            {
+              name: 'value',
+              required: true,
+              schema: {
+                kind: 'union',
+                members: [
+                  { kind: 'ref', name: 'A' },
+                  { kind: 'scalar', scalar: 'string' },
+                ],
+              },
+            },
+          ],
+        },
+      },
+    ]);
+    expect(out).toContain('export const transformHolder');
+    // The union member's transform must be guarded by a runtime object-check and
+    // CAST to the member type — `data["value"]` is typed `A | string`, so a bare
+    // `transformA(data["value"])` would fail strict tsc (TS2345). The cast makes
+    // it compile; `transformA`'s own internal string guard keeps it a runtime
+    // no-op when the value is the string member.
+    expect(out).toContain('if (data["value"] && typeof data["value"] === "object")');
+    expect(out).toContain('transformA(data["value"] as A);');
+  });
+
+  it('guards + casts each date-bearing ref in a union of refs', () => {
+    const out = render([
+      {
+        name: 'A',
+        schema: {
+          kind: 'object',
+          properties: [
+            {
+              name: 'when',
+              schema: { kind: 'scalar', scalar: 'string', metadata: { format: 'date-time' } },
+              required: true,
+            },
+          ],
+        },
+      },
+      {
+        name: 'B',
+        schema: {
+          kind: 'object',
+          properties: [
+            {
+              name: 'on',
+              schema: { kind: 'scalar', scalar: 'string', metadata: { format: 'date' } },
+              required: true,
+            },
+          ],
+        },
+      },
+      {
+        name: 'Holder',
+        schema: {
+          kind: 'object',
+          properties: [
+            {
+              name: 'value',
+              required: true,
+              schema: {
+                kind: 'union',
+                members: [
+                  { kind: 'ref', name: 'A' },
+                  { kind: 'ref', name: 'B' },
+                ],
+              },
+            },
+          ],
+        },
+      },
+    ]);
+    // Both date-bearing members share one object-guard block; each transform is
+    // cast to its member type and is internally string-guarded, so applying the
+    // wrong member to a runtime value is a safe no-op.
+    expect(out).toContain('if (data["value"] && typeof data["value"] === "object")');
+    expect(out).toContain('transformA(data["value"] as A);');
+    expect(out).toContain('transformB(data["value"] as B);');
+  });
+
+  it('keeps the string guard for a date-scalar union member', () => {
+    const out = render([
+      {
+        name: 'H',
+        schema: {
+          kind: 'object',
+          properties: [
+            {
+              name: 'v',
+              required: true,
+              schema: {
+                kind: 'union',
+                members: [
+                  { kind: 'scalar', scalar: 'string', metadata: { format: 'date-time' } },
+                  { kind: 'scalar', scalar: 'number' },
+                ],
+              },
+            },
+          ],
+        },
+      },
+    ]);
+    // A scalar date member's type is `Date` under --date-type Date, so the
+    // assignment type-checks against the `string` guard — no object-guard needed.
+    expect(out).toContain('if (typeof data["v"] === "string")');
+    expect(out).toContain('data["v"] = new Date(data["v"]);');
+    expect(out).not.toContain('typeof data["v"] === "object"');
+  });
+
+  it('skips a date-free ref member of a union', () => {
+    const out = render([
+      {
+        name: 'Plain',
+        schema: {
+          kind: 'object',
+          properties: [
+            { name: 'id', schema: { kind: 'scalar', scalar: 'integer' }, required: true },
+          ],
+        },
+      },
+      {
+        name: 'A',
+        schema: {
+          kind: 'object',
+          properties: [
+            {
+              name: 'when',
+              schema: { kind: 'scalar', scalar: 'string', metadata: { format: 'date-time' } },
+              required: true,
+            },
+          ],
+        },
+      },
+      {
+        name: 'H',
+        schema: {
+          kind: 'object',
+          properties: [
+            {
+              name: 'v',
+              required: true,
+              schema: {
+                kind: 'union',
+                members: [
+                  { kind: 'ref', name: 'Plain' },
+                  { kind: 'ref', name: 'A' },
+                ],
+              },
+            },
+          ],
+        },
+      },
+    ]);
+    expect(out).toContain('transformA(data["v"] as A);');
+    expect(out).not.toContain('transformPlain');
+  });
+
+  it('guards then recurses into an inline-object union member with a date', () => {
+    const out = render([
+      {
+        name: 'H',
+        schema: {
+          kind: 'object',
+          properties: [
+            {
+              name: 'v',
+              required: true,
+              schema: {
+                kind: 'union',
+                members: [
+                  {
+                    kind: 'object',
+                    properties: [
+                      {
+                        name: 'at',
+                        schema: {
+                          kind: 'scalar',
+                          scalar: 'string',
+                          metadata: { format: 'date-time' },
+                        },
+                        required: true,
+                      },
+                    ],
+                  },
+                  { kind: 'scalar', scalar: 'string' },
+                ],
+              },
+            },
+          ],
+        },
+      },
+    ]);
+    // The object-guard narrows the union to its object member, so the inner
+    // property access + string-guarded assign type-checks.
+    expect(out).toContain('if (data["v"] && typeof data["v"] === "object")');
+    expect(out).toContain('if (typeof data["v"]["at"] === "string")');
+    expect(out).toContain('data["v"]["at"] = new Date(data["v"]["at"]);');
+  });
+
+  it('writes back into a record of date scalars by key', () => {
+    const out = render([
+      {
+        name: 'Calendar',
+        schema: {
+          kind: 'object',
+          properties: [
+            {
+              name: 'days',
+              required: true,
+              schema: {
+                kind: 'record',
+                value: { kind: 'scalar', scalar: 'string', metadata: { format: 'date' } },
+              },
+            },
+          ],
+        },
+      },
+    ]);
+    // Records of date scalars must write back through the slot — a forEach loop
+    // variable can't, so iterate the keys and assign into the record.
+    expect(out).toContain('if (data["days"])');
+    expect(out).toContain('for (const __k of Object.keys(data["days"]))');
+    expect(out).toContain('if (typeof data["days"][__k] === "string")');
+    expect(out).toContain('data["days"][__k] = new Date(data["days"][__k]);');
+  });
+
+  it('walks intersection members that bear dates', () => {
+    const out = render([
+      {
+        name: 'WithDate',
+        schema: {
+          kind: 'object',
+          properties: [
+            {
+              name: 'on',
+              schema: { kind: 'scalar', scalar: 'string', metadata: { format: 'date' } },
+              required: true,
+            },
+          ],
+        },
+      },
+      {
+        name: 'Combined',
+        schema: {
+          kind: 'intersection',
+          members: [
+            { kind: 'ref', name: 'WithDate' },
+            {
+              kind: 'object',
+              properties: [
+                { name: 'note', schema: { kind: 'scalar', scalar: 'string' }, required: true },
+              ],
+            },
+          ],
+        },
+      },
+    ]);
+    expect(out).toContain('export const transformCombined');
+    expect(out).toContain('transformWithDate(data);');
+  });
+
+  it('iterates nested loop vars for arrays of arrays of dates', () => {
+    const out = render([
+      {
+        name: 'Grid',
+        schema: {
+          kind: 'object',
+          properties: [
+            {
+              name: 'rows',
+              required: true,
+              schema: {
+                kind: 'array',
+                items: {
+                  kind: 'array',
+                  items: {
+                    kind: 'object',
+                    properties: [
+                      {
+                        name: 'at',
+                        schema: {
+                          kind: 'scalar',
+                          scalar: 'string',
+                          metadata: { format: 'date-time' },
+                        },
+                        required: true,
+                      },
+                    ],
+                  },
+                },
+              },
+            },
+          ],
+        },
+      },
+    ]);
+    expect(out).toContain('data["rows"].forEach(item =>');
+    expect(out).toContain('item.forEach(item1 =>');
+    expect(out).toContain('item1["at"] = new Date(item1["at"]);');
+  });
+
+  it('maps-and-reassigns a three-level array of date scalars with distinct vars', () => {
+    const out = render([
+      {
+        name: 'Cube',
+        schema: {
+          kind: 'object',
+          properties: [
+            {
+              name: 'c',
+              required: true,
+              schema: {
+                kind: 'array',
+                items: {
+                  kind: 'array',
+                  items: {
+                    kind: 'array',
+                    items: { kind: 'scalar', scalar: 'string', metadata: { format: 'date-time' } },
+                  },
+                },
+              },
+            },
+          ],
+        },
+      },
+    ]);
+    // Each array level gets a distinct map var (`row`, `row2`, `v`) to avoid
+    // shadowing; every level maps-and-reassigns up to the slot.
+    expect(out).toContain(
+      'data["c"] = data["c"].map(row => row.map(row2 => row2.map(v => new Date(v))));'
+    );
+  });
+
+  it('iterates a record of date-bearing objects via Object.values', () => {
+    const out = render([
+      {
+        name: 'M',
+        schema: {
+          kind: 'object',
+          properties: [
+            {
+              name: 'm',
+              required: true,
+              schema: {
+                kind: 'record',
+                value: {
+                  kind: 'object',
+                  properties: [
+                    {
+                      name: 'at',
+                      schema: {
+                        kind: 'scalar',
+                        scalar: 'string',
+                        metadata: { format: 'date-time' },
+                      },
+                      required: true,
+                    },
+                  ],
+                },
+              },
+            },
+          ],
+        },
+      },
+    ]);
+    // Objects mutate in place, so a forEach over the values is enough — no
+    // per-key write-back needed (unlike record-of-scalars).
+    expect(out).toContain('if (data["m"])');
+    expect(out).toContain('Object.values(data["m"]).forEach(item =>');
+    expect(out).toContain('if (typeof item["at"] === "string")');
+    expect(out).toContain('item["at"] = new Date(item["at"]);');
+  });
+
+  it('maps-and-reassigns each slot of a record of arrays of date scalars', () => {
+    const out = render([
+      {
+        name: 'Buckets',
+        schema: {
+          kind: 'object',
+          properties: [
+            {
+              name: 'b',
+              required: true,
+              schema: {
+                kind: 'record',
+                value: {
+                  kind: 'array',
+                  items: { kind: 'scalar', scalar: 'string', metadata: { format: 'date-time' } },
+                },
+              },
+            },
+          ],
+        },
+      },
+    ]);
+    expect(out).toContain('if (data["b"])');
+    expect(out).toContain('for (const __k of Object.keys(data["b"]))');
+    expect(out).toContain('if (Array.isArray(data["b"][__k]))');
+    expect(out).toContain('data["b"][__k] = data["b"][__k].map(v => new Date(v));');
+  });
+
+  it('ignores a ref to a name absent from the model', () => {
+    const out = render([
+      {
+        name: 'Card',
+        schema: {
+          kind: 'object',
+          properties: [
+            { name: 'link', schema: { kind: 'ref', name: 'Missing' }, required: false },
+            {
+              name: 'at',
+              schema: { kind: 'scalar', scalar: 'string', metadata: { format: 'date-time' } },
+              required: true,
+            },
+          ],
+        },
+      },
+    ]);
+    expect(out).not.toContain('data["link"]');
+    expect(out).toContain('data["at"] = new Date(data["at"]);');
+  });
+
+  it('guards ref cycles via a visited set', () => {
+    const out = render([
+      {
+        name: 'Node',
+        schema: {
+          kind: 'object',
+          properties: [
+            {
+              name: 'at',
+              schema: { kind: 'scalar', scalar: 'string', metadata: { format: 'date-time' } },
+              required: true,
+            },
+            { name: 'next', schema: { kind: 'ref', name: 'Node' }, required: false },
+          ],
+        },
+      },
+    ]);
+    expect(out).toContain('export const transformNode');
+    expect(out).toContain('if (data["next"])');
+    expect(out).toContain('transformNode(data["next"]);');
+  });
+});
diff --git a/packages/client-generator/src/emitters/__tests__/ts.test.ts b/packages/client-generator/src/emitters/__tests__/ts.test.ts
new file mode 100644
index 0000000000..1d7ae1c86d
--- /dev/null
+++ b/packages/client-generator/src/emitters/__tests__/ts.test.ts
@@ -0,0 +1,156 @@
+import {
+  jsdoc,
+  literalExpression,
+  parseExpression,
+  parseStatements,
+  printNodes,
+  printStatements,
+  ts,
+} from '../ts.js';
+
+describe('emitters/ts foundation', () => {
+  describe('printNodes', () => {
+    it('round-trips an interface declaration', () => {
+      const decl = ts.factory.createInterfaceDeclaration(
+        [ts.factory.createModifier(ts.SyntaxKind.ExportKeyword)],
+        'Foo',
+        undefined,
+        undefined,
+        [
+          ts.factory.createPropertySignature(
+            undefined,
+            'id',
+            undefined,
+            ts.factory.createKeywordTypeNode(ts.SyntaxKind.StringKeyword)
+          ),
+        ]
+      );
+      expect(printNodes([decl])).toBe('export interface Foo {\n    id: string;\n}');
+    });
+
+    it('round-trips a const declaration', () => {
+      const decl = ts.factory.createVariableStatement(
+        [ts.factory.createModifier(ts.SyntaxKind.ExportKeyword)],
+        ts.factory.createVariableDeclarationList(
+          [
+            ts.factory.createVariableDeclaration(
+              'x',
+              undefined,
+              undefined,
+              ts.factory.createNumericLiteral(1)
+            ),
+          ],
+          ts.NodeFlags.Const
+        )
+      );
+      expect(printNodes([decl])).toBe('export const x = 1;');
+    });
+
+    it('joins multiple nodes with a newline', () => {
+      const lit = (n: number): ts.ExpressionStatement =>
+        ts.factory.createExpressionStatement(ts.factory.createNumericLiteral(n));
+      expect(printNodes([lit(1), lit(2)])).toBe('1;\n2;');
+    });
+  });
+
+  describe('printStatements', () => {
+    const lit = (n: number): ts.ExpressionStatement =>
+      ts.factory.createExpressionStatement(ts.factory.createNumericLiteral(n));
+
+    it('separates top-level declarations with a blank line', () => {
+      expect(printStatements([lit(1), lit(2)])).toBe('1;\n\n2;');
+    });
+
+    it('prints a single node with no trailing blank line', () => {
+      expect(printStatements([lit(1)])).toBe('1;');
+    });
+  });
+
+  describe('parseStatements', () => {
+    it('yields re-printable statements from source', () => {
+      const statements = parseStatements('export const x = 1;');
+      expect(statements).toHaveLength(1);
+      expect(printNodes(statements)).toBe('export const x = 1;');
+    });
+  });
+
+  describe('parseExpression', () => {
+    it('parses a source expression into a re-printable ts.Expression', () => {
+      const expr = parseExpression('new Blob([])');
+      expect(ts.isNewExpression(expr)).toBe(true);
+      expect(printNodes([expr])).toBe('new Blob([])');
+    });
+  });
+
+  describe('literalExpression', () => {
+    function print(value: unknown): string {
+      return printStatements([literalExpression(value)]);
+    }
+
+    it('converts scalars, null, arrays, and objects to expression source', () => {
+      expect(print('x')).toBe('"x"');
+      expect(print(42)).toBe('42');
+      expect(print(true)).toBe('true');
+      expect(print(false)).toBe('false');
+      expect(print(null)).toBe('null');
+      expect(print([1, 'a'])).toBe('[1, "a"]');
+      expect(print({ a: 1, b: [true] })).toBe('{ a: 1, b: [true] }');
+    });
+
+    it('prints a negative number as a unary minus', () => {
+      expect(print(-42)).toBe('-42');
+      expect(print({ min: -1.5 })).toBe('{ min: -1.5 }');
+    });
+
+    it('quotes object keys that are not identifier-safe', () => {
+      expect(print({ 'a-b': 1, ok: 2 })).toBe('{ "a-b": 1, ok: 2 }');
+    });
+  });
+
+  describe('jsdoc', () => {
+    it('prints a single-line block comment above the node', () => {
+      const decl = ts.factory.createVariableStatement(
+        undefined,
+        ts.factory.createVariableDeclarationList(
+          [
+            ts.factory.createVariableDeclaration(
+              'y',
+              undefined,
+              undefined,
+              ts.factory.createNull()
+            ),
+          ],
+          ts.NodeFlags.Const
+        )
+      );
+      const out = printNodes([jsdoc(decl, 'A note.')]);
+      expect(out).toBe('/**\n * A note.\n */\nconst y = null;');
+    });
+
+    it('prints a multi-line block comment with one star per line', () => {
+      const decl = ts.factory.createTypeAliasDeclaration(
+        undefined,
+        'T',
+        undefined,
+        ts.factory.createKeywordTypeNode(ts.SyntaxKind.StringKeyword)
+      );
+      const out = printNodes([jsdoc(decl, 'line one\nline two')]);
+      expect(out).toBe('/**\n * line one\n * line two\n */\ntype T = string;');
+    });
+
+    it('escapes an embedded `*/` so a hostile description cannot break out of the comment', () => {
+      const decl = ts.factory.createTypeAliasDeclaration(
+        undefined,
+        'T',
+        undefined,
+        ts.factory.createKeywordTypeNode(ts.SyntaxKind.StringKeyword)
+      );
+      const out = printNodes([jsdoc(decl, 'evil */ ;globalThis.PWNED=1; /*')]);
+      // The `*/` is neutralized to `*\/`; no live `*/` survives inside the comment body.
+      expect(out).toContain('evil *\\/ ;globalThis.PWNED=1; /*');
+      expect(out).not.toContain('evil */');
+      // Exactly one comment-closing `*/` (the real one the printer appends).
+      expect(out.match(/\*\//g)).toHaveLength(1);
+    });
+  });
+});
diff --git a/packages/client-generator/src/emitters/__tests__/type-guards.test.ts b/packages/client-generator/src/emitters/__tests__/type-guards.test.ts
new file mode 100644
index 0000000000..698d044d30
--- /dev/null
+++ b/packages/client-generator/src/emitters/__tests__/type-guards.test.ts
@@ -0,0 +1,465 @@
+import type { NamedSchemaModel, SchemaModel } from '../../intermediate-representation/model.js';
+import { emitClientSingleFile } from '../client-assembly.js';
+import { apiModel, namedSchema } from './fixtures.js';
+
+// The package arm keeps the emitted text free of the embedded runtime, so the
+// absence assertions below test the schema types/guards alone.
+const emitPackage: typeof emitClientSingleFile = (model, options = {}) =>
+  emitClientSingleFile(model, { ...options, runtime: 'package' });
+
+describe('discriminated-union type guards (C6.4)', () => {
+  const beverage = namedSchema('Beverage', {
+    kind: 'object',
+    properties: [
+      {
+        name: 'category',
+        schema: { kind: 'literal', value: 'beverage' },
+        required: true,
+      },
+    ],
+  });
+  const dessert = namedSchema('Dessert', {
+    kind: 'object',
+    properties: [
+      {
+        name: 'category',
+        schema: { kind: 'literal', value: 'dessert' },
+        required: true,
+      },
+    ],
+  });
+
+  it('emits is<Member>() guards for an explicit discriminator', () => {
+    const out = emitPackage(
+      apiModel({
+        schemas: [
+          beverage,
+          dessert,
+          namedSchema('MenuItem', {
+            kind: 'union',
+            members: [
+              { kind: 'ref', name: 'Beverage' },
+              { kind: 'ref', name: 'Dessert' },
+            ],
+            discriminator: {
+              propertyName: 'category',
+              mapping: [
+                { value: 'beverage', schemaName: 'Beverage' },
+                { value: 'dessert', schemaName: 'Dessert' },
+              ],
+            },
+          }),
+        ],
+      })
+    );
+    expect(out).toContain('export function isBeverage(value: MenuItem): value is Beverage {');
+    expect(out).toContain('(value as Record<string, unknown>)["category"] === "beverage"');
+    expect(out).toContain('export function isDessert(value: MenuItem): value is Dessert {');
+    expect(out).toContain('(value as Record<string, unknown>)["category"] === "dessert"');
+  });
+
+  it('skips a discriminator entry whose target is not a named schema', () => {
+    const out = emitPackage(
+      apiModel({
+        schemas: [
+          beverage,
+          namedSchema('MenuItem', {
+            kind: 'union',
+            members: [{ kind: 'ref', name: 'Beverage' }],
+            discriminator: {
+              propertyName: 'category',
+              mapping: [
+                { value: 'beverage', schemaName: 'Beverage' },
+                { value: 'ghost', schemaName: 'NotAType' },
+              ],
+            },
+          }),
+        ],
+      })
+    );
+    expect(out).toContain('export function isBeverage(');
+    expect(out).not.toContain('isNotAType');
+  });
+
+  it('emits a single guard when two discriminant values map to the same type', () => {
+    const out = emitPackage(
+      apiModel({
+        schemas: [
+          namedSchema('Pet', { kind: 'object', properties: [] }),
+          namedSchema('Other', { kind: 'object', properties: [] }),
+          namedSchema('Animal', {
+            kind: 'union',
+            members: [
+              { kind: 'ref', name: 'Pet' },
+              { kind: 'ref', name: 'Other' },
+            ],
+            discriminator: {
+              propertyName: 'kind',
+              mapping: [
+                { value: 'dog', schemaName: 'Pet' },
+                { value: 'puppy', schemaName: 'Pet' },
+                { value: 'thing', schemaName: 'Other' },
+              ],
+            },
+          }),
+        ],
+      })
+    );
+    expect(out.match(/export function isPet\(/g)).toHaveLength(1);
+    expect(out).toContain(
+      '(["dog", "puppy"] as readonly unknown[]).includes((value as Record<string, unknown>)["kind"])'
+    );
+  });
+
+  it('synthesizes an implicit discriminator from a shared distinct string const', () => {
+    const out = emitPackage(
+      apiModel({
+        schemas: [
+          beverage,
+          dessert,
+          namedSchema('MenuItem', {
+            kind: 'union',
+            members: [
+              { kind: 'ref', name: 'Beverage' },
+              { kind: 'ref', name: 'Dessert' },
+            ],
+          }),
+        ],
+      })
+    );
+    expect(out).toContain('export function isBeverage(value: MenuItem): value is Beverage {');
+    expect(out).toContain('(value as Record<string, unknown>)["category"] === "beverage"');
+  });
+
+  it('finds the implicit discriminant through intersection (allOf) members', () => {
+    const out = emitPackage(
+      apiModel({
+        schemas: [
+          namedSchema('A', {
+            kind: 'intersection',
+            members: [
+              {
+                kind: 'object',
+                properties: [
+                  {
+                    name: 't',
+                    schema: { kind: 'literal', value: 'a' },
+                    required: true,
+                  },
+                ],
+              },
+              { kind: 'ref', name: 'Base' },
+            ],
+          }),
+          namedSchema('B', {
+            kind: 'intersection',
+            members: [
+              {
+                kind: 'object',
+                properties: [
+                  {
+                    name: 't',
+                    schema: { kind: 'literal', value: 'b' },
+                    required: true,
+                  },
+                ],
+              },
+              { kind: 'ref', name: 'Base' },
+            ],
+          }),
+          namedSchema('AB', {
+            kind: 'union',
+            members: [
+              { kind: 'ref', name: 'A' },
+              { kind: 'ref', name: 'B' },
+            ],
+          }),
+        ],
+      })
+    );
+    expect(out).toContain('export function isA(value: AB): value is A {');
+    expect(out).toContain('(value as Record<string, unknown>)["t"] === "a"');
+  });
+
+  // One row per rejection clause in the guard collection/implicit-discriminator logic.
+  it.each<[string, NamedSchemaModel[]]>([
+    [
+      'a member is not a ref to a named schema',
+      [
+        beverage,
+        namedSchema('Mixed', {
+          kind: 'union',
+          members: [
+            { kind: 'ref', name: 'Beverage' },
+            { kind: 'scalar', scalar: 'string' },
+          ],
+        }),
+      ],
+    ],
+    [
+      'a member ref points to an unknown schema',
+      [
+        beverage,
+        namedSchema('Ghosty', {
+          kind: 'union',
+          members: [
+            { kind: 'ref', name: 'Beverage' },
+            { kind: 'ref', name: 'DoesNotExist' },
+          ],
+        }),
+      ],
+    ],
+    [
+      'the union has a single member',
+      [
+        beverage,
+        namedSchema('Solo', { kind: 'union', members: [{ kind: 'ref', name: 'Beverage' }] }),
+      ],
+    ],
+    [
+      'members pin different property names',
+      [
+        namedSchema('P', {
+          kind: 'object',
+          properties: [{ name: 'a', schema: { kind: 'literal', value: 'x' }, required: true }],
+        }),
+        namedSchema('Q', {
+          kind: 'object',
+          properties: [{ name: 'b', schema: { kind: 'literal', value: 'y' }, required: true }],
+        }),
+        namedSchema('PQ', {
+          kind: 'union',
+          members: [
+            { kind: 'ref', name: 'P' },
+            { kind: 'ref', name: 'Q' },
+          ],
+        }),
+      ],
+    ],
+    [
+      'the shared const values are not distinct',
+      [
+        namedSchema('X', {
+          kind: 'object',
+          properties: [{ name: 'k', schema: { kind: 'literal', value: 'same' }, required: true }],
+        }),
+        namedSchema('Y', {
+          kind: 'object',
+          properties: [{ name: 'k', schema: { kind: 'literal', value: 'same' }, required: true }],
+        }),
+        namedSchema('XY', {
+          kind: 'union',
+          members: [
+            { kind: 'ref', name: 'X' },
+            { kind: 'ref', name: 'Y' },
+          ],
+        }),
+      ],
+    ],
+    [
+      'the shared const is not a string',
+      [
+        namedSchema('N1', {
+          kind: 'object',
+          properties: [{ name: 'v', schema: { kind: 'literal', value: 1 }, required: true }],
+        }),
+        namedSchema('N2', {
+          kind: 'object',
+          properties: [{ name: 'v', schema: { kind: 'literal', value: 2 }, required: true }],
+        }),
+        namedSchema('N12', {
+          kind: 'union',
+          members: [
+            { kind: 'ref', name: 'N1' },
+            { kind: 'ref', name: 'N2' },
+          ],
+        }),
+      ],
+    ],
+    [
+      'a nested union mixes ref and non-ref members',
+      [
+        beverage,
+        namedSchema('Wrapper', {
+          kind: 'array',
+          items: {
+            kind: 'union',
+            members: [
+              { kind: 'ref', name: 'Beverage' },
+              { kind: 'scalar', scalar: 'string' },
+            ],
+            discriminator: {
+              propertyName: 'category',
+              mapping: [{ value: 'beverage', schemaName: 'Beverage' }],
+            },
+          },
+        }),
+      ],
+    ],
+  ])('emits no guards when %s', (_reason, schemas) => {
+    expect(emitPackage(apiModel({ schemas }))).not.toContain('value is');
+  });
+
+  it('ignores non-literal properties while detecting the implicit discriminant', () => {
+    const out = emitPackage(
+      apiModel({
+        schemas: [
+          namedSchema('R1', {
+            kind: 'object',
+            properties: [
+              {
+                name: 'note',
+                schema: { kind: 'scalar', scalar: 'string' },
+                required: false,
+              },
+              {
+                name: 'kind',
+                schema: { kind: 'literal', value: 'one' },
+                required: true,
+              },
+            ],
+          }),
+          namedSchema('R2', {
+            kind: 'object',
+            properties: [
+              {
+                name: 'note',
+                schema: { kind: 'scalar', scalar: 'string' },
+                required: false,
+              },
+              {
+                name: 'kind',
+                schema: { kind: 'literal', value: 'two' },
+                required: true,
+              },
+            ],
+          }),
+          namedSchema('R12', {
+            kind: 'union',
+            members: [
+              { kind: 'ref', name: 'R1' },
+              { kind: 'ref', name: 'R2' },
+            ],
+          }),
+        ],
+      })
+    );
+    expect(out).toContain('export function isR1(value: R12): value is R1 {');
+    expect(out).toContain('(value as Record<string, unknown>)["kind"] === "one"');
+  });
+
+  const cat = namedSchema('Cat', {
+    kind: 'object',
+    properties: [{ name: 'kind', schema: { kind: 'literal', value: 'cat' }, required: true }],
+  });
+  const dog = namedSchema('Dog', {
+    kind: 'object',
+    properties: [{ name: 'kind', schema: { kind: 'literal', value: 'dog' }, required: true }],
+  });
+  const catOrDog: SchemaModel = {
+    kind: 'union',
+    members: [
+      { kind: 'ref', name: 'Cat' },
+      { kind: 'ref', name: 'Dog' },
+    ],
+  };
+
+  // Each container position is a distinct branch of the nested-site walk. The
+  // guard param is the inline member union, not the (unnamed) nested union.
+  it.each<[string, SchemaModel]>([
+    ['array items', { kind: 'array', items: catOrDog }],
+    ['a record value', { kind: 'record', value: catOrDog }],
+    [
+      'an object property',
+      { kind: 'object', properties: [{ name: 'pet', schema: catOrDog, required: true }] },
+    ],
+  ])('emits guards for a discriminated union nested under %s', (_position, container) => {
+    const out = emitPackage(apiModel({ schemas: [cat, dog, namedSchema('PetBox', container)] }));
+    expect(out).toContain('export function isCat(value: Cat | Dog): value is Cat {');
+    expect(out).toContain('export function isDog(value: Cat | Dog): value is Dog {');
+  });
+
+  it('emits a guard once when the same nested union appears in two schemas', () => {
+    const item = (name: string, value: string) =>
+      namedSchema(name, {
+        kind: 'object',
+        properties: [{ name: 'status', schema: { kind: 'literal', value }, required: true }],
+      });
+    const arrayOfUnion = (name: string) =>
+      namedSchema(name, {
+        kind: 'array',
+        items: {
+          kind: 'union',
+          members: [
+            { kind: 'ref', name: 'Ok' },
+            { kind: 'ref', name: 'Err' },
+          ],
+          discriminator: {
+            propertyName: 'status',
+            mapping: [
+              { value: 'ok', schemaName: 'Ok' },
+              { value: 'error', schemaName: 'Err' },
+            ],
+          },
+        },
+      });
+    const out = emitPackage(
+      apiModel({
+        schemas: [
+          item('Ok', 'ok'),
+          item('Err', 'error'),
+          arrayOfUnion('ListA'),
+          arrayOfUnion('ListB'),
+        ],
+      })
+    );
+    expect(out.match(/export function isOk\(/g)).toHaveLength(1);
+    expect(out.match(/export function isErr\(/g)).toHaveLength(1);
+  });
+
+  it('prefers the top-level named union param when a member also nests elsewhere', () => {
+    const out = emitPackage(
+      apiModel({
+        schemas: [
+          beverage,
+          dessert,
+          // Top-level named union processed first → guard param is `MenuItem`.
+          namedSchema('MenuItem', {
+            kind: 'union',
+            members: [
+              { kind: 'ref', name: 'Beverage' },
+              { kind: 'ref', name: 'Dessert' },
+            ],
+            discriminator: {
+              propertyName: 'category',
+              mapping: [
+                { value: 'beverage', schemaName: 'Beverage' },
+                { value: 'dessert', schemaName: 'Dessert' },
+              ],
+            },
+          }),
+          // Same members nested as array items; the dedup keeps the top-level guard.
+          namedSchema('MenuList', {
+            kind: 'array',
+            items: {
+              kind: 'union',
+              members: [
+                { kind: 'ref', name: 'Beverage' },
+                { kind: 'ref', name: 'Dessert' },
+              ],
+              discriminator: {
+                propertyName: 'category',
+                mapping: [
+                  { value: 'beverage', schemaName: 'Beverage' },
+                  { value: 'dessert', schemaName: 'Dessert' },
+                ],
+              },
+            },
+          }),
+        ],
+      })
+    );
+    expect(out.match(/export function isBeverage\(/g)).toHaveLength(1);
+    expect(out).toContain('export function isBeverage(value: MenuItem): value is Beverage {');
+  });
+});
diff --git a/packages/client-generator/src/emitters/__tests__/types.test.ts b/packages/client-generator/src/emitters/__tests__/types.test.ts
new file mode 100644
index 0000000000..6bcfa0976f
--- /dev/null
+++ b/packages/client-generator/src/emitters/__tests__/types.test.ts
@@ -0,0 +1,599 @@
+import type { PropertyModel, SchemaModel } from '../../intermediate-representation/model.js';
+import { emitClientSingleFile } from '../client-assembly.js';
+import { printNodes } from '../ts.js';
+import { renderSchema, schemaToTypeNode, typesStatements } from '../types.js';
+import { SCALAR, apiModel, namedSchema } from './fixtures.js';
+
+// The package arm keeps the emitted text free of the embedded runtime, so the
+// absence assertions below test the schema types/guards alone.
+const emitPackage: typeof emitClientSingleFile = (model, options = {}) =>
+  emitClientSingleFile(model, { ...options, runtime: 'package' });
+
+describe('renderTypes', () => {
+  it('produces nothing when there are no schemas', () => {
+    const out = emitPackage(apiModel({ schemas: [] }));
+    // Two consecutive blank lines would be a sign of an empty types block; check absence.
+    expect(out).not.toContain('export type T');
+  });
+
+  it('emits each named schema with its description', () => {
+    const out = emitPackage(
+      apiModel({
+        schemas: [namedSchema('Foo', { kind: 'scalar', scalar: 'string' }, 'a foo')],
+      })
+    );
+    expect(out).toContain('/**\n * a foo\n */');
+    expect(out).toContain('export type Foo = string;');
+  });
+
+  it('prefers schema description over the named-schema description', () => {
+    const out = emitPackage(
+      apiModel({
+        schemas: [
+          namedSchema('Foo', { kind: 'scalar', scalar: 'string', description: 'inner' }, 'outer'),
+        ],
+      })
+    );
+    expect(out).toContain('/**\n * inner\n */');
+    expect(out).not.toContain('outer');
+  });
+
+  it('omits JSDoc when the schema description is whitespace-only', () => {
+    // Exercises the `!text.trim()` short-circuit inside renderJsDoc.
+    const out = emitPackage(
+      apiModel({
+        schemas: [namedSchema('Foo', { kind: 'scalar', scalar: 'string' }, '   ')],
+      })
+    );
+    expect(out).not.toContain('/**  ');
+    expect(out).toContain('export type Foo = string;');
+  });
+
+  it('trims leading and trailing blank lines from multi-line schema descriptions', () => {
+    // Exercises both `start++` and `end--` arms of trimLines.
+    const out = emitPackage(
+      apiModel({
+        schemas: [
+          namedSchema('Foo', {
+            kind: 'scalar',
+            scalar: 'string',
+            description: '\n\nfirst\nsecond\n\n',
+          }),
+        ],
+      })
+    );
+    expect(out).toContain('/**\n * first\n * second\n */');
+    expect(out).not.toMatch(/\/\*\*\n \*\n/);
+  });
+});
+
+describe('renderSchema (and its branches)', () => {
+  it('renders scalars: string/number/integer/boolean', () => {
+    expect(renderSchema({ kind: 'scalar', scalar: 'string' })).toBe('string');
+    expect(renderSchema({ kind: 'scalar', scalar: 'number' })).toBe('number');
+    expect(renderSchema({ kind: 'scalar', scalar: 'integer' })).toBe('number');
+    expect(renderSchema({ kind: 'scalar', scalar: 'boolean' })).toBe('boolean');
+  });
+
+  it('renders a ref as the bare name', () => {
+    expect(renderSchema({ kind: 'ref', name: 'Foo' })).toBe('Foo');
+  });
+
+  it('renders a binary-format string as Blob (file/upload content)', () => {
+    expect(renderSchema({ kind: 'scalar', scalar: 'string', metadata: { format: 'binary' } })).toBe(
+      'Blob'
+    );
+    // `byte` (base64) stays a string; only `binary` is raw content.
+    expect(renderSchema({ kind: 'scalar', scalar: 'string', metadata: { format: 'byte' } })).toBe(
+      'string'
+    );
+  });
+
+  it('renders string/number/boolean literals correctly', () => {
+    expect(renderSchema({ kind: 'literal', value: 'hi' })).toBe('"hi"');
+    expect(renderSchema({ kind: 'literal', value: 42 })).toBe('42');
+    expect(renderSchema({ kind: 'literal', value: true })).toBe('true');
+    expect(renderSchema({ kind: 'literal', value: false })).toBe('false');
+  });
+
+  it('renders negative number literals (built via a prefix-minus expression)', () => {
+    // TypeScript's factory rejects a bare negative numeric literal — it must be a
+    // unary-minus over a positive literal, which this exercises.
+    expect(renderSchema({ kind: 'literal', value: -5 })).toBe('-5');
+    expect(renderSchema({ kind: 'enum', values: [-1, 2], scalar: 'number' })).toBe('-1 | 2');
+  });
+
+  it('renders single-value enums without parens when wrapped in array (parens=true)', () => {
+    expect(
+      renderSchema({
+        kind: 'array',
+        items: { kind: 'enum', values: ['a'], scalar: 'string' },
+      })
+    ).toBe('"a"[]');
+  });
+
+  it('renders multi-value enums WITH parens when wrapped in array (parens=true)', () => {
+    expect(
+      renderSchema({
+        kind: 'array',
+        items: { kind: 'enum', values: ['a', 'b'], scalar: 'string' },
+      })
+    ).toBe('("a" | "b")[]');
+  });
+
+  it('renders number enums without JSON-quoting them', () => {
+    expect(renderSchema({ kind: 'enum', values: [1, 2, 3], scalar: 'number' })).toBe('1 | 2 | 3');
+  });
+
+  it('renders boolean enums without JSON-quoting them', () => {
+    expect(renderSchema({ kind: 'enum', values: [true, false], scalar: 'boolean' })).toBe(
+      'true | false'
+    );
+  });
+
+  it('renders null and unknown', () => {
+    expect(renderSchema({ kind: 'null' })).toBe('null');
+    expect(renderSchema({ kind: 'unknown' })).toBe('unknown');
+  });
+
+  it('renders array of scalars', () => {
+    expect(renderSchema({ kind: 'array', items: SCALAR })).toBe('string[]');
+  });
+
+  it('parenthesizes unions inside arrays', () => {
+    expect(
+      renderSchema({
+        kind: 'array',
+        items: { kind: 'union', members: [SCALAR, { kind: 'null' }] },
+      })
+    ).toBe('(string | null)[]');
+  });
+
+  it('renders records', () => {
+    expect(renderSchema({ kind: 'record', value: SCALAR })).toBe('Record<string, string>');
+  });
+
+  it('renders empty objects as `{}`', () => {
+    expect(renderSchema({ kind: 'object', properties: [] })).toBe('{}');
+  });
+
+  it('renders required vs optional properties', () => {
+    const props: PropertyModel[] = [
+      { name: 'id', schema: SCALAR, required: true },
+      { name: 'name', schema: SCALAR, required: false },
+    ];
+    const got = renderSchema({ kind: 'object', properties: props });
+    expect(got).toContain('id: string;');
+    expect(got).toContain('name?: string;');
+  });
+
+  it('renders an inline single-line JSDoc above a property with a short description', () => {
+    const got = renderSchema({
+      kind: 'object',
+      properties: [{ name: 'a', schema: SCALAR, required: true, description: 'short' }],
+    });
+    expect(got).toContain('    /**\n     * short\n     */\n    a: string;');
+  });
+
+  it('renders an inline multi-line JSDoc above a property with a long description', () => {
+    const got = renderSchema({
+      kind: 'object',
+      properties: [
+        {
+          name: 'a',
+          schema: SCALAR,
+          required: true,
+          description: 'line1\nline2',
+        },
+      ],
+    });
+    expect(got).toContain('    /**\n     * line1\n     * line2\n     */\n');
+  });
+
+  it('emits a `readonly` modifier on readOnly properties', () => {
+    // readOnly (server-managed) props are marked `readonly` so consumer write-type
+    // utilities (e.g. OmitReadOnly<T>) can strip them; non-readOnly props are plain.
+    const got = renderSchema({
+      kind: 'object',
+      properties: [
+        { name: 'id', schema: SCALAR, required: true, readOnly: true },
+        { name: 'name', schema: SCALAR, required: true },
+      ],
+    });
+    expect(got).toContain('readonly id: string;');
+    expect(got).toMatch(/\n {4}name: string;/);
+    expect(got).not.toContain('readonly name');
+  });
+
+  it('renders an omit schema as Omit<Base, keys>', () => {
+    expect(renderSchema({ kind: 'omit', base: 'Pet', keys: ['id', 'createdAt'] })).toBe(
+      'Omit<Pet, "id" | "createdAt">'
+    );
+  });
+
+  it('renders union and intersection', () => {
+    expect(renderSchema({ kind: 'union', members: [SCALAR, { kind: 'null' }] })).toBe(
+      'string | null'
+    );
+    const inter = renderSchema({
+      kind: 'intersection',
+      members: [
+        { kind: 'ref', name: 'A' },
+        { kind: 'ref', name: 'B' },
+      ],
+    });
+    expect(inter).toBe('A & B');
+  });
+
+  it('quotes property names that contain disallowed characters', () => {
+    const got = renderSchema({
+      kind: 'object',
+      properties: [{ name: 'menu:read', schema: SCALAR, required: true }],
+    });
+    expect(got).toContain('"menu:read": string;');
+  });
+
+  it('quotes property names that are reserved words', () => {
+    const got = renderSchema({
+      kind: 'object',
+      properties: [{ name: 'class', schema: SCALAR, required: true }],
+    });
+    expect(got).toContain('"class": string;');
+  });
+
+  it('renders an inline empty-description JSDoc as nothing', () => {
+    const got = renderSchema({
+      kind: 'object',
+      properties: [{ name: 'a', schema: SCALAR, required: true, description: '   ' }],
+    });
+    // empty description ⇒ no JSDoc and no leading 2-space indent before the prop
+    expect(got).not.toContain('/**');
+    expect(got).toContain('  a: string;');
+  });
+});
+
+describe('JSDoc validation metadata (@minimum / @maxLength / @pattern / @format / @deprecated)', () => {
+  it('renders numeric constraints as JSDoc tags on a named schema', () => {
+    const out = emitPackage(
+      apiModel({
+        schemas: [
+          namedSchema('Limit', {
+            kind: 'scalar',
+            scalar: 'integer',
+            metadata: { minimum: 1, maximum: 100 },
+          }),
+        ],
+      })
+    );
+    expect(out).toMatch(
+      /\/\*\*[\s\S]*@minimum 1[\s\S]*@maximum 100[\s\S]*\*\/\s*export type Limit = number;/
+    );
+  });
+
+  it('renders string constraints (minLength, maxLength, pattern, format) as JSDoc tags', () => {
+    const out = emitPackage(
+      apiModel({
+        schemas: [
+          namedSchema('Name', {
+            kind: 'scalar',
+            scalar: 'string',
+            metadata: {
+              minLength: 1,
+              maxLength: 50,
+              pattern: '^[A-Z]+$',
+              format: 'email',
+            },
+          }),
+        ],
+      })
+    );
+    expect(out).toContain('@minLength 1');
+    expect(out).toContain('@maxLength 50');
+    expect(out).toContain('@pattern ^[A-Z]+$');
+    expect(out).toContain('@format email');
+  });
+
+  it('renders array constraints (minItems, maxItems, uniqueItems) as JSDoc tags', () => {
+    const out = emitPackage(
+      apiModel({
+        schemas: [
+          namedSchema('Tags', {
+            kind: 'array',
+            items: { kind: 'scalar', scalar: 'string' },
+            metadata: { minItems: 1, maxItems: 5, uniqueItems: true },
+          }),
+        ],
+      })
+    );
+    expect(out).toContain('@minItems 1');
+    expect(out).toContain('@maxItems 5');
+    expect(out).toContain('@uniqueItems');
+    // No value after @uniqueItems — it's a presence-only tag.
+    expect(out).not.toContain('@uniqueItems true');
+  });
+
+  it('renders @exclusiveMinimum / @exclusiveMaximum in numeric form', () => {
+    const out = emitPackage(
+      apiModel({
+        schemas: [
+          namedSchema('Volume', {
+            kind: 'scalar',
+            scalar: 'number',
+            metadata: { exclusiveMinimum: 0, exclusiveMaximum: 1000 },
+          }),
+        ],
+      })
+    );
+    expect(out).toContain('@exclusiveMinimum 0');
+    expect(out).toContain('@exclusiveMaximum 1000');
+  });
+
+  it('renders @deprecated as a presence-only tag', () => {
+    const out = emitPackage(
+      apiModel({
+        schemas: [
+          namedSchema('Old', {
+            kind: 'scalar',
+            scalar: 'string',
+            metadata: { deprecated: true },
+          }),
+        ],
+      })
+    );
+    expect(out).toContain('@deprecated');
+    expect(out).not.toContain('@deprecated true');
+  });
+
+  it('combines description text and tags in the same JSDoc block', () => {
+    const out = emitPackage(
+      apiModel({
+        schemas: [
+          namedSchema('Limit', {
+            kind: 'scalar',
+            scalar: 'integer',
+            description: 'Page size.',
+            metadata: { minimum: 1, maximum: 100 },
+          }),
+        ],
+      })
+    );
+    // Description first, then tag lines.
+    expect(out).toMatch(/\*\s*Page size\.\s*\n\s*\*\s*@minimum 1\s*\n\s*\*\s*@maximum 100/);
+  });
+
+  it('renders metadata above inline object properties', () => {
+    const got = renderSchema({
+      kind: 'object',
+      properties: [
+        {
+          name: 'name',
+          required: true,
+          description: 'Display name.',
+          schema: {
+            kind: 'scalar',
+            scalar: 'string',
+            metadata: { minLength: 1, maxLength: 50, pattern: '^[A-Z]+$' },
+          },
+        },
+      ],
+    });
+    // Multi-line JSDoc with description then tags, immediately above the prop line.
+    expect(got).toMatch(/\* Display name\./);
+    expect(got).toMatch(/\* @minLength 1/);
+    expect(got).toMatch(/\* @maxLength 50/);
+    expect(got).toMatch(/\* @pattern \^\[A-Z\]\+\$/);
+    expect(got).toContain('name: string;');
+  });
+
+  it('omits the JSDoc block when there is neither description nor metadata', () => {
+    const got = renderSchema({
+      kind: 'object',
+      properties: [{ name: 'a', schema: SCALAR, required: true }],
+    });
+    expect(got).not.toContain('/**');
+  });
+
+  it('emits a JSDoc block when metadata exists even without a description', () => {
+    const got = renderSchema({
+      kind: 'object',
+      properties: [
+        {
+          name: 'page',
+          required: true,
+          schema: {
+            kind: 'scalar',
+            scalar: 'integer',
+            metadata: { minimum: 1 },
+          },
+        },
+      ],
+    });
+    expect(got).toMatch(/\/\*\*\n {5}\* @minimum 1\n {5}\*\/\n {4}page: number;/);
+  });
+
+  it('escapes `*/` inside pattern strings so it cannot terminate the JSDoc block', () => {
+    // Defensive guard: a regex pattern of `^a*/b$` would otherwise break the comment.
+    const out = emitPackage(
+      apiModel({
+        schemas: [
+          namedSchema('Tricky', {
+            kind: 'scalar',
+            scalar: 'string',
+            metadata: { pattern: '^a*/b$' },
+          }),
+        ],
+      })
+    );
+    expect(out).toContain('@pattern ^a*\\/b$');
+    expect(out).not.toContain('@pattern ^a*/b$');
+  });
+
+  it('does not emit a JSDoc block when metadata bag is present but empty', () => {
+    // We never produce `{}` from the builder, but harden the renderer anyway.
+    const got = renderSchema({
+      kind: 'object',
+      properties: [{ name: 'a', schema: { ...SCALAR, metadata: {} }, required: true }],
+    });
+    expect(got).not.toContain('/**');
+  });
+});
+
+describe('dateType knob (string → Date for date formats)', () => {
+  const dateTime = (): SchemaModel => ({
+    kind: 'scalar',
+    scalar: 'string',
+    metadata: { format: 'date-time' },
+  });
+
+  it('emits Date for a date-time string scalar under dateType "Date"', () => {
+    expect(renderSchema(dateTime(), 'Date')).toBe('Date');
+  });
+
+  it('emits Date for a date string scalar under dateType "Date"', () => {
+    expect(
+      renderSchema({ kind: 'scalar', scalar: 'string', metadata: { format: 'date' } }, 'Date')
+    ).toBe('Date');
+  });
+
+  it('keeps string for date-time under dateType "string"', () => {
+    expect(renderSchema(dateTime(), 'string')).toBe('string');
+  });
+
+  it('keeps string for date-time by default (omitted dateType — byte-identical)', () => {
+    expect(renderSchema(dateTime())).toBe('string');
+  });
+
+  it('keeps string for a non-date string format regardless of dateType', () => {
+    const email: SchemaModel = { kind: 'scalar', scalar: 'string', metadata: { format: 'email' } };
+    expect(renderSchema(email, 'Date')).toBe('string');
+  });
+
+  it('leaves non-string scalars unaffected under dateType "Date"', () => {
+    expect(renderSchema({ kind: 'scalar', scalar: 'integer' }, 'Date')).toBe('number');
+  });
+
+  it('threads Date into nested object properties and arrays under "Date"', () => {
+    const out = renderSchema(
+      {
+        kind: 'object',
+        properties: [
+          { name: 'createdAt', schema: dateTime(), required: true },
+          { name: 'days', schema: { kind: 'array', items: dateTime() }, required: false },
+        ],
+      },
+      'Date'
+    );
+    expect(out).toContain('createdAt: Date;');
+    expect(out).toContain('days?: Date[];');
+  });
+
+  it('emits Date in the named-schema alias body under emitOptions dateType "Date"', () => {
+    const out = emitPackage(apiModel({ schemas: [namedSchema('Created', dateTime())] }), {
+      dateType: 'Date',
+    });
+    expect(out).toContain('export type Created = Date;');
+  });
+
+  it('leaves the named-schema alias as string by default', () => {
+    const out = emitPackage(apiModel({ schemas: [namedSchema('Created', dateTime())] }));
+    expect(out).toContain('export type Created = string;');
+  });
+
+  it('defaults schemaToTypeNode dateType to string (called with one arg)', () => {
+    expect(printNodes([schemaToTypeNode(dateTime())])).toBe('string');
+  });
+
+  it('defaults typesStatements dateType to string (called without it)', () => {
+    const out = printNodes(typesStatements([namedSchema('Created', dateTime())], 'union'));
+    expect(out).toContain('export type Created = string;');
+  });
+});
+
+describe('enum style — const-object companion (C6.2)', () => {
+  const orderStatus = namedSchema('OrderStatus', {
+    kind: 'enum',
+    scalar: 'string',
+    values: ['placed', 'completed'],
+  });
+
+  it('emits a const-object companion for named string enums by default', () => {
+    const out = emitPackage(apiModel({ schemas: [orderStatus] }));
+    expect(out).toContain('export type OrderStatus = "placed" | "completed";');
+    expect(out).toContain('export const OrderStatus = {');
+    expect(out).toContain('placed: "placed",');
+    expect(out).toContain('completed: "completed"');
+    expect(out).toContain('} as const;');
+  });
+
+  it('emits only the union type when enumStyle is "union"', () => {
+    const out = emitPackage(apiModel({ schemas: [orderStatus] }), {
+      enumStyle: 'union',
+    });
+    expect(out).toContain('export type OrderStatus = "placed" | "completed";');
+    expect(out).not.toContain('export const OrderStatus');
+  });
+
+  it('does not emit a const object for integer enums', () => {
+    const out = emitPackage(
+      apiModel({
+        schemas: [
+          namedSchema('Code', {
+            kind: 'enum',
+            scalar: 'integer',
+            values: [1, 2],
+          }),
+        ],
+      })
+    );
+    expect(out).toContain('export type Code = 1 | 2;');
+    expect(out).not.toContain('export const Code');
+  });
+
+  it('does not emit a const object for boolean enums', () => {
+    const out = emitPackage(
+      apiModel({
+        schemas: [
+          namedSchema('Flag', {
+            kind: 'enum',
+            scalar: 'boolean',
+            values: [true, false],
+          }),
+        ],
+      })
+    );
+    expect(out).not.toContain('export const Flag');
+  });
+
+  it('skips the const object when any value is not a valid identifier', () => {
+    const out = emitPackage(
+      apiModel({
+        schemas: [
+          namedSchema('Scope', {
+            kind: 'enum',
+            scalar: 'string',
+            values: ['menu:read', 'menuWrite'],
+          }),
+        ],
+      })
+    );
+    expect(out).toContain('export type Scope = "menu:read" | "menuWrite";');
+    expect(out).not.toContain('export const Scope');
+  });
+
+  it('skips the const object for a string-scalar enum that contains a non-string value', () => {
+    // scalarForEnumValues can return 'string' for a mixed enum; the const-object
+    // path must still bail when a value isn't actually a string.
+    const out = emitPackage(
+      apiModel({
+        schemas: [
+          namedSchema('Mixed', {
+            kind: 'enum',
+            scalar: 'string',
+            values: ['a', 1],
+          }),
+        ],
+      })
+    );
+    expect(out).not.toContain('export const Mixed');
+  });
+});
diff --git a/packages/client-generator/src/emitters/__tests__/zod.test.ts b/packages/client-generator/src/emitters/__tests__/zod.test.ts
new file mode 100644
index 0000000000..bc749627e4
--- /dev/null
+++ b/packages/client-generator/src/emitters/__tests__/zod.test.ts
@@ -0,0 +1,429 @@
+import type { NamedSchemaModel, SchemaModel } from '../../intermediate-representation/model.js';
+import { printStatements } from '../ts.js';
+import { renderZodModule, schemaToZodExpression } from '../zod.js';
+import { apiModel, operation, response } from './fixtures.js';
+
+/** Print a single expression by wrapping it in a throwaway const. */
+function expr(schema: SchemaModel): string {
+  return renderZodModule(apiModel({ schemas: [{ name: 'X', schema }] }))
+    .split('= ')[1]
+    .replace(/;$/, '');
+}
+
+describe('schemaToZodExpression — scalars', () => {
+  it('string → z.string()', () => {
+    expect(expr({ kind: 'scalar', scalar: 'string' })).toBe('z.string()');
+  });
+
+  it('number → z.number()', () => {
+    expect(expr({ kind: 'scalar', scalar: 'number' })).toBe('z.number()');
+  });
+
+  it('boolean → z.boolean()', () => {
+    expect(expr({ kind: 'scalar', scalar: 'boolean' })).toBe('z.boolean()');
+  });
+
+  it('integer → z.number().int()', () => {
+    expect(expr({ kind: 'scalar', scalar: 'integer' })).toBe('z.number().int()');
+  });
+
+  it('binary-format string → z.instanceof(Blob) (matches the Blob TS type)', () => {
+    expect(expr({ kind: 'scalar', scalar: 'string', metadata: { format: 'binary' } })).toBe(
+      'z.instanceof(Blob)'
+    );
+  });
+});
+
+describe('schemaToZodExpression — object', () => {
+  it('emits required and optional properties', () => {
+    const out = expr({
+      kind: 'object',
+      properties: [
+        { name: 'id', schema: { kind: 'scalar', scalar: 'integer' }, required: true },
+        { name: 'name', schema: { kind: 'scalar', scalar: 'string' }, required: false },
+      ],
+    });
+    expect(out).toContain('z.object({');
+    expect(out).toContain('id: z.number().int()');
+    expect(out).toContain('name: z.string().optional()');
+  });
+
+  it('quotes non-identifier keys', () => {
+    const out = expr({
+      kind: 'object',
+      properties: [
+        { name: 'x-trace', schema: { kind: 'scalar', scalar: 'string' }, required: true },
+      ],
+    });
+    expect(out).toContain('"x-trace": z.string()');
+  });
+
+  it('emits an empty object literal for no properties', () => {
+    expect(expr({ kind: 'object', properties: [] })).toBe('z.object({})');
+  });
+});
+
+describe('schemaToZodExpression — composites', () => {
+  it('array → z.array(items)', () => {
+    expect(expr({ kind: 'array', items: { kind: 'scalar', scalar: 'string' } })).toBe(
+      'z.array(z.string())'
+    );
+  });
+
+  it('record → z.record(z.string(), value)', () => {
+    expect(expr({ kind: 'record', value: { kind: 'scalar', scalar: 'number' } })).toBe(
+      'z.record(z.string(), z.number())'
+    );
+  });
+
+  it('ref → z.lazy(() => <Name>Schema)', () => {
+    expect(expr({ kind: 'ref', name: 'pet' })).toBe('z.lazy(() => PetSchema)');
+  });
+
+  it('omit → <Base>Schema.omit({ k: true })', () => {
+    expect(expr({ kind: 'omit', base: 'pet', keys: ['id', 'x-trace'] })).toBe(
+      'PetSchema.omit({ id: true, "x-trace": true })'
+    );
+  });
+});
+
+describe('schemaToZodExpression — literals and enums', () => {
+  it('string literal → z.literal("a")', () => {
+    expect(expr({ kind: 'literal', value: 'a' })).toBe('z.literal("a")');
+  });
+
+  it('number literal → z.literal(1)', () => {
+    expect(expr({ kind: 'literal', value: 1 })).toBe('z.literal(1)');
+  });
+
+  it('negative number literal uses a prefix-unary minus', () => {
+    expect(expr({ kind: 'literal', value: -2 })).toBe('z.literal(-2)');
+  });
+
+  it('boolean literal → z.literal(true)', () => {
+    expect(expr({ kind: 'literal', value: true })).toBe('z.literal(true)');
+    expect(expr({ kind: 'literal', value: false })).toBe('z.literal(false)');
+  });
+
+  it('all-string enum → z.enum([…])', () => {
+    expect(expr({ kind: 'enum', scalar: 'string', values: ['a', 'b'] })).toBe('z.enum(["a", "b"])');
+  });
+
+  it('mixed/number enum → z.union of literals', () => {
+    expect(expr({ kind: 'enum', scalar: 'number', values: [1, 2] })).toBe(
+      'z.union([z.literal(1), z.literal(2)])'
+    );
+  });
+});
+
+describe('schemaToZodExpression — unions and intersections', () => {
+  it('multi-member union → z.union([…])', () => {
+    expect(
+      expr({
+        kind: 'union',
+        members: [
+          { kind: 'scalar', scalar: 'string' },
+          { kind: 'scalar', scalar: 'number' },
+        ],
+      })
+    ).toBe('z.union([z.string(), z.number()])');
+  });
+
+  it('single-member union collapses to the member', () => {
+    expect(expr({ kind: 'union', members: [{ kind: 'scalar', scalar: 'boolean' }] })).toBe(
+      'z.boolean()'
+    );
+  });
+
+  it('intersection chains .and', () => {
+    expect(
+      expr({
+        kind: 'intersection',
+        members: [
+          { kind: 'ref', name: 'a' },
+          { kind: 'ref', name: 'b' },
+          { kind: 'ref', name: 'c' },
+        ],
+      })
+    ).toBe('z.lazy(() => ASchema).and(z.lazy(() => BSchema)).and(z.lazy(() => CSchema))');
+  });
+});
+
+describe('schemaToZodExpression — null and unknown', () => {
+  it('null → z.null()', () => {
+    expect(expr({ kind: 'null' })).toBe('z.null()');
+  });
+
+  it('unknown → z.unknown()', () => {
+    expect(expr({ kind: 'unknown' })).toBe('z.unknown()');
+  });
+});
+
+describe('schemaToZodExpression — refinements', () => {
+  it('string min/max/pattern', () => {
+    expect(
+      expr({
+        kind: 'scalar',
+        scalar: 'string',
+        metadata: { minLength: 1, maxLength: 5, pattern: '^a.+$' },
+      })
+    ).toBe('z.string().min(1).max(5).regex(new RegExp("^a.+$"))');
+  });
+
+  it('number bounds and exclusive bounds', () => {
+    expect(
+      expr({
+        kind: 'scalar',
+        scalar: 'number',
+        metadata: { minimum: 0, maximum: 10, exclusiveMinimum: 1, exclusiveMaximum: 9 },
+      })
+    ).toBe('z.number().min(0).max(10).gt(1).lt(9)');
+  });
+
+  it('integer keeps .int() before bounds', () => {
+    expect(expr({ kind: 'scalar', scalar: 'integer', metadata: { minimum: -5, maximum: 5 } })).toBe(
+      'z.number().int().min(-5).max(5)'
+    );
+  });
+
+  it('array min/max items', () => {
+    expect(
+      expr({
+        kind: 'array',
+        items: { kind: 'scalar', scalar: 'string' },
+        metadata: { minItems: 1, maxItems: 3 },
+      })
+    ).toBe('z.array(z.string()).min(1).max(3)');
+  });
+
+  it('ignores metadata on kinds without a stable refinement (e.g. boolean)', () => {
+    expect(expr({ kind: 'scalar', scalar: 'boolean', metadata: { minimum: 1 } })).toBe(
+      'z.boolean()'
+    );
+  });
+
+  it('emits only the string refinements that are set (others skipped)', () => {
+    expect(expr({ kind: 'scalar', scalar: 'string', metadata: { maxLength: 5 } })).toBe(
+      'z.string().max(5)'
+    );
+  });
+
+  it('emits only the number refinements that are set (others skipped)', () => {
+    expect(expr({ kind: 'scalar', scalar: 'number', metadata: { maximum: 9 } })).toBe(
+      'z.number().max(9)'
+    );
+    expect(expr({ kind: 'scalar', scalar: 'number', metadata: { exclusiveMaximum: 9 } })).toBe(
+      'z.number().lt(9)'
+    );
+  });
+
+  it('emits only the array refinements that are set (others skipped)', () => {
+    expect(
+      expr({
+        kind: 'array',
+        items: { kind: 'scalar', scalar: 'string' },
+        metadata: { maxItems: 3 },
+      })
+    ).toBe('z.array(z.string()).max(3)');
+    expect(
+      expr({
+        kind: 'array',
+        items: { kind: 'scalar', scalar: 'string' },
+        metadata: { minItems: 1 },
+      })
+    ).toBe('z.array(z.string()).min(1)');
+  });
+
+  it('an empty metadata object adds no refinements', () => {
+    expect(expr({ kind: 'scalar', scalar: 'string', metadata: {} })).toBe('z.string()');
+  });
+});
+
+describe('renderZodModule', () => {
+  it('returns empty string when there is nothing to emit', () => {
+    expect(renderZodModule(apiModel())).toBe('');
+  });
+
+  it('emits the z import and one export const per schema', () => {
+    const schemas: NamedSchemaModel[] = [
+      {
+        name: 'Pet',
+        schema: {
+          kind: 'object',
+          properties: [
+            { name: 'id', schema: { kind: 'scalar', scalar: 'integer' }, required: true },
+            { name: 'tag', schema: { kind: 'scalar', scalar: 'string' }, required: false },
+          ],
+        },
+      },
+    ];
+    const out = renderZodModule(apiModel({ schemas }));
+    expect(out).toContain('import { z } from "zod";');
+    expect(out).toContain('export const PetSchema = z.object({');
+    // No operation has a JSON body -> no validation surface.
+    expect(out).not.toContain('operationSchemas');
+    expect(out).not.toContain('zodValidation');
+  });
+});
+
+describe('renderZodModule — operation validation surface', () => {
+  const model = (op: Parameters<typeof operation>[0]) =>
+    apiModel({ services: [{ name: 'Default', operations: [operation(op)] }] });
+
+  it('maps a JSON request body and response by operationId and emits the middleware', () => {
+    const out = renderZodModule(
+      model({
+        name: 'createOrder',
+        method: 'post',
+        requestBody: {
+          contentType: 'application/json',
+          schema: { kind: 'ref', name: 'OrderInput' },
+          required: true,
+        },
+        successResponses: [response({ schema: { kind: 'ref', name: 'Order' } })],
+      })
+    );
+    expect(out).toContain('export const operationSchemas: {');
+    expect(out).toContain(
+      'createOrder: { request: z.lazy(() => OrderInputSchema), response: z.lazy(() => OrderSchema) }'
+    );
+    expect(out).toContain('export function zodValidation(');
+    expect(out).toContain('export class ZodValidationError extends Error {');
+  });
+
+  it('annotates the map with z.ZodType so declaration emit stays small (TS7056)', () => {
+    const out = renderZodModule(
+      model({
+        name: 'createOrder',
+        method: 'post',
+        requestBody: {
+          contentType: 'application/json',
+          schema: { kind: 'ref', name: 'OrderInput' },
+          required: true,
+        },
+        successResponses: [response({ schema: { kind: 'ref', name: 'Order' } })],
+      })
+    );
+    expect(out).toContain(
+      'createOrder: {\n        request: z.ZodType;\n        response: z.ZodType;\n    };'
+    );
+  });
+
+  it('distributes a readOnly omit into an allOf intersection instead of calling .omit on it', () => {
+    const out = renderZodModule(
+      apiModel({
+        schemas: [
+          {
+            name: 'Base',
+            schema: {
+              kind: 'object',
+              properties: [
+                { name: 'id', schema: { kind: 'scalar', scalar: 'string' }, required: true },
+                { name: 'name', schema: { kind: 'scalar', scalar: 'string' }, required: true },
+              ],
+            },
+          },
+          {
+            name: 'Combined',
+            schema: {
+              kind: 'intersection',
+              members: [
+                { kind: 'ref', name: 'Base' },
+                {
+                  kind: 'object',
+                  properties: [
+                    {
+                      name: 'extra',
+                      schema: { kind: 'scalar', scalar: 'string' },
+                      required: false,
+                    },
+                  ],
+                },
+              ],
+            },
+          },
+        ],
+        services: [
+          {
+            name: 'Default',
+            operations: [
+              operation({
+                name: 'createCombined',
+                method: 'post',
+                requestBody: {
+                  contentType: 'application/json',
+                  schema: { kind: 'omit', base: 'Combined', keys: ['id'] },
+                  required: true,
+                },
+              }),
+            ],
+          },
+        ],
+      })
+    );
+    // ZodIntersection has no .omit — the omission lands on the object members instead.
+    expect(out).not.toContain('CombinedSchema.omit');
+    expect(out).toContain('BaseSchema.omit({ id: true })');
+  });
+
+  it('renders an inline (non-ref) body schema in place', () => {
+    const out = renderZodModule(
+      model({
+        name: 'ping',
+        successResponses: [
+          response({
+            schema: {
+              kind: 'object',
+              properties: [
+                { name: 'ok', schema: { kind: 'scalar', scalar: 'boolean' }, required: true },
+              ],
+            },
+          }),
+        ],
+      })
+    );
+    expect(out).toContain('ping: { response: z.object(');
+  });
+
+  it('skips SSE operations and non-JSON bodies', () => {
+    const out = renderZodModule(
+      apiModel({
+        schemas: [{ name: 'Keep', schema: { kind: 'scalar', scalar: 'string' } }],
+        services: [
+          {
+            name: 'Default',
+            operations: [
+              operation({
+                name: 'stream',
+                successResponses: [
+                  response({
+                    contentType: 'text/event-stream',
+                    schema: { kind: 'ref', name: 'Keep' },
+                  }),
+                ],
+              }),
+              operation({
+                name: 'upload',
+                method: 'post',
+                requestBody: {
+                  contentType: 'application/octet-stream',
+                  schema: { kind: 'scalar', scalar: 'string' },
+                  required: true,
+                },
+              }),
+            ],
+          },
+        ],
+      })
+    );
+    expect(out).toContain('export const KeepSchema');
+    expect(out).not.toContain('operationSchemas');
+  });
+});
+
+describe('schemaToZodExpression — direct export', () => {
+  it('is callable directly and returns an expression node', () => {
+    const node = schemaToZodExpression({ kind: 'scalar', scalar: 'string' });
+    expect(printStatements([node])).toBe('z.string()');
+  });
+});
diff --git a/packages/client-generator/src/emitters/auth.ts b/packages/client-generator/src/emitters/auth.ts
new file mode 100644
index 0000000000..483dc7a6f4
--- /dev/null
+++ b/packages/client-generator/src/emitters/auth.ts
@@ -0,0 +1,33 @@
+// The auth *naming* conventions of the generated surface. Credential injection itself
+// lives in the runtime (src/runtime/auth.ts); the wiring emitter only derives the
+// public setter names bound to the client instance's `auth` members.
+
+import type { SecuritySchemeModel } from '../intermediate-representation/model.js';
+import { pascalCase } from './support.js';
+
+/**
+ * Public setter name for an apiKey scheme: `setApiKey` when it's the only apiKey
+ * scheme (of any `in`), else `setApiKey<Key>` to disambiguate.
+ */
+export function apiKeySetterName(key: string, sole: boolean): string {
+  return sole ? 'setApiKey' : `setApiKey${pascalCase(key)}`;
+}
+
+/**
+ * The public credential-setter names the client exports for a set of schemes,
+ * in emission order (`setBearer`, then `setBasicAuth`, then each apiKey setter).
+ * Also seeds the reserved-identifier set (`packageIdents`) so operation names
+ * can't collide with a setter.
+ */
+export function authSetterNames(schemes: SecuritySchemeModel[]): string[] {
+  const names: string[] = [];
+  if (schemes.some((s) => s.kind === 'bearer')) names.push('setBearer');
+  if (schemes.some((s) => s.kind === 'basic')) names.push('setBasicAuth');
+  const apiKeySchemes = schemes.filter(
+    (s) => s.kind === 'apiKeyHeader' || s.kind === 'apiKeyQuery' || s.kind === 'apiKeyCookie'
+  );
+  for (const scheme of apiKeySchemes) {
+    names.push(apiKeySetterName(scheme.key, apiKeySchemes.length === 1));
+  }
+  return names;
+}
diff --git a/packages/client-generator/src/emitters/client-assembly.ts b/packages/client-generator/src/emitters/client-assembly.ts
new file mode 100644
index 0000000000..1d5712d591
--- /dev/null
+++ b/packages/client-generator/src/emitters/client-assembly.ts
@@ -0,0 +1,400 @@
+// Client assembly, shared by both runtime distributions and both output modes. The
+// wiring (descriptor map + `Ops` interface, emitters/descriptor.ts) is identical; only
+// the runtime block differs — `runtime: 'package'` imports `createClient` from
+// `@redocly/client-generator`, everything else (inline, the default) embeds the
+// assembled runtime sources in its place (emitters/inline-runtime.ts). Single-file
+// layout: runtime (import line | embedded block) → schema types → type guards →
+// `<Op>*` aliases → Ops → OPERATIONS → (baked setup) → client instance → sugar →
+// (package mode only) type re-exports — the embedded types are already exported in
+// place, so the embed arm needs none. Split mode moves the schema types + guards into
+// a sibling `<stem>.schemas.ts` the entry re-exports (`emitClientSplit`).
+
+import {
+  allOperations,
+  type ApiModel,
+  type OperationModel,
+  type SecuritySchemeModel,
+} from '../intermediate-representation/model.js';
+import { apiKeySetterName } from './auth.js';
+import { descriptorStatements, opsInterfaceStatements, packageIdents } from './descriptor.js';
+import { banner, type EmitOptions, HEADER, renderTitleComment } from './emit-options.js';
+import { isIdentifier } from './identifier.js';
+import { assembleInlineRuntime } from './inline-runtime.js';
+import { renderOperationAliases, sseAliases } from './operation-aliases.js';
+import { operationSignature } from './operation-signature.js';
+import { computeResponse, errorTypeNodes, isTypedMultipart } from './operation-types.js';
+import { type EmitContext, renderArgList } from './operations.js';
+import { resolveModelPagination } from './pagination.js';
+import { isSseOp } from './sse.js';
+import { pascalCase } from './support.js';
+import {
+  arrow,
+  exportConstStatement,
+  parseStatements,
+  printNodes,
+  printStatements,
+  ts,
+} from './ts.js';
+import { typeGuardStatements } from './type-guards.js';
+import { typesStatements } from './types.js';
+
+const { factory } = ts;
+
+const PACKAGE_SPECIFIER = '@redocly/client-generator';
+
+/**
+ * A double-quoted TS string literal for generated code. `JSON.stringify` alone leaves
+ * U+2028/U+2029 raw (legal JSON, line terminators in code contexts) — escape them so a
+ * hostile spec value can never alter the shape of the emitted statement.
+ */
+function codeString(value: string): string {
+  return JSON.stringify(value)
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029');
+}
+
+export function emitClientSingleFile(model: ApiModel, options: EmitOptions = {}): string {
+  return emitClient(model, options).entry;
+}
+
+/**
+ * `split` mode: the same client with the schema types + type guards carved out into a
+ * sibling `<stem>.schemas.ts`. The entry file re-exports the schemas module
+ * (`export *`) and type-imports exactly the schema names its own code references, so
+ * both files hold under `noUnusedLocals`. `schemas` is absent when the document
+ * declares no schema statements (the entry is then self-contained).
+ */
+export function emitClientSplit(
+  model: ApiModel,
+  options: EmitOptions,
+  stem: string
+): { entry: string; schemas?: string } {
+  return emitClient(model, options, stem);
+}
+
+/** The shared assembly; `splitStem` (when given) selects the two-file split layout. */
+function emitClient(
+  model: ApiModel,
+  options: EmitOptions,
+  splitStem?: string
+): { entry: string; schemas?: string } {
+  const embed = options.runtime !== 'package';
+  const ops = allOperations(model.services);
+  const idents = packageIdents(model);
+  // Resolved (and VERIFIED) up front: an explicit rule that doesn't fit throws here,
+  // before any statement is built — one aggregated error for the whole model.
+  const pagination = resolveModelPagination(model, options.pagination);
+  const ctx: EmitContext = {
+    argsStyle: options.argsStyle ?? 'flat',
+    errorMode: options.errorMode ?? 'throw',
+    dateType: options.dateType ?? 'string',
+    schemaNames: new Set(model.schemas.map((s) => s.name)),
+    pagination,
+  };
+  const flat = ctx.argsStyle === 'flat';
+  const hasSse = ops.some(isSseOp);
+  const hasRegular = ops.some((op) => !isSseOp(op));
+  const apiKeySchemes = model.securitySchemes.filter(
+    (s) => s.kind === 'apiKeyHeader' || s.kind === 'apiKeyQuery' || s.kind === 'apiKeyCookie'
+  );
+
+  const wiring =
+    ops.length > 0
+      ? [
+          ...opsInterfaceStatements(model, idents, ctx),
+          ...descriptorStatements(model, idents, ctx.dateType, pagination),
+        ]
+      : // A spec with no operations still gets the uniform wiring shape.
+        parseStatements(
+          'export type Ops = Record<string, never>;\n' +
+            'export const OPERATIONS = {} as const satisfies Record<string, OperationDescriptor>;'
+        );
+
+  const runtimeSection = embed
+    ? assembleInlineRuntime({
+        multipart: ops.some((op) => op.requestBody && isTypedMultipart(op.requestBody)),
+        // Auth sugar needs schemes; `resolveAuth` fires when a descriptor carries
+        // `security` — a valid spec implies the former, but embed on either.
+        auth: model.securitySchemes.length > 0 || ops.some((op) => op.security.length > 0),
+        sse: hasSse,
+        setup: !!options.setup,
+        paginate: pagination.size > 0,
+      })
+    : importLine(options, ctx, {
+        hasFlatSse: hasSse && flat,
+        hasFlatRegular: hasRegular && flat,
+        hasRegular,
+        hasApiKey: apiKeySchemes.length > 0,
+      });
+  const schemaStatements = [
+    ...typesStatements(model.schemas, options.enumStyle ?? 'const-object', ctx.dateType),
+    ...typeGuardStatements(model.schemas),
+  ];
+  const bodyStatements = [...ops.flatMap((op) => aliasStatements(op, ctx)), ...wiring];
+  const sugar = printNodes(sugarStatements(ops, idents, ctx, model.securitySchemes, apiKeySchemes));
+  // Embed mode exports its whole public surface in place; only the package arm re-exports.
+  const reexports = embed ? '' : reexportLines(ctx, hasSse);
+
+  // Layout puts the reader's OWN API first (types → aliases → Ops → OPERATIONS) and the
+  // machinery after it. In embed mode the runtime block sits between the descriptors and
+  // the `client` initializer — after it for readability, before `client` so every
+  // declaration the module-init call chain touches (hoisted functions AND any future
+  // top-level const) is already evaluated; in package mode the import line leads.
+  if (splitStem === undefined) {
+    return {
+      entry: banner([
+        HEADER,
+        renderTitleComment(model),
+        ...(embed ? [] : [runtimeSection]),
+        printStatements([...schemaStatements, ...bodyStatements]),
+        ...(embed ? [runtimeSection] : []),
+        clientSection(options, ctx, model),
+        sugar,
+        reexports,
+      ]),
+    };
+  }
+
+  const body = printStatements(bodyStatements);
+  const hasSchemas = schemaStatements.length > 0;
+  return {
+    entry: banner([
+      HEADER,
+      renderTitleComment(model),
+      hasSchemas
+        ? schemaLinks(
+            body + '\n' + sugar,
+            ctx.schemaNames,
+            `./${splitStem}.schemas.${options.importExt ?? 'js'}`
+          )
+        : '',
+      ...(embed ? [] : [runtimeSection]),
+      body,
+      ...(embed ? [runtimeSection] : []),
+      clientSection(options, ctx, model),
+      sugar,
+      reexports,
+    ]),
+    schemas: hasSchemas
+      ? banner([HEADER, renderTitleComment(model), printStatements(schemaStatements)])
+      : undefined,
+  };
+}
+
+/**
+ * The entry ⇄ schemas linkage of the split layout: a type-only import of exactly the
+ * schema names the entry's own code references, plus the public `export *` re-export.
+ * Referenced names are found by walking the printed entry code's identifiers (an AST
+ * pass over the emitted text, not a substring search — operation JSDoc may mention a
+ * schema name, and importing an unreferenced type would trip `noUnusedLocals`).
+ */
+function schemaLinks(entryCode: string, schemaNames: Set<string>, specifier: string): string {
+  const referenced = new Set<string>();
+  const visit = (node: ts.Node): void => {
+    if (ts.isIdentifier(node) && schemaNames.has(node.text)) referenced.add(node.text);
+    node.forEachChild(visit);
+  };
+  for (const statement of parseStatements(entryCode)) visit(statement);
+  const names = [...referenced].sort();
+  const importLine =
+    names.length > 0 ? `import type { ${names.join(', ')} } from '${specifier}';\n` : '';
+  return `${importLine}export * from '${specifier}';`;
+}
+
+/** The single import from the runtime package — only names the file actually references. */
+function importLine(
+  options: EmitOptions,
+  ctx: EmitContext,
+  refs: { hasFlatSse: boolean; hasFlatRegular: boolean; hasRegular: boolean; hasApiKey: boolean }
+): string {
+  const values = ['createClient', ...(options.setup ? ['mergeSetup'] : [])];
+  const types = [
+    ...(options.setup ? ['ClientConfig', 'Middleware'] : []),
+    'OperationDescriptor',
+    // Flat sugar signatures reference the per-call option types.
+    ...(refs.hasFlatRegular ? ['RequestOptions'] : []),
+    // `Ops` wraps results in `Result` in result mode — but only NON-SSE members
+    // (an SSE-only spec would otherwise import it unused and fail noUnusedLocals).
+    ...(ctx.errorMode === 'result' && refs.hasRegular ? ['Result'] : []),
+    ...(refs.hasFlatSse ? ['SseOptions'] : []),
+    // The apiKey sugar closures take a `TokenProvider`.
+    ...(refs.hasApiKey ? ['TokenProvider'] : []),
+  ].sort();
+  const names = [...values, ...types.map((t) => `type ${t}`)].join(', ');
+  return `import { ${names} } from '${PACKAGE_SPECIFIER}';`;
+}
+
+/** One operation's `<Op>*` aliases — the same emitters and suppression rules as inline mode. */
+function aliasStatements(op: OperationModel, ctx: EmitContext): ts.Statement[] {
+  const { pathParams } = operationSignature(op);
+  const ordered = pathParams.map((p) => p.param);
+  const identMap = new Map(pathParams.map((p) => [p.param.name, p.ident]));
+  if (isSseOp(op)) return sseAliases(op, ordered, identMap, ctx, 'wire');
+  const { responseType } = computeResponse(op.successResponses, ctx.dateType);
+  const errorMembers =
+    ctx.errorMode === 'result' ? errorTypeNodes(op.errorResponses, ctx.dateType) : [];
+  const errorAlias = errorMembers.length > 0 ? `${pascalCase(op.name)}Error` : '';
+  return renderOperationAliases(
+    op,
+    responseType,
+    ordered,
+    identMap,
+    errorAlias,
+    errorMembers,
+    ctx,
+    true,
+    'wire'
+  );
+}
+
+/** The (optional) baked setup + the default `client` instance. */
+function clientSection(options: EmitOptions, ctx: EmitContext, model: ApiModel): string {
+  const serverUrl = options.serverUrl ?? model.serverUrl;
+  const fields = [
+    // Always baked when the document declares one: the runtime's fallback is a
+    // relative URL, which Node's fetch rejects.
+    ...(serverUrl !== undefined ? [`serverUrl: ${codeString(serverUrl)}`] : []),
+    ...(ctx.errorMode === 'result' ? ['errorMode: "result"'] : []),
+  ];
+  const config = fields.length > 0 ? `{ ${fields.join(', ')} }` : '{}';
+  // Precedence, lowest → highest: spec defaults → baked publisher setup → app `configure()`.
+  // The inner merge flattens the setup into a ClientConfig; the outer layers it OVER the
+  // spec defaults (mergeSetup's second argument wins per-field; middleware composes).
+  const configArg = options.setup
+    ? `mergeSetup({ config: ${config} }, mergeSetup(__redoclySetup, {}))`
+    : config;
+  // The trailing type args narrow `ctx.operation` to the spec's literal unions.
+  // `OperationTag` mirrors descriptorStatements' gate: derived only when some
+  // operation is tagged (it would otherwise be `never`); zero-ops specs have no
+  // derived unions at all, so they keep the string defaults.
+  const ops = allOperations(model.services);
+  const hasTags = ops.some((op) => op.tags.length > 0);
+  const typeArgs =
+    ops.length > 0
+      ? `<Ops, OperationId, OperationPath, ${hasTags ? 'OperationTag' : 'string'}>`
+      : '<Ops>';
+  const client = `export const client = createClient${typeArgs}(OPERATIONS, ${configArg});`;
+  if (!options.setup) return client;
+  return (
+    '// ─── Baked-in setup (--setup) ───\n' +
+    `const __redoclySetup: { config?: ClientConfig; middleware?: Middleware[] } = ${options.setup};\n` +
+    client
+  );
+}
+
+/** Core destructure + per-scheme auth setters + per-operation call sugar. */
+function sugarStatements(
+  ops: OperationModel[],
+  idents: Map<string, string>,
+  ctx: EmitContext,
+  schemes: SecuritySchemeModel[],
+  apiKeySchemes: SecuritySchemeModel[]
+): ts.Statement[] {
+  const statements = [...parseStatements('export const { configure, use } = client;')];
+  // Auth sugar in `authSetterNames` order: bearer, basic, then each apiKey scheme.
+  // The runtime's auth members close over the instance config (no `this`), so
+  // direct bindings are safe.
+  if (schemes.some((s) => s.kind === 'bearer')) {
+    statements.push(...parseStatements('export const setBearer = client.auth.bearer;'));
+  }
+  if (schemes.some((s) => s.kind === 'basic')) {
+    statements.push(...parseStatements('export const setBasicAuth = client.auth.basic;'));
+  }
+  for (const scheme of apiKeySchemes) {
+    const name = apiKeySetterName(scheme.key, apiKeySchemes.length === 1);
+    statements.push(
+      ...parseStatements(
+        `export const ${name} = (value: TokenProvider) => client.auth.apiKey(${codeString(scheme.key)}, value);`
+      )
+    );
+  }
+  if (ops.length === 0) return statements;
+  if (ctx.argsStyle === 'grouped') {
+    // Grouped style: the client methods already take the grouped args shape.
+    const names = ops.map((op) => idents.get(op.name)!).join(', ');
+    statements.push(...parseStatements(`export const { ${names} } = client;`));
+    return statements;
+  }
+  for (const op of ops) statements.push(flatSugarStatement(op, idents.get(op.name)!, ctx));
+  return statements;
+}
+
+/**
+ * One flat one-liner: today's positional signature forwarding to the grouped client
+ * method. Path values are keyed by the WIRE name (the runtime routes
+ * `args[param.name]`); a path param literally named `params`/`body`/`headers` would
+ * collide with the slot keys — a spec-acknowledged runtime-contract limitation.
+ * A paginated operation's arrow is wrapped in `Object.assign(…, { pages, items })`
+ * so the flat sugar preserves the method-attached iterators.
+ */
+function flatSugarStatement(op: OperationModel, ident: string, ctx: EmitContext): ts.Statement {
+  const { pathParams } = operationSignature(op);
+  const params = renderArgList(
+    op,
+    pathParams.map((p) => p.param),
+    new Map(pathParams.map((p) => [p.param.name, p.ident])),
+    ctx
+  );
+  const props: ts.ObjectLiteralElementLike[] = pathParams.map(({ param, ident: paramIdent }) =>
+    param.name === paramIdent
+      ? factory.createShorthandPropertyAssignment(paramIdent)
+      : factory.createPropertyAssignment(
+          isIdentifier(param.name) ? param.name : factory.createStringLiteral(param.name),
+          factory.createIdentifier(paramIdent)
+        )
+  );
+  if (op.queryParams.length > 0) props.push(factory.createShorthandPropertyAssignment('params'));
+  if (op.requestBody) props.push(factory.createShorthandPropertyAssignment('body'));
+  if (op.headerParams.length > 0) {
+    props.push(factory.createShorthandPropertyAssignment('headers'));
+  }
+  if (op.cookieParams.length > 0) {
+    props.push(factory.createShorthandPropertyAssignment('cookies'));
+  }
+  const call = factory.createCallExpression(
+    factory.createPropertyAccessExpression(factory.createIdentifier('client'), ident),
+    undefined,
+    [factory.createObjectLiteralExpression(props, false), factory.createIdentifier('init')]
+  );
+  const fn = arrow(params, call);
+  if (!ctx.pagination?.has(op.name)) return exportConstStatement(ident, fn);
+  const methodMember = (name: string) =>
+    factory.createPropertyAssignment(
+      name,
+      factory.createPropertyAccessExpression(
+        factory.createPropertyAccessExpression(factory.createIdentifier('client'), ident),
+        name
+      )
+    );
+  return exportConstStatement(
+    ident,
+    factory.createCallExpression(
+      factory.createPropertyAccessExpression(factory.createIdentifier('Object'), 'assign'),
+      undefined,
+      [
+        fn,
+        factory.createObjectLiteralExpression(
+          [methodMember('pages'), methodMember('items')],
+          false
+        ),
+      ]
+    )
+  );
+}
+
+/** Public type surface re-exported for single-import DX (plus the `ApiError` class). */
+function reexportLines(ctx: EmitContext, hasSse: boolean): string {
+  const types = [
+    'ClientConfig',
+    'Middleware',
+    'RequestOptions',
+    ...(ctx.errorMode === 'result' ? ['Result'] : []),
+    ...(hasSse ? ['ServerSentEvent', 'SseOptions'] : []),
+  ].sort();
+  return (
+    // `createClient` is re-exported so package-mode consumers can build additional
+    // instances from the generated module alone — symmetric with inline output.
+    `export { ApiError, createClient } from '${PACKAGE_SPECIFIER}';\n` +
+    `export type { ${types.join(', ')} } from '${PACKAGE_SPECIFIER}';`
+  );
+}
diff --git a/packages/client-generator/src/emitters/descriptor.ts b/packages/client-generator/src/emitters/descriptor.ts
new file mode 100644
index 0000000000..f517c6ee69
--- /dev/null
+++ b/packages/client-generator/src/emitters/descriptor.ts
@@ -0,0 +1,296 @@
+// Package-mode descriptor emission: the identifier plan for a generated module that
+// shares scope with the `@redocly/client-generator` wiring, plus the `OPERATIONS`
+// descriptor map (`satisfies Record<string, OperationDescriptor>` — the semver skew
+// guard against the runtime contract in src/runtime/types.ts).
+
+import {
+  allOperations,
+  type ApiModel,
+  type OperationModel,
+  type SecuritySchemeModel,
+} from '../intermediate-representation/model.js';
+import type { SecuritySpec } from '../runtime/types.js';
+import { authSetterNames } from './auth.js';
+import { uniqueIdent } from './identifier.js';
+import { variablesTypeLiteral } from './operation-aliases.js';
+import { operationSignature } from './operation-signature.js';
+import { computeResponse, errorTypeNodes, isTypedMultipart } from './operation-types.js';
+import type { EmitContext } from './operations.js';
+import type { ModelPagination } from './pagination.js';
+import { isSseOp, sseDataKind, sseEventType } from './sse.js';
+import { pascalCase } from './support.js';
+import { jsdoc, literalExpression, parseStatements, ts } from './ts.js';
+import { type DateType, schemaToTypeNode } from './types.js';
+
+const { factory } = ts;
+
+/** Module-scope identifiers every package-mode file emits or imports — never renamed. */
+const WIRING_NAMES = [
+  'client',
+  'OPERATIONS',
+  'Ops',
+  'OperationId',
+  'OperationPath',
+  'OperationTag',
+  'createClient',
+  'mergeSetup',
+  'ApiError',
+  'configure',
+  'use',
+  'auth',
+  'ClientConfig',
+  'RequestOptions',
+  'SseOptions',
+  'Middleware',
+  'OperationDescriptor',
+  'ServerSentEvent',
+  'Result',
+  'TokenProvider',
+  '__redoclySetup',
+];
+
+/**
+ * Operation-name → emitted-identifier plan. The full reserved set (wiring + imported
+ * bindings + auth sugar, computed from the model FIRST) is seeded before any operation
+ * is sanitized, so collisions rename the operation (`configure` → `configure_2`)
+ * deterministically regardless of document order.
+ */
+export function packageIdents(model: ApiModel): Map<string, string> {
+  const used = new Set<string>([...WIRING_NAMES, ...authSetterNames(model.securitySchemes)]);
+  const idents = new Map<string, string>();
+  for (const op of allOperations(model.services)) idents.set(op.name, uniqueIdent(op.name, used));
+  return idents;
+}
+
+/** One operation's OperationDescriptor as plain data (only non-default fields present). */
+function descriptorValue(
+  op: OperationModel,
+  schemes: SecuritySchemeModel[],
+  dateType: DateType,
+  pagination?: ModelPagination
+) {
+  const params = [...op.pathParams, ...op.queryParams, ...op.headerParams, ...op.cookieParams].map(
+    (p) => ({
+      name: p.name,
+      in: p.in,
+      ...(p.style !== undefined ? { style: p.style } : {}),
+      ...(p.explode !== undefined ? { explode: p.explode } : {}),
+      ...(p.allowReserved !== undefined ? { allowReserved: p.allowReserved } : {}),
+    })
+  );
+  const toSpecs = (key: string): SecuritySpec[] => {
+    const s = schemes.find((scheme) => scheme.key === key);
+    if (!s) return [];
+    if (s.kind === 'bearer' || s.kind === 'basic') return [{ scheme: key, kind: s.kind }];
+    if (s.kind === 'apiKeyHeader') {
+      return [{ scheme: key, kind: 'apiKey', name: s.headerName, in: 'header' }];
+    }
+    if (s.kind === 'apiKeyQuery') {
+      return [{ scheme: key, kind: 'apiKey', name: s.paramName, in: 'query' }];
+    }
+    return [{ scheme: key, kind: 'apiKey', name: s.cookieName, in: 'cookie' }];
+  };
+  const security = op.security
+    .map((alternative) => alternative.flatMap(toSpecs))
+    .filter((alternative) => alternative.length > 0);
+  const sse = isSseOp(op);
+  const responseKind = sse ? 'sse' : computeResponse(op.successResponses, dateType).responseKind;
+  return {
+    // The spec's operationId, NOT the (possibly renamed) map key: `id` drives middleware
+    // targeting (`ctx.operation.id`) and must match inline mode's `operationMetaExpr`.
+    id: op.name,
+    method: op.method.toUpperCase(),
+    path: op.path,
+    ...(op.tags.length > 0 ? { tags: op.tags } : {}),
+    ...(params.length > 0 ? { params } : {}),
+    ...(op.requestBody
+      ? {
+          body: {
+            contentType: op.requestBody.contentType,
+            ...(isTypedMultipart(op.requestBody) ? { multipart: true } : {}),
+          },
+        }
+      : {}),
+    ...(responseKind !== 'json' ? { responseKind } : {}),
+    ...(sse ? { sseDataKind: sseDataKind(op) } : {}),
+    ...(security.length > 0 ? { security } : {}),
+    // The resolved spec is already normalized with stable key order (see pagination.ts).
+    ...(pagination?.has(op.name) ? { pagination: pagination.get(op.name)!.spec } : {}),
+  };
+}
+
+/** `export const OPERATIONS = {…} as const satisfies Record<string, OperationDescriptor>;` + unions. */
+export function descriptorStatements(
+  model: ApiModel,
+  idents: Map<string, string>,
+  dateType: DateType,
+  pagination?: ModelPagination
+): ts.Statement[] {
+  const ops = allOperations(model.services);
+  if (ops.length === 0) return [];
+  const entries = ops.map((op) =>
+    factory.createPropertyAssignment(
+      idents.get(op.name)!,
+      literalExpression(descriptorValue(op, model.securitySchemes, dateType, pagination))
+    )
+  );
+  const operations = jsdoc(
+    factory.createVariableStatement(
+      [factory.createModifier(ts.SyntaxKind.ExportKeyword)],
+      factory.createVariableDeclarationList(
+        [
+          factory.createVariableDeclaration(
+            'OPERATIONS',
+            undefined,
+            undefined,
+            factory.createSatisfiesExpression(
+              factory.createAsExpression(
+                factory.createObjectLiteralExpression(entries, true),
+                factory.createTypeReferenceNode('const')
+              ),
+              factory.createTypeReferenceNode('Record', [
+                factory.createKeywordTypeNode(ts.SyntaxKind.StringKeyword),
+                factory.createTypeReferenceNode('OperationDescriptor'),
+              ])
+            )
+          ),
+        ],
+        ts.NodeFlags.Const
+      )
+    ),
+    'The wire-shape descriptor for every operation, keyed by operationId — the data the\n' +
+      'runtime routes requests by. Also minification-safe static metadata (method, path,\n' +
+      'tags) for cache keys, tracing span names, and request logging.'
+  );
+  // `tags` is present only on tagged entries, so `OperationTag` is derived via `Extract`
+  // (a plain `["tags"]` index would not compile against the untagged entries), and is
+  // omitted entirely when no operation has a tag (it would be `never`).
+  const hasTags = ops.some((op) => op.tags.length > 0);
+  const derived = parseStatements(
+    'export type OperationId = keyof typeof OPERATIONS;\n' +
+      'export type OperationPath = (typeof OPERATIONS)[OperationId]["path"];' +
+      (hasTags
+        ? '\nexport type OperationTag = Extract<(typeof OPERATIONS)[OperationId], { tags: readonly string[] }>["tags"][number];'
+        : '')
+  );
+  return [operations, ...derived];
+}
+
+/**
+ * `export type Ops = { <ident>: { args: …; result: …; kind?: "sse" } }` — the type map
+ * `createClient<Ops>` consumes. A type alias (not an interface) on purpose: aliases get
+ * an implicit index signature, so `Ops` satisfies the runtime's `OpsShape` constraint;
+ * an interface would need an explicit `[key: string]` member.
+ */
+export function opsInterfaceStatements(
+  model: ApiModel,
+  idents: Map<string, string>,
+  ctx: EmitContext
+): ts.Statement[] {
+  const ops = allOperations(model.services);
+  if (ops.length === 0) return [];
+  return [
+    jsdoc(
+      factory.createTypeAliasDeclaration(
+        [factory.createModifier(ts.SyntaxKind.ExportKeyword)],
+        'Ops',
+        undefined,
+        factory.createTypeLiteralNode(ops.map((op) => opsMember(op, idents.get(op.name)!, ctx)))
+      ),
+      "Per-operation `args`/`result` shapes (plus `kind: 'sse'` for event streams) — the\n" +
+        'type-level companion of `OPERATIONS` that gives `createClient<Ops>` its typed methods.'
+    ),
+  ];
+}
+
+/** One `<ident>: { args; result; kind? }` member of the `Ops` type. */
+function opsMember(op: OperationModel, ident: string, ctx: EmitContext): ts.PropertySignature {
+  const { pathParams } = operationSignature(op);
+  // Path params are keyed by WIRE name — the runtime routes `args[param.name]`.
+  const args = variablesTypeLiteral(
+    op,
+    pascalCase(op.name),
+    pathParams.map((p) => p.param),
+    new Map(pathParams.map((p) => [p.param.name, p.ident])),
+    ctx,
+    'wire'
+  );
+  const members = [
+    factory.createPropertySignature(undefined, 'args', undefined, args),
+    factory.createPropertySignature(undefined, 'result', undefined, resultType(op, ctx)),
+  ];
+  // Paginated operations declare the page's element type — it drives the runtime's
+  // `.pages()`/`.items()` members on the method (`Client<Ops>` keys off `item`).
+  const paginated = ctx.pagination?.get(op.name);
+  if (paginated) {
+    members.push(
+      factory.createPropertySignature(
+        undefined,
+        'item',
+        undefined,
+        schemaToTypeNode(paginated.itemSchema, ctx.dateType)
+      )
+    );
+    // Result mode wraps `result` in the envelope, but iteration unwraps it — `page`
+    // carries the RAW page type `.pages()` yields. Throw mode emits no `page` member
+    // (`Client<Ops>`'s pages-generator falls back to `result`, already the raw page).
+    if (ctx.errorMode === 'result') {
+      members.push(
+        factory.createPropertySignature(undefined, 'page', undefined, rawResultRef(op, ctx))
+      );
+    }
+  }
+  if (isSseOp(op)) {
+    members.push(
+      factory.createPropertySignature(
+        undefined,
+        'kind',
+        undefined,
+        factory.createLiteralTypeNode(factory.createStringLiteral('sse'))
+      )
+    );
+  }
+  return factory.createPropertySignature(
+    undefined,
+    ident,
+    undefined,
+    factory.createTypeLiteralNode(members)
+  );
+}
+
+/**
+ * The raw success-response reference — the same suppression rule as
+ * renderOperationParts: the emitted `<Op>Result` alias, or the inline response type
+ * when that name collides with a schema.
+ */
+function rawResultRef(op: OperationModel, ctx: EmitContext): ts.TypeNode {
+  const { responseType } = computeResponse(op.successResponses, ctx.dateType);
+  const resultName = `${pascalCase(op.name)}Result`;
+  return ctx.schemaNames.has(resultName)
+    ? responseType
+    : factory.createTypeReferenceNode(resultName);
+}
+
+/** The `result` slot: SSE event payload, or the response type — `Result`-wrapped in result mode. */
+function resultType(op: OperationModel, ctx: EmitContext): ts.TypeNode {
+  if (isSseOp(op)) return sseEventType(op, ctx.dateType);
+  const resultRef = rawResultRef(op, ctx);
+  if (ctx.errorMode !== 'result') return resultRef;
+  return factory.createTypeReferenceNode('Result', [resultRef, errorTypeArg(op, ctx)]);
+}
+
+/**
+ * The `Result<…, E>` error argument — the same composition `renderOperationParts` uses for
+ * `__requestResult<R, E>`: `unknown` when the operation declares no error responses, the
+ * emitted `<Op>Error` alias otherwise, or the inline (union of) error type(s) when that
+ * alias name collides with a schema and is suppressed.
+ */
+function errorTypeArg(op: OperationModel, ctx: EmitContext): ts.TypeNode {
+  const errorMembers = errorTypeNodes(op.errorResponses, ctx.dateType);
+  if (errorMembers.length === 0) {
+    return factory.createKeywordTypeNode(ts.SyntaxKind.UnknownKeyword);
+  }
+  const errorAlias = `${pascalCase(op.name)}Error`;
+  if (!ctx.schemaNames.has(errorAlias)) return factory.createTypeReferenceNode(errorAlias);
+  return errorMembers.length === 1 ? errorMembers[0] : factory.createUnionTypeNode(errorMembers);
+}
diff --git a/packages/client-generator/src/emitters/emit-options.ts b/packages/client-generator/src/emitters/emit-options.ts
new file mode 100644
index 0000000000..eda07c5d45
--- /dev/null
+++ b/packages/client-generator/src/emitters/emit-options.ts
@@ -0,0 +1,101 @@
+import type { ApiModel } from '../intermediate-representation/model.js';
+import type { ArgsStyle } from './operations.js';
+import type { PaginationConfig } from './pagination.js';
+import { splitLines } from './support.js';
+import { escapeJsDoc } from './ts.js';
+import type { DateType, EnumStyle } from './types.js';
+
+// The public option vocabulary is re-exported from this module, so generators
+// and the package barrel import the emitter surface from one place.
+export type { ArgsStyle } from './operations.js';
+
+/** The generated-by banner prepended to every emitted module. */
+export const HEADER = `// Generated by @redocly/client-generator — do not edit by hand.
+// Source: OpenAPI document. Re-run \`redocly generate-client\` to update.`;
+
+export type EmitOptions = {
+  /**
+   * Override the server URL baked into the generated client config. When omitted,
+   * the value is derived from `servers[0].url` in the source OpenAPI document.
+   */
+  serverUrl?: string;
+  /**
+   * How named string enums are emitted:
+   * - `'union'`: only the string-literal union type (`type X = "a" | "b"`).
+   * - `'const-object'` (default): the union type *and* a sibling
+   *   `export const X = { a: "a", b: "b" } as const;` so callers can reference
+   *   the values at runtime (`X.a`).
+   */
+  enumStyle?: EnumStyle;
+  /**
+   * How operation inputs are passed to each call. Defaults to `'flat'`;
+   * `'grouped'` bundles inputs into a single `args` object.
+   */
+  argsStyle?: ArgsStyle;
+  /** Error-handling shape of the generated client. Defaults to `'throw'`. */
+  errorMode?: 'throw' | 'result';
+  /**
+   * How `format: date-time`/`date` string fields are typed. `'string'` (default)
+   * keeps the ISO wire shape; `'Date'` emits a `Date` reference. Opt-in — pair with
+   * the `transformers` generator so the runtime value matches the type.
+   */
+  dateType?: DateType;
+  /**
+   * TanStack Query adapter the generated module imports from
+   * (`@tanstack/${queryFramework}-query`). Defaults to `'react'`; the emitted body
+   * is byte-identical across frameworks — only the import specifier changes.
+   */
+  queryFramework?: 'react' | 'vue' | 'svelte' | 'solid';
+  /**
+   * How the `mock` generator produces data. `'baked'` (default) inlines deterministic
+   * literals (zero-dep, contract-faithful); `'faker'` emits `@faker-js/faker` calls for
+   * realistic data — reproducible when `mockSeed` is set. Only the mock module is affected.
+   */
+  mockData?: 'baked' | 'faker';
+  /** Seed for faker-mode mocks: emits a top-level `faker.seed(<n>)` so runs reproduce. */
+  mockSeed?: number;
+  /**
+   * A pre-baked publisher setup block (from `bakeSetup`) merged into the client's config
+   * via `mergeSetup`. Absent when no `--setup` is given.
+   */
+  setup?: string;
+  /** Runtime distribution: 'inline' (default, self-contained) | 'package' (imports @redocly/client-generator). */
+  runtime?: 'inline' | 'package';
+  /**
+   * Extension used in generated relative import specifiers (the split entry's schemas
+   * re-export and each satellite's sdk import). `'js'` (default) is the tsc/bundler
+   * convention; `'ts'` targets runtimes that resolve specifiers literally, like Node's
+   * built-in type stripping (`node client.ts`).
+   */
+  importExt?: 'js' | 'ts';
+  /**
+   * Auto-pagination rules (a convention rule + per-operation overrides + `exclude`),
+   * resolved together with each operation's `x-pagination` extension. Verified
+   * statically: an explicit rule that doesn't fit its operation fails generation.
+   */
+  pagination?: PaginationConfig;
+};
+
+/**
+ * Assemble file content from a header banner and a printed body: the leading
+ * `// Generated by …` comment and the `/** title *​/` block are structural
+ * banners (not part of the printed AST), prepended with blank-line separation.
+ * Trailing newline mirrors a hand-authored file.
+ */
+export function banner(sections: string[]): string {
+  return sections.filter((s) => s.length > 0).join('\n\n') + '\n';
+}
+
+export function renderTitleComment(model: ApiModel): string {
+  // This banner is a raw string (it does not flow through `jsdoc()`), so escape
+  // `*/` here too — `info.title`/`info.description` are attacker-controllable and
+  // would otherwise close the comment and inject code at the top of every file.
+  const lines = [`/**`, ` * ${escapeJsDoc(`${model.title} (v${model.version})`)}`];
+  if (model.description) {
+    for (const line of splitLines(escapeJsDoc(model.description))) {
+      lines.push(` * ${line}`);
+    }
+  }
+  lines.push(' */');
+  return lines.join('\n');
+}
diff --git a/packages/client-generator/src/emitters/faker.ts b/packages/client-generator/src/emitters/faker.ts
new file mode 100644
index 0000000000..f290caa2e0
--- /dev/null
+++ b/packages/client-generator/src/emitters/faker.ts
@@ -0,0 +1,260 @@
+// Builds the body expression for a faker-mode mock factory: a tree of
+// `@faker-js/faker` call expressions that produce realistic — and, with a seed,
+// reproducible — data. Structurally mirrors `emitters/sample.ts`'s `walk` (same
+// recursion + same visited-set cycle guard), but returns a `ts.Expression` of
+// faker calls instead of a baked value. Nested refs are INLINED under the same
+// cycle guard (never `create<Ref>()` calls), so a cyclic schema terminates with
+// `null` at the cycle instead of recursing forever at runtime — exactly like the
+// baked path. The factory signatures are identical to the baked mode's, so a
+// consumer can flip `mockData` without touching call sites; `@faker-js/faker`
+// becomes their dev-dep while the real client stays dependency-free.
+
+import type {
+  NamedSchemaModel,
+  ScalarKind,
+  SchemaMetadata,
+  SchemaModel,
+} from '../intermediate-representation/model.js';
+import { safeIdent } from './identifier.js';
+import { constArray, literalExpression, ts } from './ts.js';
+import type { DateType } from './types.js';
+
+const { factory } = ts;
+
+/** The faker-call expression for an IR schema. Refs resolve against `schemas`;
+ *  recursion is cut with a visited-set (`null` at the cycle). `dateType` mirrors
+ *  the sdk's `--date-type`: under `'Date'`, date fields stay `faker.date.recent()`
+ *  (a `Date`); otherwise they are stringified to match the `string`-typed sdk. */
+export function fakerExpression(
+  schema: SchemaModel,
+  schemas: NamedSchemaModel[],
+  opts: { dateType?: DateType } = {}
+): ts.Expression {
+  const byName = new Map(schemas.map((s) => [s.name, s.schema]));
+  const expr = walk(schema, byName, new Set(), opts.dateType ?? 'string');
+  // A `CYCLE` that reaches the root has no container to absorb it (e.g. a
+  // self-referential union); fall back to null.
+  return expr === CYCLE ? factory.createNull() : expr;
+}
+
+/**
+ * Sentinel returned by `walk` when a `$ref` re-enters a name already on the stack.
+ * Containers turn it into the type-correct empty value for their position — an array
+ * to `[]`, a record to `{}`, an optional property to omission — mirroring `emitters/sample.ts`
+ * so a recursive schema yields a faker tree that still satisfies its non-nullable type.
+ * Only a required, non-container self-reference (an uninhabitable schema) degrades to null.
+ */
+const CYCLE = Symbol('cycle');
+
+type WalkResult = ts.Expression | typeof CYCLE;
+
+function walk(
+  schema: SchemaModel,
+  byName: Map<string, SchemaModel>,
+  visiting: Set<string>,
+  dateType: DateType
+): WalkResult {
+  switch (schema.kind) {
+    case 'scalar':
+      return scalarExpr(schema.scalar, schema.metadata, dateType);
+    case 'array': {
+      // A cyclic item type collapses the array to `[]` — itself a valid `T[]`.
+      const item = walk(schema.items, byName, visiting, dateType);
+      return item === CYCLE ? factory.createArrayLiteralExpression([], false) : multiple(item);
+    }
+    case 'object':
+      return objectExpr(
+        schema.properties.flatMap((p): Array<[string, ts.Expression]> => {
+          const value = walk(p.schema, byName, visiting, dateType);
+          // A cyclic optional property is omitted; a cyclic required property is
+          // uninhabitable, so null is the only stand-in.
+          if (value === CYCLE) return p.required ? [[p.name, factory.createNull()]] : [];
+          return [[p.name, value]];
+        })
+      );
+    case 'record': {
+      const value = walk(schema.value, byName, visiting, dateType);
+      return value === CYCLE
+        ? factory.createObjectLiteralExpression([], false)
+        : objectExpr([['key', value]]);
+    }
+    case 'enum':
+      return call('faker.helpers.arrayElement', [constArray(schema.values.map(literalExpression))]);
+    case 'literal':
+      return literalExpression(schema.value);
+    case 'union': {
+      // First non-cyclic member; if every member cycles, propagate `CYCLE`.
+      for (const member of schema.members) {
+        const value = walk(member, byName, visiting, dateType);
+        if (value !== CYCLE) return value;
+      }
+      return schema.members.length > 0 ? CYCLE : factory.createNull();
+    }
+    case 'intersection':
+      return factory.createObjectLiteralExpression(
+        schema.members.flatMap((m) => {
+          const part = walk(m, byName, visiting, dateType);
+          return part !== CYCLE && ts.isObjectLiteralExpression(part) ? assignments(part) : [];
+        }),
+        true
+      );
+    case 'omit':
+      return omitExpr(schema.base, schema.keys, byName, visiting, dateType);
+    case 'ref': {
+      if (visiting.has(schema.name)) return CYCLE;
+      const target = byName.get(schema.name);
+      if (!target) return factory.createNull();
+      visiting.add(schema.name);
+      const result = walk(target, byName, visiting, dateType);
+      visiting.delete(schema.name);
+      return result;
+    }
+    case 'null':
+    case 'unknown':
+      return factory.createNull();
+  }
+}
+
+/** The faker call for a scalar, keyed by kind then `format`. A binary field has no
+ *  faker generator (its type is `Blob`), so it emits `new Blob([])` — the same
+ *  type-demanded expression the baked path uses, taking precedence over any example. */
+function scalarExpr(
+  scalar: ScalarKind,
+  meta: SchemaMetadata | undefined,
+  dateType: DateType
+): ts.Expression {
+  if (meta?.format === 'binary') return newBlob();
+  if (scalar === 'boolean') return call('faker.datatype.boolean', []);
+  if (scalar === 'integer') return call('faker.number.int', boundsArg(meta));
+  if (scalar === 'number') return call('faker.number.float', boundsArg(meta));
+  switch (meta?.format) {
+    case 'email':
+      return call('faker.internet.email', []);
+    case 'uuid':
+      return call('faker.string.uuid', []);
+    case 'uri':
+    case 'url':
+      return call('faker.internet.url', []);
+    case 'hostname':
+      return call('faker.internet.domainName', []);
+    case 'ipv4':
+      return call('faker.internet.ipv4', []);
+    case 'date-time':
+      return dateExpr(dateType, false);
+    case 'date':
+      return dateExpr(dateType, true);
+    default:
+      return call('faker.lorem.word', []);
+  }
+}
+
+/** `faker.date.recent()` (under `dateType: 'Date'`); else its ISO string, sliced to
+ *  `YYYY-MM-DD` for a `date` so the wire shape matches the `string`-typed field. */
+function dateExpr(dateType: DateType, dateOnly: boolean): ts.Expression {
+  const recent = call('faker.date.recent', []);
+  if (dateType === 'Date') return recent;
+  const iso = call(member(recent, 'toISOString'), []);
+  if (!dateOnly) return iso;
+  return call(member(iso, 'slice'), [
+    factory.createNumericLiteral(0),
+    factory.createNumericLiteral(10),
+  ]);
+}
+
+/** `{ min, max }` arg list for a bounded numeric, or no args when neither bound is set. */
+function boundsArg(meta: SchemaMetadata | undefined): ts.Expression[] {
+  const props: ts.PropertyAssignment[] = [];
+  if (meta?.minimum !== undefined) {
+    props.push(factory.createPropertyAssignment('min', literalExpression(meta.minimum)));
+  }
+  if (meta?.maximum !== undefined) {
+    props.push(factory.createPropertyAssignment('max', literalExpression(meta.maximum)));
+  }
+  return props.length > 0 ? [factory.createObjectLiteralExpression(props, false)] : [];
+}
+
+/** `faker.helpers.multiple(() => <item>, { count: 1 })` — one element keeps output small. */
+function multiple(item: ts.Expression): ts.Expression {
+  const fn = factory.createArrowFunction(
+    undefined,
+    undefined,
+    [],
+    undefined,
+    factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken),
+    item
+  );
+  const count = factory.createObjectLiteralExpression(
+    [factory.createPropertyAssignment('count', factory.createNumericLiteral(1))],
+    false
+  );
+  return call('faker.helpers.multiple', [fn, count]);
+}
+
+/** An `omit`: the base named schema's faker expr minus the dropped keys. Resolves the
+ *  base via the schema set (cycle-guarded); a non-object base passes through unchanged. */
+function omitExpr(
+  base: string,
+  keys: string[],
+  byName: Map<string, SchemaModel>,
+  visiting: Set<string>,
+  dateType: DateType
+): WalkResult {
+  const target = byName.get(base);
+  if (!target) return factory.createNull();
+  const expr = walk(target, byName, visiting, dateType);
+  // A cyclic or non-object base passes through unchanged (a container/root absorbs `CYCLE`).
+  if (expr === CYCLE || !ts.isObjectLiteralExpression(expr)) return expr;
+  const drop = new Set(keys.map(safeIdent));
+  return factory.createObjectLiteralExpression(
+    assignments(expr).filter((a) => !drop.has(propKey(a))),
+    true
+  );
+}
+
+/** An object literal from `[key, expr]` entries; keys are quoted when not bare identifiers. */
+function objectExpr(entries: Array<[string, ts.Expression]>): ts.Expression {
+  return factory.createObjectLiteralExpression(
+    entries.map(([key, value]) => {
+      const safe = safeIdent(key);
+      const name = safe === key ? factory.createIdentifier(key) : factory.createStringLiteral(key);
+      return factory.createPropertyAssignment(name, value);
+    }),
+    true
+  );
+}
+
+/** The property assignments of an object literal (the spread/intersection merge unit). */
+function assignments(object: ts.ObjectLiteralExpression): ts.PropertyAssignment[] {
+  return object.properties.filter((p): p is ts.PropertyAssignment => ts.isPropertyAssignment(p));
+}
+
+/** The printed key text of a property assignment (matching `safeIdent`'s quoting). */
+function propKey(a: ts.PropertyAssignment): string {
+  return ts.isStringLiteral(a.name) ? safeIdent(a.name.text) : (a.name as ts.Identifier).text;
+}
+
+/** `new Blob([])` — the type-correct stand-in for a `format: binary` field. */
+function newBlob(): ts.Expression {
+  return factory.createNewExpression(factory.createIdentifier('Blob'), undefined, [
+    factory.createArrayLiteralExpression([], false),
+  ]);
+}
+
+/** A call expression from a dotted callee name (`faker.number.int`) or a built node. */
+function call(callee: string | ts.Expression, args: ts.Expression[]): ts.CallExpression {
+  const target = typeof callee === 'string' ? dotted(callee) : callee;
+  return factory.createCallExpression(target, undefined, args);
+}
+
+/** Turn `a.b.c` into nested property access on an identifier. */
+function dotted(path: string): ts.Expression {
+  const [head, ...rest] = path.split('.');
+  return rest.reduce<ts.Expression>(
+    (acc, name) => member(acc, name),
+    factory.createIdentifier(head)
+  );
+}
+
+function member(target: ts.Expression, name: string): ts.PropertyAccessExpression {
+  return factory.createPropertyAccessExpression(target, name);
+}
diff --git a/packages/client-generator/src/emitters/identifier.ts b/packages/client-generator/src/emitters/identifier.ts
new file mode 100644
index 0000000000..956129d3e1
--- /dev/null
+++ b/packages/client-generator/src/emitters/identifier.ts
@@ -0,0 +1,98 @@
+// Identifier sanitization — mapping OpenAPI names (which may contain `-`, `.`,
+// spaces, or be reserved words) onto valid TypeScript identifiers. Pure string
+// logic with no dependency on the IR or other emitters.
+
+/** Matches a string that is already a valid JS identifier (ignoring reserved words). */
+const IDENT_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+const TS_RESERVED = new Set([
+  'break',
+  'case',
+  'catch',
+  'class',
+  'const',
+  'continue',
+  'debugger',
+  'default',
+  'delete',
+  'do',
+  'else',
+  'enum',
+  'export',
+  'extends',
+  'false',
+  'finally',
+  'for',
+  'function',
+  'if',
+  'import',
+  'in',
+  'instanceof',
+  'new',
+  'null',
+  'return',
+  'super',
+  'switch',
+  'this',
+  'throw',
+  'true',
+  'try',
+  'typeof',
+  'var',
+  'void',
+  'while',
+  'with',
+  'yield',
+]);
+
+/** True when `name` matches the JS identifier grammar (reserved words still pass). */
+export function isIdentifier(name: string): boolean {
+  return IDENT_RE.test(name);
+}
+
+/** True when `name` is a valid JS identifier AND not a reserved word — safe as a binding name. */
+export function isSafeIdentifier(name: string): boolean {
+  return IDENT_RE.test(name) && !TS_RESERVED.has(name);
+}
+
+/**
+ * Coerce an arbitrary spec-supplied name into a valid, non-reserved JS identifier
+ * (no uniqueness guarantee — see `uniqueIdent`). Non-identifier characters become
+ * `_`; an empty result, a leading digit, or a reserved word is prefixed with `_`.
+ * This is the security boundary for any name that lands in a declaration slot —
+ * `ts.factory.createIdentifier` prints its text verbatim, so an unsanitized name
+ * like `foo(){};evil()` would emit as executable code.
+ */
+export function sanitizeIdentifier(name: string): string {
+  let base = name.replace(/[^A-Za-z0-9_$]/g, '_');
+  if (base === '' || /^[0-9]/.test(base) || TS_RESERVED.has(base)) base = `_${base}`;
+  return base;
+}
+
+/**
+ * Render `name` as an object key or property name: bare when it is a valid,
+ * non-reserved identifier, quoted otherwise. Safe only where quoting is legal
+ * (object keys, property signatures) — not for binding names; use `uniqueIdent`
+ * there.
+ */
+export function safeIdent(name: string): string {
+  if (IDENT_RE.test(name) && !TS_RESERVED.has(name)) {
+    return name;
+  }
+  return JSON.stringify(name);
+}
+
+/**
+ * `sanitizeIdentifier(name)` made unique within `used` (which it mutates):
+ * collisions get a `_2`, `_3`, … suffix. Used wherever a name lands in a binding
+ * slot that — unlike an object key — cannot be quoted (function/type/parameter
+ * names), so `safeIdent`'s quote-on-failure fallback would not compile.
+ */
+export function uniqueIdent(name: string, used: Set<string>): string {
+  const base = sanitizeIdentifier(name);
+  let ident = base;
+  let n = 2;
+  while (used.has(ident)) ident = `${base}_${n++}`;
+  used.add(ident);
+  return ident;
+}
diff --git a/packages/client-generator/src/emitters/inline-runtime.ts b/packages/client-generator/src/emitters/inline-runtime.ts
new file mode 100644
index 0000000000..6ac919a54d
--- /dev/null
+++ b/packages/client-generator/src/emitters/inline-runtime.ts
@@ -0,0 +1,105 @@
+// Assembles the embedded runtime block for inline-mode clients: the real
+// `src/runtime/` sources (snapshotted into `RUNTIME_SOURCES`) in import-graph
+// order, stripped of module syntax, followed by a local `createClient` factory
+// wiring only the capabilities this API needs — the embedded equivalent of the
+// package barrel (`runtime/index.ts`), which is never embedded itself.
+
+import { RUNTIME_SOURCES, type RuntimeModuleName } from './runtime-sources.js';
+import { parseStatements, ts } from './ts.js';
+
+/** Which optional runtime capabilities the generated client must embed. */
+export type InlineRuntimeNeeds = {
+  multipart: boolean;
+  auth: boolean;
+  sse: boolean;
+  setup: boolean;
+  paginate: boolean;
+};
+
+const HEADER =
+  "// ─── Embedded runtime (@redocly/client-generator, assembled per this API's needs) ───";
+
+// The embedded block keeps `export` only on the surface the generated wiring and its
+// type re-exports reference; everything else becomes module-local. `types.ts` is the
+// public type surface (it replaces package-mode type imports — and TS `noUnusedLocals`
+// never flags exported declarations, so unused types in a given output are fine).
+const KEEP_EXPORTS: Partial<Record<RuntimeModuleName, (statement: ts.Statement) => boolean>> = {
+  'types.ts': () => true,
+  'errors.ts': ts.isClassDeclaration, // ApiError stays public; abortError goes local
+  'setup.ts': () => true, // mergeSetup — the baked-setup wiring calls it
+};
+
+/** The embedded runtime source block: stripped modules in dependency order + the factory. */
+export function assembleInlineRuntime(needs: InlineRuntimeNeeds): string {
+  // Import-graph topological order; the optional capability modules slot in where the
+  // package barrel would import them (core never imports them statically).
+  const modules: RuntimeModuleName[] = ['types.ts', 'errors.ts', 'url.ts', 'parse.ts', 'retry.ts'];
+  if (needs.multipart) modules.push('multipart.ts');
+  if (needs.auth) modules.push('auth.ts');
+  if (needs.setup) modules.push('setup.ts');
+  // paginate.ts has only type imports (types.ts + create-client.ts's OperationArgs),
+  // so it can sit anywhere; keep it with the other capability modules, before send.ts.
+  if (needs.paginate) modules.push('paginate.ts');
+  modules.push('send.ts');
+  if (needs.sse) modules.push('sse.ts');
+  modules.push('create-client.ts');
+  return [HEADER, ...modules.map(embedModule), clientFactory(needs)].join('\n\n');
+}
+
+// Strip module syntax from one runtime source: drop every import declaration (all are
+// relative `./x.js` imports within the runtime) and remove the `export` modifier from
+// declarations outside the kept surface. Slices are driven by AST positions from
+// `parseStatements` (no regexes), so comments and formatting survive byte-for-byte.
+function embedModule(name: RuntimeModuleName): string {
+  const source = RUNTIME_SOURCES[name];
+  const keeps = KEEP_EXPORTS[name];
+  const parts: string[] = [];
+  for (const statement of parseStatements(source)) {
+    if (ts.isImportDeclaration(statement)) continue;
+    // Full text includes leading trivia (JSDoc, blank lines), so spacing is preserved.
+    const text = source.slice(statement.getFullStart(), statement.end);
+    // Every top-level runtime statement is a declaration (`getModifiers` is total —
+    // it returns undefined when the node carries no modifiers).
+    const exportModifier = ts
+      .getModifiers(statement as ts.HasModifiers)
+      ?.find((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword);
+    if (exportModifier && !keeps?.(statement)) {
+      const at = exportModifier.getStart() - statement.getFullStart();
+      parts.push(text.slice(0, at) + text.slice(at + 'export '.length));
+    } else {
+      parts.push(text);
+    }
+  }
+  return parts.join('').trim();
+}
+
+// The embedded equivalent of the package barrel's `createClient`: `createClientCore`
+// with only the included capabilities wired. EXPORTED — the design spec promises the
+// generated module re-exports `createClient`/`OPERATIONS`/`Ops` so apps can build
+// additional per-tenant instances over the same descriptors.
+function clientFactory(needs: InlineRuntimeNeeds): string {
+  const caps = [
+    ...(needs.multipart ? ['serializeMultipart: toFormData'] : []),
+    ...(needs.auth ? ['resolveAuth'] : []),
+    ...(needs.sse ? ['sse'] : []),
+    ...(needs.paginate ? ['paginate: { pages, items }'] : []),
+  ];
+  const wired = caps.length > 0 ? `{ ${caps.join(', ')} }` : '{}';
+  return `/**
+ * The client factory: \`createClientCore\` wired with the capabilities this API needs.
+ * Exported so apps can build additional instances (per-tenant, per-environment) over
+ * the same \`OPERATIONS\`/\`Ops\`. The trailing string params carry the wiring's literal
+ * unions (\`OperationId\`/\`OperationPath\`/\`OperationTag\`) into \`ctx.operation\`.
+ */
+export function createClient<
+  Ops extends OpsShape,
+  Id extends string = string,
+  Path extends string = string,
+  Tag extends string = string,
+>(
+  operations: Record<string, OperationDescriptor>,
+  config?: ClientConfig<OperationContext<Id, Path, Tag>>
+): Client<Ops, OperationContext<Id, Path, Tag>> {
+  return createClientCore<Ops, Id, Path, Tag>(operations, config, ${wired});
+}`;
+}
diff --git a/packages/client-generator/src/emitters/jsdoc.ts b/packages/client-generator/src/emitters/jsdoc.ts
new file mode 100644
index 0000000000..1e824fc47e
--- /dev/null
+++ b/packages/client-generator/src/emitters/jsdoc.ts
@@ -0,0 +1,72 @@
+import type { SchemaMetadata } from '../intermediate-representation/model.js';
+import { splitLines } from './support.js';
+import { escapeJsDoc } from './ts.js';
+
+/**
+ * The JSDoc body for a description + metadata as a single `\n`-joined string,
+ * or `undefined` when there's nothing to document. The AST emitters feed this
+ * to `ts.ts`'s `jsdoc` helper (which owns the `*`-prefixing and indentation),
+ * so this returns only the raw body — no comment delimiters, no padding.
+ */
+export function jsdocText(text: string | undefined, metadata?: SchemaMetadata): string | undefined {
+  const lines = jsdocLines(text, metadata);
+  return lines.length === 0 ? undefined : lines.join('\n');
+}
+
+/**
+ * Build the body of a JSDoc block from a description and an optional metadata
+ * bag. Description lines come first (trimmed of leading/trailing blanks); then
+ * the metadata tag lines in a stable, source-driven order.
+ *
+ * Returns `[]` when there's nothing to render — callers use the empty result
+ * to skip emitting any JSDoc at all.
+ */
+function jsdocLines(text: string | undefined, metadata: SchemaMetadata | undefined): string[] {
+  const lines: string[] = [];
+  if (text && text.trim()) {
+    lines.push(...trimLines(splitLines(text)));
+  }
+  if (metadata) {
+    lines.push(...formatMetadata(metadata));
+  }
+  return lines;
+}
+
+/**
+ * Project a SchemaMetadata bag into JSDoc tag lines.
+ *
+ * Order matches the (near-)spec order so generated output is deterministic and
+ * diff-stable. `pattern` is escaped so an embedded `*​/` cannot terminate the
+ * surrounding JSDoc block.
+ */
+function formatMetadata(metadata: SchemaMetadata): string[] {
+  const lines: string[] = [];
+  const push = (tag: string, value?: number | string | boolean): void => {
+    if (value === undefined) {
+      lines.push(`@${tag}`);
+    } else {
+      lines.push(`@${tag} ${value}`);
+    }
+  };
+  if (metadata.minimum !== undefined) push('minimum', metadata.minimum);
+  if (metadata.maximum !== undefined) push('maximum', metadata.maximum);
+  if (metadata.exclusiveMinimum !== undefined) push('exclusiveMinimum', metadata.exclusiveMinimum);
+  if (metadata.exclusiveMaximum !== undefined) push('exclusiveMaximum', metadata.exclusiveMaximum);
+  if (metadata.minLength !== undefined) push('minLength', metadata.minLength);
+  if (metadata.maxLength !== undefined) push('maxLength', metadata.maxLength);
+  if (metadata.pattern !== undefined) push('pattern', escapeJsDoc(metadata.pattern));
+  if (metadata.minItems !== undefined) push('minItems', metadata.minItems);
+  if (metadata.maxItems !== undefined) push('maxItems', metadata.maxItems);
+  if (metadata.uniqueItems === true) push('uniqueItems');
+  if (metadata.format !== undefined) push('format', metadata.format);
+  if (metadata.deprecated === true) push('deprecated');
+  return lines;
+}
+
+function trimLines(lines: string[]): string[] {
+  let start = 0;
+  let end = lines.length;
+  while (start < end && lines[start] === '') start++;
+  while (end > start && lines[end - 1] === '') end--;
+  return lines.slice(start, end);
+}
diff --git a/packages/client-generator/src/emitters/mock.ts b/packages/client-generator/src/emitters/mock.ts
new file mode 100644
index 0000000000..c65ab1f26d
--- /dev/null
+++ b/packages/client-generator/src/emitters/mock.ts
@@ -0,0 +1,430 @@
+// Emits a `*.mocks.ts` module: a `create<Schema>(overrides?)` data factory per
+// named schema, an `<op>Handler(override?)` MSW request handler per operation
+// (its primary success response), and an aggregated `handlers` array. Response
+// data is baked at codegen time via the sampler (`sampleValue`) and printed as
+// TypeScript literals through `ts.factory`, so the generated module depends only
+// on `msw` — the real client stays zero-dependency.
+
+import { isPlainObject } from '@redocly/openapi-core';
+
+import {
+  allOperations,
+  type ApiModel,
+  type NamedSchemaModel,
+  type OperationModel,
+  type ResponseBodyModel,
+  type SchemaModel,
+} from '../intermediate-representation/model.js';
+import { fakerExpression } from './faker.js';
+import { safeIdent } from './identifier.js';
+import { sampleValue, SampleExpression } from './sample.js';
+import { pascalCase } from './support.js';
+import { literalExpression, parseExpression, printStatements, ts } from './ts.js';
+import type { DateType } from './types.js';
+
+const { factory } = ts;
+
+export type MockOptions = {
+  /** Import specifier for the sdk entry the schema types live in. */
+  sdkModule: string;
+  /** Must match the sdk's `--date-type`: under `'Date'` the sampler bakes date
+   *  fields as `new Date(...)` so the mock data matches the `Date`-typed sdk. */
+  dateType?: DateType;
+  /**
+   * How factory/handler bodies produce data. `'baked'` (default) inlines deterministic
+   * literals from the sampler (zero-dep, contract-faithful). `'faker'` emits
+   * `@faker-js/faker` calls for realistic data — reproducible when `mockSeed` is set —
+   * making `@faker-js/faker` the consumer's dev-dep. Factory signatures are identical
+   * across modes, so a consumer can flip this without changing call sites.
+   */
+  mockData?: 'baked' | 'faker';
+  /** When set in `'faker'` mode, emit a top-level `faker.seed(<n>);` so runs reproduce. */
+  mockSeed?: number;
+};
+
+/** The body expression for `schema` under the active data mode: a baked literal tree
+ *  (`'baked'`) or a tree of `@faker-js/faker` calls (`'faker'`). Both honor `dateType`
+ *  and the binary/Blob type demand; the faker path inlines refs with the same cycle
+ *  guard as the baked sampler, so neither recurses forever on a cyclic schema. */
+function bodyExpression(schema: SchemaModel, model: ApiModel, opts: MockOptions): ts.Expression {
+  return opts.mockData === 'faker'
+    ? fakerExpression(schema, model.schemas, { dateType: opts.dateType })
+    : literal(sampleValue(schema, model.schemas, { dateType: opts.dateType }));
+}
+
+/** Render the full `*.mocks.ts` source. `''` when the model has no operations. */
+export function renderMockModule(model: ApiModel, opts: MockOptions): string {
+  const operations = allOperations(model.services);
+  if (operations.length === 0) return '';
+  const factories = model.schemas.map((s) => factoryFor(s, model, opts));
+  const handlers = operations.flatMap((op) => [
+    handlerFor(op, model, opts),
+    ...(op.errorResponses.length > 0 ? [errorHandlerFor(op, model, opts)] : []),
+  ]);
+  const typeImport = schemaTypeImport(model, opts);
+  // Faker mode imports `faker` (the consumer's dev-dep) and, with a seed, pins it once
+  // at module top so every run reproduces. Baked mode emits neither (stays zero-dep).
+  const fakerImport = opts.mockData === 'faker' ? "import { faker } from '@faker-js/faker';\n" : '';
+  const seed =
+    opts.mockData === 'faker' && opts.mockSeed !== undefined ? [seedStatement(opts.mockSeed)] : [];
+  return `import { http, HttpResponse } from 'msw';\n${fakerImport}\n${printStatements([
+    ...typeImport,
+    ...seed,
+    ...factories,
+    ...handlers,
+    handlersArray(operations),
+  ])}`;
+}
+
+/** `faker.seed(<n>);` — pins faker's PRNG so a seeded faker-mode module reproduces. */
+function seedStatement(seed: number): ts.Statement {
+  return factory.createExpressionStatement(
+    factory.createCallExpression(
+      factory.createPropertyAccessExpression(factory.createIdentifier('faker'), 'seed'),
+      undefined,
+      [factory.createNumericLiteral(seed)]
+    )
+  );
+}
+
+/**
+ * `import type { A, B, … } from '<sdkModule>';` — the named-schema types the factories
+ * reference (`create<Pascal>` returns/accepts `<Pascal>`). Sorted for stable output.
+ * Empty when the model has no named schemas (so no type import is emitted). Importing
+ * the schema types also shadows globals of the same name (e.g. an `Error` schema) so the
+ * factory return types resolve to the generated type, not `globalThis.Error`.
+ */
+function schemaTypeImport(model: ApiModel, opts: MockOptions): ts.Statement[] {
+  if (model.schemas.length === 0) return [];
+  const names = model.schemas.map((s) => pascalCase(s.name)).sort();
+  return [
+    factory.createImportDeclaration(
+      undefined,
+      factory.createImportClause(
+        true,
+        undefined,
+        factory.createNamedImports(
+          names.map((name) =>
+            factory.createImportSpecifier(false, undefined, factory.createIdentifier(name))
+          )
+        )
+      ),
+      factory.createStringLiteral(opts.sdkModule)
+    ),
+  ];
+}
+
+/** `export function create<Pascal>(overrides?: Partial<Pascal>): Pascal { return { …sampled, ...overrides }; }`. */
+function factoryFor(named: NamedSchemaModel, model: ApiModel, opts: MockOptions): ts.Statement {
+  const pascal = pascalCase(named.name);
+  const sampled = bodyExpression(named.schema, model, opts);
+  const typeRef = factory.createTypeReferenceNode(pascal);
+  // Spreading `Partial<Union>` (the override type of a union schema) distributes into
+  // `Partial<A> | Partial<B>`, which widens any discriminant property (e.g. `category`)
+  // and defeats narrowing — TS can no longer place the literal in a single union member.
+  // The sampled object is already a complete, correct member, so re-assert the type.
+  const body =
+    named.schema.kind === 'union'
+      ? factory.createAsExpression(spreadOverrides(sampled, 'overrides'), typeRef)
+      : spreadOverrides(sampled, 'overrides');
+  return factory.createFunctionDeclaration(
+    [factory.createModifier(ts.SyntaxKind.ExportKeyword)],
+    undefined,
+    `create${pascal}`,
+    undefined,
+    [
+      factory.createParameterDeclaration(
+        undefined,
+        undefined,
+        'overrides',
+        factory.createToken(ts.SyntaxKind.QuestionToken),
+        factory.createTypeReferenceNode('Partial', [typeRef])
+      ),
+    ],
+    typeRef,
+    factory.createBlock([factory.createReturnStatement(body)], true)
+  );
+}
+
+/** `export const <op>Handler = (override?: <OverrideType>) => http.<method>('<path>', () => <response>);`. */
+function handlerFor(op: OperationModel, model: ApiModel, opts: MockOptions): ts.Statement {
+  const arrow = factory.createArrowFunction(
+    undefined,
+    undefined,
+    [
+      factory.createParameterDeclaration(
+        undefined,
+        undefined,
+        'override',
+        factory.createToken(ts.SyntaxKind.QuestionToken),
+        overrideType(op)
+      ),
+    ],
+    undefined,
+    factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken),
+    handlerCall(op, model, opts)
+  );
+  return factory.createVariableStatement(
+    [factory.createModifier(ts.SyntaxKind.ExportKeyword)],
+    factory.createVariableDeclarationList(
+      [factory.createVariableDeclaration(`${op.name}Handler`, undefined, undefined, arrow)],
+      ts.NodeFlags.Const
+    )
+  );
+}
+
+/**
+ * `export const <op>ErrorHandler = (status: <StatusUnion>, body?: <BodyType>) =>
+ *    http.<method>("<mswPath>", () => HttpResponse.json(body ?? <bakedSample>, { status }));`
+ *
+ * Opt-in (not added to `handlers`): `server.use(getPetErrorHandler(404))` overrides the
+ * happy path with an error. `<StatusUnion>` is the declared error statuses as literals
+ * (plus `number` when a `default` error is present, so any status is allowed). The baked
+ * fallback samples the FIRST error response's schema.
+ */
+function errorHandlerFor(op: OperationModel, model: ApiModel, opts: MockOptions): ts.Statement {
+  const first = op.errorResponses[0];
+  const baked = bodyExpression(first.schema, model, opts);
+  const body = factory.createBinaryExpression(
+    factory.createIdentifier('body'),
+    factory.createToken(ts.SyntaxKind.QuestionQuestionToken),
+    baked
+  );
+  const resolver = factory.createArrowFunction(
+    undefined,
+    undefined,
+    [],
+    undefined,
+    factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken),
+    factory.createCallExpression(
+      factory.createPropertyAccessExpression(factory.createIdentifier('HttpResponse'), 'json'),
+      undefined,
+      [
+        body,
+        factory.createObjectLiteralExpression(
+          [factory.createShorthandPropertyAssignment('status')],
+          false
+        ),
+      ]
+    )
+  );
+  const call = factory.createCallExpression(
+    factory.createPropertyAccessExpression(factory.createIdentifier('http'), op.method),
+    undefined,
+    [factory.createStringLiteral(mswPath(op.path)), resolver]
+  );
+  const arrow = factory.createArrowFunction(
+    undefined,
+    undefined,
+    [
+      factory.createParameterDeclaration(
+        undefined,
+        undefined,
+        'status',
+        undefined,
+        errorStatusType(op)
+      ),
+      factory.createParameterDeclaration(
+        undefined,
+        undefined,
+        'body',
+        factory.createToken(ts.SyntaxKind.QuestionToken),
+        errorBodyType(op)
+      ),
+    ],
+    undefined,
+    factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken),
+    call
+  );
+  return factory.createVariableStatement(
+    [factory.createModifier(ts.SyntaxKind.ExportKeyword)],
+    factory.createVariableDeclarationList(
+      [factory.createVariableDeclaration(`${op.name}ErrorHandler`, undefined, undefined, arrow)],
+      ts.NodeFlags.Const
+    )
+  );
+}
+
+/**
+ * A union of the op's declared numeric error statuses (as literals); `number` is used in place
+ * of a literal whenever a `default` error is present, so any status is accepted. De-duped, since
+ * a multi-media-type error contributes the same status more than once.
+ */
+function errorStatusType(op: OperationModel): ts.TypeNode {
+  const codes = [
+    ...new Set(
+      op.errorResponses.filter((r) => r.status !== 'default').map((r) => r.status as number)
+    ),
+  ];
+  const members: ts.TypeNode[] = codes.map((c) =>
+    factory.createLiteralTypeNode(factory.createNumericLiteral(c))
+  );
+  // A `default` error means any status is valid, so widen the union with `number`.
+  if (op.errorResponses.some((r) => r.status === 'default')) {
+    members.push(factory.createKeywordTypeNode(ts.SyntaxKind.NumberKeyword));
+  }
+  return members.length === 1 ? members[0] : factory.createUnionTypeNode(members);
+}
+
+/**
+ * The `body?` type: the union of the error responses' body types — `ref` bodies map to their
+ * named type, anything else to `unknown` (matching how the success handler types its override
+ * loosely). De-duped by printed name.
+ */
+function errorBodyType(op: OperationModel): ts.TypeNode {
+  const names = new Set<string>();
+  let hasUnknown = false;
+  for (const r of op.errorResponses) {
+    if (r.schema.kind === 'ref') names.add(pascalCase(r.schema.name));
+    else hasUnknown = true;
+  }
+  const members: ts.TypeNode[] = [...names].map((n) => factory.createTypeReferenceNode(n));
+  if (hasUnknown || members.length === 0) {
+    members.push(factory.createKeywordTypeNode(ts.SyntaxKind.UnknownKeyword));
+  }
+  return members.length === 1 ? members[0] : factory.createUnionTypeNode(members);
+}
+
+/**
+ * The static type of a handler's `override?` parameter, matching how the response uses it.
+ * A `ref` success body forwards `override` to `create<Schema>(override)` (whose parameter is
+ * `Partial<Schema>`), so the override is `Partial<Schema>`. Otherwise `override` is either spread
+ * into an inline object literal or unused, so `Record<string, unknown>` types it without error.
+ */
+function overrideType(op: OperationModel): ts.TypeNode {
+  const success = op.successResponses[0];
+  if (success?.schema.kind === 'ref') {
+    return factory.createTypeReferenceNode('Partial', [
+      factory.createTypeReferenceNode(pascalCase(success.schema.name)),
+    ]);
+  }
+  return factory.createTypeReferenceNode('Record', [
+    factory.createKeywordTypeNode(ts.SyntaxKind.StringKeyword),
+    factory.createKeywordTypeNode(ts.SyntaxKind.UnknownKeyword),
+  ]);
+}
+
+/** `http.<method>('<mswPath>', () => <responseExpr>)`. */
+function handlerCall(op: OperationModel, model: ApiModel, opts: MockOptions): ts.Expression {
+  const resolver = factory.createArrowFunction(
+    undefined,
+    undefined,
+    [],
+    undefined,
+    factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken),
+    responseExpression(op, model, opts)
+  );
+  return factory.createCallExpression(
+    factory.createPropertyAccessExpression(factory.createIdentifier('http'), op.method),
+    undefined,
+    [factory.createStringLiteral(mswPath(op.path)), resolver]
+  );
+}
+
+/**
+ * The handler's response. A primary success body becomes `HttpResponse.json(…)`:
+ * a `ref` body calls its named `create<Schema>(override)` factory; an inline body
+ * is sampled and printed in place with `...override` spread in. A success with no
+ * usable body (an `unknown` schema, or no success response at all) becomes a
+ * body-less `new HttpResponse(null, { status })`. The status is the success
+ * response's declared code, or 200 when it's `default`/absent.
+ */
+function responseExpression(op: OperationModel, model: ApiModel, opts: MockOptions): ts.Expression {
+  const success = op.successResponses[0];
+  const status = statusCode(success?.status);
+  if (!success || success.schema.kind === 'unknown') return emptyResponse(status);
+  const data =
+    success.schema.kind === 'ref'
+      ? factory.createCallExpression(
+          factory.createIdentifier(`create${pascalCase(success.schema.name)}`),
+          undefined,
+          [factory.createIdentifier('override')]
+        )
+      : spreadOverrides(bodyExpression(success.schema, model, opts), 'override');
+  // `HttpResponse.json(x)` already defaults to 200, so only pass `{ status }` when it differs.
+  const args = status === 200 ? [data] : [data, statusInit(status)];
+  return factory.createCallExpression(
+    factory.createPropertyAccessExpression(factory.createIdentifier('HttpResponse'), 'json'),
+    undefined,
+    args
+  );
+}
+
+/** Numeric status for a response, mapping `default`/absent to 200. */
+function statusCode(status: ResponseBodyModel['status'] | undefined): number {
+  return typeof status === 'number' ? status : 200;
+}
+
+/** `{ status: <n> }`. */
+function statusInit(status: number): ts.Expression {
+  return factory.createObjectLiteralExpression(
+    [factory.createPropertyAssignment('status', factory.createNumericLiteral(status))],
+    false
+  );
+}
+
+/** `new HttpResponse(null, { status: <n> })`. */
+function emptyResponse(status: number): ts.Expression {
+  return factory.createNewExpression(factory.createIdentifier('HttpResponse'), undefined, [
+    factory.createNull(),
+    statusInit(status),
+  ]);
+}
+
+/** `export const handlers = [<op>Handler(), …];`. */
+function handlersArray(operations: OperationModel[]): ts.Statement {
+  const elements = operations.map((op) =>
+    factory.createCallExpression(factory.createIdentifier(`${op.name}Handler`), undefined, [])
+  );
+  return factory.createVariableStatement(
+    [factory.createModifier(ts.SyntaxKind.ExportKeyword)],
+    factory.createVariableDeclarationList(
+      [
+        factory.createVariableDeclaration(
+          'handlers',
+          undefined,
+          undefined,
+          factory.createArrayLiteralExpression(elements, false)
+        ),
+      ],
+      ts.NodeFlags.Const
+    )
+  );
+}
+
+/** Spread `<spreadName>` into an object literal; non-object values pass through unchanged. */
+function spreadOverrides(value: ts.Expression, spreadName: string): ts.Expression {
+  if (!ts.isObjectLiteralExpression(value)) return value;
+  return factory.createObjectLiteralExpression(
+    [...value.properties, factory.createSpreadAssignment(factory.createIdentifier(spreadName))],
+    true
+  );
+}
+
+/** `/pets/{petId}` → `*​/pets/:petId` — MSW path with a wildcard origin and `:param` segments. */
+function mswPath(path: string): string {
+  return `*${path.replace(/\{([^{}]+)\}/g, ':$1')}`;
+}
+
+/** Recursively print a sampled JS value as a TypeScript literal expression. Containers
+ *  stay local rather than delegating to the shared `literalExpression`: sampled trees
+ *  print multiline and may nest a `SampleExpression` at any depth. */
+function literal(value: unknown): ts.Expression {
+  if (value instanceof SampleExpression) return parseExpression(value.code);
+  if (Array.isArray(value)) {
+    return factory.createArrayLiteralExpression(value.map(literal), true);
+  }
+  if (isPlainObject(value)) {
+    const entries = Object.entries(value);
+    return factory.createObjectLiteralExpression(
+      entries.map(([key, v]) => {
+        const safe = safeIdent(key);
+        const name =
+          safe === key ? factory.createIdentifier(key) : factory.createStringLiteral(key);
+        return factory.createPropertyAssignment(name, literal(v));
+      }),
+      true
+    );
+  }
+  return literalExpression(value);
+}
diff --git a/packages/client-generator/src/emitters/operation-aliases.ts b/packages/client-generator/src/emitters/operation-aliases.ts
new file mode 100644
index 0000000000..c8950dff91
--- /dev/null
+++ b/packages/client-generator/src/emitters/operation-aliases.ts
@@ -0,0 +1,268 @@
+// The `<Op>*` derived type-alias builders (`<Op>Result`/`Error`/`Params`/`Body`/`Headers`/`Variables`).
+// Split out of operations.ts: this is the cohesive cluster the sdk emits so callers can name
+// intermediate values. Reuses the shared type builders (operation-types.ts) and the block-wide
+// `EmitContext` (a type-only import from operations.ts — erased, so there is no runtime cycle).
+
+import type { OperationModel, ParamModel } from '../intermediate-representation/model.js';
+import { safeIdent } from './identifier.js';
+import { jsdocText } from './jsdoc.js';
+import { operationSignature } from './operation-signature.js';
+import { bodyTypeNode, paramsTypeLiteral, propertyKey } from './operation-types.js';
+import type { EmitContext } from './operations.js';
+import { pascalCase } from './support.js';
+import { jsdoc, ts } from './ts.js';
+import { schemaToTypeNode } from './types.js';
+
+const { factory } = ts;
+
+/**
+ * Emit derived type aliases for an operation so callers can name intermediate
+ * values without re-deriving via `Awaited<ReturnType<...>>` plumbing.
+ *
+ * `*Result` is always emitted (even for `void`). The others are conditional on
+ * the operation actually having the corresponding inputs — emitting empty
+ * `*Params = {}` or `*Body = unknown` aliases would just be noise.
+ */
+export function renderOperationAliases(
+  op: OperationModel,
+  responseType: ts.TypeNode,
+  orderedPathParams: ParamModel[],
+  pathParamIdent: Map<string, string>,
+  errorAlias: string,
+  errorMembers: ts.TypeNode[],
+  ctx: EmitContext,
+  // SSE ops have no one-shot response, so they omit `*Result`/`*Error` and keep only the input
+  // aliases.
+  emitResultAndError = true,
+  // Threaded to the `<Op>Variables` body — see `variablesTypeLiteral`.
+  pathKeys: 'ident' | 'wire' = 'ident'
+): ts.Statement[] {
+  const { dateType, schemaNames } = ctx;
+  const name = pascalCase(op.name);
+  const aliases: ts.Statement[] = [];
+
+  // Every derived alias is suppressed when its name collides with an exported schema (a
+  // duplicate `export type` is a TS2300 error). References to a suppressed alias inline the
+  // underlying type instead — see `renderOperationParts` (Result/Error) and `renderVariablesAlias`
+  // / the grouped signature (Params/Body/Headers/Variables).
+
+  // Emit `export type <Op>Result = …` unless its name collides with an exported schema. Two
+  // cases collide: self-referential (operation `search` returning schema `SearchResult` →
+  // `export type SearchResult = SearchResult;`, circular) and plain (operation `login` returning
+  // some other type while a `LoginResult` schema also exists). In both, call sites reference the
+  // response type directly (`renderOperationParts`), so the alias is redundant.
+  const resultName = `${name}Result`;
+  if (emitResultAndError && !schemaNames.has(resultName)) {
+    aliases.push(exportType(resultName, responseType));
+  }
+
+  // Result mode only, and only when the operation declares error responses: the typed `error`.
+  if (emitResultAndError && errorAlias && !schemaNames.has(errorAlias)) {
+    aliases.push(
+      exportType(
+        errorAlias,
+        errorMembers.length === 1 ? errorMembers[0] : factory.createUnionTypeNode(errorMembers)
+      )
+    );
+  }
+
+  if (op.queryParams.length > 0 && !schemaNames.has(`${name}Params`)) {
+    // Reuse the params type-literal builder so the alias body picks up per-prop
+    // JSDoc automatically — no second renderer to keep in sync.
+    aliases.push(exportType(`${name}Params`, paramsTypeLiteral(op.queryParams, dateType)));
+  }
+
+  if (op.requestBody && !schemaNames.has(`${name}Body`)) {
+    // Use the same content-type → TS-type mapping as the function signature, so
+    // `<Op>Body` matches the second-positional arg of the function exactly.
+    aliases.push(exportType(`${name}Body`, bodyTypeNode(op.requestBody, dateType)));
+  }
+
+  if (op.headerParams.length > 0 && !schemaNames.has(`${name}Headers`)) {
+    aliases.push(exportType(`${name}Headers`, paramsTypeLiteral(op.headerParams, dateType)));
+  }
+
+  if (op.cookieParams.length > 0 && !schemaNames.has(`${name}Cookies`)) {
+    aliases.push(exportType(`${name}Cookies`, paramsTypeLiteral(op.cookieParams, dateType)));
+  }
+
+  if (!schemaNames.has(`${name}Variables`)) {
+    const variables = renderVariablesAlias(
+      op,
+      name,
+      orderedPathParams,
+      pathParamIdent,
+      ctx,
+      pathKeys
+    );
+    if (variables) aliases.push(variables);
+  }
+
+  return aliases;
+}
+
+/**
+ * An SSE op's input aliases (`*Params` / `*Body` / `*Headers` / `*Variables`) — but NOT
+ * `*Result`/`*Error`, which describe a one-shot response an event stream has no equivalent of.
+ * Passes the real `schemaNames` so the input aliases still get collision suppression, and sets
+ * `emitResultAndError = false` to omit the result/error pair.
+ */
+export function sseAliases(
+  op: OperationModel,
+  orderedPathParams: ParamModel[],
+  pathParamIdent: Map<string, string>,
+  ctx: EmitContext,
+  pathKeys: 'ident' | 'wire' = 'ident'
+): ts.Statement[] {
+  return renderOperationAliases(
+    op,
+    factory.createKeywordTypeNode(ts.SyntaxKind.UnknownKeyword),
+    orderedPathParams,
+    pathParamIdent,
+    '',
+    [],
+    ctx,
+    false,
+    pathKeys
+  );
+}
+
+/** `export type <name> = <type>;` */
+function exportType(name: string, type: ts.TypeNode): ts.TypeAliasDeclaration {
+  return factory.createTypeAliasDeclaration(
+    [factory.createModifier(ts.SyntaxKind.ExportKeyword)],
+    name,
+    undefined,
+    type
+  );
+}
+
+/**
+ * Combined inputs alias — a single object that bundles every positional input
+ * the operation function accepts. The seam React Query / SWR wrappers use:
+ *
+ *   useMutation({ mutationFn: (vars: UpdateOrderVariables) => updateOrder(vars.orderId, vars.params, vars.body) })
+ *
+ * Conventions:
+ * - Property order: path params (URL-template order), then `params`, then `body`,
+ *   then `headers`. Mirrors the function's positional argument order.
+ * - Path-param props carry the same JSDoc (description + schema metadata) the
+ *   function declaration omits.
+ * - `params?` is optional iff the function signature defaults to `= {}` (all query
+ *   params optional). Same rule for `body?` / `headers?`.
+ * - References `<Op>Params` / `<Op>Body` / `<Op>Headers` when those aliases were
+ *   also emitted, so the aliases stay in sync without duplicating their bodies.
+ *
+ * Returns `undefined` for operations with no inputs at all.
+ */
+function renderVariablesAlias(
+  op: OperationModel,
+  name: string,
+  orderedPathParams: ParamModel[],
+  pathParamIdent: Map<string, string>,
+  ctx: EmitContext,
+  pathKeys: 'ident' | 'wire'
+): ts.TypeAliasDeclaration | undefined {
+  if (!operationSignature(op).hasInputs) return undefined;
+  return exportType(
+    name + 'Variables',
+    variablesTypeLiteral(op, name, orderedPathParams, pathParamIdent, ctx, pathKeys)
+  );
+}
+
+/**
+ * The `<Op>Variables` object type literal (the body of the alias, reused inline by the grouped
+ * signature when the alias name itself collides). Each `params`/`body`/`headers` property
+ * references its `<Op>X` alias, or inlines the type when that alias name collides with a schema
+ * (so a suppressed alias is never referenced).
+ */
+export function variablesTypeLiteral(
+  op: OperationModel,
+  name: string,
+  orderedPathParams: ParamModel[],
+  pathParamIdent: Map<string, string>,
+  ctx: EmitContext,
+  // How path-param properties are keyed: `'ident'` (default) uses the sanitized identifier
+  // that doubles as the flat positional argument; `'wire'` (package mode) uses the spec's
+  // param name — quoted when needed — because the runtime routes `args[param.name]`.
+  pathKeys: 'ident' | 'wire' = 'ident'
+): ts.TypeNode {
+  const { dateType, schemaNames } = ctx;
+  const props: ts.PropertySignature[] = [];
+
+  for (const p of orderedPathParams) {
+    // Ident mode: same safe identifier the function uses, so a wrapper can map
+    // `vars.<ident>` straight onto the positional argument.
+    const sig = factory.createPropertySignature(
+      undefined,
+      pathKeys === 'wire' ? propertyKey(safeIdent(p.name)) : pathParamIdent.get(p.name)!,
+      undefined,
+      schemaToTypeNode(p.schema, dateType)
+    );
+    const doc = jsdocText(p.description, p.schema.metadata);
+    props.push(doc === undefined ? sig : jsdoc(sig, doc));
+  }
+
+  if (op.queryParams.length > 0) {
+    props.push(
+      inputProp(
+        'params',
+        `${name}Params`,
+        () => paramsTypeLiteral(op.queryParams, dateType),
+        op.queryParams.some((p) => p.required),
+        schemaNames
+      )
+    );
+  }
+  if (op.requestBody) {
+    props.push(
+      inputProp(
+        'body',
+        `${name}Body`,
+        () => bodyTypeNode(op.requestBody!, dateType),
+        op.requestBody.required,
+        schemaNames
+      )
+    );
+  }
+  if (op.headerParams.length > 0) {
+    props.push(
+      inputProp(
+        'headers',
+        `${name}Headers`,
+        () => paramsTypeLiteral(op.headerParams, dateType),
+        op.headerParams.some((p) => p.required),
+        schemaNames
+      )
+    );
+  }
+  if (op.cookieParams.length > 0) {
+    props.push(
+      inputProp(
+        'cookies',
+        `${name}Cookies`,
+        () => paramsTypeLiteral(op.cookieParams, dateType),
+        op.cookieParams.some((p) => p.required),
+        schemaNames
+      )
+    );
+  }
+
+  return factory.createTypeLiteralNode(props);
+}
+
+/** A `<key>(?): <Alias>` property, or an inline-typed one when `<Alias>` collides with a schema. */
+function inputProp(
+  key: string,
+  alias: string,
+  inlineType: () => ts.TypeNode,
+  required: boolean,
+  schemaNames: Set<string>
+): ts.PropertySignature {
+  return factory.createPropertySignature(
+    undefined,
+    key,
+    required ? undefined : factory.createToken(ts.SyntaxKind.QuestionToken),
+    schemaNames.has(alias) ? inlineType() : factory.createTypeReferenceNode(alias)
+  );
+}
diff --git a/packages/client-generator/src/emitters/operation-signature.ts b/packages/client-generator/src/emitters/operation-signature.ts
new file mode 100644
index 0000000000..450a5efbf4
--- /dev/null
+++ b/packages/client-generator/src/emitters/operation-signature.ts
@@ -0,0 +1,59 @@
+// The shared calling-convention description for an operation. Both the sdk (which
+// emits each operation's parameter list) and the wrapper generators (which emit the
+// forwarding call) derive their argument *order*, slot presence, and `<Op>Variables`
+// naming from this one source — so a flat-mode signature and its call site can never drift.
+
+import type { OperationModel, ParamModel } from '../intermediate-representation/model.js';
+import { uniqueIdent } from './identifier.js';
+import { pascalCase } from './support.js';
+
+/** A path parameter paired with the unique JS identifier used for it in flat mode. */
+export type SignaturePathParam = { param: ParamModel; ident: string };
+
+export type OperationSignature = {
+  /** Path params in URL-template order, each with its unique JS identifier. */
+  pathParams: SignaturePathParam[];
+  /** Slot presence, in the order flat-mode arguments follow the path params. */
+  hasQuery: boolean;
+  hasBody: boolean;
+  hasHeaders: boolean;
+  hasCookies: boolean;
+  /** Any input at all — i.e. a `<Op>Variables` type exists for the operation. */
+  hasInputs: boolean;
+  /** Grouped mode: whether `vars` is required (else it defaults to `= {}`). */
+  varsRequired: boolean;
+  /** The `<Op>Variables` type-alias name. */
+  variablesTypeName: string;
+};
+
+/** Compute the calling-convention description for `op`. Pure; no AST. */
+export function operationSignature(op: OperationModel): OperationSignature {
+  const byName = new Map(op.pathParams.map((p) => [p.name, p] as const));
+  const ordered: ParamModel[] = [];
+  for (const match of op.path.matchAll(/\{([^{}]+)\}/g)) {
+    const p = byName.get(match[1]);
+    if (p) ordered.push(p);
+  }
+  const used = new Set<string>();
+  const pathParams = ordered.map((param) => ({ param, ident: uniqueIdent(param.name, used) }));
+
+  const hasQuery = op.queryParams.length > 0;
+  const hasBody = Boolean(op.requestBody);
+  const hasHeaders = op.headerParams.length > 0;
+  const hasCookies = op.cookieParams.length > 0;
+  return {
+    pathParams,
+    hasQuery,
+    hasBody,
+    hasHeaders,
+    hasCookies,
+    hasInputs: pathParams.length > 0 || hasQuery || hasBody || hasHeaders || hasCookies,
+    varsRequired:
+      pathParams.length > 0 ||
+      op.queryParams.some((p) => p.required) ||
+      (op.requestBody?.required ?? false) ||
+      op.headerParams.some((p) => p.required) ||
+      op.cookieParams.some((p) => p.required),
+    variablesTypeName: `${pascalCase(op.name)}Variables`,
+  };
+}
diff --git a/packages/client-generator/src/emitters/operation-types.ts b/packages/client-generator/src/emitters/operation-types.ts
new file mode 100644
index 0000000000..f9cc54eaea
--- /dev/null
+++ b/packages/client-generator/src/emitters/operation-types.ts
@@ -0,0 +1,155 @@
+// TypeScript type/parameter builders shared by the operation emitter and the operation-alias
+// builders: turn an operation's params / body / responses into `ts` type and parameter nodes.
+// Leaf module — depends only on the IR types and the codegen foundation, never back on operations.ts.
+
+import type {
+  ParamModel,
+  RequestBodyModel,
+  ResponseBodyModel,
+} from '../intermediate-representation/model.js';
+import { safeIdent } from './identifier.js';
+import { jsdocText } from './jsdoc.js';
+import { jsdoc, printNodes, ts } from './ts.js';
+import { type DateType, schemaToTypeNode } from './types.js';
+
+const { factory } = ts;
+
+/** A `<name>: <type>` parameter, defaulting to `= {}` when `withDefault`. */
+export function simpleParam(
+  name: string,
+  type: ts.TypeNode,
+  withDefault: boolean
+): ts.ParameterDeclaration {
+  return factory.createParameterDeclaration(
+    undefined,
+    undefined,
+    name,
+    undefined,
+    type,
+    withDefault ? factory.createObjectLiteralExpression([], false) : undefined
+  );
+}
+
+/**
+ * A `<slot>: { … }` argument bundling `params` into one object, each property
+ * carrying its own JSDoc (description + metadata). Defaults to `= {}` when every
+ * property is optional. Shared by the query `params` and the operation `headers`
+ * slots, which have the identical layout.
+ */
+export function renderParamsObjectArg(
+  slot: string,
+  params: ParamModel[],
+  dateType: DateType
+): ts.ParameterDeclaration {
+  return simpleParam(slot, paramsTypeLiteral(params, dateType), !params.some((p) => p.required));
+}
+
+/** The `{ … }` type literal for a params object (query or headers), with per-prop JSDoc. */
+export function paramsTypeLiteral(params: ParamModel[], dateType: DateType): ts.TypeLiteralNode {
+  return factory.createTypeLiteralNode(
+    params.map((p) => {
+      const sig = factory.createPropertySignature(
+        undefined,
+        propertyKey(safeIdent(p.name)),
+        p.required ? undefined : factory.createToken(ts.SyntaxKind.QuestionToken),
+        schemaToTypeNode(p.schema, dateType)
+      );
+      const doc = jsdocText(p.description, p.schema.metadata);
+      return doc === undefined ? sig : jsdoc(sig, doc);
+    })
+  );
+}
+
+/** A bare identifier key when valid, a quoted string-literal key otherwise. */
+export function propertyKey(safe: string): ts.PropertyName {
+  return safe.startsWith('"')
+    ? factory.createStringLiteral(JSON.parse(safe) as string)
+    : factory.createIdentifier(safe);
+}
+
+/**
+ * A multipart body whose schema is a concrete object — the case worth typing. Such a body
+ * is emitted as its object shape (binary fields → `Blob`); the runtime serializes it to
+ * `FormData` (`runtime/multipart.ts`) after the onRequest chain. Multipart bodies with a
+ * non-object schema can't be typed field-by-field, so they keep the raw `FormData` escape hatch.
+ */
+export function isTypedMultipart(rb: RequestBodyModel): boolean {
+  return rb.contentType === 'multipart/form-data' && rb.schema.kind === 'object';
+}
+
+/** The request-body TS type: special wrapper types per content-type, else the schema. */
+export function bodyTypeNode(rb: RequestBodyModel, dateType: DateType): ts.TypeNode {
+  if (isTypedMultipart(rb)) return schemaToTypeNode(rb.schema, dateType);
+  switch (rb.contentType) {
+    case 'multipart/form-data':
+      return factory.createTypeReferenceNode('FormData');
+    case 'application/x-www-form-urlencoded':
+      return factory.createTypeReferenceNode('URLSearchParams');
+    case 'application/octet-stream':
+      return factory.createUnionTypeNode([
+        factory.createTypeReferenceNode('Blob'),
+        factory.createTypeReferenceNode('ArrayBuffer'),
+      ]);
+    default:
+      return schemaToTypeNode(rb.schema, dateType);
+  }
+}
+
+/** The deduped error-response body type nodes (by printed form), or `[]` when none. */
+export function errorTypeNodes(responses: ResponseBodyModel[], dateType: DateType): ts.TypeNode[] {
+  const seen = new Set<string>();
+  const nodes: ts.TypeNode[] = [];
+  for (const r of responses) {
+    const node = schemaToTypeNode(r.schema, dateType);
+    const key = printNodes([node]);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    nodes.push(node);
+  }
+  return nodes;
+}
+
+export function computeResponse(
+  responses: ResponseBodyModel[],
+  dateType: DateType
+): {
+  responseType: ts.TypeNode;
+  responseKind: 'json' | 'blob' | 'text' | 'void';
+} {
+  if (responses.length === 0)
+    return {
+      responseType: factory.createKeywordTypeNode(ts.SyntaxKind.VoidKeyword),
+      responseKind: 'void',
+    };
+
+  // Prefer JSON; fall back to other content types.
+  const jsonResponse = responses.find((r) => r.contentType.toLowerCase().includes('json'));
+  if (jsonResponse) {
+    return { responseType: schemaToTypeNode(jsonResponse.schema, dateType), responseKind: 'json' };
+  }
+  // No JSON — handle binary/text gracefully.
+  const nodes: ts.TypeNode[] = [];
+  const seen = new Set<string>();
+  let hasBinary = false;
+  let hasText = false;
+  for (const r of responses) {
+    let node: ts.TypeNode;
+    if (r.contentType.startsWith('image/') || r.contentType === 'application/octet-stream') {
+      node = factory.createTypeReferenceNode('Blob');
+      hasBinary = true;
+    } else if (r.contentType.startsWith('text/')) {
+      node = factory.createKeywordTypeNode(ts.SyntaxKind.StringKeyword);
+      hasText = true;
+    } else {
+      node = schemaToTypeNode(r.schema, dateType);
+    }
+    const key = printNodes([node]);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    nodes.push(node);
+  }
+  // `nodes` is guaranteed non-empty here: each iteration above always builds one.
+  const responseType = nodes.length === 1 ? nodes[0] : factory.createUnionTypeNode(nodes);
+  const responseKind: 'blob' | 'text' | 'json' = hasBinary ? 'blob' : hasText ? 'text' : 'json';
+  return { responseType, responseKind };
+}
diff --git a/packages/client-generator/src/emitters/operations.ts b/packages/client-generator/src/emitters/operations.ts
new file mode 100644
index 0000000000..69c41cd311
--- /dev/null
+++ b/packages/client-generator/src/emitters/operations.ts
@@ -0,0 +1,89 @@
+import type { OperationModel, ParamModel } from '../intermediate-representation/model.js';
+import { bodyTypeNode, renderParamsObjectArg, simpleParam } from './operation-types.js';
+import type { ModelPagination } from './pagination.js';
+import { isSseOp } from './sse.js';
+import { ts } from './ts.js';
+import { type DateType, schemaToTypeNode } from './types.js';
+
+const { factory } = ts;
+
+/** Error-handling shape of the generated client: throw on non-2xx, or return a result union. */
+export type ErrorMode = 'throw' | 'result';
+
+/**
+ * How an operation's inputs are passed to the generated call.
+ * - `'flat'` (default): path params spread as positional args, then the
+ *   `params`/`body`/`headers` slots — one exported sugar arrow per operation.
+ * - `'grouped'`: the client methods' own shape — a single `args` object bundling
+ *   every input; the sugar is a plain destructure of the client. The per-call
+ *   `init: RequestOptions` stays a separate trailing argument in both styles.
+ */
+export type ArgsStyle = 'flat' | 'grouped';
+
+/**
+ * The emit configuration every operation shares. Bundling it into one value keeps
+ * it out of the positional parameter lists of the operation emitters (which would
+ * otherwise thread the same arguments through every layer, inviting transposition
+ * bugs). Per-call structural data (response type, ordered path params, …) stays an
+ * explicit argument; only this cross-cutting config travels as `ctx`.
+ */
+export type EmitContext = {
+  argsStyle: ArgsStyle;
+  errorMode: ErrorMode;
+  dateType: DateType;
+  /** Names of every exported schema, used for `<Op>*` alias collision suppression. */
+  schemaNames: Set<string>;
+  /** Resolved auto-pagination per operation name (absent ⇒ nothing paginates). */
+  pagination?: ModelPagination;
+};
+
+/**
+ * The flat sugar's parameter list: path params spread as positional args (in URL
+ * template order), then the `params`/`body`/`headers`/`cookies` slots, ending with
+ * the trailing `init: RequestOptions` (`SseOptions` for streams). Optional slots
+ * default to `= {}` so trailing arguments can be omitted.
+ */
+export function renderArgList(
+  op: OperationModel,
+  orderedPathParams: ParamModel[],
+  pathParamIdent: Map<string, string>,
+  ctx: EmitContext
+): ts.ParameterDeclaration[] {
+  const { dateType } = ctx;
+  const args: ts.ParameterDeclaration[] = [];
+  for (const p of orderedPathParams) {
+    args.push(
+      simpleParam(pathParamIdent.get(p.name)!, schemaToTypeNode(p.schema, dateType), false)
+    );
+  }
+  if (op.queryParams.length > 0)
+    args.push(renderParamsObjectArg('params', op.queryParams, dateType));
+  if (op.requestBody) {
+    const type = bodyTypeNode(op.requestBody, dateType);
+    args.push(
+      factory.createParameterDeclaration(
+        undefined,
+        undefined,
+        'body',
+        op.requestBody.required ? undefined : factory.createToken(ts.SyntaxKind.QuestionToken),
+        type
+      )
+    );
+  }
+  // Operation header params are explicit, typed inputs; security-scheme headers
+  // are injected by the runtime and live underneath them.
+  if (op.headerParams.length > 0)
+    args.push(renderParamsObjectArg('headers', op.headerParams, dateType));
+  if (op.cookieParams.length > 0)
+    args.push(renderParamsObjectArg('cookies', op.cookieParams, dateType));
+  // SSE ops take per-stream `SseOptions` (reconnect knobs); everyone else the
+  // standard per-call `RequestOptions`.
+  args.push(
+    simpleParam(
+      'init',
+      factory.createTypeReferenceNode(isSseOp(op) ? 'SseOptions' : 'RequestOptions'),
+      true
+    )
+  );
+  return args;
+}
diff --git a/packages/client-generator/src/emitters/pagination.ts b/packages/client-generator/src/emitters/pagination.ts
new file mode 100644
index 0000000000..56e10a1ab5
--- /dev/null
+++ b/packages/client-generator/src/emitters/pagination.ts
@@ -0,0 +1,323 @@
+// Auto-pagination resolution: turns config rules and `x-pagination` extensions into the
+// normalized descriptor `PaginationSpec`, statically VERIFYING each rule fits its
+// operation (the advance param is a declared query param whose schema fits the style —
+// string-ish for `cursor`, a numeric scalar for `offset`/`page`; the JSON pointers
+// resolve over the success response schema). A convention rule that doesn't fit silently skips the
+// operation; an explicit rule (per-op config or extension) that doesn't fit — and a
+// malformed rule from ANY source — is a generate-time error. No heuristics, ever.
+
+import { isPlainObject } from '@redocly/openapi-core';
+
+import {
+  allOperations,
+  type ApiModel,
+  type OperationModel,
+  type SchemaModel,
+} from '../intermediate-representation/model.js';
+import type { PaginationSpec } from '../runtime/types.js';
+import { isSseOp } from './sse.js';
+
+/** The pagination styles the generated runtime can drive. */
+export type PaginationStyle = 'cursor' | 'offset' | 'page';
+
+/**
+ * One user-facing pagination rule — the shared shape of the `x-pagination` operation
+ * extension and every `pagination` config rule. `nextCursor` and `items` are RFC 6901
+ * JSON pointers (starting with `/`) into the operation's success response.
+ */
+export type PaginationRule = {
+  /** `cursor` follows a response cursor; `offset`/`page` increment a numeric param. */
+  style: PaginationStyle;
+  /** Cursor style: the request query param that receives the cursor. */
+  cursorParam?: string;
+  /** Cursor style: JSON pointer to the next cursor in the response. */
+  nextCursor?: string;
+  /**
+   * Cursor style: optional JSON pointer to a boolean "more pages" flag. When it
+   * resolves to `false`, iteration stops without the follow-up request — for
+   * connection-style APIs whose cursor stays non-null on the last page.
+   */
+  hasMore?: string;
+  /** Offset/page styles: the request query param the iterator advances. */
+  offsetParam?: string;
+  /** Optional page-size query param (any style; recorded for tooling). */
+  limitParam?: string;
+  /** JSON pointer to the page's item array in the response. */
+  items: string;
+};
+
+/**
+ * The `pagination` config block: an optional convention rule (the top-level rule
+ * fields, applied to every operation it structurally fits when `style` is set), plus
+ * per-operation overrides and exclusions. Precedence per operation:
+ * `operations[id]` > the spec's `x-pagination` extension > the convention rule.
+ */
+export type PaginationConfig = Partial<PaginationRule> & {
+  /** operationIds no source may paginate. */
+  exclude?: string[];
+  /** Per-operation rules, keyed by operationId (beat `x-pagination` and the convention). */
+  operations?: Record<string, PaginationRule>;
+};
+
+/** One operation's resolution: the normalized spec + item element schema, or an error. */
+export type ResolvedPagination = {
+  spec?: PaginationSpec;
+  itemSchema?: SchemaModel;
+  error?: string;
+};
+
+/** Every paginated operation's spec + item schema, keyed by operation name. */
+export type ModelPagination = Map<string, { spec: PaginationSpec; itemSchema: SchemaModel }>;
+
+/**
+ * Resolve one operation's pagination across the three sources (per-op config >
+ * `x-pagination` > convention); `config.exclude` kills all of them. Returns the
+ * normalized spec + the item element schema, `{}` when the operation doesn't paginate
+ * (no source, or a convention that doesn't fit), or an `error` for a malformed rule
+ * (any source) and for an explicit rule that doesn't fit the operation.
+ */
+export function resolveOperationPagination(
+  op: OperationModel,
+  model: ApiModel,
+  config: PaginationConfig | undefined
+): ResolvedPagination {
+  const configName = op.specName ?? op.name;
+  if (config?.exclude?.includes(configName)) return {};
+  const perOp = config?.operations?.[configName];
+  if (perOp !== undefined) {
+    return applyRule(op, model, perOp, `pagination.operations["${configName}"]`, true);
+  }
+  if (op.paginationExtension !== undefined) {
+    return applyRule(op, model, op.paginationExtension, 'x-pagination', true);
+  }
+  if (config?.style !== undefined) {
+    const { exclude: _exclude, operations: _operations, ...convention } = config;
+    return applyRule(op, model, convention, 'pagination convention', false);
+  }
+  return {};
+}
+
+/**
+ * Resolve pagination for every operation of the model. Errors (malformed rules,
+ * explicit rules that don't fit) are aggregated into ONE throw listing every
+ * failing operation, so a generate run reports the whole problem set at once.
+ */
+export function resolveModelPagination(
+  model: ApiModel,
+  config: PaginationConfig | undefined
+): ModelPagination {
+  const resolved: ModelPagination = new Map();
+  const errors: string[] = [];
+  for (const op of allOperations(model.services)) {
+    const result = resolveOperationPagination(op, model, config);
+    if (result.error !== undefined) errors.push(result.error);
+    else if (result.spec !== undefined) {
+      resolved.set(op.name, { spec: result.spec, itemSchema: result.itemSchema! });
+    }
+  }
+  if (errors.length > 0) {
+    throw new Error(['Invalid pagination configuration:', ...errors].join('\n  - '));
+  }
+  return resolved;
+}
+
+/** Validate the rule's shape and fit, then normalize it into a descriptor spec. */
+function applyRule(
+  op: OperationModel,
+  model: ApiModel,
+  rule: unknown,
+  source: string,
+  explicit: boolean
+): ResolvedPagination {
+  const label = `Pagination for operation "${op.name}" (${source})`;
+  // Shape problems are errors from EVERY source — a malformed convention is a config bug.
+  const shapeProblem = ruleShapeProblem(rule);
+  if (shapeProblem !== undefined) return { error: `${label}: ${shapeProblem}` };
+  const valid = rule as PaginationRule;
+  // Fit problems: explicit declarations fail generation; a convention silently skips.
+  const misfit = (problem: string): ResolvedPagination =>
+    explicit ? { error: `${label}: ${problem}` } : {};
+
+  if (isSseOp(op)) return misfit('the operation is a Server-Sent Events stream');
+  const paramField = valid.style === 'cursor' ? 'cursorParam' : 'offsetParam';
+  const param = valid.style === 'cursor' ? valid.cursorParam! : valid.offsetParam!;
+  const advance = op.queryParams.find((p) => p.name === param);
+  if (!advance) {
+    return misfit(`query parameter "${param}" is not declared on the operation`);
+  }
+  // The advance param must accept what the runtime sends: the response's cursor
+  // (string-ish, same predicate as nextCursor) or the incremented number.
+  const advanceSchema = deref(advance.schema, model);
+  const advanceFits =
+    advanceSchema !== undefined &&
+    (valid.style === 'cursor'
+      ? isStringish(advanceSchema, model)
+      : advanceSchema.kind === 'scalar' &&
+        (advanceSchema.scalar === 'number' || advanceSchema.scalar === 'integer'));
+  if (!advanceFits) {
+    const expected = valid.style === 'cursor' ? 'a string' : 'a number';
+    return misfit(
+      `the "${paramField}" query parameter "${param}" must accept ${expected} (got ${describeSchema(advanceSchema)})`
+    );
+  }
+  // The page the pointers address is the operation's primary JSON success response —
+  // the same response `computeResponse` types (JSON preferred over other content types).
+  const page = op.successResponses.find((r) => r.contentType.toLowerCase().includes('json'));
+  if (!page) return misfit('the operation has no JSON success response');
+  const itemsTarget = resolveSchemaPointer(page.schema, valid.items, model);
+  if (itemsTarget === undefined) {
+    return misfit(
+      `the "items" pointer "${valid.items}" does not resolve in the success response schema`
+    );
+  }
+  if (itemsTarget.kind !== 'array') {
+    return misfit(
+      `the "items" pointer "${valid.items}" must point at an array (got ${itemsTarget.kind})`
+    );
+  }
+  if (valid.style === 'cursor') {
+    const cursorTarget = resolveSchemaPointer(page.schema, valid.nextCursor!, model);
+    if (cursorTarget === undefined) {
+      return misfit(
+        `the "nextCursor" pointer "${valid.nextCursor}" does not resolve in the success response schema`
+      );
+    }
+    if (!isStringish(cursorTarget, model)) {
+      return misfit(
+        `the "nextCursor" pointer "${valid.nextCursor}" must point at a string (got ${cursorTarget.kind})`
+      );
+    }
+    if (valid.hasMore !== undefined) {
+      const moreTarget = resolveSchemaPointer(page.schema, valid.hasMore, model);
+      if (moreTarget === undefined) {
+        return misfit(
+          `the "hasMore" pointer "${valid.hasMore}" does not resolve in the success response schema`
+        );
+      }
+      if (moreTarget.kind !== 'scalar' || moreTarget.scalar !== 'boolean') {
+        return misfit(
+          `the "hasMore" pointer "${valid.hasMore}" must point at a boolean (got ${moreTarget.kind})`
+        );
+      }
+    }
+  }
+  return {
+    spec: {
+      style: valid.style,
+      param,
+      ...(valid.limitParam !== undefined ? { limitParam: valid.limitParam } : {}),
+      ...(valid.style === 'cursor' ? { nextCursor: valid.nextCursor! } : {}),
+      ...(valid.style === 'cursor' && valid.hasMore !== undefined
+        ? { hasMore: valid.hasMore }
+        : {}),
+      items: valid.items,
+    },
+    itemSchema: itemsTarget.items,
+  };
+}
+
+/**
+ * The rule's structural problem, or `undefined` when it is a well-formed
+ * `PaginationRule`. Works over `unknown` — the extension is arbitrary spec data and
+ * config arrives from YAML, so both are checked field-by-field.
+ */
+function ruleShapeProblem(rule: unknown): string | undefined {
+  if (!isPlainObject(rule)) return 'the rule must be an object';
+  const { style, cursorParam, nextCursor, hasMore, offsetParam, limitParam, items } = rule;
+  if (style !== 'cursor' && style !== 'offset' && style !== 'page') {
+    return `"style" must be one of "cursor" | "offset" | "page" (got ${JSON.stringify(style)})`;
+  }
+  if (typeof items !== 'string' || !items.startsWith('/')) {
+    return '"items" must be a JSON pointer starting with "/"';
+  }
+  if (style === 'cursor') {
+    if (typeof cursorParam !== 'string' || cursorParam === '') {
+      return 'cursor style requires a "cursorParam" query parameter name';
+    }
+    if (typeof nextCursor !== 'string' || !nextCursor.startsWith('/')) {
+      return 'cursor style requires a "nextCursor" JSON pointer starting with "/"';
+    }
+    if (hasMore !== undefined && (typeof hasMore !== 'string' || !hasMore.startsWith('/'))) {
+      return '"hasMore" must be a JSON pointer starting with "/"';
+    }
+  } else if (typeof offsetParam !== 'string' || offsetParam === '') {
+    return `${style} style requires an "offsetParam" query parameter name`;
+  }
+  if (limitParam !== undefined && typeof limitParam !== 'string') {
+    return '"limitParam" must be a query parameter name';
+  }
+  return undefined;
+}
+
+/**
+ * Resolve an RFC 6901 JSON pointer (`~1` → `/`, `~0` → `~`) over a schema, walking the
+ * VALUE shape it describes: object property steps by name, record values for any token,
+ * array items for numeric tokens, with `ref` steps resolved through the model's named
+ * schemas (cycle-guarded). Unions and intersections bail (v1 is strict). Returns
+ * `undefined` on any miss — the caller decides whether that is an error.
+ */
+export function resolveSchemaPointer(
+  schema: SchemaModel,
+  pointer: string,
+  model: ApiModel
+): SchemaModel | undefined {
+  let current = deref(schema, model);
+  if (current === undefined || (pointer !== '' && !pointer.startsWith('/'))) return undefined;
+  if (pointer === '') return current;
+  for (const token of pointer.slice(1).split('/')) {
+    const key = token.replaceAll('~1', '/').replaceAll('~0', '~');
+    let next: SchemaModel | undefined;
+    if (current.kind === 'object') {
+      next = current.properties.find((p) => p.name === key)?.schema;
+    } else if (current.kind === 'record') {
+      next = current.value;
+    } else if (current.kind === 'array' && /^(0|[1-9]\d*)$/.test(key)) {
+      next = current.items;
+    }
+    if (next === undefined) return undefined;
+    current = deref(next, model);
+    if (current === undefined) return undefined;
+  }
+  return current;
+}
+
+/** A (dereferenced) schema named for a fit-error message; scalars/enums by their scalar. */
+function describeSchema(schema: SchemaModel | undefined): string {
+  if (schema === undefined) return 'an unresolvable ref';
+  return schema.kind === 'scalar' || schema.kind === 'enum' ? schema.scalar : schema.kind;
+}
+
+/** Follow a `ref` chain through the model's named schemas; `undefined` on a miss or cycle. */
+function deref(schema: SchemaModel, model: ApiModel): SchemaModel | undefined {
+  const seen = new Set<string>();
+  let current = schema;
+  while (current.kind === 'ref') {
+    const { name } = current;
+    if (seen.has(name)) return undefined;
+    seen.add(name);
+    const named = model.schemas.find((s) => s.name === name);
+    if (named === undefined) return undefined;
+    current = named.schema;
+  }
+  return current;
+}
+
+/**
+ * Whether a (dereferenced) schema is string-ish per the cursor contract: a string
+ * scalar, an enum of strings, or a literal string — nullable ok (a union whose members
+ * are `null` or string-ish leaves; nested unions stay out, v1 is strict).
+ */
+function isStringish(schema: SchemaModel, model: ApiModel): boolean {
+  if (schema.kind === 'scalar' || schema.kind === 'enum') return schema.scalar === 'string';
+  if (schema.kind === 'literal') return typeof schema.value === 'string';
+  if (schema.kind === 'union') {
+    return schema.members.every((member) => {
+      const resolved = deref(member, model);
+      return (
+        resolved !== undefined &&
+        (resolved.kind === 'null' || (resolved.kind !== 'union' && isStringish(resolved, model)))
+      );
+    });
+  }
+  return false;
+}
diff --git a/packages/client-generator/src/emitters/runtime-sources.ts b/packages/client-generator/src/emitters/runtime-sources.ts
new file mode 100644
index 0000000000..8f12b8258b
--- /dev/null
+++ b/packages/client-generator/src/emitters/runtime-sources.ts
@@ -0,0 +1,29 @@
+// GENERATED by scripts/generate-runtime-sources.mjs — do not edit. Regenerated on install (`prepare`); manually: `npm run prepare -w @redocly/client-generator`.
+export const RUNTIME_SOURCES = {
+  'types.ts':
+    "/**\n * The public type surface of the client runtime — `@redocly/client-generator`'s\n * app-facing runtime module. Pure types, no runtime code (excluded from coverage).\n * The generator emits `OPERATIONS` literals typed\n * `satisfies Record<string, OperationDescriptor>` against this module, so an\n * incompatible runtime/generated pair fails the consumer's build (the semver skew guard).\n */\n\n/** How one operation parameter is sent: its location plus OpenAPI query-serialization hints. */\nexport type ParamSpec = {\n  name: string;\n  in: 'path' | 'query' | 'header' | 'cookie';\n  style?: 'form' | 'spaceDelimited' | 'pipeDelimited' | 'deepObject';\n  explode?: boolean;\n  allowReserved?: boolean;\n};\n\n/** One security scheme, denormalized onto the operation (`scheme` names the spec's scheme). */\nexport type SecuritySpec =\n  | { scheme: string; kind: 'bearer' | 'basic' }\n  | { scheme: string; kind: 'apiKey'; name: string; in: 'header' | 'query' | 'cookie' };\n\n/**\n * How to auto-iterate a paginated operation (drives its `.pages()`/`.items()` members).\n * `nextCursor` and `items` are RFC 6901 JSON pointers into the page (response) value.\n */\nexport type PaginationSpec = {\n  style: 'cursor' | 'offset' | 'page';\n  /** The query param the iterator advances: the cursor (`cursor`) or number (`offset`/`page`). */\n  param: string;\n  /** Optional page-size query param (recorded for tooling; never set by the runtime). */\n  limitParam?: string;\n  /** Cursor style only: pointer to the next cursor in the page. */\n  nextCursor?: string;\n  /** Cursor style only: optional pointer to a boolean \"more pages\" flag — `false` stops iteration. */\n  hasMore?: string;\n  /** Pointer to the page's item array. */\n  items: string;\n};\n\n/** The frozen data contract between generated code and the runtime: one operation's wire shape. */\nexport type OperationDescriptor = {\n  id: string;\n  method: string;\n  path: string;\n  tags?: readonly string[];\n  params?: readonly ParamSpec[];\n  /** `multipart: true` marks a typed object body serialized to FormData by the runtime. */\n  body?: { contentType: string; multipart?: boolean };\n  /** Defaults to `'json'` (content-type negotiation on parse). */\n  responseKind?: 'json' | 'text' | 'blob' | 'void' | 'sse';\n  sseDataKind?: 'json' | 'text';\n  /** OR-alternatives, each an AND-set: the runtime applies the first fully-configured one. */\n  security?: readonly (readonly SecuritySpec[])[];\n  pagination?: PaginationSpec;\n};\n\n/** A query value: scalars, arrays of scalars, or objects (serialized as deepObject brackets). */\nexport type QueryValue =\n  | string\n  | number\n  | boolean\n  | null\n  | undefined\n  | Array<string | number | boolean | null | undefined>\n  | Record<string, unknown>;\n\n/** A credential: a literal, or a (possibly async) function resolved per request (refresh flows). */\nexport type TokenProvider = string | (() => string | Promise<string>);\n\n/** Per-instance credentials, keyed by the scheme kinds the runtime can inject. */\nexport type AuthCredentials = {\n  bearer?: TokenProvider;\n  basic?: { username: string; password: string };\n  apiKey?: Record<string, TokenProvider>;\n};\n\n/** Backoff shape: 'fixed' = constant delay; 'exponential' = doubling per attempt. */\nexport type RetryStrategy = 'fixed' | 'exponential';\n\n/**\n * The operation's identity, exposed to middleware for targeting (`ctx.operation`).\n * Generated clients instantiate the type parameters with the spec's literal unions\n * (`OperationId`/`OperationPath`/`OperationTag`) so a misspelled operation id in a\n * middleware comparison fails to compile; the string defaults keep every\n * spec-independent consumer (`runtime-contract.ts`, the runtime internals) working\n * with the base shape. `tags` stays mutable (`Tag[]`) so setup-contract types\n * (byte-locked to generated output) remain assignable through middleware callbacks.\n */\nexport type OperationContext<\n  Id extends string = string,\n  Path extends string = string,\n  Tag extends string = string,\n> = { id: Id; path: Path; tags: Tag[] };\n\n/** The mutable request context threaded through the middleware chain. */\nexport type RequestContext<Op extends OperationContext = OperationContext> = {\n  url: string;\n  method: string;\n  headers: Record<string, string>;\n  body?: unknown;\n  operation: Op;\n};\n\n/** The failed attempt handed to a custom `retryOn`: exactly one of `response`/`error` is set. */\nexport type RetryContext<Op extends OperationContext = OperationContext> = {\n  attempt: number;\n  request: RequestContext<Op>;\n  response?: Response;\n  error?: unknown;\n};\n\n/** Opt-in retry policy; a per-call override merges field-by-field over the config policy. */\nexport type RetryConfig<Op extends OperationContext = OperationContext> = {\n  retries?: number;\n  retryDelay?: number;\n  retryStrategy?: RetryStrategy;\n  jitter?: boolean;\n  retryOn?: (ctx: RetryContext<Op>) => boolean | Promise<boolean>;\n};\n\n/**\n * Structural stand-in for the runtime's ApiError so this module stays import-free\n * (pure types); the real `ApiError` class is assignable to it.\n */\nexport type ApiErrorLike = globalThis.Error & {\n  url: string;\n  status: number;\n  statusText: string;\n  body: unknown;\n};\n\n/** One interceptor: any subset of the three hooks. */\nexport type Middleware<Op extends OperationContext = OperationContext> = {\n  onRequest?: (ctx: RequestContext<Op>) => void | Promise<void>;\n  onResponse?: (\n    response: Response,\n    ctx: RequestContext<Op>\n  ) => Response | void | Promise<Response | void>;\n  /** Throw mode only: may map/replace the error. */\n  // `globalThis.Error` so a spec schema named `Error` cannot shadow it in inline mode.\n  onError?: (\n    error: ApiErrorLike,\n    ctx: RequestContext<Op>\n  ) => globalThis.Error | Promise<globalThis.Error>;\n};\n\n/** Client configuration: transport, defaults, retry policy, middleware, and credentials. */\nexport type ClientConfig<Op extends OperationContext = OperationContext> = {\n  serverUrl?: string;\n  fetch?: typeof fetch;\n  headers?:\n    | Record<string, string>\n    | (() => Record<string, string> | Promise<Record<string, string>>);\n  retry?: RetryConfig<Op>;\n  middleware?: Middleware<Op>[];\n  auth?: AuthCredentials;\n  /** Fixed at generate time by the generator (`'throw'` when omitted); `configure()` ignores it. */\n  errorMode?: 'throw' | 'result';\n  onRequest?: Middleware<Op>['onRequest'];\n  onResponse?: Middleware<Op>['onResponse'];\n  onError?: Middleware<Op>['onError'];\n};\n\n/** Response readers for the per-call `parseAs` override. */\nexport type ParseAs = 'auto' | 'json' | 'text' | 'blob' | 'arrayBuffer' | 'formData' | 'stream';\n\n/** Per-call options: standard `RequestInit` plus a retry override and a forced reader. */\nexport type RequestOptions = RequestInit & { retry?: RetryConfig; parseAs?: ParseAs };\n\n/** Per-call options for an SSE stream; reconnect defaults to true. */\nexport type SseOptions = RequestInit & { reconnect?: boolean; reconnectDelay?: number };\n\n/** A single decoded Server-Sent Event with its payload typed from the spec. */\nexport type ServerSentEvent<T> = { event?: string; data: T; id?: string; retry?: number };\n\n/** Result-mode return shape: exactly one of `data`/`error` is set. */\nexport type Result<TData, TError> =\n  | { data: TData; error: undefined; response: Response }\n  | { data: undefined; error: TError; response: Response };\n\n/**\n * The generated `Ops` type's shape: per-operation args/result, plus `kind: 'sse'` for\n * streams and, for paginated operations, `item` (the page's element type) and — on\n * result-mode clients only — `page` (the RAW page type `.pages()` yields, since\n * iteration unwraps the `Result` envelope the one-shot `result` carries).\n */\nexport type OpsShape = Record<\n  string,\n  { args: object; result: unknown; kind?: 'sse'; item?: unknown; page?: unknown }\n>;\n\n/** The always-present client members (assigned after the operation loop — they win collisions). */\nexport type ClientCore<Op extends OperationContext = OperationContext> = {\n  /** Merge into the config; note `middleware` REPLACES the chain (use `use()` to compose). */\n  configure(config: ClientConfig<Op>): void;\n  /** Append interceptors (composes with baked/publisher middleware). */\n  use(...middleware: Middleware<Op>[]): void;\n  auth: {\n    bearer(token: TokenProvider): void;\n    basic(username: string, password: string): void;\n    apiKey(scheme: string, value: TokenProvider): void;\n  };\n};\n\n/**\n * The standard TypeScript optionality probe: `{}` has no required members, so\n * `{} extends A` is true exactly when every member of `A` is optional.\n */\n// oxlint-disable-next-line typescript/no-empty-object-type\ntype NoRequiredKeys<A> = {} extends A ? true : false;\n\n/**\n * The page type `.pages()` yields: the RAW page declared by `page` (the generator\n * writes it only on result-mode paginated entries, whose `result` is the envelope),\n * or the method's own `result` (throw mode — already the raw page).\n */\ntype PageOf<Entry extends OpsShape[string]> = Entry extends { page: unknown }\n  ? Entry['page']\n  : Entry['result'];\n\n/**\n * The auto-pagination members intersected onto a paginated method — present exactly when\n * the Ops entry declares `item` (the generator writes it only for paginated operations).\n * Args optionality mirrors the method's own; `unknown` otherwise (identity under `&`).\n * Iteration is error-mode-agnostic: `.pages()`/`.items()` yield raw pages/items, and a\n * failed page aborts iteration by throwing `ApiError`, even on result-mode clients; the\n * `onError` middleware hook (throw-mode-only) is not invoked.\n */\ntype Paginated<Entry extends OpsShape[string]> = 'item' extends keyof Entry\n  ? NoRequiredKeys<Entry['args']> extends true\n    ? {\n        pages(args?: Entry['args'], init?: RequestOptions): AsyncGenerator<PageOf<Entry>>;\n        items(args?: Entry['args'], init?: RequestOptions): AsyncGenerator<Entry['item']>;\n      }\n    : {\n        pages(args: Entry['args'], init?: RequestOptions): AsyncGenerator<PageOf<Entry>>;\n        items(args: Entry['args'], init?: RequestOptions): AsyncGenerator<Entry['item']>;\n      }\n  : unknown;\n\n/** The typed instance client: one bound method per operation plus the core members. */\nexport type Client<Ops extends OpsShape, Op extends OperationContext = OperationContext> = {\n  [K in keyof Ops]: Ops[K] extends { kind: 'sse' }\n    ? NoRequiredKeys<Ops[K]['args']> extends true\n      ? (\n          args?: Ops[K]['args'],\n          init?: SseOptions\n        ) => AsyncGenerator<ServerSentEvent<Ops[K]['result']>>\n      : (\n          args: Ops[K]['args'],\n          init?: SseOptions\n        ) => AsyncGenerator<ServerSentEvent<Ops[K]['result']>>\n    : (NoRequiredKeys<Ops[K]['args']> extends true\n        ? (args?: Ops[K]['args'], init?: RequestOptions) => Promise<Ops[K]['result']>\n        : (args: Ops[K]['args'], init?: RequestOptions) => Promise<Ops[K]['result']>) &\n        Paginated<Ops[K]>;\n} & ClientCore<Op>;\n",
+  'errors.ts':
+    "/** The error thrown (throw mode) for a non-2xx response, carrying the decoded error body. */\nexport class ApiError extends Error {\n  public readonly url: string;\n  public readonly status: number;\n  public readonly statusText: string;\n  public readonly body: unknown;\n  constructor(url: string, status: number, statusText: string, body: unknown) {\n    super(`Request failed with status ${status}`);\n    this.name = 'ApiError';\n    this.url = url;\n    this.status = status;\n    this.statusText = statusText;\n    this.body = body;\n  }\n}\n\n/** The error to throw for an aborted request: the caller's abort reason when it is an Error. */\n// `globalThis.Error` (not bare `Error`) so a spec schema named `Error` cannot shadow it\n// when this module is embedded alongside generated types (inline mode).\nexport function abortError(signal: AbortSignal): globalThis.Error {\n  const reason = (signal as { reason?: unknown }).reason;\n  if (reason instanceof Error) return reason;\n  return new DOMException('The operation was aborted.', 'AbortError');\n}\n",
+  'url.ts':
+    "import type { ParamSpec, QueryValue } from './types.js';\n\n/**\n * The RESOLVED OpenAPI serialization spec for one query parameter — callers apply the\n * OpenAPI defaults (`style: 'form'`, `explode: true`) before building one.\n */\nexport type QueryStyle = {\n  style: NonNullable<ParamSpec['style']>;\n  explode: boolean;\n  allowReserved?: boolean;\n};\n\n/**\n * Encode everything except the RFC-3986 reserved set, for `allowReserved: true` params —\n * `filter=a/b` survives instead of `filter=a%2Fb`.\n */\nexport function encodeReserved(value: string): string {\n  return encodeURIComponent(value).replace(\n    /%(3A|2F|3F|23|5B|5D|40|21|24|26|27|28|29|2A|2B|2C|3B|3D)/g,\n    (match) => decodeURIComponent(match)\n  );\n}\n\n/** Substitute `{name}` template segments with encoded values; a missing value is a caller bug. */\nexport function substitutePath(template: string, values: Record<string, unknown>): string {\n  return template.replace(/\\{([^{}]+)\\}/g, (_match, name: string) => {\n    const value = values[name];\n    if (value === undefined) throw new Error(`Missing path parameter \"${name}\"`);\n    return encodeURIComponent(String(value));\n  });\n}\n\n/**\n * Build the request URL: `serverUrl` (trailing slash trimmed) + path + serialized query.\n * Query parameters honor their OpenAPI `style`/`explode`/`allowReserved` (from `styles`);\n * without a spec, arrays repeat the key (`form`+`explode`), objects serialize as\n * `deepObject` brackets, and `null`/`undefined` entries are skipped.\n */\nexport function buildUrl(\n  serverUrl: string,\n  path: string,\n  query?: Record<string, QueryValue>,\n  styles?: Record<string, QueryStyle>\n): string {\n  // Trim trailing slashes with a scan, not `/\\/+$/` — an anchored `+` regex is\n  // quadratic on adversarial many-slash input (the server URL is caller data).\n  let end = serverUrl.length;\n  while (end > 0 && serverUrl.charCodeAt(end - 1) === 47 /* '/' */) end--;\n  const url = serverUrl.slice(0, end) + path;\n  if (!query) return url;\n  const params = new URLSearchParams();\n  const raw: string[] = [];\n  for (const [key, value] of Object.entries(query)) {\n    if (value === undefined || value === null) continue;\n    const spec = styles?.[key];\n    if (!spec) {\n      if (Array.isArray(value)) {\n        for (const v of value) {\n          if (v !== undefined && v !== null) params.append(key, String(v));\n        }\n      } else if (Object(value) === value) {\n        // Object-valued query params use `deepObject` style: key[subKey]=subValue.\n        for (const [subKey, subValue] of Object.entries(value)) {\n          if (subValue !== undefined && subValue !== null) {\n            params.append(`${key}[${subKey}]`, String(subValue));\n          }\n        }\n      } else {\n        params.append(key, String(value));\n      }\n      continue;\n    }\n    if (Array.isArray(value)) {\n      const items = value.filter((v) => v !== undefined && v !== null).map(String);\n      if (spec.style === 'form' && spec.explode) {\n        for (const v of items) {\n          if (spec.allowReserved) raw.push(`${key}=${encodeReserved(v)}`);\n          else params.append(key, v);\n        }\n      } else {\n        // Delimited styles put the LITERAL delimiter on the wire; only the\n        // values are encoded. `%20` (not `+`) is the literal space delimiter.\n        const delim =\n          spec.style === 'pipeDelimited' ? '|' : spec.style === 'spaceDelimited' ? '%20' : ',';\n        const enc = spec.allowReserved ? encodeReserved : encodeURIComponent;\n        raw.push(`${encodeURIComponent(key)}=${items.map(enc).join(delim)}`);\n      }\n    } else if (Object(value) === value) {\n      // `deepObject` (and any object spec, for now): key[subKey]=subValue.\n      for (const [subKey, subValue] of Object.entries(value)) {\n        if (subValue !== undefined && subValue !== null) {\n          if (spec.allowReserved) raw.push(`${key}[${subKey}]=${encodeReserved(String(subValue))}`);\n          else params.append(`${key}[${subKey}]`, String(subValue));\n        }\n      }\n    } else if (spec.allowReserved) {\n      raw.push(`${key}=${encodeReserved(String(value))}`);\n    } else {\n      params.append(key, String(value));\n    }\n  }\n  const qs = [params.toString(), ...raw].filter(Boolean).join('&');\n  return qs ? `${url}?${qs}` : url;\n}\n",
+  'parse.ts':
+    "import type { ParseAs } from './types.js';\n\n/**\n * Read the response body per `kind`. `'auto'` negotiates from the content type\n * (JSON, then `text/*`, then Blob); `'void'` and `204` responses read nothing.\n */\nexport async function parse(response: Response, kind: ParseAs | 'void'): Promise<unknown> {\n  if (kind === 'void' || response.status === 204) return undefined;\n  if (kind === 'stream') return response.body;\n  if (kind === 'blob') return response.blob();\n  if (kind === 'arrayBuffer') return response.arrayBuffer();\n  if (kind === 'formData') return response.formData();\n  if (kind === 'text') return response.text();\n  if (kind === 'json') return response.json();\n  // 'auto' — negotiate from the response's content type (case-insensitively:\n  // `Text/Plain` and `application/JSON` are valid per RFC 9110).\n  const contentType = (response.headers.get('content-type') ?? '').toLowerCase();\n  if (contentType.includes('json')) return response.json();\n  if (contentType.startsWith('text/')) return response.text();\n  return response.blob();\n}\n\n/** Best-effort decode of a non-2xx body (JSON when declared, else text; undefined on failure). */\nexport async function readError(response: Response): Promise<unknown> {\n  const contentType = response.headers.get('content-type') ?? '';\n  if (contentType.toLowerCase().includes('json')) {\n    return response.json().catch(() => undefined);\n  }\n  return response.text().catch(() => undefined);\n}\n",
+  'retry.ts':
+    "import { abortError } from './errors.js';\nimport type { RetryConfig, RetryContext } from './types.js';\n\nconst IDEMPOTENT_METHODS = new Set(['GET', 'HEAD', 'PUT', 'DELETE', 'OPTIONS']);\nconst TRANSIENT_STATUS = new Set([408, 429, 500, 502, 503, 504]);\n\n/**\n * The default retry predicate: idempotent methods only, on a transport error or a\n * transient status. A custom `retryOn` fully replaces this (no method check kept).\n */\nexport function defaultRetryOn(ctx: RetryContext): boolean {\n  if (!IDEMPOTENT_METHODS.has(ctx.request.method.toUpperCase())) return false;\n  return ctx.response === undefined || TRANSIENT_STATUS.has(ctx.response.status);\n}\n\n/**\n * The delay before the next attempt: a `Retry-After` header (seconds or HTTP-date)\n * wins; otherwise fixed/exponential backoff over `retryDelay`, with full jitter\n * unless `jitter === false`.\n */\nexport function retryDelay(retry: RetryConfig, attempt: number, retryAfter: string | null): number {\n  if (retryAfter) {\n    const seconds = Number(retryAfter);\n    if (!Number.isNaN(seconds)) return seconds * 1000;\n    const when = Date.parse(retryAfter);\n    if (!Number.isNaN(when)) return Math.max(0, when - Date.now());\n  }\n  const base = retry.retryDelay ?? 1000;\n  const raw = retry.retryStrategy === 'fixed' ? base : base * Math.pow(2, attempt - 1);\n  return retry.jitter === false ? raw : Math.random() * raw;\n}\n\n/** Abort-aware sleep: resolves after `ms`, rejects with the abort reason immediately on abort. */\nexport function sleep(ms: number, signal?: AbortSignal): Promise<void> {\n  return new Promise((resolve, reject) => {\n    if (signal?.aborted) {\n      reject(abortError(signal));\n      return;\n    }\n    const onAbort = () => {\n      clearTimeout(timer);\n      reject(abortError(signal as AbortSignal));\n    };\n    const timer = setTimeout(() => {\n      if (signal) signal.removeEventListener('abort', onAbort);\n      resolve();\n    }, ms);\n    if (signal) signal.addEventListener('abort', onAbort, { once: true });\n  });\n}\n",
+  'multipart.ts':
+    "/**\n * Serialize a plain object into `FormData` for a typed `multipart/form-data` body\n * (capability module — wired into `createClient`, never imported by the send core).\n * `Blob`/`File` and strings pass through; `Date`s become ISO strings; arrays append\n * one field per item; other objects are JSON-encoded; everything else is stringified.\n * `undefined`/`null` entries are skipped.\n */\nexport function toFormData(body: Record<string, unknown>): FormData {\n  const fd = new FormData();\n  const append = (key: string, value: unknown): void => {\n    if (value === undefined || value === null) return;\n    if (value instanceof Blob || typeof value === 'string') fd.append(key, value);\n    else if (value instanceof Date) fd.append(key, value.toISOString());\n    else if (Object(value) === value) fd.append(key, JSON.stringify(value));\n    else fd.append(key, String(value));\n  };\n  for (const [key, value] of Object.entries(body)) {\n    if (Array.isArray(value)) for (const item of value) append(key, item);\n    else append(key, value);\n  }\n  return fd;\n}\n",
+  'auth.ts':
+    "import type { ClientConfig, SecuritySpec, TokenProvider } from './types.js';\n\n/** Resolve a credential: a literal passes through; a function is awaited per request. */\nasync function resolveToken(provider: TokenProvider): Promise<string> {\n  return typeof provider === 'function' ? await provider() : provider;\n}\n\n/** UTF-8-safe base64: bare `btoa` throws on non-Latin-1 credentials (RFC 7617 allows UTF-8). */\nfunction encodeBase64(text: string): string {\n  let binary = '';\n  for (const byte of new TextEncoder().encode(text)) binary += String.fromCharCode(byte);\n  return btoa(binary);\n}\n\n/** Whether a credential for this scheme is configured on the instance. */\nfunction isConfigured(scheme: SecuritySpec, config: ClientConfig): boolean {\n  if (scheme.kind === 'apiKey') return config.auth?.apiKey?.[scheme.scheme] !== undefined;\n  if (scheme.kind === 'bearer') return config.auth?.bearer !== undefined;\n  return config.auth?.basic !== undefined;\n}\n\n/**\n * Build the auth headers/query for one operation's `security` OR-alternatives from the\n * instance credentials (`config.auth`) — capability module, wired into `createClient`.\n * The first alternative whose schemes (an AND-set) are all configured is applied, so\n * \"bearer OR apiKey\" works with either credential and never sends both. When none is\n * fully configured, the first alternative's configured schemes are still sent (the\n * server rejects the request, mirroring the previous behavior).\n * Cookie-borne apiKeys fold into a single `Cookie` header joined with `; `.\n */\nexport async function resolveAuth(\n  security: readonly (readonly SecuritySpec[])[],\n  config: ClientConfig\n): Promise<{ headers: Record<string, string>; query: Record<string, string> }> {\n  const alternative =\n    security.find((schemes) => schemes.every((scheme) => isConfigured(scheme, config))) ??\n    security[0] ??\n    [];\n  const headers: Record<string, string> = {};\n  const query: Record<string, string> = {};\n  const cookies: string[] = [];\n  for (const scheme of alternative) {\n    if (scheme.kind === 'apiKey') {\n      const provider = config.auth?.apiKey?.[scheme.scheme];\n      if (provider === undefined) continue;\n      const value = await resolveToken(provider);\n      if (scheme.in === 'header') headers[scheme.name] = value;\n      else if (scheme.in === 'query') query[scheme.name] = value;\n      // Cookie values may contain reserved characters (`;`, `=`, space, …); percent-encode\n      // so the credential can't break the `Cookie` header syntax.\n      else cookies.push(`${scheme.name}=${encodeURIComponent(value)}`);\n    } else if (scheme.kind === 'bearer') {\n      const provider = config.auth?.bearer;\n      if (provider !== undefined) headers.Authorization = `Bearer ${await resolveToken(provider)}`;\n    } else {\n      const basic = config.auth?.basic;\n      if (basic !== undefined) {\n        headers.Authorization = `Basic ${encodeBase64(`${basic.username}:${basic.password}`)}`;\n      }\n    }\n  }\n  if (cookies.length > 0) headers.Cookie = cookies.join('; ');\n  return { headers, query };\n}\n",
+  'setup.ts':
+    "import type { ClientConfig, Middleware } from './types.js';\n\n/**\n * Merge a publisher's baked setup (`defineClientSetup({...})`) with the app's config:\n * app config fields win per-field over baked defaults, while middleware composes —\n * baked middleware runs first, then the app's.\n */\nexport function mergeSetup(\n  setup: { config?: ClientConfig; middleware?: Middleware[] } | undefined,\n  config: ClientConfig = {}\n): ClientConfig {\n  return {\n    ...setup?.config,\n    ...config,\n    middleware: [...(setup?.middleware ?? []), ...(config.middleware ?? [])],\n  };\n}\n",
+  'send.ts':
+    "import { abortError } from './errors.js';\nimport { defaultRetryOn, retryDelay, sleep } from './retry.js';\nimport type {\n  ClientConfig,\n  Middleware,\n  OperationContext,\n  RequestContext,\n  RequestOptions,\n  RetryConfig,\n} from './types.js';\n\n/**\n * Optional behaviors the send core can use but never statically imports — wired by\n * `createClient` (the same seam the future inline-mode assembler relies on).\n */\nexport type SendCapabilities = {\n  /** Serialize a typed multipart body (a plain object) to FormData. */\n  serializeMultipart?: (body: Record<string, unknown>) => FormData;\n};\n\n/**\n * Normalize a caller's `HeadersInit` (plain record, `Headers` instance, or entry pairs)\n * to a plain record — spreading a `Headers` or an array contributes no entries.\n */\nexport function toHeaderRecord(headers: HeadersInit | undefined): Record<string, string> {\n  if (headers === undefined) return {};\n  if (headers instanceof Headers) {\n    const record: Record<string, string> = {};\n    headers.forEach((value, key) => {\n      record[key] = value;\n    });\n    return record;\n  }\n  if (Array.isArray(headers)) return Object.fromEntries(headers);\n  return headers;\n}\n\n/**\n * The effective middleware chain for a request: the single `onRequest`/`onResponse`/\n * `onError` config hooks as one implicit first middleware, then `config.middleware`.\n */\nexport function middlewareChain(config: ClientConfig): Middleware[] {\n  const single =\n    config.onRequest || config.onResponse || config.onError\n      ? [{ onRequest: config.onRequest, onResponse: config.onResponse, onError: config.onError }]\n      : [];\n  return [...single, ...(config.middleware ?? [])];\n}\n\n/**\n * The fetch core shared by every operation: default + config + per-call headers, the\n * `onRequest` chain (BEFORE body serialization, so mutations are sent), body\n * serialization (JSON, or FormData via the multipart capability), the retry loop\n * (idempotent-only defaults, `Retry-After`, abandoned-body drain), and the reverse\n * `onResponse` onion. Returns the final response plus the request context.\n */\nexport async function send(\n  config: ClientConfig,\n  op: OperationContext,\n  url: string,\n  init: RequestOptions,\n  body: unknown | undefined,\n  multipart: boolean,\n  caps: SendCapabilities\n): Promise<{ response: Response; context: RequestContext }> {\n  const { retry: callRetry, ...fetchInit } = init;\n  const retry: RetryConfig = { ...config.retry, ...callRetry };\n  const extra = typeof config.headers === 'function' ? await config.headers() : config.headers;\n  const headers: Record<string, string> = {\n    Accept: 'application/json',\n    ...extra,\n    ...toHeaderRecord(fetchInit.headers),\n  };\n  const context: RequestContext = {\n    url,\n    method: fetchInit.method ?? 'GET',\n    headers,\n    body,\n    operation: op,\n  };\n  const middleware = middlewareChain(config);\n  for (const mw of middleware) if (mw.onRequest) await mw.onRequest(context);\n  // Serialize AFTER onRequest so body mutations (case conversion, enveloping, signing) take effect.\n  let payload: BodyInit | undefined;\n  if (context.body !== undefined) {\n    const value = context.body;\n    const isBinary =\n      value instanceof Blob ||\n      value instanceof ArrayBuffer ||\n      ArrayBuffer.isView(value as ArrayBufferView);\n    const isFormData = typeof FormData !== 'undefined' && value instanceof FormData;\n    const isURLSearchParams = value instanceof URLSearchParams;\n    if (isFormData || isURLSearchParams || isBinary || typeof value === 'string') {\n      payload = value as BodyInit;\n    } else if (multipart) {\n      if (!caps.serializeMultipart) {\n        throw new Error('Multipart capability not wired: cannot serialize the request body');\n      }\n      payload = caps.serializeMultipart(value as Record<string, unknown>);\n    } else {\n      payload = JSON.stringify(value);\n      if (!('Content-Type' in context.headers) && !('content-type' in context.headers)) {\n        context.headers['Content-Type'] = 'application/json';\n      }\n    }\n  }\n  const doFetch = config.fetch ?? fetch;\n  const maxAttempts = 1 + (retry.retries ?? 0);\n  const retryOn = retry.retryOn ?? defaultRetryOn;\n  const signal = fetchInit.signal ?? undefined;\n\n  let attempt = 0;\n  while (true) {\n    attempt++;\n    if (signal?.aborted) throw abortError(signal);\n    let response: Response;\n    try {\n      response = await doFetch(context.url, {\n        ...fetchInit,\n        method: context.method,\n        headers: context.headers,\n        body: payload,\n      });\n    } catch (error) {\n      if (\n        attempt < maxAttempts &&\n        !signal?.aborted &&\n        (await retryOn({ attempt, request: context, error }))\n      ) {\n        await sleep(retryDelay(retry, attempt, null), signal);\n        continue;\n      }\n      throw error;\n    }\n    // Reverse order: the last-registered middleware wraps closest to the network (onion).\n    for (let i = middleware.length - 1; i >= 0; i--) {\n      const onResponse = middleware[i].onResponse;\n      if (onResponse) {\n        const replaced = await onResponse(response, context);\n        if (replaced && replaced !== response) {\n          // Cancel the abandoned original's body — like the retry path, an unread body\n          // keeps its connection checked out under Node/undici.\n          await response.body?.cancel().catch(() => undefined);\n          response = replaced;\n        }\n      }\n    }\n    if (\n      !response.ok &&\n      attempt < maxAttempts &&\n      !signal?.aborted &&\n      (await retryOn({ attempt, request: context, response }))\n    ) {\n      const retryAfter = response.headers.get('retry-after');\n      // Drain the abandoned response body before the next attempt: an unread body\n      // keeps the connection checked out (and can stall the pool) under Node/undici\n      // and other strict HTTP clients. Ignore errors (e.g. a middleware already read it).\n      await response.body?.cancel().catch(() => undefined);\n      await sleep(retryDelay(retry, attempt, retryAfter), signal);\n      continue;\n    }\n    return { response, context };\n  }\n}\n",
+  'sse.ts':
+    "import { ApiError } from './errors.js';\nimport { readError } from './parse.js';\nimport { sleep } from './retry.js';\nimport { send, toHeaderRecord } from './send.js';\nimport type { ClientConfig, OperationContext, ServerSentEvent, SseOptions } from './types.js';\n\n/**\n * A frame delimiter: two consecutive line terminators (each CR, LF, or CRLF, per the SSE\n * spec — so mixed endings like `\\n\\r\\n` are valid boundaries, not just matching pairs).\n */\nconst FRAME_DELIMITER = /(?:\\r\\n|\\r|\\n){2}/;\n\n/**\n * A terminally malformed event stream — unparseable JSON `data` or an unbounded frame.\n * A stable bad payload, not a dropped connection, so the stream never reconnects on it.\n */\nexport class SseParseError extends Error {}\n\n/**\n * Consume a `text/event-stream` operation as typed events (capability module — wired\n * into `createClient`). Auto-reconnects on dropped connections, resuming from the last\n * seen event id via `Last-Event-ID` (backoff: the server's `retry:` value, then\n * `reconnectDelay`, then 1s — exponential with jitter, capped at 30s). A clean stream\n * end flushes a trailing frame and finishes; `break`/abort end the iterator cleanly.\n */\nexport async function* sse<T>(\n  config: ClientConfig,\n  op: OperationContext,\n  prepare: () => Promise<{ url: string; init: SseOptions; body?: unknown }>,\n  dataKind: 'json' | 'text' = 'text'\n): AsyncGenerator<ServerSentEvent<T>> {\n  let lastEventId: string | undefined;\n  let serverRetry: number | undefined;\n  let failures = 0;\n  while (true) {\n    // Re-prepare each attempt so a refresh-style TokenProvider yields a fresh credential\n    // on reconnect (the auth is baked into `url` query + `init.headers`). `reconnect`,\n    // `reconnectDelay`, and `signal` come from the caller's original options unchanged.\n    const { url, init, body: requestBody } = await prepare();\n    const { reconnect = true, reconnectDelay, ...rest } = init;\n    const signal = rest.signal ?? undefined;\n    if (signal?.aborted) return;\n    const headers: Record<string, string> = {\n      Accept: 'text/event-stream',\n      ...toHeaderRecord(rest.headers),\n    };\n    const sendHeaders =\n      lastEventId === undefined ? headers : { ...headers, 'Last-Event-ID': lastEventId };\n    try {\n      const { response } = await send(\n        config,\n        op,\n        url,\n        { ...rest, method: rest.method ?? 'GET', headers: sendHeaders },\n        requestBody,\n        false,\n        {}\n      );\n      if (!response.ok) {\n        const errorBody = await readError(response);\n        throw new ApiError(url, response.status, response.statusText, errorBody);\n      }\n      failures = 0;\n      const body = response.body;\n      if (!body) return;\n      const reader = body.getReader();\n      const decoder = new TextDecoder();\n      let buffer = '';\n      try {\n        while (true) {\n          const { done, value } = await reader.read();\n          buffer += done ? decoder.decode() : decoder.decode(value, { stream: true });\n          let match: RegExpMatchArray | null;\n          while ((match = buffer.match(FRAME_DELIMITER)) !== null) {\n            const index = match.index!;\n            const raw = buffer.slice(0, index);\n            buffer = buffer.slice(index + match[0].length);\n            const event = parseSseFrame(raw, dataKind);\n            if (event) {\n              if (event.id !== undefined) lastEventId = event.id;\n              if (event.retry !== undefined) serverRetry = event.retry;\n              yield event as ServerSentEvent<T>;\n            }\n          }\n          if (done) {\n            // Stream closed cleanly. Flush a final event that arrived without a trailing\n            // delimiter, then finish — a clean end is not a dropped connection, so do not reconnect.\n            const event = buffer.length > 0 ? parseSseFrame(buffer, dataKind) : undefined;\n            if (event) {\n              if (event.id !== undefined) lastEventId = event.id;\n              if (event.retry !== undefined) serverRetry = event.retry;\n              yield event as ServerSentEvent<T>;\n            }\n            return;\n          }\n          // Bound memory: a server that never sends a frame delimiter would otherwise\n          // grow `buffer` without limit. 1 MiB is far above any real SSE frame.\n          if (buffer.length > 1048576) {\n            throw new SseParseError('SSE frame exceeded 1048576 characters without a delimiter');\n          }\n        }\n      } finally {\n        await reader.cancel().catch(() => undefined);\n      }\n    } catch (error) {\n      if (signal?.aborted) return;\n      // A non-OK HTTP response (4xx/5xx) or an unparseable JSON payload is a definitive\n      // error, not a transient drop — surface it instead of reconnecting in a loop (a\n      // stable bad payload would otherwise reconnect forever).\n      if (error instanceof ApiError || error instanceof SseParseError) throw error;\n      // A transport failure (connect/DNS/reset) when opening the request, or a mid-stream\n      // read error, is a dropped connection: fall through to backoff/reconnect when enabled.\n      if (!reconnect) throw error;\n    }\n    // Only the swallowed-drop path reaches here: reconnect is on and the signal not aborted.\n    failures++;\n    const base = serverRetry ?? reconnectDelay ?? 1000;\n    const delay = Math.min(base * Math.pow(2, failures - 1), 30_000);\n    try {\n      await sleep(Math.random() * delay, signal);\n    } catch {\n      return; // sleep rejects only on abort — end the iterator cleanly\n    }\n  }\n}\n\n/** Parse one raw SSE frame (its lines) into an event; returns undefined for comment-only frames. */\nexport function parseSseFrame(\n  raw: string,\n  dataKind: 'json' | 'text'\n): ServerSentEvent<unknown> | undefined {\n  let event: string | undefined;\n  const dataLines: string[] = [];\n  let id: string | undefined;\n  let retry: number | undefined;\n  let sawField = false;\n  for (const line of raw.split(/\\r\\n|\\n|\\r/)) {\n    if (line === '' || line.startsWith(':')) continue;\n    const colon = line.indexOf(':');\n    const field = colon === -1 ? line : line.slice(0, colon);\n    let val = colon === -1 ? '' : line.slice(colon + 1);\n    if (val.startsWith(' ')) val = val.slice(1);\n    sawField = true;\n    if (field === 'event') event = val;\n    else if (field === 'data') dataLines.push(val);\n    else if (field === 'id') id = val;\n    else if (field === 'retry') {\n      const n = Number(val);\n      if (!Number.isNaN(n)) retry = n;\n    }\n  }\n  if (!sawField) return undefined;\n  const dataText = dataLines.join('\\n');\n  let data: unknown = dataText;\n  if (dataKind === 'json' && dataText !== '') {\n    try {\n      data = JSON.parse(dataText);\n    } catch (error) {\n      throw new SseParseError(\n        `Failed to parse SSE event data as JSON: ${error instanceof Error ? error.message : String(error)}`\n      );\n    }\n  }\n  return { event, data, id, retry };\n}\n",
+  'create-client.ts':
+    "import { ApiError } from './errors.js';\nimport { parse, readError } from './parse.js';\nimport { middlewareChain, send, toHeaderRecord, type SendCapabilities } from './send.js';\nimport type {\n  ApiErrorLike,\n  Client,\n  ClientConfig,\n  Middleware,\n  OperationContext,\n  OperationDescriptor,\n  OpsShape,\n  PaginationSpec,\n  ParseAs,\n  QueryValue,\n  RequestOptions,\n  SecuritySpec,\n  ServerSentEvent,\n  SseOptions,\n  TokenProvider,\n} from './types.js';\nimport { buildUrl, substitutePath, type QueryStyle } from './url.js';\n\n/**\n * The optional behaviors `createClientCore` can dispatch to but never statically\n * imports. The package's public `createClient` wires the full set; the future\n * inline-mode assembler wires only the capabilities a spec needs.\n */\nexport type Capabilities = SendCapabilities & {\n  resolveAuth?: (\n    security: readonly (readonly SecuritySpec[])[],\n    config: ClientConfig\n  ) => Promise<{ headers: Record<string, string>; query: Record<string, string> }>;\n  sse?: (\n    config: ClientConfig,\n    op: OperationContext,\n    // Re-preparing per (re)connect (not a frozen url/init) lets a refresh-style\n    // TokenProvider issue a fresh credential after a dropped stream reconnects.\n    prepare: () => Promise<{ url: string; init: SseOptions }>,\n    dataKind: 'json' | 'text'\n  ) => AsyncGenerator<ServerSentEvent<unknown>>;\n  paginate?: {\n    pages: (\n      call: (args?: OperationArgs, init?: RequestOptions) => Promise<unknown>,\n      spec: PaginationSpec,\n      args?: OperationArgs,\n      init?: RequestOptions\n    ) => AsyncGenerator<unknown>;\n    items: (\n      call: (args?: OperationArgs, init?: RequestOptions) => Promise<unknown>,\n      spec: PaginationSpec,\n      args?: OperationArgs,\n      init?: RequestOptions\n    ) => AsyncGenerator<unknown>;\n  };\n};\n\n/** The grouped args wire shape: path params by name plus the `params`/`body`/`headers`/`cookies` slots. */\nexport type OperationArgs = {\n  params?: Record<string, QueryValue>;\n  body?: unknown;\n  headers?: Record<string, unknown>;\n  cookies?: Record<string, unknown>;\n} & Record<string, unknown>;\n\n/** The response reader implied by the descriptor (before any per-call `parseAs` override). */\nfunction kindFor(op: OperationDescriptor): ParseAs | 'void' {\n  if (op.responseKind === 'void' || op.responseKind === 'blob' || op.responseKind === 'text') {\n    return op.responseKind;\n  }\n  return 'auto';\n}\n\n/** Route the grouped args by the descriptor: path values, query object, body, extra headers, cookies. */\nfunction splitArgs(op: OperationDescriptor, args: OperationArgs) {\n  const path: Record<string, unknown> = {};\n  for (const param of op.params ?? []) {\n    if (param.in === 'path') path[param.name] = args[param.name];\n  }\n  return {\n    path,\n    query: args.params,\n    body: args.body,\n    headers: args.headers,\n    cookies: args.cookies,\n  };\n}\n\n/**\n * The query-serialization hints for the descriptor's query params. A spec is built only\n * when the param deviates from the OpenAPI defaults (`form` + `explode: true`, encoded),\n * and always fully resolved — so `explode: false` or `allowReserved` alone (no `style`)\n * are honored, and an omitted `explode` keeps the exploded default.\n */\nfunction queryStyles(op: OperationDescriptor): Record<string, QueryStyle> | undefined {\n  let styles: Record<string, QueryStyle> | undefined;\n  for (const param of op.params ?? []) {\n    if (param.in !== 'query') continue;\n    const deviates =\n      (param.style !== undefined && param.style !== 'form') ||\n      param.explode === false ||\n      param.allowReserved === true;\n    if (!deviates) continue;\n    styles ??= {};\n    styles[param.name] = {\n      style: param.style ?? 'form',\n      explode: param.explode ?? true,\n      allowReserved: param.allowReserved,\n    };\n  }\n  return styles;\n}\n\n/** Stringify caller-supplied extra headers, skipping empty entries. */\nfunction stringHeaders(headers: Record<string, unknown> | undefined): Record<string, string> {\n  const out: Record<string, string> = {};\n  for (const [key, value] of Object.entries(headers ?? {})) {\n    if (value !== undefined && value !== null) out[key] = String(value);\n  }\n  return out;\n}\n\n/** Build the request pieces an attempt needs: the final URL and the merged per-call init. */\nasync function prepareRequest(\n  config: ClientConfig,\n  op: OperationDescriptor,\n  args: OperationArgs,\n  init: RequestOptions | SseOptions,\n  caps: Capabilities\n): Promise<{ url: string; init: RequestOptions; body: unknown }> {\n  const { path, query, body, headers, cookies } = splitArgs(op, args);\n  const authed: { headers: Record<string, string>; query: Record<string, string> } =\n    op.security?.length && caps.resolveAuth\n      ? await caps.resolveAuth(op.security, config)\n      : { headers: {}, query: {} };\n  // Cookie params join the auth-injected cookies in one `Cookie` header (values\n  // percent-encoded, like auth cookies). Server-side only — browsers own the header.\n  const cookiePairs = Object.entries(cookies ?? {})\n    .filter(([, value]) => value !== undefined && value !== null)\n    .map(([cookieName, value]) => `${cookieName}=${encodeURIComponent(String(value))}`);\n  if (cookiePairs.length > 0) {\n    authed.headers.Cookie = [authed.headers.Cookie, ...cookiePairs].filter(Boolean).join('; ');\n  }\n  const fullQuery: Record<string, QueryValue> = { ...query, ...authed.query };\n  const url = buildUrl(\n    config.serverUrl ?? '',\n    substitutePath(op.path, path),\n    Object.keys(fullQuery).length > 0 ? fullQuery : undefined,\n    queryStyles(op)\n  );\n  const mergedInit: RequestOptions = {\n    ...init,\n    method: op.method.toUpperCase(),\n    // Precedence, lowest → highest (later spreads win): injected auth → explicit\n    // header params → caller `init.headers` — the caller always overrides both.\n    headers: {\n      ...authed.headers,\n      ...stringHeaders(headers),\n      ...toHeaderRecord(init.headers),\n    },\n  };\n  return { url, init: mergedInit, body };\n}\n\n/** One non-SSE call: send, then branch on the configured error mode. */\nasync function execute(\n  config: ClientConfig,\n  op: OperationDescriptor,\n  args: OperationArgs,\n  init: RequestOptions,\n  caps: Capabilities\n): Promise<unknown> {\n  const prepared = await prepareRequest(config, op, args, init, caps);\n  const opCtx: OperationContext = { id: op.id, path: op.path, tags: [...(op.tags ?? [])] };\n  const { parseAs, ...sendInit } = prepared.init;\n  const { response, context } = await send(\n    config,\n    opCtx,\n    prepared.url,\n    sendInit,\n    prepared.body,\n    op.body?.multipart === true,\n    caps\n  );\n  const readKind = parseAs ?? kindFor(op);\n  if (config.errorMode === 'result') {\n    if (!response.ok) {\n      return { data: undefined, error: await readError(response), response };\n    }\n    return { data: await parse(response, readKind), error: undefined, response };\n  }\n  if (!response.ok) {\n    let error: globalThis.Error = new ApiError(\n      context.url,\n      response.status,\n      response.statusText,\n      await readError(response)\n    );\n    // Thread the error through each middleware's onError in turn (each may replace it).\n    for (const mw of middlewareChain(config)) {\n      if (mw.onError) error = await mw.onError(error as ApiErrorLike, context);\n    }\n    throw error;\n  }\n  return parse(response, readKind);\n}\n\n/** The paginate capability, or a descriptive throw when a paginated op is iterated unwired. */\nfunction paginateCapability(caps: Capabilities, op: OperationDescriptor) {\n  if (!caps.paginate) {\n    throw new Error(`Pagination capability not wired: cannot iterate operation \"${op.id}\"`);\n  }\n  return caps.paginate;\n}\n\n/**\n * The per-page call the iterators drive: the method itself in throw mode; in result\n * mode a wrapper that unwraps the `{ data, error, response }` envelope — the page\n * pointers are data-rooted — rethrowing a failed page as `ApiError` (iteration is\n * error-mode-agnostic; the throw-mode-only `onError` middleware hook is not invoked).\n */\nfunction pageCall(\n  method: (args?: OperationArgs, init?: RequestOptions) => Promise<unknown>,\n  config: ClientConfig\n) {\n  if (config.errorMode !== 'result') return method;\n  return async (args?: OperationArgs, init?: RequestOptions) => {\n    const envelope = (await method(args, init)) as {\n      data: unknown;\n      error: unknown;\n      response: Response;\n    };\n    // Failure is `!response.ok` — NOT `data === undefined`: a successful bodyless page\n    // (204/void) also parses to undefined data, and a failed page's `error` can be\n    // undefined too (unreadable body). The pointers then miss on the undefined data\n    // and iteration stops cleanly, which is the correct semantics for an empty page.\n    if (!envelope.response.ok) {\n      const { response } = envelope;\n      throw new ApiError(response.url, response.status, response.statusText, envelope.error);\n    }\n    return envelope.data;\n  };\n}\n\n/**\n * Build a typed instance client over operation descriptors: one real bound method per\n * operation (attached by a construction-time loop — no Proxy), plus the core members\n * (`configure`/`use`/`auth`), which are assigned AFTER the loop so they win any name\n * collision with an operation. All behavior dispatches through the capability seam.\n */\nexport function createClientCore<\n  Ops extends OpsShape,\n  Id extends string = string,\n  Path extends string = string,\n  Tag extends string = string,\n>(\n  operations: Record<string, OperationDescriptor>,\n  initial: ClientConfig<OperationContext<Id, Path, Tag>> = {},\n  caps: Capabilities = {}\n): Client<Ops, OperationContext<Id, Path, Tag>> {\n  // The literal-union narrowing is a compile-time DX contract only; internally the\n  // runtime works with the base (string-typed) context. One cast at this boundary —\n  // `ClientConfig<Narrow>` is not assignable to `ClientConfig` (middleware ctx\n  // params are contravariant).\n  const given = initial as ClientConfig;\n  // Private mutable config; the middleware array is copied so `use()` never mutates the caller's.\n  const config: ClientConfig = { ...given, middleware: [...(given.middleware ?? [])] };\n  const client = {} as Record<string, unknown>;\n\n  for (const [name, op] of Object.entries(operations)) {\n    if (op.responseKind === 'sse') {\n      const method = (args: OperationArgs = {}, init: SseOptions = {}) => {\n        if (!caps.sse) {\n          throw new Error(`SSE capability not wired: cannot stream operation \"${op.id}\"`);\n        }\n        const stream = caps.sse;\n        return (async function* () {\n          const opCtx: OperationContext = { id: op.id, path: op.path, tags: [...(op.tags ?? [])] };\n          // A thunk the stream re-runs on every (re)connect, so auth (which `prepareRequest`\n          // resolves) is refreshed per attempt rather than frozen at the first connect.\n          const prepare = async () => {\n            const prepared = await prepareRequest(config, op, args, init, caps);\n            return { url: prepared.url, init: prepared.init as SseOptions, body: prepared.body };\n          };\n          yield* stream(config, opCtx, prepare, op.sseDataKind ?? 'text');\n        })();\n      };\n      // Consumers key off the function reference (cache keys, `OPERATIONS[fn.name]`), so\n      // each closure carries its operationId instead of an inferred binding name.\n      Object.defineProperty(method, 'name', { value: name });\n      client[name] = method;\n    } else {\n      const method = (args: OperationArgs = {}, init: RequestOptions = {}) =>\n        execute(config, op, args, init, caps);\n      Object.defineProperty(method, 'name', { value: name });\n      const spec = op.pagination;\n      // Paginated ops keep their one-shot call and gain `.pages`/`.items`, dispatching\n      // through the capability seam (like SSE: absent capability throws descriptively).\n      // Iteration is error-mode-agnostic: the iterators' pointers are data-rooted, so on\n      // a result-mode client (`errorMode` is fixed at construction — `configure()`\n      // ignores it) each page's envelope is unwrapped before it reaches the capability.\n      // A failed page aborts iteration by throwing ApiError, even on result-mode\n      // clients; the `onError` middleware hook (throw-mode-only) is not invoked.\n      client[name] = spec\n        ? Object.assign(method, {\n            pages: (args?: OperationArgs, init?: RequestOptions) =>\n              paginateCapability(caps, op).pages(pageCall(method, config), spec, args, init),\n            items: (args?: OperationArgs, init?: RequestOptions) =>\n              paginateCapability(caps, op).items(pageCall(method, config), spec, args, init),\n          })\n        : method;\n    }\n  }\n\n  // Core members are assigned AFTER the operation loop — they win over colliding op names.\n  client.configure = (next: ClientConfig): void => {\n    // `errorMode` is fixed at generate time (it shapes the static types); flipping it at\n    // runtime would silently desync return shapes from `Client<Ops>`, so it is ignored.\n    const { errorMode: _fixed, auth, ...rest } = next;\n    Object.assign(config, rest);\n    // `auth` merges into existing credentials (like the `auth.*` setters) rather than\n    // replacing wholesale — so `configure({ auth: { bearer } })` keeps a previously set\n    // basic/apiKey. `apiKey` merges per scheme.\n    if (auth) {\n      config.auth = {\n        ...config.auth,\n        ...auth,\n        ...(auth.apiKey ? { apiKey: { ...config.auth?.apiKey, ...auth.apiKey } } : {}),\n      };\n    }\n  };\n  client.use = (...middleware: Middleware[]): void => {\n    // Reassign (don't push) so a caller-provided `middleware` array isn't mutated.\n    config.middleware = [...(config.middleware ?? []), ...middleware];\n  };\n  client.auth = {\n    bearer(token: TokenProvider): void {\n      config.auth = { ...config.auth, bearer: token };\n    },\n    basic(username: string, password: string): void {\n      config.auth = { ...config.auth, basic: { username, password } };\n    },\n    apiKey(scheme: string, value: TokenProvider): void {\n      config.auth = { ...config.auth, apiKey: { ...config.auth?.apiKey, [scheme]: value } };\n    },\n  };\n\n  return client as Client<Ops, OperationContext<Id, Path, Tag>>;\n}\n",
+  'paginate.ts':
+    "import type { OperationArgs } from './create-client.js';\nimport type { PaginationSpec, QueryValue, RequestOptions } from './types.js';\n\n/**\n * Auto-pagination (capability module — wired into `createClient`, dispatched by the\n * method's `.pages()`/`.items()`): walk an operation's pages by advancing the descriptor's\n * `param` query parameter, per its `style`. The caller's args are never mutated — each\n * request gets a fresh `params` clone — and `init` is forwarded to every call.\n *\n * Iteration is error-mode-agnostic: `call` always resolves to the RAW page (on a\n * result-mode client the attachment unwraps the envelope first), so a failed page\n * aborts iteration by throwing `ApiError`, even on result-mode clients; the `onError`\n * middleware hook (throw-mode-only) is not invoked.\n */\n\n/**\n * Resolve an RFC 6901 JSON pointer (`~1` → `/`, `~0` → `~`) against a value.\n * The empty pointer is the whole document; anything else must start with `/`.\n * Returns `undefined` on any miss (bad token, absent key, non-object step) — never throws.\n */\nexport function resolvePointer(value: unknown, pointer: string): unknown {\n  if (pointer === '') return value;\n  if (!pointer.startsWith('/')) return undefined;\n  let current = value;\n  for (const token of pointer.slice(1).split('/')) {\n    const key = token.replaceAll('~1', '/').replaceAll('~0', '~');\n    if (Array.isArray(current)) {\n      if (!/^(0|[1-9]\\d*)$/.test(key)) return undefined;\n      current = current[Number(key)];\n    } else if (Object(current) === current && key in (current as object)) {\n      current = (current as Record<string, unknown>)[key];\n    } else {\n      return undefined;\n    }\n  }\n  return current;\n}\n\n/**\n * Iterate an operation's full page results. Every page is yielded before the stop\n * condition is evaluated, so the last page always arrives. Cursor style resumes from a\n * caller-provided `params[spec.param]`, stops when the optional `hasMore` pointer\n * resolves to `false` or when `nextCursor` resolves to `undefined`/`null`/`''`, and\n * throws if the next cursor is not a string or number, or\n * if the same cursor comes back twice in a row (infinite-loop guards). Offset/page\n * styles advance by item count / by one and stop when\n * the `items` pointer misses or the array is empty.\n */\nexport async function* pages<TPage>(\n  call: (args?: OperationArgs, init?: RequestOptions) => Promise<TPage>,\n  spec: PaginationSpec,\n  args: OperationArgs = {},\n  init?: RequestOptions\n): AsyncGenerator<TPage> {\n  if (spec.style === 'cursor') {\n    let cursor: unknown = args.params?.[spec.param];\n    while (true) {\n      const params = { ...args.params };\n      if (cursor !== undefined) params[spec.param] = cursor as QueryValue;\n      const page = await call({ ...args, params }, init);\n      yield page;\n      // Connection-style APIs keep a non-null cursor on the last page and signal the\n      // end via a boolean flag — honor it before the cursor check to skip the\n      // follow-up empty request. Strictly `false`: a missing pointer falls through.\n      if (spec.hasMore !== undefined && resolvePointer(page, spec.hasMore) === false) return;\n      const next = resolvePointer(page, spec.nextCursor!);\n      if (next === undefined || next === null || next === '') return;\n      if (typeof next !== 'string' && typeof next !== 'number') {\n        // A fresh non-scalar cursor never compares equal, so without this guard a lying\n        // server would slip past the did-not-advance check into an infinite loop.\n        throw new Error(`Pagination cursor at ${spec.nextCursor} is not a string or number`);\n      }\n      if (next === cursor) {\n        throw new Error('Pagination did not advance: operation returned the same cursor twice');\n      }\n      cursor = next;\n    }\n  } else {\n    // Coerce the starting position to a number: a caller may pass `params[spec.param]` as a\n    // string (common from URL/form input), and `+=` on a string would concatenate.\n    const start = args.params?.[spec.param];\n    const fallback = spec.style === 'page' ? 1 : 0;\n    let position = start === undefined || Number.isNaN(Number(start)) ? fallback : Number(start);\n    while (true) {\n      const page = await call(\n        { ...args, params: { ...args.params, [spec.param]: position } },\n        init\n      );\n      yield page;\n      const pageItems = resolvePointer(page, spec.items);\n      if (!Array.isArray(pageItems) || pageItems.length === 0) return;\n      position += spec.style === 'page' ? 1 : pageItems.length;\n    }\n  }\n}\n\n/**\n * Iterate the operation's individual items: each page's `items` pointer, flattened.\n * A cursor-style page whose pointer misses yields nothing but pagination continues;\n * for offset/page styles a miss has already stopped `pages`.\n */\nexport async function* items<TItem>(\n  call: (args?: OperationArgs, init?: RequestOptions) => Promise<unknown>,\n  spec: PaginationSpec,\n  args?: OperationArgs,\n  init?: RequestOptions\n): AsyncGenerator<TItem> {\n  for await (const page of pages(call, spec, args, init)) {\n    const pageItems = resolvePointer(page, spec.items);\n    if (Array.isArray(pageItems)) yield* pageItems as TItem[];\n  }\n}\n",
+} as const;
+
+export type RuntimeModuleName = keyof typeof RUNTIME_SOURCES;
diff --git a/packages/client-generator/src/emitters/sample.ts b/packages/client-generator/src/emitters/sample.ts
new file mode 100644
index 0000000000..6c2b6e7614
--- /dev/null
+++ b/packages/client-generator/src/emitters/sample.ts
@@ -0,0 +1,177 @@
+import { isPlainObject } from '@redocly/openapi-core';
+
+import type {
+  NamedSchemaModel,
+  ScalarKind,
+  SchemaMetadata,
+  SchemaModel,
+} from '../intermediate-representation/model.js';
+import type { DateType } from './types.js';
+
+/** A sampled value the emitter must print as a raw TS expression rather than a JSON
+ *  literal — e.g. a `format: binary` field, whose generated type is `Blob`. The `code`
+ *  strings are generator-authored constants (never spec-derived), so emitting them
+ *  verbatim is safe. */
+export class SampleExpression {
+  constructor(readonly code: string) {}
+}
+
+/** Options for `sampleValue`. `dateType` mirrors the type emitter's `--date-type`
+ *  knob: when `'Date'`, date/date-time fields are typed `Date` (not `string`), so
+ *  the sample must be a `new Date(...)` expression to match. Defaults to `'string'`. */
+export type SampleOptions = { dateType?: DateType };
+
+/**
+ * Turn an IR schema into a single deterministic JS value for baked mocks. Prefers
+ * a spec `example`, then `default`, then a type/format-aware synthesized value —
+ * EXCEPT for type-demanding fields (binary, or date/date-time under `dateType: 'Date'`)
+ * whose generated type is not a JSON literal: those emit a fixed raw expression that
+ * matches the type, regardless of any example/default (see `typeDemandedExpression`).
+ * Refs resolve against `schemas`; recursion is cut with a visited-set so cyclic
+ * schemas terminate (`null` at the cycle) instead of looping forever.
+ */
+export function sampleValue(
+  schema: SchemaModel,
+  schemas: NamedSchemaModel[],
+  opts: SampleOptions = {}
+): unknown {
+  const byName = new Map(schemas.map((s) => [s.name, s.schema]));
+  const value = walk(schema, byName, new Set(), opts.dateType ?? 'string');
+  // A `CYCLE` that propagates all the way to the root has no container to absorb it
+  // into a valid empty value (e.g. a self-referential union); fall back to null.
+  return value === CYCLE ? null : value;
+}
+
+/**
+ * Sentinel returned by `walk` when a `$ref` re-enters a name already on the stack.
+ * Containers turn it into the type-correct empty value for their position — an array
+ * to `[]`, a record to `{}`, an optional property to omission — so a recursive schema
+ * yields data that still satisfies its (non-nullable) generated type. Only a required,
+ * non-container self-reference (a genuinely uninhabitable schema) degrades to null.
+ */
+const CYCLE = Symbol('cycle');
+
+/**
+ * The expression a field MUST sample to because its generated type is not a JSON
+ * literal — so it takes precedence over any spec `example`/`default` (baking those
+ * would not type-check). The returned `code` is a generator-authored CONSTANT and
+ * is NEVER interpolated from spec data: it flows verbatim into `parseExpression`,
+ * so feeding a spec example string in here would be an injection vector. `undefined`
+ * when the field has no type demand (the normal example/default/synthesis path applies).
+ */
+function typeDemandedExpression(
+  schema: SchemaModel,
+  dateType: DateType
+): SampleExpression | undefined {
+  if (schema.kind !== 'scalar') return undefined;
+  const format = schema.metadata?.format;
+  if (format === 'binary') return new SampleExpression('new Blob([])');
+  if (dateType === 'Date') {
+    if (format === 'date-time') return new SampleExpression('new Date("2024-01-01T00:00:00Z")');
+    if (format === 'date') return new SampleExpression('new Date("2024-01-01")');
+  }
+  return undefined;
+}
+
+function walk(
+  schema: SchemaModel,
+  byName: Map<string, SchemaModel>,
+  visiting: Set<string>,
+  dateType: DateType
+): unknown {
+  const demanded = typeDemandedExpression(schema, dateType);
+  if (demanded) return demanded;
+
+  const meta = schema.metadata;
+  if (meta?.example !== undefined) return meta.example;
+  if (meta?.default !== undefined) return meta.default;
+
+  switch (schema.kind) {
+    case 'scalar':
+      return scalarSample(schema.scalar, meta);
+    case 'array': {
+      // A cyclic item type collapses the array to `[]` — itself a valid `T[]`.
+      const item = walk(schema.items, byName, visiting, dateType);
+      return item === CYCLE ? [] : [item];
+    }
+    case 'object':
+      return Object.fromEntries(
+        schema.properties.flatMap((p) => {
+          const value = walk(p.schema, byName, visiting, dateType);
+          // A cyclic optional property is omitted (a null would not satisfy `T | undefined`);
+          // a cyclic required property is uninhabitable, so null is the only stand-in.
+          if (value === CYCLE) return p.required ? [[p.name, null]] : [];
+          return [[p.name, value]];
+        })
+      );
+    case 'record': {
+      const value = walk(schema.value, byName, visiting, dateType);
+      return value === CYCLE ? {} : { key: value };
+    }
+    case 'enum':
+      return schema.values[0];
+    case 'literal':
+      return schema.value;
+    case 'union': {
+      // Pick the first member that is not itself a cycle; if every member cycles the
+      // union is uninhabitable, so propagate `CYCLE` for a container/root to absorb.
+      for (const member of schema.members) {
+        const value = walk(member, byName, visiting, dateType);
+        if (value !== CYCLE) return value;
+      }
+      return schema.members.length > 0 ? CYCLE : null;
+    }
+    case 'intersection':
+      return schema.members.reduce<Record<string, unknown>>((acc, m) => {
+        const part = walk(m, byName, visiting, dateType);
+        return isPlainObject(part) ? Object.assign(acc, part) : acc;
+      }, {});
+    case 'omit': {
+      // base is a named schema reference (string), resolve it then drop the listed keys
+      const target = byName.get(schema.base);
+      if (!target) return null;
+      const base = walk(target, byName, visiting, dateType);
+      if (isPlainObject(base)) {
+        const copy = { ...(base as Record<string, unknown>) };
+        for (const key of schema.keys) delete copy[key];
+        return copy;
+      }
+      return base;
+    }
+    case 'ref': {
+      if (visiting.has(schema.name)) return CYCLE;
+      const target = byName.get(schema.name);
+      if (!target) return null;
+      visiting.add(schema.name);
+      const result = walk(target, byName, visiting, dateType);
+      visiting.delete(schema.name);
+      return result;
+    }
+    case 'null':
+    case 'unknown':
+      return null;
+  }
+}
+
+function scalarSample(scalar: ScalarKind, meta: SchemaMetadata | undefined): unknown {
+  if (scalar === 'boolean') return true;
+  if (scalar === 'integer' || scalar === 'number') return 0;
+  // Type-demanding formats (binary, and date/date-time under `dateType: 'Date'`) are
+  // handled earlier in `walk` via `typeDemandedExpression`; here the date formats fall
+  // through to the ISO-string path (the `dateType: 'string'` types them as `string`).
+  switch (meta?.format) {
+    case 'email':
+      return 'user@example.com';
+    case 'uuid':
+      return '00000000-0000-4000-8000-000000000000';
+    case 'date-time':
+      return '2024-01-01T00:00:00Z';
+    case 'date':
+      return '2024-01-01';
+    case 'uri':
+    case 'url':
+      return 'https://example.com';
+    default:
+      return 'string';
+  }
+}
diff --git a/packages/client-generator/src/emitters/setup-bake.ts b/packages/client-generator/src/emitters/setup-bake.ts
new file mode 100644
index 0000000000..098ad0892b
--- /dev/null
+++ b/packages/client-generator/src/emitters/setup-bake.ts
@@ -0,0 +1,81 @@
+import { NotSupportedError } from '../errors.js';
+import { ts } from './ts.js';
+
+const SETUP_IMPORT = '@redocly/client-generator';
+
+/**
+ * Transform a publisher `--setup` module into the neutral **setup expression** the emitter splices
+ * into a client as `const __redoclySetup = <expr>` — merged into the client's config via
+ * `mergeSetup`. Strips the (package-only) imports, extracts the default
+ * export's `defineClientSetup({ config, middleware })` argument, and — when the file declares
+ * helpers — wraps them in an IIFE so they are preserved yet scoped (only `__redoclySetup` lands in
+ * module scope, avoiding collisions):
+ *
+ *   (() => { <file helpers…> return <arg>; })()
+ *
+ * The transform is textual (`node.getText()`): re-printing parsed nodes through the TS printer
+ * loses string-literal text, so we preserve the publisher's exact source for each kept node.
+ */
+export function bakeSetup(source: string): string {
+  const sf = ts.createSourceFile(
+    'setup.ts',
+    source,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TS
+  );
+  const kept: string[] = [];
+  let argText: string | undefined;
+  // The local name `defineClientSetup` is imported as (it may be aliased:
+  // `import { defineClientSetup as setup }`), so `unwrap` matches the right callee.
+  let defineClientSetupLocal = 'defineClientSetup';
+
+  for (const stmt of sf.statements) {
+    if (ts.isImportDeclaration(stmt)) {
+      const spec = (stmt.moduleSpecifier as ts.StringLiteral).text;
+      if (spec !== SETUP_IMPORT) {
+        throw new NotSupportedError(
+          `A --setup file may only import from "${SETUP_IMPORT}"; found "${spec}". ` +
+            `Setup code may use web globals and the client contract only (keeps the client zero-dependency).`
+        );
+      }
+      const named = stmt.importClause?.namedBindings;
+      if (named && ts.isNamedImports(named)) {
+        for (const el of named.elements) {
+          if ((el.propertyName?.text ?? el.name.text) === 'defineClientSetup') {
+            defineClientSetupLocal = el.name.text;
+          }
+        }
+      }
+      continue; // drop — the symbols resolve in the baked client's own scope
+    }
+    if (ts.isExportAssignment(stmt) && !stmt.isExportEquals) {
+      argText = unwrap(stmt.expression, defineClientSetupLocal).getText(sf);
+      continue;
+    }
+    kept.push(stmt.getText(sf));
+  }
+
+  if (argText === undefined) {
+    throw new NotSupportedError(
+      'A --setup file must `export default defineClientSetup({ config, middleware })` (or a setup object).'
+    );
+  }
+
+  if (kept.length === 0) return argText;
+  return `(() => {\n${kept.join('\n')}\nreturn ${argText};\n})()`;
+}
+
+/** `defineClientSetup(<arg>)` → `<arg>`; a bare object literal passes through unchanged.
+ * `localName` is the (possibly aliased) local binding the setup module imported it as. */
+function unwrap(expr: ts.Expression, localName: string): ts.Expression {
+  if (
+    ts.isCallExpression(expr) &&
+    ts.isIdentifier(expr.expression) &&
+    expr.expression.text === localName &&
+    expr.arguments.length === 1
+  ) {
+    return expr.arguments[0];
+  }
+  return expr;
+}
diff --git a/packages/client-generator/src/emitters/sse.ts b/packages/client-generator/src/emitters/sse.ts
new file mode 100644
index 0000000000..b41d70159b
--- /dev/null
+++ b/packages/client-generator/src/emitters/sse.ts
@@ -0,0 +1,55 @@
+import type {
+  OperationModel,
+  ResponseBodyModel,
+  SchemaModel,
+} from '../intermediate-representation/model.js';
+import { ts } from './ts.js';
+import { type DateType, schemaToTypeNode } from './types.js';
+
+const { factory } = ts;
+
+/** The media type that marks an operation as a Server-Sent Events stream. */
+const SSE_CONTENT_TYPE = 'text/event-stream';
+
+/** The event-stream success response of an operation, if it declares one. */
+function sseResponse(op: OperationModel): ResponseBodyModel | undefined {
+  return op.successResponses.find(
+    (r) => r.contentType.split(';')[0].trim().toLowerCase() === SSE_CONTENT_TYPE
+  );
+}
+
+/** Whether an operation streams Server-Sent Events. */
+export function isSseOp(op: OperationModel): boolean {
+  return sseResponse(op) !== undefined;
+}
+
+/** The per-event schema: `itemSchema` → the response `schema` → undefined (typeless slots skipped). */
+function eventSchema(op: OperationModel): SchemaModel | undefined {
+  const r = sseResponse(op);
+  if (!r) return undefined;
+  if (r.itemSchema && r.itemSchema.kind !== 'unknown') return r.itemSchema;
+  if (r.schema.kind !== 'unknown') return r.schema;
+  return undefined;
+}
+
+/** The TS type of a streamed event payload (`string` when no schema is declared). */
+export function sseEventType(op: OperationModel, dateType: DateType): ts.TypeNode {
+  const schema = eventSchema(op);
+  return schema
+    ? schemaToTypeNode(schema, dateType)
+    : factory.createKeywordTypeNode(ts.SyntaxKind.StringKeyword);
+}
+
+/** Whether the streamed `data:` payload should be `JSON.parse`d (`'json'`) or passed raw (`'text'`). */
+export function sseDataKind(op: OperationModel): 'json' | 'text' {
+  const schema = eventSchema(op);
+  if (!schema) return 'text';
+  return schema.kind === 'object' ||
+    schema.kind === 'ref' ||
+    schema.kind === 'array' ||
+    schema.kind === 'record' ||
+    schema.kind === 'union' ||
+    schema.kind === 'intersection'
+    ? 'json'
+    : 'text';
+}
diff --git a/packages/client-generator/src/emitters/support.ts b/packages/client-generator/src/emitters/support.ts
new file mode 100644
index 0000000000..392ec3cadb
--- /dev/null
+++ b/packages/client-generator/src/emitters/support.ts
@@ -0,0 +1,22 @@
+// Low-level text helpers shared across the emitters. Private to `emitters/`.
+
+/**
+ * Upper-case the first character of an operation name. We don't normalize the
+ * rest because almost every spec uses camelCase or PascalCase, and names that
+ * contain digits or `_` are passed through unchanged — the user named them that
+ * way for a reason.
+ *
+ * `op.name` reaches here already sanitized into a non-empty, valid TS identifier
+ * by the IR builder (see `intermediate-representation/sanitize-identifiers.ts`), so no empty-string or
+ * unsafe-character guard is needed.
+ */
+export function pascalCase(name: string): string {
+  return name[0].toUpperCase() + name.slice(1);
+}
+
+export function splitLines(text: string): string[] {
+  return text
+    .replace(/\r\n/g, '\n')
+    .split('\n')
+    .map((line) => line.trimEnd());
+}
diff --git a/packages/client-generator/src/emitters/swr.ts b/packages/client-generator/src/emitters/swr.ts
new file mode 100644
index 0000000000..d9d0901437
--- /dev/null
+++ b/packages/client-generator/src/emitters/swr.ts
@@ -0,0 +1,166 @@
+// Emits an idiomatic SWR module wrapping the sdk operation functions. Per query
+// operation (GET/HEAD) a `<op>Key(vars)` tuple factory + a `use<Op>(vars, init?)`
+// hook returning `useSWR(key, fetcher)`; per mutation (everything else) a
+// `use<Op>()` hook returning `useSWRMutation(key, (key, { arg }) => <op>(arg))`.
+// The fetcher forwards args per the configured args style (grouped `<op>(vars, init)`
+// or flat `<op>(vars.petId, …, init)`) via the shared `operationSignature`, so the
+// call type-checks against the generated sdk.
+// `swr`/`swr/mutation` are the consumer's peer; the sdk stays dependency-free.
+// AST-native via `ts.factory`.
+
+import type { ApiModel, OperationModel } from '../intermediate-representation/model.js';
+import { pascalCase } from './support.js';
+import {
+  arrow,
+  constArray,
+  exportConstStatement as exportConst,
+  printStatements,
+  ts,
+} from './ts.js';
+import {
+  hasInputs,
+  initParam,
+  isQuery,
+  sdkCall,
+  sdkNamedImport,
+  variablesName,
+  varsParam,
+  wrappableOperations,
+} from './wrapper-support.js';
+
+const { factory } = ts;
+
+export type SwrOptions = {
+  /** Import specifier for the sdk entry the operation functions/types live in. */
+  sdkModule: string;
+  /** How the sdk function takes its inputs — must match the generated client. */
+  argsStyle: 'flat' | 'grouped';
+};
+
+/** Render the full SWR module source. `''` when there are no wrappable operations. */
+export function renderSwrModule(model: ApiModel, opts: SwrOptions): string {
+  const ops = wrappableOperations(model, 'swr');
+  if (ops.length === 0) return '';
+  return printStatements(swrStatements(ops, opts));
+}
+
+/** The SWR module statements: the import header followed by per-op hooks. */
+function swrStatements(ops: OperationModel[], opts: SwrOptions): ts.Statement[] {
+  const hasQuery = ops.some(isQuery);
+  const hasMutation = ops.some((op) => !isQuery(op));
+  const statements: ts.Statement[] = [];
+  for (const op of ops) {
+    statements.push(...(isQuery(op) ? queryStatements(op, opts) : [mutationStatement(op, opts)]));
+  }
+  return [...importHeader(ops, opts, hasQuery, hasMutation), ...statements];
+}
+
+/** An exported `function use<Op>(<params>) { <body> }` declaration. */
+function exportHook(
+  op: OperationModel,
+  params: ts.ParameterDeclaration[],
+  ret: ts.Expression
+): ts.Statement {
+  const name = `use${pascalCase(op.name)}`;
+  return factory.createFunctionDeclaration(
+    [factory.createModifier(ts.SyntaxKind.ExportKeyword)],
+    undefined,
+    name,
+    undefined,
+    params,
+    undefined,
+    factory.createBlock([factory.createReturnStatement(ret)], true)
+  );
+}
+
+/** A query op's `<op>Key` factory + `use<Op>` hook calling `useSWR`. */
+function queryStatements(op: OperationModel, opts: SwrOptions): ts.Statement[] {
+  const inputs = hasInputs(op);
+  const keyId = factory.createStringLiteral(op.name);
+  const keyParams = inputs ? [varsParam(op)] : [];
+  const keyElements = inputs ? [keyId, factory.createIdentifier('vars')] : [keyId];
+  const key = exportConst(`${op.name}Key`, arrow(keyParams, constArray(keyElements)));
+
+  const keyCall = factory.createCallExpression(
+    factory.createIdentifier(`${op.name}Key`),
+    undefined,
+    inputs ? [factory.createIdentifier('vars')] : []
+  );
+  const useSwr = factory.createCallExpression(factory.createIdentifier('useSWR'), undefined, [
+    keyCall,
+    arrow([], sdkCall(op, opts.argsStyle, 'vars', true)),
+  ]);
+
+  const params = inputs ? [varsParam(op), initParam()] : [initParam()];
+  return [key, exportHook(op, params, useSwr)];
+}
+
+/** A mutation op's `use<Op>` hook calling `useSWRMutation`. */
+function mutationStatement(op: OperationModel, opts: SwrOptions): ts.Statement {
+  const inputs = hasInputs(op);
+  const key = factory.createStringLiteral(op.name);
+
+  // `(_key: string, { arg }: { arg: <Op>Variables }) => <op>(…arg)` when the op has inputs;
+  // a no-arg `() => <op>()` when it has none (`arg` would be unused).
+  const trigger = inputs
+    ? triggerWithArg(op, opts)
+    : arrow([], sdkCall(op, opts.argsStyle, 'arg', false));
+  const useSwrMutation = factory.createCallExpression(
+    factory.createIdentifier('useSWRMutation'),
+    undefined,
+    [key, trigger]
+  );
+  return exportHook(op, [], useSwrMutation);
+}
+
+/** `(_key: string, { arg }: { arg: <Op>Variables }) => <op>(…arg)`. */
+function triggerWithArg(op: OperationModel, opts: SwrOptions): ts.ArrowFunction {
+  const keyParam = factory.createParameterDeclaration(
+    undefined,
+    undefined,
+    '_key',
+    undefined,
+    factory.createKeywordTypeNode(ts.SyntaxKind.StringKeyword)
+  );
+  const argParam = factory.createParameterDeclaration(
+    undefined,
+    undefined,
+    factory.createObjectBindingPattern([factory.createBindingElement(undefined, undefined, 'arg')]),
+    undefined,
+    factory.createTypeLiteralNode([
+      factory.createPropertySignature(
+        undefined,
+        'arg',
+        undefined,
+        factory.createTypeReferenceNode(variablesName(op))
+      ),
+    ])
+  );
+  return arrow([keyParam, argParam], sdkCall(op, opts.argsStyle, 'arg', false));
+}
+
+/**
+ * The import header: `useSWR` from `swr` (when any query op), `useSWRMutation` from
+ * `swr/mutation` (when any mutation op), then the shared sdk named import.
+ */
+function importHeader(
+  ops: OperationModel[],
+  opts: SwrOptions,
+  hasQuery: boolean,
+  hasMutation: boolean
+): ts.Statement[] {
+  const imports: ts.Statement[] = [];
+  if (hasQuery) imports.push(defaultImport('useSWR', 'swr'));
+  if (hasMutation) imports.push(defaultImport('useSWRMutation', 'swr/mutation'));
+  imports.push(sdkNamedImport(ops, opts.sdkModule, hasQuery));
+  return imports;
+}
+
+/** `import <name> from "<module>";` (default import). */
+function defaultImport(name: string, module: string): ts.Statement {
+  return factory.createImportDeclaration(
+    undefined,
+    factory.createImportClause(false, factory.createIdentifier(name), undefined),
+    factory.createStringLiteral(module)
+  );
+}
diff --git a/packages/client-generator/src/emitters/tanstack-query.ts b/packages/client-generator/src/emitters/tanstack-query.ts
new file mode 100644
index 0000000000..185a2e7137
--- /dev/null
+++ b/packages/client-generator/src/emitters/tanstack-query.ts
@@ -0,0 +1,136 @@
+// Emits an idiomatic TanStack Query v5 (React) module wrapping the sdk operation
+// functions. Per query operation (GET/HEAD) a `<op>QueryKey(vars)` +
+// `<op>Options(vars, init?)` (`queryOptions({ queryKey, queryFn })`); per mutation
+// (everything else) a `<op>Mutation()` (`{ mutationKey, mutationFn }`). Each
+// factory forwards to the sdk function per the configured args style — grouped
+// (`getPet(vars, init)`) or flat (`getPet(vars.petId, vars.params, …, init)`),
+// matching `operations.ts` positional order so the call type-checks against the
+// generated sdk. AST-native via `ts.factory`.
+
+import type { ApiModel, OperationModel } from '../intermediate-representation/model.js';
+import {
+  arrow,
+  constArray,
+  exportConstStatement as exportConst,
+  printStatements,
+  ts,
+} from './ts.js';
+import {
+  hasInputs,
+  initParam,
+  isQuery,
+  sdkCall,
+  sdkNamedImport,
+  varsParam,
+  wrappableOperations,
+} from './wrapper-support.js';
+
+const { factory } = ts;
+
+export type TanstackOptions = {
+  argsStyle: 'flat' | 'grouped';
+  /** Import specifier for the sdk entry the operation functions/types live in. */
+  sdkModule: string;
+  /** TanStack adapter to import `queryOptions` from (`@tanstack/${framework}-query`). */
+  framework: 'react' | 'vue' | 'svelte' | 'solid';
+};
+
+/** Render the full TanStack Query module source. `''` when there are no wrappable operations. */
+export function renderTanstackModule(model: ApiModel, opts: TanstackOptions): string {
+  const ops = wrappableOperations(model, 'tanstack-query');
+  if (ops.length === 0) return '';
+  return printStatements(tanstackStatements(ops, opts));
+}
+
+/** The TanStack module statements: the import header followed by per-op factories. */
+function tanstackStatements(ops: OperationModel[], opts: TanstackOptions): ts.Statement[] {
+  const hasQuery = ops.some(isQuery);
+  const statements: ts.Statement[] = [];
+  for (const op of ops) {
+    statements.push(...(isQuery(op) ? queryStatements(op, opts) : [mutationStatement(op, opts)]));
+  }
+  return [...importHeader(ops, opts, hasQuery), ...statements];
+}
+
+/** A query op's `<op>QueryKey` + `<op>Options` statements. */
+function queryStatements(op: OperationModel, opts: TanstackOptions): ts.Statement[] {
+  const inputs = hasInputs(op);
+  const keyId = factory.createStringLiteral(op.name);
+  const keyParams = inputs ? [varsParam(op)] : [];
+  const keyElements = inputs ? [keyId, factory.createIdentifier('vars')] : [keyId];
+
+  const queryKey = exportConst(`${op.name}QueryKey`, arrow(keyParams, constArray(keyElements)));
+
+  const keyCall = factory.createCallExpression(
+    factory.createIdentifier(`${op.name}QueryKey`),
+    undefined,
+    inputs ? [factory.createIdentifier('vars')] : []
+  );
+  const queryOptionsCall = factory.createCallExpression(
+    factory.createIdentifier('queryOptions'),
+    undefined,
+    [
+      factory.createObjectLiteralExpression(
+        [
+          factory.createPropertyAssignment('queryKey', keyCall),
+          factory.createPropertyAssignment(
+            'queryFn',
+            arrow([], sdkCall(op, opts.argsStyle, 'vars', true))
+          ),
+        ],
+        true
+      ),
+    ]
+  );
+  const optionsParams = inputs ? [varsParam(op), initParam()] : [initParam()];
+  const options = exportConst(`${op.name}Options`, arrow(optionsParams, queryOptionsCall));
+
+  return [queryKey, options];
+}
+
+/** A mutation op's `<op>Mutation` statement. */
+function mutationStatement(op: OperationModel, opts: TanstackOptions): ts.Statement {
+  const inputs = hasInputs(op);
+  const mutationFn = arrow(
+    inputs ? [varsParam(op)] : [],
+    sdkCall(op, opts.argsStyle, 'vars', false)
+  );
+
+  const obj = factory.createObjectLiteralExpression(
+    [
+      factory.createPropertyAssignment(
+        'mutationKey',
+        constArray([factory.createStringLiteral(op.name)])
+      ),
+      factory.createPropertyAssignment('mutationFn', mutationFn),
+    ],
+    true
+  );
+
+  // Wrap in parens so the arrow body is an object literal, not a block.
+  return exportConst(`${op.name}Mutation`, arrow([], factory.createParenthesizedExpression(obj)));
+}
+
+/**
+ * The import header: `queryOptions` from `@tanstack/${framework}-query` (when any
+ * query op), then the shared sdk named import.
+ */
+function importHeader(
+  ops: OperationModel[],
+  opts: TanstackOptions,
+  hasQuery: boolean
+): ts.Statement[] {
+  const tanstack = factory.createImportDeclaration(
+    undefined,
+    factory.createImportClause(
+      false,
+      undefined,
+      factory.createNamedImports([
+        factory.createImportSpecifier(false, undefined, factory.createIdentifier('queryOptions')),
+      ])
+    ),
+    factory.createStringLiteral(`@tanstack/${opts.framework}-query`)
+  );
+  const sdkImport = sdkNamedImport(ops, opts.sdkModule, hasQuery);
+  return hasQuery ? [tanstack, sdkImport] : [sdkImport];
+}
diff --git a/packages/client-generator/src/emitters/transformers.ts b/packages/client-generator/src/emitters/transformers.ts
new file mode 100644
index 0000000000..bb5557de12
--- /dev/null
+++ b/packages/client-generator/src/emitters/transformers.ts
@@ -0,0 +1,469 @@
+// Emits standalone Date-transformer functions from the IR. For each named
+// schema that (recursively) carries a `format: date-time`/`date` string field,
+// emits `export const transform<Name> = (data: <Name>): <Name> => { … };` that
+// walks the value and rewrites those wire ISO strings to `new Date(...)` in
+// place, so the runtime value matches the sdk's `--date-type Date` types.
+//
+// Pairs with the sdk generated under `dateType: 'Date'`; the client itself
+// stays zero-dep (Date is standard). Transformers compose across refs:
+// `transformPet` calls `transformPerson(data["owner"])` when `Pet.owner` is a
+// `Person` that has dates.
+
+import type {
+  ApiModel,
+  NamedSchemaModel,
+  SchemaModel,
+} from '../intermediate-representation/model.js';
+import { safeIdent } from './identifier.js';
+import { pascalCase } from './support.js';
+import { arrow, exportConstStatement, printStatements, ts } from './ts.js';
+
+const { factory } = ts;
+
+/** `transform<Name>` — the function bound to a named schema. */
+function transformName(name: string): string {
+  return `transform${pascalCase(name)}`;
+}
+
+/** A scalar string with a `date-time`/`date` format — the leaf we convert. */
+function isDateScalar(schema: SchemaModel): boolean {
+  return (
+    schema.kind === 'scalar' &&
+    schema.scalar === 'string' &&
+    (schema.metadata?.format === 'date-time' || schema.metadata?.format === 'date')
+  );
+}
+
+/**
+ * Whether a schema contains a date leaf, following refs. `seen` guards ref
+ * cycles (a self-referential schema would otherwise recurse forever); a ref
+ * back into the visited set carries no *new* dates from here.
+ */
+function hasDates(
+  schema: SchemaModel,
+  byName: Map<string, SchemaModel>,
+  seen: Set<string>
+): boolean {
+  if (isDateScalar(schema)) return true;
+  switch (schema.kind) {
+    case 'array':
+      return hasDates(schema.items, byName, seen);
+    case 'record':
+      return hasDates(schema.value, byName, seen);
+    case 'object':
+      return schema.properties.some((p) => hasDates(p.schema, byName, seen));
+    case 'union':
+    case 'intersection':
+      return schema.members.some((m) => hasDates(m, byName, seen));
+    case 'ref': {
+      const target = byName.get(schema.name);
+      return target !== undefined && !seen.has(schema.name)
+        ? hasDates(target, byName, new Set(seen).add(schema.name))
+        : false;
+    }
+    default:
+      return false;
+  }
+}
+
+/** `<target>["key"]` — bracket access, robust for any (incl. non-identifier) key. */
+function index(target: ts.Expression, key: string): ts.ElementAccessExpression {
+  return factory.createElementAccessExpression(target, factory.createStringLiteral(key));
+}
+
+/** `new Date(<arg>)`. */
+function newDate(arg: ts.Expression): ts.Expression {
+  return factory.createNewExpression(factory.createIdentifier('Date'), undefined, [arg]);
+}
+
+/** `typeof <expr> === "string"`. */
+function isStringGuard(expr: ts.Expression): ts.Expression {
+  return factory.createBinaryExpression(
+    factory.createTypeOfExpression(expr),
+    factory.createToken(ts.SyntaxKind.EqualsEqualsEqualsToken),
+    factory.createStringLiteral('string')
+  );
+}
+
+/** `Array.isArray(<expr>)`. */
+function isArrayGuard(expr: ts.Expression): ts.Expression {
+  return factory.createCallExpression(
+    factory.createPropertyAccessExpression(factory.createIdentifier('Array'), 'isArray'),
+    undefined,
+    [expr]
+  );
+}
+
+/** `<expr> && typeof <expr> === "object"` — truthy and a (non-null) object. */
+function isObjectGuard(expr: ts.Expression): ts.Expression {
+  return factory.createBinaryExpression(
+    expr,
+    factory.createToken(ts.SyntaxKind.AmpersandAmpersandToken),
+    factory.createBinaryExpression(
+      factory.createTypeOfExpression(expr),
+      factory.createToken(ts.SyntaxKind.EqualsEqualsEqualsToken),
+      factory.createStringLiteral('object')
+    )
+  );
+}
+
+/** `<expr> as <Type>` — a type assertion, to satisfy a union-narrowing transform. */
+function asType(expr: ts.Expression, typeName: string): ts.Expression {
+  return factory.createAsExpression(expr, factory.createTypeReferenceNode(pascalCase(typeName)));
+}
+
+/** `if (<cond>) <then>;`. */
+function ifThen(cond: ts.Expression, then: ts.Statement): ts.Statement {
+  return factory.createIfStatement(cond, then);
+}
+
+function exprStatement(expr: ts.Expression): ts.Statement {
+  return factory.createExpressionStatement(expr);
+}
+
+/** `<target> = <value>;`. */
+function assign(target: ts.Expression, value: ts.Expression): ts.Statement {
+  return exprStatement(
+    factory.createBinaryExpression(target, factory.createToken(ts.SyntaxKind.EqualsToken), value)
+  );
+}
+
+/** `<recv>.<method>(<args>)`. */
+function method(recv: ts.Expression, name: string, args: ts.Expression[]): ts.Expression {
+  return factory.createCallExpression(
+    factory.createPropertyAccessExpression(recv, name),
+    undefined,
+    args
+  );
+}
+
+function param(name: string): ts.ParameterDeclaration {
+  return factory.createParameterDeclaration(undefined, undefined, name);
+}
+
+/** Next nested loop variable: `item`, `item2`, `item3`, … (avoids shadowing). */
+function nextItemVar(current: string): string {
+  if (current === 'data') return 'item';
+  return `item${Number(current.slice('item'.length)) + 1}`;
+}
+
+/**
+ * Conversion statements that, given the runtime value at `target` typed by
+ * `schema`, rewrite date leaves in place. Each branch self-gates by returning
+ * `[]` when nothing under it carries a date, so callers need no pre-check.
+ * `seen` follows refs and guards cycles; `itemVar` names nested loop variables.
+ *
+ * Covers the shapes a date can hide in: date scalars, arrays of them, refs to
+ * date-bearing schemas (composed via `transform<Ref>`), arrays of such refs,
+ * records, nested inline objects, and the date-bearing members of a
+ * union/intersection.
+ */
+function convert(
+  target: ts.Expression,
+  schema: SchemaModel,
+  byName: Map<string, SchemaModel>,
+  seen: Set<string>,
+  itemVar: string
+): ts.Statement[] {
+  if (isDateScalar(schema)) {
+    return [ifThen(isStringGuard(target), assign(target, newDate(target)))];
+  }
+  switch (schema.kind) {
+    case 'ref':
+      return convertRef(target, schema.name, byName, seen);
+    case 'object': {
+      const stmts: ts.Statement[] = [];
+      for (const p of schema.properties) {
+        stmts.push(...convertProperty(index(target, p.name), p.schema, byName, seen, itemVar));
+      }
+      return stmts;
+    }
+    case 'array':
+      return convertArray(target, schema.items, byName, seen, itemVar);
+    case 'record':
+      return convertCollection(target, schema.value, byName, seen, itemVar, true);
+    case 'intersection': {
+      // An intersection value satisfies *every* member type, so each member's
+      // transform applies directly to `target` with no narrowing needed.
+      const stmts: ts.Statement[] = [];
+      for (const m of schema.members) stmts.push(...convert(target, m, byName, seen, itemVar));
+      return stmts;
+    }
+    case 'union':
+      return convertUnion(target, schema.members, byName, seen, itemVar);
+    default:
+      return [];
+  }
+}
+
+/**
+ * A union position. A runtime value inhabits exactly one member, so we apply
+ * every date-bearing member's conversion to the same `target` and let the
+ * unmatched members' runtime guards no-op.
+ *
+ * Type-safety is the catch: `target` is typed as the whole union, so an
+ * object/ref member's `transform<Ref>(target)` would fail `--date-type Date`
+ * strict-tsc (TS2345). We therefore gate the object-shaped members behind a
+ * single `typeof target === "object"` check and CAST `target` to each member's
+ * type — the cast makes it compile, the cast target's own internal string
+ * guards make a wrong-member application a safe runtime no-op. Scalar date
+ * members keep their `typeof === "string"` guard (their type is `Date` under
+ * `--date-type Date`, so the assignment type-checks).
+ */
+function convertUnion(
+  target: ts.Expression,
+  members: SchemaModel[],
+  byName: Map<string, SchemaModel>,
+  seen: Set<string>,
+  itemVar: string
+): ts.Statement[] {
+  const stmts: ts.Statement[] = [];
+  const objectGuarded: ts.Statement[] = [];
+  for (const m of members) {
+    if (isDateScalar(m)) {
+      stmts.push(...convert(target, m, byName, seen, itemVar));
+    } else if (m.kind === 'ref') {
+      if (!hasDates(m, byName, seen)) continue;
+      objectGuarded.push(
+        exprStatement(
+          factory.createCallExpression(factory.createIdentifier(transformName(m.name)), undefined, [
+            asType(target, m.name),
+          ])
+        )
+      );
+    } else {
+      // Object/array/record members: recurse under the shared object guard.
+      objectGuarded.push(...convert(target, m, byName, seen, itemVar));
+    }
+  }
+  if (objectGuarded.length > 0) {
+    stmts.push(ifThen(isObjectGuard(target), factory.createBlock(objectGuarded, true)));
+  }
+  return stmts;
+}
+
+/**
+ * A ref position: `if (<target>) transform<Ref>(<target>);`, emitted only when
+ * the ref target carries dates (so the sibling transform exists).
+ */
+function convertRef(
+  target: ts.Expression,
+  name: string,
+  byName: Map<string, SchemaModel>,
+  seen: Set<string>
+): ts.Statement[] {
+  if (!hasDates({ kind: 'ref', name }, byName, seen)) return [];
+  const call = factory.createCallExpression(
+    factory.createIdentifier(transformName(name)),
+    undefined,
+    [target]
+  );
+  return [ifThen(target, exprStatement(call))];
+}
+
+/**
+ * A property position: a nested inline object guards presence and recurses
+ * inside a block; everything else (scalars, refs, arrays, …) delegates to
+ * `convert`, which guards itself.
+ */
+function convertProperty(
+  target: ts.Expression,
+  schema: SchemaModel,
+  byName: Map<string, SchemaModel>,
+  seen: Set<string>,
+  itemVar: string
+): ts.Statement[] {
+  if (schema.kind === 'ref') return convertRef(target, schema.name, byName, seen);
+  if (schema.kind === 'object') {
+    const inner = convert(target, schema, byName, seen, itemVar);
+    return inner.length === 0 ? [] : [ifThen(target, factory.createBlock(inner, true))];
+  }
+  return convert(target, schema, byName, seen, itemVar);
+}
+
+/**
+ * A "replace-by-value" element is one a transform must overwrite wholesale
+ * rather than mutate in place: a date scalar (`new Date(v)`) or an array of
+ * such elements (`v.map(...)`). Returns the expression that yields the replaced
+ * value for the element bound to `value`, or `null` when the element instead
+ * mutates in place (object/ref/record). Recurses for arrays-of-arrays.
+ *
+ * Reassigning a loop *variable* is a no-op, so date scalars (and arrays of
+ * them) can only be converted by reassigning their container slot — an array
+ * via `slot = slot.map(...)`, a record via per-key assignment. This builds the
+ * per-element value for those write-backs.
+ */
+function replacer(value: ts.Expression, element: SchemaModel, depth = 0): ts.Expression | null {
+  if (isDateScalar(element)) return newDate(value);
+  if (element.kind === 'array') {
+    // Map var for the level below: `v` over the scalar leaf, else `row`, `row2`,
+    // … per array level — distinct names by depth avoid shadowing. Yields
+    // `.map((v) => new Date(v))` and `.map((row) => row.map((v) => new Date(v)))`.
+    const varName = element.items.kind === 'array' ? rowVar(depth + 1) : 'v';
+    const inner = replacer(factory.createIdentifier(varName), element.items, depth + 1);
+    if (inner === null) return null;
+    return method(value, 'map', [arrow([param(varName)], inner)]);
+  }
+  return null;
+}
+
+/** Array map-var name by depth: `row`, `row2`, `row3`, … (avoids shadowing). */
+function rowVar(depth: number): string {
+  return depth <= 1 ? 'row' : `row${depth}`;
+}
+
+/** Conversions for `target` being an array whose elements are typed by `items`. */
+function convertArray(
+  target: ts.Expression,
+  items: SchemaModel,
+  byName: Map<string, SchemaModel>,
+  seen: Set<string>,
+  itemVar: string
+): ts.Statement[] {
+  // Date scalars / arrays-of-date-scalars are replace-by-value: map over the
+  // array and reassign the slot (reassigning a loop var would be lost).
+  const varName = items.kind === 'array' ? rowVar(1) : 'v';
+  const mapped = replacer(factory.createIdentifier(varName), items, 1);
+  if (mapped !== null) {
+    // `if (Array.isArray(t)) t = t.map((v) => new Date(v));`  (or nested `row`)
+    return [
+      ifThen(
+        isArrayGuard(target),
+        assign(target, method(target, 'map', [arrow([param(varName)], mapped)]))
+      ),
+    ];
+  }
+  if (items.kind === 'ref') {
+    if (!hasDates(items, byName, seen)) return [];
+    // `if (Array.isArray(t)) t.forEach(transformRef);`
+    const forEach = method(target, 'forEach', [
+      factory.createIdentifier(transformName(items.name)),
+    ]);
+    return [ifThen(isArrayGuard(target), exprStatement(forEach))];
+  }
+  return convertCollection(target, items, byName, seen, itemVar, false);
+}
+
+/**
+ * Iterate a collection (array or record) of mutate-in-place elements (objects,
+ * refs, records) and recurse with a fresh loop variable. Arrays iterate the
+ * value directly; records iterate `Object.values(...)`. `[]` when the element
+ * bears no dates.
+ *
+ * Replace-by-value elements (date scalars) never reach the array path here —
+ * `convertArray` handles them via map-and-reassign. A *record* of date scalars
+ * does land here: a `forEach` loop variable can't write back, so we iterate the
+ * keys and assign back into the record (`rec[k] = new Date(rec[k])`).
+ */
+function convertCollection(
+  target: ts.Expression,
+  element: SchemaModel,
+  byName: Map<string, SchemaModel>,
+  seen: Set<string>,
+  itemVar: string,
+  isRecord: boolean
+): ts.Statement[] {
+  if (isRecord) {
+    // Replace-by-value elements (date scalars, arrays of them) can't be written
+    // through a `forEach` loop var, so iterate the keys and assign back into the
+    // record slot. Date scalars are string-guarded; nested arrays array-guarded.
+    const slot = factory.createElementAccessExpression(target, factory.createIdentifier('__k'));
+    const replaced = replacer(slot, element);
+    if (replaced !== null) {
+      const guard = isDateScalar(element) ? isStringGuard(slot) : isArrayGuard(slot);
+      return [ifThen(target, keyLoop(target, ifThen(guard, assign(slot, replaced))))];
+    }
+  }
+  const next = nextItemVar(itemVar);
+  const body = convert(factory.createIdentifier(next), element, byName, seen, next);
+  if (body.length === 0) return [];
+  const iterable = isRecord
+    ? method(factory.createIdentifier('Object'), 'values', [target])
+    : target;
+  const forEach = method(iterable, 'forEach', [
+    arrow([param(next)], factory.createBlock(body, true)),
+  ]);
+  return [ifThen(isRecord ? target : isArrayGuard(target), exprStatement(forEach))];
+}
+
+/** `for (const __k of Object.keys(<target>)) <body>`. */
+function keyLoop(target: ts.Expression, body: ts.Statement): ts.Statement {
+  return factory.createForOfStatement(
+    undefined,
+    factory.createVariableDeclarationList(
+      [factory.createVariableDeclaration('__k')],
+      ts.NodeFlags.Const
+    ),
+    method(factory.createIdentifier('Object'), 'keys', [target]),
+    body
+  );
+}
+
+/** `export const transform<Name> = (data: <Name>): <Name> => { … };`. */
+function transformStatement(
+  named: NamedSchemaModel,
+  byName: Map<string, SchemaModel>
+): ts.Statement {
+  const typeName = pascalCase(named.name);
+  const data = factory.createIdentifier('data');
+  const body =
+    named.schema.kind === 'ref'
+      ? convertRef(data, named.schema.name, byName, new Set())
+      : convert(data, named.schema, byName, new Set(), 'data');
+  const fn = arrow(
+    [
+      factory.createParameterDeclaration(
+        undefined,
+        undefined,
+        'data',
+        undefined,
+        factory.createTypeReferenceNode(typeName)
+      ),
+    ],
+    factory.createBlock([...body, factory.createReturnStatement(data)], true)
+  );
+  const typed = factory.createArrowFunction(
+    fn.modifiers,
+    fn.typeParameters,
+    fn.parameters,
+    factory.createTypeReferenceNode(typeName),
+    fn.equalsGreaterThanToken,
+    fn.body
+  );
+  return exportConstStatement(transformName(named.name), typed);
+}
+
+/** `import type { <Name>, … } from "<module>";`. */
+function typeImport(names: string[], module: string): ts.Statement {
+  return factory.createImportDeclaration(
+    undefined,
+    factory.createImportClause(
+      true,
+      undefined,
+      factory.createNamedImports(
+        names.map((n) =>
+          factory.createImportSpecifier(false, undefined, factory.createIdentifier(safeIdent(n)))
+        )
+      )
+    ),
+    factory.createStringLiteral(module)
+  );
+}
+
+/**
+ * Render the transformers module. Emits one `transform<Name>` per named schema
+ * that carries a date field; `''` when none do. `opts.sdkModule` is the import
+ * specifier the schema TYPES are pulled from (the transformers call each other
+ * as siblings, so only the types need importing).
+ */
+export function renderTransformersModule(model: ApiModel, opts: { sdkModule: string }): string {
+  const byName = new Map(model.schemas.map((s) => [s.name, s.schema]));
+  const dated = model.schemas.filter((s) => hasDates(s.schema, byName, new Set()));
+  if (dated.length === 0) return '';
+  const types = dated.map((s) => pascalCase(s.name));
+  const statements = [
+    typeImport(types, opts.sdkModule),
+    ...dated.map((s) => transformStatement(s, byName)),
+  ];
+  return printStatements(statements);
+}
diff --git a/packages/client-generator/src/emitters/ts.ts b/packages/client-generator/src/emitters/ts.ts
new file mode 100644
index 0000000000..63cb570fb4
--- /dev/null
+++ b/packages/client-generator/src/emitters/ts.ts
@@ -0,0 +1,163 @@
+// Foundation for AST-based code emission: a shared TypeScript printer plus
+// `ts.factory` ergonomics. Emitters build `ts.Node`s and print them through
+// `printNodes`; hand-authored reference TypeScript is embedded via
+// `parseStatements`. The compiler (`ts`) is re-exported so emitters import the
+// factory from one place.
+
+import ts from 'typescript';
+
+import { isIdentifier } from './identifier.js';
+
+export { ts };
+
+const printer = ts.createPrinter({
+  newLine: ts.NewLineKind.LineFeed,
+  removeComments: false,
+});
+
+const blankFile = ts.createSourceFile('', '', ts.ScriptTarget.Latest, false, ts.ScriptKind.TS);
+
+/** Print a list of nodes to source, tight (one per line) — for import/export groups and single nodes. */
+export function printNodes(nodes: readonly ts.Node[]): string {
+  return nodes.map(printOne).join('\n');
+}
+
+/** Print top-level declarations separated by one blank line, for readable declaration bodies. */
+export function printStatements(nodes: readonly ts.Node[]): string {
+  return nodes.map(printOne).join('\n\n');
+}
+
+function printOne(node: ts.Node): string {
+  return printer.printNode(ts.EmitHint.Unspecified, node, sourceFileOf(node));
+}
+
+// Synthesized (`ts.factory`) nodes have no parent chain — print them against the
+// shared blank file. Parsed nodes (from `parseStatements`, built with parent
+// nodes set) must print against their own source so literal token text survives.
+function sourceFileOf(node: ts.Node): ts.SourceFile {
+  let current: ts.Node | undefined = node;
+  while (current) {
+    if (ts.isSourceFile(current)) return current;
+    current = current.parent;
+  }
+  return blankFile;
+}
+
+/** Parse a source string into its top-level statements (for embedding hand-authored code). */
+export function parseStatements(source: string): ts.Statement[] {
+  return [
+    ...ts.createSourceFile('__embed.ts', source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS)
+      .statements,
+  ];
+}
+
+/** Parse a single source expression into a ts.Expression (for emitting generator-authored
+ *  expressions like `new Blob([])` that aren't plain data literals). */
+export function parseExpression(source: string): ts.Expression {
+  const stmt = ts.createSourceFile(
+    '__expr.ts',
+    `(${source});`,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TS
+  ).statements[0];
+  const parenthesized = (stmt as ts.ExpressionStatement).expression as ts.ParenthesizedExpression;
+  return parenthesized.expression;
+}
+
+/**
+ * Attach a block JSDoc leading comment to `node` so it prints as a `/** … *​/`
+ * block above the node. Multi-line `text` becomes `*`-prefixed lines.
+ */
+export function jsdoc<T extends ts.Node>(node: T, text: string): T {
+  // Neutralize any embedded `*/` here, at the single choke point every JSDoc block
+  // flows through: a spec-supplied description/summary/title containing `*/` would
+  // otherwise close the comment early and turn the rest into live code (injection).
+  const body = `*\n${escapeJsDoc(text)
+    .split('\n')
+    .map((line) => ` * ${line}`.replace(/ +$/, ''))
+    .join('\n')}\n `;
+  return ts.addSyntheticLeadingComment(node, ts.SyntaxKind.MultiLineCommentTrivia, body, true);
+}
+
+/** Backslash-escape any comment-closing star-slash so it cannot terminate a block comment. */
+export function escapeJsDoc(text: string): string {
+  return text.replace(/\*\//g, '*\\/');
+}
+
+const { factory } = ts;
+
+/**
+ * Shared `ts.factory` builders for the handful of node shapes every emitter was
+ * re-implementing locally (variable statements, arrow functions, `as const`
+ * arrays). Centralizing them keeps emitters terse and their output identical.
+ */
+
+/** `export const <name> = <init>;` */
+export function exportConstStatement(name: string, init: ts.Expression): ts.Statement {
+  return factory.createVariableStatement(
+    [factory.createModifier(ts.SyntaxKind.ExportKeyword)],
+    factory.createVariableDeclarationList(
+      [factory.createVariableDeclaration(name, undefined, undefined, init)],
+      ts.NodeFlags.Const
+    )
+  );
+}
+
+/** An arrow function `(<params>) => <body>` (no explicit return type). */
+export function arrow(params: ts.ParameterDeclaration[], body: ts.ConciseBody): ts.ArrowFunction {
+  return factory.createArrowFunction(
+    undefined,
+    undefined,
+    params,
+    undefined,
+    factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken),
+    body
+  );
+}
+
+/** `[<elements…>] as const`. */
+export function constArray(elements: ts.Expression[]): ts.Expression {
+  return factory.createAsExpression(
+    factory.createArrayLiteralExpression(elements, false),
+    factory.createTypeReferenceNode('const')
+  );
+}
+
+/**
+ * A plain JS value as a printable literal expression. Negative numbers print as
+ * a unary minus over the positive literal (a `NumericLiteral` node cannot carry
+ * the sign); arrays and objects recurse and print compact, with keys quoted only
+ * when they fail the identifier GRAMMAR — reserved words (a descriptor's `in`
+ * field) are legal bare object-literal keys. The primitive overload's narrower
+ * return type fits `factory.createLiteralTypeNode`.
+ */
+export function literalExpression(
+  value: string | number | boolean | null
+): ts.LiteralExpression | ts.BooleanLiteral | ts.NullLiteral | ts.PrefixUnaryExpression;
+export function literalExpression(value: unknown): ts.Expression;
+export function literalExpression(value: unknown): ts.Expression {
+  if (typeof value === 'string') return factory.createStringLiteral(value);
+  if (typeof value === 'boolean') return value ? factory.createTrue() : factory.createFalse();
+  if (typeof value === 'number') {
+    return value < 0
+      ? factory.createPrefixUnaryExpression(
+          ts.SyntaxKind.MinusToken,
+          factory.createNumericLiteral(-value)
+        )
+      : factory.createNumericLiteral(value);
+  }
+  if (value === null) return factory.createNull();
+  if (Array.isArray(value)) {
+    return factory.createArrayLiteralExpression(value.map(literalExpression), false);
+  }
+  return factory.createObjectLiteralExpression(
+    Object.entries(value as Record<string, unknown>).map(([key, entryValue]) =>
+      factory.createPropertyAssignment(
+        isIdentifier(key) ? key : factory.createStringLiteral(key),
+        literalExpression(entryValue)
+      )
+    ),
+    false
+  );
+}
diff --git a/packages/client-generator/src/emitters/type-guards.ts b/packages/client-generator/src/emitters/type-guards.ts
new file mode 100644
index 0000000000..8b5f43e47e
--- /dev/null
+++ b/packages/client-generator/src/emitters/type-guards.ts
@@ -0,0 +1,259 @@
+import type {
+  DiscriminatorModel,
+  NamedSchemaModel,
+  SchemaModel,
+} from '../intermediate-representation/model.js';
+import { jsdoc, ts } from './ts.js';
+
+/**
+ * A discriminated union we can emit guards for, found while walking the schema
+ * tree. `makeParamType` builds the guard's `value` parameter type — the named
+ * union for a top-level union (`MenuItem`), or the inline member union for one
+ * nested inside another schema (`SuccessItem | ErrorItem`). `label` is the same,
+ * rendered for the JSDoc line. A thunk (not a cached node) avoids reusing one
+ * `ts.TypeNode` across the several guard declarations a site produces.
+ */
+type UnionSite = {
+  union: Extract<SchemaModel, { kind: 'union' }>;
+  label: string;
+  makeParamType: () => ts.TypeNode;
+};
+
+/**
+ * Emit `is<Member>(value): value is <Member>` type guards for every discriminated
+ * union with a usable discriminator — whether it is a top-level named schema
+ * (`MenuItem = A | B`) or nested inside one (e.g. the `items` of an array, the
+ * value of a property). Two discriminator sources:
+ *
+ * - Explicit: the union carries a `discriminator` (built from the spec).
+ * - Implicit: no discriminator, but every member is a ref to a named schema and
+ *   they all constrain one shared property to a distinct string `const`.
+ *
+ * Nested unions only qualify when every member is a ref to a named schema, so the
+ * `value` parameter is a clean union of exported types. Guard names are globally
+ * deduped (`is<Member>`), keeping the first in document order — so a top-level
+ * union wins its nicer `value: <UnionName>` parameter over a nested re-occurrence.
+ * Undiscriminated unions are skipped — TypeScript can't soundly narrow them.
+ * Returns the guard declarations as nodes (empty when no union narrows).
+ */
+export function typeGuardStatements(schemas: NamedSchemaModel[]): ts.FunctionDeclaration[] {
+  const byName = new Map(schemas.map((s) => [s.name, s.schema] as const));
+  const nodes: ts.FunctionDeclaration[] = [];
+  const emitted = new Set<string>();
+
+  for (const named of schemas) {
+    for (const site of collectUnionSites(named)) {
+      const discriminator =
+        site.union.discriminator ?? detectImplicitDiscriminator(site.union, byName);
+      if (!discriminator) continue;
+
+      // Group discriminant values by target schema so two mapping keys pointing at
+      // the same type produce one guard (a duplicate `is<Name>` would not compile).
+      const valuesByTarget = new Map<string, string[]>();
+      for (const entry of discriminator.mapping) {
+        if (!byName.has(entry.schemaName)) continue;
+        const existing = valuesByTarget.get(entry.schemaName);
+        if (existing) existing.push(entry.value);
+        else valuesByTarget.set(entry.schemaName, [entry.value]);
+      }
+
+      for (const [schemaName, values] of valuesByTarget) {
+        const guardName = `is${schemaName}`;
+        if (emitted.has(guardName)) continue;
+        emitted.add(guardName);
+        nodes.push(
+          buildTypeGuard(
+            site.makeParamType(),
+            site.label,
+            discriminator.propertyName,
+            schemaName,
+            values
+          )
+        );
+      }
+    }
+  }
+
+  return nodes;
+}
+
+const { factory } = ts;
+
+/**
+ * The discriminated-union sites reachable from a named schema, in a stable order:
+ * the schema itself (when it is a union), then any nested unions found by walking
+ * its tree. A top-level union keeps its name as the guard parameter; nested unions
+ * use their inline member union.
+ */
+function collectUnionSites(named: NamedSchemaModel): UnionSite[] {
+  const sites: UnionSite[] = [];
+  const root = named.schema;
+  if (root.kind === 'union') {
+    sites.push({
+      union: root,
+      label: named.name,
+      makeParamType: () => factory.createTypeReferenceNode(named.name),
+    });
+    for (const member of root.members) collectNestedSites(member, sites);
+  } else {
+    collectNestedSites(root, sites);
+  }
+  return sites;
+}
+
+/** Walk a schema subtree, recording each nested all-named-ref union as a site. */
+function collectNestedSites(schema: SchemaModel, sites: UnionSite[]): void {
+  switch (schema.kind) {
+    case 'union': {
+      const names = schema.members.map((m) => (m.kind === 'ref' ? m.name : undefined));
+      if (names.every((n): n is string => n !== undefined)) {
+        sites.push({
+          union: schema,
+          label: names.join(' | '),
+          makeParamType: () =>
+            factory.createUnionTypeNode(names.map((n) => factory.createTypeReferenceNode(n))),
+        });
+      }
+      for (const member of schema.members) collectNestedSites(member, sites);
+      break;
+    }
+    case 'array':
+      collectNestedSites(schema.items, sites);
+      break;
+    case 'record':
+      collectNestedSites(schema.value, sites);
+      break;
+    case 'object':
+      for (const prop of schema.properties) collectNestedSites(prop.schema, sites);
+      break;
+    case 'intersection':
+      for (const member of schema.members) collectNestedSites(member, sites);
+      break;
+    // scalar / literal / enum / ref / null / unknown / omit have no nested unions.
+  }
+}
+
+/** `(value as Record<string, unknown>)[<prop>]` — the narrowed property access. */
+function propertyAccess(propertyName: string): ts.Expression {
+  const recordType = factory.createTypeReferenceNode('Record', [
+    factory.createKeywordTypeNode(ts.SyntaxKind.StringKeyword),
+    factory.createKeywordTypeNode(ts.SyntaxKind.UnknownKeyword),
+  ]);
+  return factory.createElementAccessExpression(
+    factory.createAsExpression(factory.createIdentifier('value'), recordType),
+    factory.createStringLiteral(propertyName)
+  );
+}
+
+function buildTypeGuard(
+  paramType: ts.TypeNode,
+  unionLabel: string,
+  propertyName: string,
+  schemaName: string,
+  values: string[]
+): ts.FunctionDeclaration {
+  const access = propertyAccess(propertyName);
+  const check =
+    values.length === 1
+      ? factory.createBinaryExpression(
+          access,
+          factory.createToken(ts.SyntaxKind.EqualsEqualsEqualsToken),
+          factory.createStringLiteral(values[0])
+        )
+      : // `([...values] as readonly unknown[]).includes(<access>)`
+        factory.createCallExpression(
+          factory.createPropertyAccessExpression(
+            factory.createParenthesizedExpression(
+              factory.createAsExpression(
+                factory.createArrayLiteralExpression(
+                  values.map((v) => factory.createStringLiteral(v))
+                ),
+                factory.createTypeOperatorNode(
+                  ts.SyntaxKind.ReadonlyKeyword,
+                  factory.createArrayTypeNode(
+                    factory.createKeywordTypeNode(ts.SyntaxKind.UnknownKeyword)
+                  )
+                )
+              )
+            ),
+            'includes'
+          ),
+          undefined,
+          [access]
+        );
+
+  const fn = factory.createFunctionDeclaration(
+    [factory.createModifier(ts.SyntaxKind.ExportKeyword)],
+    undefined,
+    `is${schemaName}`,
+    undefined,
+    [factory.createParameterDeclaration(undefined, undefined, 'value', undefined, paramType)],
+    factory.createTypePredicateNode(
+      undefined,
+      'value',
+      factory.createTypeReferenceNode(schemaName)
+    ),
+    factory.createBlock([factory.createReturnStatement(check)], true)
+  );
+
+  return jsdoc(
+    fn,
+    `Narrow a \`${unionLabel}\` to \`${schemaName}\` via its \`${propertyName}\` discriminant.`
+  );
+}
+
+/**
+ * Detect an implicit discriminator: every member is a ref to a named schema,
+ * and they all pin one shared property to a distinct string literal. Returns
+ * `undefined` if no such property exists (so the union is left without guards).
+ */
+function detectImplicitDiscriminator(
+  union: Extract<SchemaModel, { kind: 'union' }>,
+  byName: Map<string, SchemaModel>
+): DiscriminatorModel | undefined {
+  const memberNames: string[] = [];
+  for (const member of union.members) {
+    if (member.kind !== 'ref') return undefined;
+    const target = byName.get(member.name);
+    if (!target) return undefined;
+    memberNames.push(member.name);
+  }
+  if (memberNames.length < 2) return undefined;
+
+  const literalsPerMember = memberNames.map((name) => literalPropsOf(byName.get(name)!));
+
+  for (const propName of Object.keys(literalsPerMember[0])) {
+    if (!literalsPerMember.every((props) => propName in props)) continue;
+    const values = literalsPerMember.map((props) => props[propName]);
+    if (!values.every((v): v is string => typeof v === 'string')) continue;
+    if (new Set(values).size !== values.length) continue;
+    return {
+      propertyName: propName,
+      mapping: memberNames.map((name, i) => ({
+        value: values[i] as string,
+        schemaName: name,
+      })),
+    };
+  }
+  return undefined;
+}
+
+/**
+ * Collect a schema's literal-valued properties (name → const value), descending
+ * through `intersection` members (the shape `allOf` produces). Only inline
+ * object/intersection members are inspected; nested refs are not resolved.
+ */
+function literalPropsOf(schema: SchemaModel): Record<string, string | number | boolean> {
+  const out: Record<string, string | number | boolean> = {};
+  const collect = (s: SchemaModel): void => {
+    if (s.kind === 'object') {
+      for (const prop of s.properties) {
+        if (prop.schema.kind === 'literal') out[prop.name] = prop.schema.value;
+      }
+    } else if (s.kind === 'intersection') {
+      for (const member of s.members) collect(member);
+    }
+  };
+  collect(schema);
+  return out;
+}
diff --git a/packages/client-generator/src/emitters/types.ts b/packages/client-generator/src/emitters/types.ts
new file mode 100644
index 0000000000..bd97138417
--- /dev/null
+++ b/packages/client-generator/src/emitters/types.ts
@@ -0,0 +1,209 @@
+import type {
+  NamedSchemaModel,
+  PropertyModel,
+  ScalarKind,
+  SchemaMetadata,
+  SchemaModel,
+} from '../intermediate-representation/model.js';
+import { isIdentifier, safeIdent } from './identifier.js';
+import { jsdocText } from './jsdoc.js';
+import { jsdoc, literalExpression, printNodes, ts } from './ts.js';
+
+const { factory } = ts;
+
+/**
+ * How named string enums are emitted:
+ * - `'union'`: only the string-literal union type (`type X = "a" | "b"`).
+ * - `'const-object'`: the union type *and* a sibling
+ *   `export const X = { a: "a", b: "b" } as const;` so callers can reference
+ *   the values at runtime (`X.a`).
+ */
+export type EnumStyle = 'union' | 'const-object';
+
+/**
+ * How `format: date-time`/`date` string fields are typed:
+ * - `'string'` (default): the wire shape — an ISO string.
+ * - `'Date'`: a `Date` reference. Opt-in; pair with the `transformers` generator
+ *   so the runtime value matches (the client stays zero-dep — `Date` is standard).
+ */
+export type DateType = 'string' | 'Date';
+
+/** The model type aliases (and const-object enum companions) as nodes. */
+export function typesStatements(
+  schemas: NamedSchemaModel[],
+  enumStyle: EnumStyle,
+  dateType: DateType = 'string'
+): ts.Statement[] {
+  const nodes: ts.Statement[] = [];
+  for (const s of schemas) {
+    nodes.push(
+      jsdocOn(
+        factory.createTypeAliasDeclaration(
+          [factory.createModifier(ts.SyntaxKind.ExportKeyword)],
+          s.name,
+          undefined,
+          schemaToTypeNode(s.schema, dateType)
+        ),
+        s.schema.description ?? s.description,
+        s.schema.metadata
+      )
+    );
+    if (enumStyle === 'const-object') {
+      const constObject = enumConstObject(s);
+      if (constObject) nodes.push(constObject);
+    }
+  }
+  return nodes;
+}
+
+/**
+ * For a named **string** enum, build a runtime companion
+ * `export const X = { a: "a", … } as const;` that cohabits with the same-named
+ * type (TypeScript allows a type and value to share an identifier). This lets
+ * callers reference values at runtime (`X.a`) instead of retyping literals.
+ *
+ * Returns `undefined` (so only the type union is emitted) when:
+ * - the schema isn't a string enum (integer/boolean enums gain nothing), or
+ * - any value isn't a valid JS identifier (e.g. `"menu:read"`) — we don't emit
+ *   a half-usable object with quoted keys.
+ */
+function enumConstObject(named: NamedSchemaModel): ts.VariableStatement | undefined {
+  const schema = named.schema;
+  if (schema.kind !== 'enum' || schema.scalar !== 'string') return undefined;
+  if (!schema.values.every((v) => typeof v === 'string' && isIdentifier(v))) return undefined;
+
+  const object = factory.createObjectLiteralExpression(
+    schema.values.map((v) =>
+      factory.createPropertyAssignment(v as string, factory.createStringLiteral(v as string))
+    ),
+    true
+  );
+  return factory.createVariableStatement(
+    [factory.createModifier(ts.SyntaxKind.ExportKeyword)],
+    factory.createVariableDeclarationList(
+      [
+        factory.createVariableDeclaration(
+          named.name,
+          undefined,
+          undefined,
+          factory.createAsExpression(object, factory.createTypeReferenceNode('const'))
+        ),
+      ],
+      ts.NodeFlags.Const
+    )
+  );
+}
+
+export function renderSchema(schema: SchemaModel, dateType: DateType = 'string'): string {
+  return printNodes([schemaToTypeNode(schema, dateType)]);
+}
+
+/** Build the TypeScript type node for an IR schema. */
+export function schemaToTypeNode(schema: SchemaModel, dateType: DateType = 'string'): ts.TypeNode {
+  switch (schema.kind) {
+    case 'scalar':
+      return scalarTypeNode(schema.scalar, schema.metadata, dateType);
+    case 'ref':
+      return factory.createTypeReferenceNode(schema.name);
+    case 'literal':
+      return factory.createLiteralTypeNode(literalExpression(schema.value));
+    case 'enum': {
+      const members = schema.values.map((v) => factory.createLiteralTypeNode(literalExpression(v)));
+      // A single-value enum is just that literal — wrapping it in a one-member
+      // union would make the printer parenthesize it inside `T[]` (`("a")[]`).
+      return members.length === 1 ? members[0] : factory.createUnionTypeNode(members);
+    }
+    case 'null':
+      return factory.createLiteralTypeNode(factory.createNull());
+    case 'unknown':
+      return factory.createKeywordTypeNode(ts.SyntaxKind.UnknownKeyword);
+    case 'array':
+      // The printer parenthesizes union/intersection element types itself
+      // (`(string | null)[]`), so just hand it the element node.
+      return factory.createArrayTypeNode(schemaToTypeNode(schema.items, dateType));
+    case 'record':
+      return factory.createTypeReferenceNode('Record', [
+        factory.createKeywordTypeNode(ts.SyntaxKind.StringKeyword),
+        schemaToTypeNode(schema.value, dateType),
+      ]);
+    case 'object':
+      return factory.createTypeLiteralNode(
+        schema.properties.map((p) => propertySignature(p, dateType))
+      );
+    case 'union':
+      return factory.createUnionTypeNode(schema.members.map((m) => schemaToTypeNode(m, dateType)));
+    case 'intersection':
+      return factory.createIntersectionTypeNode(
+        schema.members.map((m) => schemaToTypeNode(m, dateType))
+      );
+    case 'omit':
+      return factory.createTypeReferenceNode('Omit', [
+        factory.createTypeReferenceNode(schema.base),
+        factory.createUnionTypeNode(
+          schema.keys.map((k) => factory.createLiteralTypeNode(factory.createStringLiteral(k)))
+        ),
+      ]);
+  }
+}
+
+function propertySignature(p: PropertyModel, dateType: DateType): ts.PropertySignature {
+  // `readOnly` (server-managed) props get the `readonly` modifier so consumer
+  // write-type utilities (OmitReadOnly<T>) can strip them and assignment is
+  // flagged. Request-body types already drop these via `Omit` in the IR.
+  const modifiers = p.readOnly
+    ? [factory.createModifier(ts.SyntaxKind.ReadonlyKeyword)]
+    : undefined;
+  const sig = factory.createPropertySignature(
+    modifiers,
+    propertyName(p.name),
+    p.required ? undefined : factory.createToken(ts.SyntaxKind.QuestionToken),
+    schemaToTypeNode(p.schema, dateType)
+  );
+  return jsdocOn(sig, p.description, p.schema.metadata);
+}
+
+/** A property name: a bare identifier when valid, a quoted string literal otherwise. */
+function propertyName(name: string): ts.PropertyName {
+  const safe = safeIdent(name);
+  return safe === name ? factory.createIdentifier(name) : factory.createStringLiteral(name);
+}
+
+function scalarTypeNode(
+  kind: ScalarKind,
+  metadata: SchemaMetadata | undefined,
+  dateType: DateType
+): ts.TypeNode {
+  switch (kind) {
+    case 'string':
+      // `format: binary` is raw byte content (file uploads / octet-stream), not text —
+      // surface it as `Blob` (the web standard; a `File` is assignable to it). `byte`
+      // (base64) stays a `string`.
+      if (metadata?.format === 'binary') {
+        return factory.createTypeReferenceNode('Blob');
+      }
+      // Opt-in: a `date-time`/`date` string surfaces as `Date` under `dateType:
+      // 'Date'`; everything else (and the default) stays the `string` keyword.
+      if (
+        dateType === 'Date' &&
+        (metadata?.format === 'date-time' || metadata?.format === 'date')
+      ) {
+        return factory.createTypeReferenceNode('Date');
+      }
+      return factory.createKeywordTypeNode(ts.SyntaxKind.StringKeyword);
+    case 'number':
+    case 'integer':
+      return factory.createKeywordTypeNode(ts.SyntaxKind.NumberKeyword);
+    case 'boolean':
+      return factory.createKeywordTypeNode(ts.SyntaxKind.BooleanKeyword);
+  }
+}
+
+/** Attach a JSDoc block (description + metadata tags) to `node`, if any. */
+function jsdocOn<T extends ts.Node>(
+  node: T,
+  text: string | undefined,
+  metadata?: SchemaMetadata
+): T {
+  const body = jsdocText(text, metadata);
+  return body === undefined ? node : jsdoc(node, body);
+}
diff --git a/packages/client-generator/src/emitters/wrapper-support.ts b/packages/client-generator/src/emitters/wrapper-support.ts
new file mode 100644
index 0000000000..f5ba14046b
--- /dev/null
+++ b/packages/client-generator/src/emitters/wrapper-support.ts
@@ -0,0 +1,154 @@
+// Shared support for the data-fetching wrapper generators (`swr`, `tanstack-query`).
+// Both wrap the sdk's exported operation functions, so they agree on which operations
+// are wrappable and on the `vars`/`init` parameter shape. Keeping that agreement in one
+// place stops the two emitters from drifting (and makes a third adapter cheap). The
+// per-operation factory/hook bodies stay in each emitter — only the cross-cutting
+// calling-convention pieces live here.
+
+import { logger } from '@redocly/openapi-core';
+
+import type { ApiModel, OperationModel } from '../intermediate-representation/model.js';
+import { operationSignature } from './operation-signature.js';
+import { isSseOp } from './sse.js';
+import { ts } from './ts.js';
+
+const { factory } = ts;
+
+/**
+ * The operations a wrapper generator can wrap, with skips reported to the user under
+ * `label` (the generator name). Two kinds are dropped:
+ *
+ * - **SSE operations** — the sdk exposes these as async generators (streams), not
+ *   request/response functions, so a query/mutation hook cannot wrap them.
+ * - **`<Op>Variables` name collisions** — a wrapper types its inputs as the sdk's
+ *   `<Op>Variables`; when that name collides with a schema the sdk suppresses the alias,
+ *   so the import would resolve to the schema (a wrong/broken type). The sdk function still
+ *   works; renaming the schema or the operation restores the wrapper.
+ */
+export function wrappableOperations(model: ApiModel, label: string): OperationModel[] {
+  const all = model.services.flatMap((s) => s.operations);
+  const sse = all.filter(isSseOp);
+  if (sse.length > 0) {
+    logger.warn(
+      `generate-client: ${label} skipped ${sse.length} server-sent-events operation(s) — iterate the sdk's exported async generators directly: ${sse
+        .map((op) => op.name)
+        .join(', ')}.\n`
+    );
+  }
+  const schemaNames = new Set(model.schemas.map((s) => s.name));
+  const clashing = all.filter((op) => !isSseOp(op) && collides(op, schemaNames));
+  if (clashing.length > 0) {
+    logger.warn(
+      `generate-client: ${label} skipped ${clashing.length} operation(s) whose variables type name collides with a schema — rename the schema or the operation: ${clashing
+        .map((op) => op.name)
+        .join(', ')}.\n`
+    );
+  }
+  return all.filter((op) => !isSseOp(op) && !collides(op, schemaNames));
+}
+
+/** Whether the operation's `<Op>Variables` type name collides with a named schema. */
+function collides(op: OperationModel, schemaNames: Set<string>): boolean {
+  const sig = operationSignature(op);
+  return sig.hasInputs && schemaNames.has(sig.variablesTypeName);
+}
+
+/** Query operations are the safe, cacheable methods. Everything else is a mutation. */
+export function isQuery(op: OperationModel): boolean {
+  return op.method === 'get' || op.method === 'head';
+}
+
+/** Whether the operation has any inputs — i.e. a `<Op>Variables` type exists in the sdk. */
+export function hasInputs(op: OperationModel): boolean {
+  return operationSignature(op).hasInputs;
+}
+
+/** The operation's `<Op>Variables` type name (the sdk's grouped-input alias). */
+export function variablesName(op: OperationModel): string {
+  return operationSignature(op).variablesTypeName;
+}
+
+/** A `vars: <Op>Variables` parameter. */
+export function varsParam(op: OperationModel): ts.ParameterDeclaration {
+  return factory.createParameterDeclaration(
+    undefined,
+    undefined,
+    'vars',
+    undefined,
+    factory.createTypeReferenceNode(variablesName(op))
+  );
+}
+
+/** An `init?: RequestOptions` parameter. */
+export function initParam(): ts.ParameterDeclaration {
+  return factory.createParameterDeclaration(
+    undefined,
+    undefined,
+    'init',
+    factory.createToken(ts.SyntaxKind.QuestionToken),
+    factory.createTypeReferenceNode('RequestOptions')
+  );
+}
+
+/**
+ * The forwarding call to the sdk operation function. Argument order comes from the
+ * shared `operationSignature`, so it lines up with the sdk's parameter list by
+ * construction. `grouped` passes the source object (when inputs); `flat` spreads
+ * `<source>.<pathIdent>` (URL-template order), then `<source>.params` / `.body` /
+ * `.headers` for the slots the op has. `init` is appended last when `withInit`
+ * (the sdk function's trailing `RequestOptions`).
+ */
+export function sdkCall(
+  op: OperationModel,
+  argsStyle: 'flat' | 'grouped',
+  source: string,
+  withInit: boolean
+): ts.Expression {
+  const sig = operationSignature(op);
+  const sourceIdent = factory.createIdentifier(source);
+  const args: ts.Expression[] = [];
+
+  if (argsStyle === 'grouped') {
+    if (sig.hasInputs) args.push(sourceIdent);
+  } else {
+    for (const { ident } of sig.pathParams) {
+      args.push(factory.createPropertyAccessExpression(sourceIdent, ident));
+    }
+    if (sig.hasQuery) args.push(factory.createPropertyAccessExpression(sourceIdent, 'params'));
+    if (sig.hasBody) args.push(factory.createPropertyAccessExpression(sourceIdent, 'body'));
+    if (sig.hasHeaders) args.push(factory.createPropertyAccessExpression(sourceIdent, 'headers'));
+    if (sig.hasCookies) args.push(factory.createPropertyAccessExpression(sourceIdent, 'cookies'));
+  }
+  if (withInit) args.push(factory.createIdentifier('init'));
+
+  return factory.createCallExpression(factory.createIdentifier(op.name), undefined, args);
+}
+
+/**
+ * The named import from the sdk module: the wrapped opFns as value specifiers, then
+ * the referenced `<Op>Variables` types + `RequestOptions` (when any query op) as
+ * `type` specifiers, each group sorted.
+ */
+export function sdkNamedImport(
+  ops: OperationModel[],
+  sdkModule: string,
+  hasQuery: boolean
+): ts.Statement {
+  const values = ops.map((op) => op.name).sort();
+  const types = ops.filter(hasInputs).map(variablesName).sort();
+  if (hasQuery) types.push('RequestOptions');
+
+  const specifiers = [
+    ...values.map((name) =>
+      factory.createImportSpecifier(false, undefined, factory.createIdentifier(name))
+    ),
+    ...types.map((name) =>
+      factory.createImportSpecifier(true, undefined, factory.createIdentifier(name))
+    ),
+  ];
+  return factory.createImportDeclaration(
+    undefined,
+    factory.createImportClause(false, undefined, factory.createNamedImports(specifiers)),
+    factory.createStringLiteral(sdkModule)
+  );
+}
diff --git a/packages/client-generator/src/emitters/zod.ts b/packages/client-generator/src/emitters/zod.ts
new file mode 100644
index 0000000000..db41643ae4
--- /dev/null
+++ b/packages/client-generator/src/emitters/zod.ts
@@ -0,0 +1,459 @@
+// Emits Zod schemas from the IR. Each named schema becomes an
+// `export const <Name>Schema = z.<…>;` built with `ts.factory`, mirroring the
+// type emitter (`types.ts`) but targeting runtime validators instead of types.
+// Operations with a JSON request or response body additionally land in the
+// `operationSchemas` map, which powers the `zodValidation` client middleware.
+//
+// Only the refinement methods stable across zod 3.23 and 4 are emitted
+// (`.min/.max/.int/.gt/.lt/.regex`); format helpers (`.email/.uuid/.url`) diverge
+// between major versions and are deferred. Refs become `z.lazy(() => …Schema)`,
+// which sidesteps declaration ordering and recursion uniformly.
+
+import {
+  allOperations,
+  type ApiModel,
+  type NamedSchemaModel,
+  type PropertyModel,
+  type ScalarKind,
+  type SchemaMetadata,
+  type SchemaModel,
+} from '../intermediate-representation/model.js';
+import { safeIdent } from './identifier.js';
+import { isSseOp } from './sse.js';
+import { pascalCase } from './support.js';
+import { jsdoc, literalExpression, printStatements, ts } from './ts.js';
+
+const { factory } = ts;
+
+/** `<Name>Schema` — the const identifier a named schema is bound to. */
+function schemaConstName(name: string): string {
+  return `${pascalCase(name)}Schema`;
+}
+
+/** `z` member access: `z.<method>`. */
+function zMember(method: string): ts.Expression {
+  return factory.createPropertyAccessExpression(factory.createIdentifier('z'), method);
+}
+
+/** `z.<method>(...args)`. */
+function zCall(method: string, args: ts.Expression[] = []): ts.CallExpression {
+  return factory.createCallExpression(zMember(method), undefined, args);
+}
+
+/** `<expr>.<method>(...args)` — chains a refinement onto a base expression. */
+function chain(expr: ts.Expression, method: string, args: ts.Expression[] = []): ts.CallExpression {
+  return factory.createCallExpression(
+    factory.createPropertyAccessExpression(expr, method),
+    undefined,
+    args
+  );
+}
+
+type SchemaByName = ReadonlyMap<string, SchemaModel>;
+
+const NO_SCHEMAS: SchemaByName = new Map();
+
+/** Map an IR schema to the Zod expression that validates it. */
+export function schemaToZodExpression(
+  schema: SchemaModel,
+  byName: SchemaByName = NO_SCHEMAS
+): ts.Expression {
+  return withRefinements(baseExpression(schema, byName), schema);
+}
+
+function baseExpression(schema: SchemaModel, byName: SchemaByName): ts.Expression {
+  switch (schema.kind) {
+    case 'scalar':
+      return scalarExpression(schema.scalar, schema.metadata);
+    case 'object':
+      return objectExpression(schema.properties, byName);
+    case 'array':
+      return zCall('array', [schemaToZodExpression(schema.items, byName)]);
+    case 'record':
+      return zCall('record', [zCall('string'), schemaToZodExpression(schema.value, byName)]);
+    case 'ref':
+      return lazyRef(schema.name);
+    case 'literal':
+      return zCall('literal', [literalExpression(schema.value)]);
+    case 'enum':
+      return enumExpression(schema.values);
+    case 'union':
+      return unionExpression(schema.members, byName);
+    case 'intersection':
+      return intersectionExpression(schema.members, byName);
+    case 'null':
+      return zCall('null');
+    case 'unknown':
+      return zCall('unknown');
+    case 'omit':
+      return omitExpression(schema.base, schema.keys, byName);
+  }
+}
+
+function scalarExpression(scalar: ScalarKind, metadata?: SchemaMetadata): ts.Expression {
+  switch (scalar) {
+    case 'string':
+      // `format: binary` is typed as `Blob` (see types.ts); validate it as one so the zod
+      // schema agrees with the generated type instead of expecting a string.
+      if (metadata?.format === 'binary') {
+        return zCall('instanceof', [factory.createIdentifier('Blob')]);
+      }
+      return zCall('string');
+    case 'integer':
+      return chain(zCall('number'), 'int');
+    case 'number':
+      return zCall('number');
+    case 'boolean':
+      return zCall('boolean');
+  }
+}
+
+/** `z.object({ <key>: <expr>(.optional() when !required), … })`. */
+function objectExpression(properties: PropertyModel[], byName: SchemaByName): ts.Expression {
+  const props = properties.map((p) => {
+    const value = p.required
+      ? schemaToZodExpression(p.schema, byName)
+      : chain(schemaToZodExpression(p.schema, byName), 'optional');
+    const safe = safeIdent(p.name);
+    const key =
+      safe === p.name ? factory.createIdentifier(p.name) : factory.createStringLiteral(p.name);
+    return factory.createPropertyAssignment(key, value);
+  });
+  return zCall('object', [factory.createObjectLiteralExpression(props, props.length > 0)]);
+}
+
+/** `z.lazy(() => <Name>Schema)` — defers reference resolution to call time. */
+function lazyRef(name: string): ts.Expression {
+  const arrow = factory.createArrowFunction(
+    undefined,
+    undefined,
+    [],
+    undefined,
+    factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken),
+    factory.createIdentifier(schemaConstName(name))
+  );
+  return zCall('lazy', [arrow]);
+}
+
+/** All-string values → `z.enum([…])`; otherwise → a union of literals. */
+function enumExpression(values: Array<string | number | boolean>): ts.Expression {
+  if (values.every((v) => typeof v === 'string')) {
+    return zCall('enum', [
+      factory.createArrayLiteralExpression(
+        values.map((v) => factory.createStringLiteral(v as string)),
+        false
+      ),
+    ]);
+  }
+  return zCall('union', [
+    factory.createArrayLiteralExpression(
+      values.map((v) => zCall('literal', [literalExpression(v)])),
+      false
+    ),
+  ]);
+}
+
+/** `z.union([…])`; a single member collapses to that member's expression. */
+function unionExpression(members: SchemaModel[], byName: SchemaByName): ts.Expression {
+  const exprs = members.map((member) => schemaToZodExpression(member, byName));
+  if (exprs.length === 1) return exprs[0];
+  return zCall('union', [factory.createArrayLiteralExpression(exprs, false)]);
+}
+
+/** `a.and(b).and(c)` — left-folds `.and` over the members. */
+function intersectionExpression(members: SchemaModel[], byName: SchemaByName): ts.Expression {
+  const exprs = members.map((member) => schemaToZodExpression(member, byName));
+  return exprs.reduce((acc, next) => chain(acc, 'and', [next]));
+}
+
+/**
+ * `<Base>Schema.omit({ k1: true, … })` when the base is a plain object schema.
+ * `.omit` exists only on `ZodObject` — for any other base (an `allOf` intersection,
+ * a union, …) the omission is distributed into the base's object members instead.
+ */
+function omitExpression(base: string, keys: string[], byName: SchemaByName): ts.Expression {
+  const target = byName.get(base);
+  if (target && target.kind !== 'object') {
+    return schemaToZodExpression(applyOmit(target, keys, byName, new Set([base])), byName);
+  }
+  const mask = factory.createObjectLiteralExpression(
+    keys.map((k) => {
+      const safe = safeIdent(k);
+      const key = safe === k ? factory.createIdentifier(k) : factory.createStringLiteral(k);
+      return factory.createPropertyAssignment(key, factory.createTrue());
+    }),
+    false
+  );
+  return chain(factory.createIdentifier(schemaConstName(base)), 'omit', [mask]);
+}
+
+/**
+ * Remove `keys` from a schema that is not a plain object: objects drop the properties,
+ * union/intersection members recurse, and a ref to an object becomes `<Ref>Schema.omit`
+ * with only the keys that exist on it (zod's mask rejects unknown keys at the type
+ * level). Cycles and non-object leaves return unchanged — there is nothing to omit.
+ */
+function applyOmit(
+  schema: SchemaModel,
+  keys: string[],
+  byName: SchemaByName,
+  seen: Set<string>
+): SchemaModel {
+  switch (schema.kind) {
+    case 'object':
+      return { ...schema, properties: schema.properties.filter((p) => !keys.includes(p.name)) };
+    case 'union':
+    case 'intersection':
+      return {
+        ...schema,
+        members: schema.members.map((member) => applyOmit(member, keys, byName, seen)),
+      };
+    case 'ref': {
+      if (seen.has(schema.name)) return schema;
+      const target = byName.get(schema.name);
+      if (!target) return schema;
+      if (target.kind === 'object') {
+        const present = keys.filter((key) =>
+          target.properties.some((property) => property.name === key)
+        );
+        return present.length > 0 ? { kind: 'omit', base: schema.name, keys: present } : schema;
+      }
+      return applyOmit(target, keys, byName, new Set([...seen, schema.name]));
+    }
+    default:
+      return schema;
+  }
+}
+
+/**
+ * Chain the stable-subset metadata refinements onto `expr`. Order: numeric/length
+ * bounds, then `.regex` (the `.int()` for integers is already on the base).
+ * `.optional()` is NOT applied here — optionality is a property-level concern
+ * handled in `objectExpression`, so a top-level schema is never spuriously optional.
+ */
+function withRefinements(expr: ts.Expression, schema: SchemaModel): ts.Expression {
+  const m = schema.metadata;
+  if (!m) return expr;
+  let out = expr;
+  if (schema.kind === 'scalar' && schema.scalar === 'string') {
+    if (m.minLength !== undefined) out = chain(out, 'min', [literalExpression(m.minLength)]);
+    if (m.maxLength !== undefined) out = chain(out, 'max', [literalExpression(m.maxLength)]);
+    if (m.pattern !== undefined) out = chain(out, 'regex', [regexExpression(m.pattern)]);
+  }
+  if (schema.kind === 'scalar' && (schema.scalar === 'number' || schema.scalar === 'integer')) {
+    out = numericRefinements(out, m);
+  }
+  if (schema.kind === 'array') {
+    if (m.minItems !== undefined) out = chain(out, 'min', [literalExpression(m.minItems)]);
+    if (m.maxItems !== undefined) out = chain(out, 'max', [literalExpression(m.maxItems)]);
+  }
+  return out;
+}
+
+function numericRefinements(expr: ts.Expression, m: SchemaMetadata): ts.Expression {
+  let out = expr;
+  if (m.minimum !== undefined) out = chain(out, 'min', [literalExpression(m.minimum)]);
+  if (m.maximum !== undefined) out = chain(out, 'max', [literalExpression(m.maximum)]);
+  if (m.exclusiveMinimum !== undefined)
+    out = chain(out, 'gt', [literalExpression(m.exclusiveMinimum)]);
+  if (m.exclusiveMaximum !== undefined)
+    out = chain(out, 'lt', [literalExpression(m.exclusiveMaximum)]);
+  return out;
+}
+
+/** `new RegExp("<pattern>")` — robust across printers regardless of pattern content. */
+function regexExpression(pattern: string): ts.Expression {
+  return factory.createNewExpression(factory.createIdentifier('RegExp'), undefined, [
+    factory.createStringLiteral(pattern),
+  ]);
+}
+
+/** `export const <Name>Schema = <expr>;` for one named schema. */
+function schemaConstStatement(named: NamedSchemaModel, byName: SchemaByName): ts.Statement {
+  return factory.createVariableStatement(
+    [factory.createModifier(ts.SyntaxKind.ExportKeyword)],
+    factory.createVariableDeclarationList(
+      [
+        factory.createVariableDeclaration(
+          schemaConstName(named.name),
+          undefined,
+          undefined,
+          schemaToZodExpression(named.schema, byName)
+        ),
+      ],
+      ts.NodeFlags.Const
+    )
+  );
+}
+
+/** `import { z } from 'zod';` */
+function zodImport(): ts.Statement {
+  return factory.createImportDeclaration(
+    undefined,
+    factory.createImportClause(
+      false,
+      undefined,
+      factory.createNamedImports([
+        factory.createImportSpecifier(false, undefined, factory.createIdentifier('z')),
+      ])
+    ),
+    factory.createStringLiteral('zod')
+  );
+}
+
+/**
+ * `<opName>: { request?: <expr>, response?: <expr> }` for every non-SSE operation with a
+ * JSON request or response body — the operation's validators, keyed by the same id the
+ * middleware sees at runtime (`ctx.operation.id`). SSE, binary, text, and void bodies
+ * have no JSON payload to validate and are skipped.
+ */
+type OperationSchemaEntry = { name: string; request?: ts.Expression; response?: ts.Expression };
+
+function operationSchemaEntries(model: ApiModel, byName: SchemaByName): OperationSchemaEntry[] {
+  const entries: OperationSchemaEntry[] = [];
+  for (const op of allOperations(model.services)) {
+    if (isSseOp(op)) continue;
+    const requestBody = op.requestBody;
+    const request =
+      requestBody && requestBody.contentType.toLowerCase().includes('json')
+        ? schemaToZodExpression(requestBody.schema, byName)
+        : undefined;
+    const jsonResponse = op.successResponses.find((response) =>
+      response.contentType.toLowerCase().includes('json')
+    );
+    const response = jsonResponse ? schemaToZodExpression(jsonResponse.schema, byName) : undefined;
+    if (!request && !response) continue;
+    entries.push({ name: op.name, request, response });
+  }
+  return entries;
+}
+
+function operationSchemasStatement(entries: OperationSchemaEntry[]): ts.Statement {
+  const zodTypeNode = () =>
+    factory.createTypeReferenceNode(
+      factory.createQualifiedName(factory.createIdentifier('z'), 'ZodType')
+    );
+  // The explicit `z.ZodType` annotation keeps the declaration-emit size proportional to
+  // the operation count: the inferred type would serialize every schema's zod generics
+  // and overflow tsc's limit (TS7056) on large APIs under `declaration: true`.
+  const typeMembers = entries.map((entry) =>
+    factory.createPropertySignature(
+      undefined,
+      entry.name,
+      undefined,
+      factory.createTypeLiteralNode(
+        [
+          entry.request
+            ? factory.createPropertySignature(undefined, 'request', undefined, zodTypeNode())
+            : undefined,
+          entry.response
+            ? factory.createPropertySignature(undefined, 'response', undefined, zodTypeNode())
+            : undefined,
+        ].filter((member) => member !== undefined)
+      )
+    )
+  );
+  const valueEntries = entries.map((entry) =>
+    factory.createPropertyAssignment(
+      entry.name,
+      factory.createObjectLiteralExpression(
+        [
+          entry.request ? factory.createPropertyAssignment('request', entry.request) : undefined,
+          entry.response ? factory.createPropertyAssignment('response', entry.response) : undefined,
+        ].filter((property) => property !== undefined),
+        false
+      )
+    )
+  );
+  return jsdoc(
+    factory.createVariableStatement(
+      [factory.createModifier(ts.SyntaxKind.ExportKeyword)],
+      factory.createVariableDeclarationList(
+        [
+          factory.createVariableDeclaration(
+            'operationSchemas',
+            undefined,
+            factory.createTypeLiteralNode(typeMembers),
+            factory.createObjectLiteralExpression(valueEntries, true)
+          ),
+        ],
+        ts.NodeFlags.Const
+      )
+    ),
+    'Request/response validators by operationId — powers `zodValidation`, or import one directly.'
+  );
+}
+
+// The validation middleware, spliced verbatim after the schemas (matches the printer's
+// double-quote/4-space style). Structurally compatible with the client's `Middleware`
+// without importing it, so the zod module keeps its single `zod` dependency.
+const VALIDATION_SUPPORT = `/** \`request\`/\`response\` validators for one operation (an absent side is not validated). */
+export type OperationSchemaSet = { request?: z.ZodType; response?: z.ZodType };
+
+const schemaIndex: Partial<Record<string, OperationSchemaSet>> = operationSchemas;
+
+/** A request or response payload failed validation. Always thrown, even on result-mode clients. */
+export class ZodValidationError extends Error {
+    constructor(
+        readonly operationId: string,
+        readonly direction: "request" | "response",
+        readonly issues: z.ZodError["issues"]
+    ) {
+        const detail = issues
+            .map((issue) => \`\${issue.path.join(".") || "(root)"}: \${issue.message}\`)
+            .join("; ");
+        super(\`\${direction === "request" ? "Request" : "Response"} validation failed for operation "\${operationId}": \${detail}\`);
+        this.name = "ZodValidationError";
+    }
+}
+
+/**
+ * Schema-validation middleware for the generated client: \`use(zodValidation())\`.
+ * Request bodies are validated before any network call; successful JSON responses are
+ * validated against the operation's response schema. Payloads are never mutated, and
+ * operations without a schema pass through untouched. A failure throws
+ * \`ZodValidationError\` — always, even on result-mode clients.
+ */
+export function zodValidation(options: { request?: boolean; response?: boolean } = {}) {
+    const { request = true, response = true } = options;
+    return {
+        onRequest(context: { body?: unknown; operation: { id: string } }): void {
+            if (!request || context.body === undefined) return;
+            const schema = schemaIndex[context.operation.id]?.request;
+            if (!schema) return;
+            const result = schema.safeParse(context.body);
+            if (!result.success) {
+                throw new ZodValidationError(context.operation.id, "request", result.error.issues);
+            }
+        },
+        async onResponse(incoming: Response, context: { operation: { id: string } }): Promise<void> {
+            if (!response || !incoming.ok) return;
+            const schema = schemaIndex[context.operation.id]?.response;
+            if (!schema) return;
+            const contentType = (incoming.headers.get("content-type") ?? "").toLowerCase();
+            if (!contentType.includes("json")) return;
+            const result = schema.safeParse(await incoming.clone().json());
+            if (!result.success) {
+                throw new ZodValidationError(context.operation.id, "response", result.error.issues);
+            }
+        },
+    };
+}`;
+
+/**
+ * Render the full zod module source: the component schemas, then — when any operation
+ * has a JSON body — the `operationSchemas` map and the `zodValidation` middleware.
+ * `''` when there is nothing to emit.
+ */
+export function renderZodModule(model: ApiModel): string {
+  const byName: SchemaByName = new Map(model.schemas.map((named) => [named.name, named.schema]));
+  const entries = operationSchemaEntries(model, byName);
+  if (model.schemas.length === 0 && entries.length === 0) return '';
+  const statements: ts.Statement[] = [
+    zodImport(),
+    ...model.schemas.map((named) => schemaConstStatement(named, byName)),
+  ];
+  if (entries.length === 0) return printStatements(statements);
+  statements.push(operationSchemasStatement(entries));
+  return `${printStatements(statements)}\n${VALIDATION_SUPPORT}\n`;
+}
diff --git a/packages/client-generator/src/errors.ts b/packages/client-generator/src/errors.ts
new file mode 100644
index 0000000000..4c400665d2
--- /dev/null
+++ b/packages/client-generator/src/errors.ts
@@ -0,0 +1,6 @@
+export class NotSupportedError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'NotSupportedError';
+  }
+}
diff --git a/packages/client-generator/src/generators/__tests__/fixtures/empty-plugin.ts b/packages/client-generator/src/generators/__tests__/fixtures/empty-plugin.ts
new file mode 100644
index 0000000000..073f10ce1e
--- /dev/null
+++ b/packages/client-generator/src/generators/__tests__/fixtures/empty-plugin.ts
@@ -0,0 +1,2 @@
+// A module that exports no generator — exercises the "must export a generator" guard.
+export const unrelated = 42;
diff --git a/packages/client-generator/src/generators/__tests__/fixtures/route-map-plugin.ts b/packages/client-generator/src/generators/__tests__/fixtures/route-map-plugin.ts
new file mode 100644
index 0000000000..1591f760c7
--- /dev/null
+++ b/packages/client-generator/src/generators/__tests__/fixtures/route-map-plugin.ts
@@ -0,0 +1,21 @@
+// A minimal custom-generator fixture loaded by specifier in resolve.test.ts and the plugin e2e.
+import type { CustomGenerator } from '../../types.js';
+
+const generator: CustomGenerator = {
+  name: 'route-map',
+  requires: ['sdk'],
+  run({ model, outputPath }) {
+    const routes = model.services
+      .flatMap((s) => s.operations)
+      .map((op) => `  ${op.name}: '${op.method.toUpperCase()} ${op.path}',`)
+      .join('\n');
+    return [
+      {
+        path: outputPath.replace(/\.ts$/, '.routes.ts'),
+        content: `export const routes = {\n${routes}\n} as const;\n`,
+      },
+    ];
+  },
+};
+
+export default generator;
diff --git a/packages/client-generator/src/generators/__tests__/index.test.ts b/packages/client-generator/src/generators/__tests__/index.test.ts
new file mode 100644
index 0000000000..3291e77510
--- /dev/null
+++ b/packages/client-generator/src/generators/__tests__/index.test.ts
@@ -0,0 +1,115 @@
+import { NotSupportedError } from '../../errors.js';
+import { builtinGenerators, validateGenerators } from '../index.js';
+import { sdkGenerator } from '../sdk.js';
+import { zodGenerator } from '../zod.js';
+
+describe('builtinGenerators', () => {
+  it('registers the sdk generator descriptor', () => {
+    expect(builtinGenerators().get('sdk')?.run).toBe(sdkGenerator);
+  });
+
+  it('registers the zod generator descriptor', () => {
+    expect(builtinGenerators().get('zod')?.run).toBe(zodGenerator);
+  });
+
+  it('has no entry for an unknown generator name', () => {
+    expect(builtinGenerators().has('nope')).toBe(false);
+  });
+});
+
+describe('validateGenerators', () => {
+  it('accepts sdk alone', () => {
+    expect(() => validateGenerators(['sdk'], {})).not.toThrow();
+  });
+
+  it('accepts zod alone — it requires nothing', () => {
+    expect(() => validateGenerators(['zod'], {})).not.toThrow();
+  });
+
+  it('accepts sdk + tanstack-query with the default error-mode', () => {
+    expect(() => validateGenerators(['sdk', 'tanstack-query'], {})).not.toThrow();
+  });
+
+  it.each(['tanstack-query', 'transformers', 'swr', 'mock'] as const)(
+    'rejects %s without sdk, naming the fix',
+    (generator) => {
+      expect(() => validateGenerators([generator], {})).toThrow(
+        new RegExp(`requires the "sdk" generator.*--generator sdk --generator ${generator}`)
+      );
+    }
+  );
+
+  it('rejects transformers without --date-type Date (would assign Date to string fields)', () => {
+    expect(() => validateGenerators(['sdk', 'transformers'], {})).toThrow(
+      /requires --date-type Date .*got "string"/
+    );
+  });
+
+  it('accepts sdk + transformers with --date-type Date', () => {
+    expect(() => validateGenerators(['sdk', 'transformers'], { dateType: 'Date' })).not.toThrow();
+  });
+
+  it.each(['tanstack-query', 'swr'] as const)('rejects %s with result error mode', (generator) => {
+    expect(() => validateGenerators(['sdk', generator], { errorMode: 'result' })).toThrow(
+      /does not support --error-mode "result".*throw/
+    );
+  });
+
+  it('throws NotSupportedError for an unknown generator name', () => {
+    expect(() => validateGenerators(['nope' as never], {})).toThrow(NotSupportedError);
+  });
+});
+
+describe('swr generator', () => {
+  it('is registered and requires sdk', () => {
+    const descriptor = builtinGenerators().get('swr');
+    expect(descriptor?.run).toBeDefined();
+    expect(descriptor?.requires).toContain('sdk');
+  });
+
+  it('accepts sdk + swr with the default error-mode', () => {
+    expect(() => validateGenerators(['sdk', 'swr'], {})).not.toThrow();
+  });
+});
+
+describe('validateGenerators — runtime compatibility', () => {
+  /** A registry with one runtimes-restricted generator (no built-in restricts runtimes anymore). */
+  function registryWith(runtimes: ('inline' | 'package')[]) {
+    const registry = builtinGenerators();
+    registry.set('inline-only', { run: () => [], runtimes });
+    return registry;
+  }
+
+  it('rejects a runtimes-restricted generator with runtime: package, naming both', () => {
+    expect(() =>
+      validateGenerators(['inline-only'], { runtime: 'package' }, registryWith(['inline']))
+    ).toThrow(/"inline-only".*runtime "package".*inline/);
+  });
+
+  it('accepts a runtimes-restricted generator when the runtime matches (or is defaulted)', () => {
+    expect(() =>
+      validateGenerators(['inline-only'], { runtime: 'inline' }, registryWith(['inline']))
+    ).not.toThrow();
+    expect(() => validateGenerators(['inline-only'], {}, registryWith(['inline']))).not.toThrow();
+  });
+
+  it('accepts the wrapper generators with runtime: package (no longer restricted)', () => {
+    expect(() =>
+      validateGenerators(
+        ['sdk', 'tanstack-query', 'swr'],
+        { runtime: 'package', queryFramework: 'react' },
+        builtinGenerators()
+      )
+    ).not.toThrow();
+  });
+});
+
+describe('mock generator', () => {
+  it('is registered and requires sdk', () => {
+    expect(builtinGenerators().get('mock')?.requires).toContain('sdk');
+  });
+
+  it('validateGenerators accepts sdk + mock', () => {
+    expect(() => validateGenerators(['sdk', 'mock'], {})).not.toThrow();
+  });
+});
diff --git a/packages/client-generator/src/generators/__tests__/mock.test.ts b/packages/client-generator/src/generators/__tests__/mock.test.ts
new file mode 100644
index 0000000000..4573c50f09
--- /dev/null
+++ b/packages/client-generator/src/generators/__tests__/mock.test.ts
@@ -0,0 +1,28 @@
+import { apiModel, operation } from '../../emitters/__tests__/fixtures.js';
+import { mockGenerator } from '../mock.js';
+
+describe('mockGenerator', () => {
+  it('returns [] for a model with no operations', () => {
+    const result = mockGenerator({
+      model: apiModel(),
+      outputPath: '/out/client.ts',
+      outputMode: 'single',
+      emit: {},
+    });
+    expect(result).toEqual([]);
+  });
+
+  it('returns a single mocks file when the model has operations', () => {
+    const model = apiModel({ services: [{ name: 'Default', operations: [operation()] }] });
+    const result = mockGenerator({
+      model,
+      outputPath: '/out/client.ts',
+      outputMode: 'single',
+      emit: {},
+    });
+    expect(result).toHaveLength(1);
+    expect(result[0].path).toBe('/out/client.mocks.ts');
+    expect(result[0].content).toContain('Generated by @redocly/client-generator');
+    expect(result[0].content).toContain("import { http, HttpResponse } from 'msw'");
+  });
+});
diff --git a/packages/client-generator/src/generators/__tests__/resolve.test.ts b/packages/client-generator/src/generators/__tests__/resolve.test.ts
new file mode 100644
index 0000000000..241c442b6a
--- /dev/null
+++ b/packages/client-generator/src/generators/__tests__/resolve.test.ts
@@ -0,0 +1,84 @@
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { resolveGenerators } from '../resolve.js';
+import type { CustomGenerator } from '../types.js';
+
+const fixtures = join(dirname(fileURLToPath(import.meta.url)), 'fixtures');
+
+const noopRun = () => [];
+
+describe('resolveGenerators', () => {
+  it('passes built-in names through unchanged', async () => {
+    const { selected, registry } = await resolveGenerators(['sdk', 'zod']);
+    expect(selected).toEqual(['sdk', 'zod']);
+    expect(registry.has('sdk')).toBe(true);
+    expect(registry.has('zod')).toBe(true);
+  });
+
+  it('registers an inline custom generator and selects it by name', async () => {
+    const custom: CustomGenerator = { name: 'route-map', run: noopRun };
+    const { selected, registry } = await resolveGenerators(['sdk', 'route-map'], {
+      customGenerators: [custom],
+    });
+    expect(selected).toEqual(['sdk', 'route-map']);
+    expect(registry.get('route-map')?.run).toBe(noopRun);
+  });
+
+  it('registers an inline custom that is available (for requires) but not selected', async () => {
+    const custom: CustomGenerator = { name: 'extra', run: noopRun };
+    const { selected, registry } = await resolveGenerators(['sdk'], { customGenerators: [custom] });
+    expect(selected).toEqual(['sdk']);
+    expect(registry.has('extra')).toBe(true);
+  });
+
+  it('rejects a custom generator whose name collides with a built-in', async () => {
+    const custom: CustomGenerator = { name: 'sdk', run: noopRun };
+    await expect(resolveGenerators(['sdk'], { customGenerators: [custom] })).rejects.toThrow(
+      /collides/
+    );
+  });
+
+  it('rejects two custom generators with the same name', async () => {
+    const a: CustomGenerator = { name: 'dup', run: noopRun };
+    const b: CustomGenerator = { name: 'dup', run: noopRun };
+    await expect(resolveGenerators(['dup'], { customGenerators: [a, b] })).rejects.toThrow(
+      /collides/
+    );
+  });
+
+  it('rejects an invalid inline custom generator (missing run)', async () => {
+    const bad = { name: 'broken' } as unknown as CustomGenerator;
+    await expect(resolveGenerators(['broken'], { customGenerators: [bad] })).rejects.toThrow(
+      /Invalid custom generator/
+    );
+  });
+
+  it('loads a generator from a relative path specifier and selects its declared name', async () => {
+    const { selected, registry } = await resolveGenerators(['sdk', './route-map-plugin.ts'], {
+      configDir: fixtures,
+    });
+    expect(selected).toEqual(['sdk', 'route-map']);
+    expect(registry.has('route-map')).toBe(true);
+  });
+
+  it('throws an actionable error when a specifier cannot be loaded', async () => {
+    await expect(
+      resolveGenerators(['./does-not-exist.ts'], { configDir: fixtures })
+    ).rejects.toThrow(/Could not load generator "\.\/does-not-exist\.ts"/);
+  });
+
+  it('treats a non-built-in entry with no configDir as a package specifier (resolved from cwd)', async () => {
+    // A bare specifier that does not resolve surfaces the load error; this also exercises the
+    // package-name (non-path) branch and the default `configDir = cwd`.
+    await expect(resolveGenerators(['@redocly/not-a-real-generator-pkg'])).rejects.toThrow(
+      /Could not load generator "@redocly\/not-a-real-generator-pkg"/
+    );
+  });
+
+  it('throws when a loaded module does not export a generator', async () => {
+    await expect(resolveGenerators(['./empty-plugin.ts'], { configDir: fixtures })).rejects.toThrow(
+      /must export a generator/
+    );
+  });
+});
diff --git a/packages/client-generator/src/generators/__tests__/sdk.test.ts b/packages/client-generator/src/generators/__tests__/sdk.test.ts
new file mode 100644
index 0000000000..3bb65e6970
--- /dev/null
+++ b/packages/client-generator/src/generators/__tests__/sdk.test.ts
@@ -0,0 +1,73 @@
+import { HEADER } from '../../emitters/emit-options.js';
+import type { ApiModel } from '../../intermediate-representation/model.js';
+import { sdkGenerator } from '../sdk.js';
+
+function apiModel(): ApiModel {
+  return {
+    title: 'T',
+    version: '1.0.0',
+    serverUrl: 'https://api.example.com',
+    services: [
+      {
+        name: 'Default',
+        operations: [
+          {
+            name: 'op',
+            method: 'get',
+            path: '/p',
+            pathParams: [],
+            queryParams: [],
+            headerParams: [],
+            cookieParams: [],
+            successResponses: [],
+            errorResponses: [],
+            security: [],
+            tags: [],
+          },
+        ],
+      },
+    ],
+    schemas: [],
+    securitySchemes: [],
+  };
+}
+
+describe('sdkGenerator', () => {
+  it('writes the whole client to the output path in single mode', () => {
+    const files = sdkGenerator({
+      model: apiModel(),
+      outputPath: '/out/api.ts',
+      outputMode: 'single',
+      emit: {},
+    });
+    expect(files.map((file) => file.path)).toEqual(['/out/api.ts']);
+    expect(files[0].content.startsWith(HEADER)).toBe(true);
+    expect(files[0].content).toContain('export const client =');
+  });
+
+  it('honors the output mode (split carves the schemas into a sibling file)', () => {
+    const model = apiModel();
+    model.schemas = [{ name: 'Thing', schema: { kind: 'object', properties: [] } }];
+    const files = sdkGenerator({
+      model,
+      outputPath: '/out/api.ts',
+      outputMode: 'split',
+      emit: {},
+    });
+    expect(files.map((f) => f.path)).toEqual(['/out/api.schemas.ts', '/out/api.ts']);
+  });
+
+  it('emits .ts import extensions when importExt is ts (Node native TS execution)', () => {
+    const model = apiModel();
+    model.schemas = [{ name: 'Thing', schema: { kind: 'object', properties: [] } }];
+    const files = sdkGenerator({
+      model,
+      outputPath: '/out/api.ts',
+      outputMode: 'split',
+      emit: { importExt: 'ts' },
+    });
+    const entry = files.find((file) => file.path === '/out/api.ts')!;
+    expect(entry.content).toContain("from './api.schemas.ts'");
+    expect(entry.content).not.toContain('.schemas.js');
+  });
+});
diff --git a/packages/client-generator/src/generators/__tests__/swr.test.ts b/packages/client-generator/src/generators/__tests__/swr.test.ts
new file mode 100644
index 0000000000..0af00c52f6
--- /dev/null
+++ b/packages/client-generator/src/generators/__tests__/swr.test.ts
@@ -0,0 +1,46 @@
+import { apiModel, operation } from '../../emitters/__tests__/fixtures.js';
+import { builtinGenerators } from '../index.js';
+import { swrGenerator } from '../swr.js';
+
+const SERVICES = [
+  {
+    name: 'Default',
+    operations: [
+      operation({ name: 'getPet', method: 'get', path: '/pet' }),
+      operation({ name: 'createPet', method: 'post', path: '/pet' }),
+    ],
+  },
+];
+
+describe('swrGenerator', () => {
+  it('emits one <stem>.swr.ts file beside the client with the header + hooks', () => {
+    const files = swrGenerator({
+      model: apiModel({ services: SERVICES }),
+      outputPath: '/tmp/out/client.ts',
+      outputMode: 'single',
+      emit: {},
+    });
+    expect(files).toHaveLength(1);
+    expect(files[0].path).toBe('/tmp/out/client.swr.ts');
+    expect(files[0].content).toContain('// Generated by @redocly/client-generator');
+    expect(files[0].content).toContain('import useSWR from "swr"');
+    expect(files[0].content).toContain('import useSWRMutation from "swr/mutation"');
+    expect(files[0].content).toContain('export function useGetPet');
+    expect(files[0].content).toContain('export function useCreatePet');
+    expect(files[0].content).toContain('from "./client.js"');
+  });
+
+  it('emits nothing when the model has no operations', () => {
+    const files = swrGenerator({
+      model: apiModel({ services: [{ name: 'Default', operations: [] }] }),
+      outputPath: '/tmp/out/client.ts',
+      outputMode: 'single',
+      emit: {},
+    });
+    expect(files).toEqual([]);
+  });
+
+  it('is registered under "swr"', () => {
+    expect(builtinGenerators().get('swr')?.run).toBe(swrGenerator);
+  });
+});
diff --git a/packages/client-generator/src/generators/__tests__/tanstack-query.test.ts b/packages/client-generator/src/generators/__tests__/tanstack-query.test.ts
new file mode 100644
index 0000000000..8f25b7359c
--- /dev/null
+++ b/packages/client-generator/src/generators/__tests__/tanstack-query.test.ts
@@ -0,0 +1,65 @@
+import { apiModel, operation } from '../../emitters/__tests__/fixtures.js';
+import { builtinGenerators } from '../index.js';
+import { tanstackQueryGenerator } from '../tanstack-query.js';
+
+const SERVICES = [
+  {
+    name: 'Default',
+    operations: [
+      operation({ name: 'getPet', method: 'get', path: '/pet' }),
+      operation({ name: 'createPet', method: 'post', path: '/pet' }),
+    ],
+  },
+];
+
+describe('tanstackQueryGenerator', () => {
+  it('emits one <stem>.tanstack.ts file beside the client with the header + factories', () => {
+    const files = tanstackQueryGenerator({
+      model: apiModel({ services: SERVICES }),
+      outputPath: '/tmp/out/client.ts',
+      outputMode: 'single',
+      emit: {},
+    });
+    expect(files).toHaveLength(1);
+    expect(files[0].path).toBe('/tmp/out/client.tanstack.ts');
+    expect(files[0].content).toContain('// Generated by @redocly/client-generator');
+    expect(files[0].content).toContain('import { queryOptions } from "@tanstack/react-query"');
+    expect(files[0].content).toContain('export const getPetOptions');
+    expect(files[0].content).toContain('export const createPetMutation');
+    expect(files[0].content).toContain('from "./client.js"');
+  });
+
+  it('emits nothing when the model has no operations', () => {
+    const files = tanstackQueryGenerator({
+      model: apiModel({ services: [{ name: 'Default', operations: [] }] }),
+      outputPath: '/tmp/out/client.ts',
+      outputMode: 'single',
+      emit: {},
+    });
+    expect(files).toEqual([]);
+  });
+
+  it('imports the sdk entry with a .ts extension when importExt is ts', () => {
+    const files = tanstackQueryGenerator({
+      model: apiModel({ services: SERVICES }),
+      outputPath: '/tmp/out/client.ts',
+      outputMode: 'single',
+      emit: { importExt: 'ts' },
+    });
+    expect(files[0].content).toContain('from "./client.ts"');
+  });
+
+  it('passes queryFramework through to the import specifier', () => {
+    const files = tanstackQueryGenerator({
+      model: apiModel({ services: SERVICES }),
+      outputPath: '/tmp/out/client.ts',
+      outputMode: 'single',
+      emit: { queryFramework: 'svelte' },
+    });
+    expect(files[0].content).toContain('import { queryOptions } from "@tanstack/svelte-query"');
+  });
+
+  it('is registered under "tanstack-query"', () => {
+    expect(builtinGenerators().get('tanstack-query')?.run).toBe(tanstackQueryGenerator);
+  });
+});
diff --git a/packages/client-generator/src/generators/__tests__/transformers.test.ts b/packages/client-generator/src/generators/__tests__/transformers.test.ts
new file mode 100644
index 0000000000..3746089bf2
--- /dev/null
+++ b/packages/client-generator/src/generators/__tests__/transformers.test.ts
@@ -0,0 +1,51 @@
+import { apiModel, namedSchema } from '../../emitters/__tests__/fixtures.js';
+import { builtinGenerators } from '../index.js';
+import { transformersGenerator } from '../transformers.js';
+
+const EVENT = namedSchema('Event', {
+  kind: 'object',
+  properties: [
+    {
+      name: 'createdAt',
+      schema: { kind: 'scalar', scalar: 'string', metadata: { format: 'date-time' } },
+      required: true,
+    },
+  ],
+});
+
+const PLAIN = namedSchema('Plain', {
+  kind: 'object',
+  properties: [{ name: 'id', schema: { kind: 'scalar', scalar: 'string' }, required: true }],
+});
+
+describe('transformersGenerator', () => {
+  it('emits one <stem>.transformers.ts beside the client with header + type import + transformer', () => {
+    const files = transformersGenerator({
+      model: apiModel({ schemas: [EVENT] }),
+      outputPath: '/tmp/out/client.ts',
+      outputMode: 'single',
+      emit: {},
+    });
+    expect(files).toHaveLength(1);
+    expect(files[0].path).toBe('/tmp/out/client.transformers.ts');
+    expect(files[0].content).toContain('// Generated by @redocly/client-generator');
+    expect(files[0].content).toContain('import type {');
+    expect(files[0].content).toContain('from "./client.js"');
+    expect(files[0].content).toContain('export const transformEvent');
+    expect(files[0].content).toContain('new Date(');
+  });
+
+  it('emits nothing when no schema carries a date field', () => {
+    const files = transformersGenerator({
+      model: apiModel({ schemas: [PLAIN] }),
+      outputPath: '/tmp/out/client.ts',
+      outputMode: 'single',
+      emit: {},
+    });
+    expect(files).toEqual([]);
+  });
+
+  it('is registered under "transformers"', () => {
+    expect(builtinGenerators().get('transformers')?.run).toBe(transformersGenerator);
+  });
+});
diff --git a/packages/client-generator/src/generators/__tests__/zod.test.ts b/packages/client-generator/src/generators/__tests__/zod.test.ts
new file mode 100644
index 0000000000..314381615a
--- /dev/null
+++ b/packages/client-generator/src/generators/__tests__/zod.test.ts
@@ -0,0 +1,33 @@
+import { apiModel, namedSchema } from '../../emitters/__tests__/fixtures.js';
+import { zodGenerator } from '../zod.js';
+
+const PET = namedSchema('Pet', {
+  kind: 'object',
+  properties: [{ name: 'id', schema: { kind: 'scalar', scalar: 'string' }, required: true }],
+});
+
+describe('zodGenerator', () => {
+  it('emits one <stem>.zod.ts file beside the client with the header + schemas', () => {
+    const files = zodGenerator({
+      model: apiModel({ schemas: [PET] }),
+      outputPath: '/tmp/out/client.ts',
+      outputMode: 'single',
+      emit: {},
+    });
+    expect(files).toHaveLength(1);
+    expect(files[0].path).toBe('/tmp/out/client.zod.ts');
+    expect(files[0].content).toContain('// Generated by @redocly/client-generator');
+    expect(files[0].content).toContain('import { z } from "zod"');
+    expect(files[0].content).toContain('export const PetSchema = z.object(');
+  });
+
+  it('emits nothing when the model has no schemas', () => {
+    const files = zodGenerator({
+      model: apiModel({ schemas: [] }),
+      outputPath: '/tmp/out/client.ts',
+      outputMode: 'single',
+      emit: {},
+    });
+    expect(files).toEqual([]);
+  });
+});
diff --git a/packages/client-generator/src/generators/anchor.ts b/packages/client-generator/src/generators/anchor.ts
new file mode 100644
index 0000000000..ca629642b6
--- /dev/null
+++ b/packages/client-generator/src/generators/anchor.ts
@@ -0,0 +1,10 @@
+import { parse } from 'node:path';
+
+/**
+ * Derive the directory and base name (stem, without `.ts`) from the `--output`
+ * anchor path. Generators build sibling-file paths from these.
+ */
+export function anchor(outputPath: string): { dir: string; stem: string } {
+  const { dir, name } = parse(outputPath);
+  return { dir, stem: name };
+}
diff --git a/packages/client-generator/src/generators/index.ts b/packages/client-generator/src/generators/index.ts
new file mode 100644
index 0000000000..538a321687
--- /dev/null
+++ b/packages/client-generator/src/generators/index.ts
@@ -0,0 +1,86 @@
+import type { EmitOptions } from '../emitters/emit-options.js';
+import { NotSupportedError } from '../errors.js';
+import { mockGenerator } from './mock.js';
+import { sdkGenerator } from './sdk.js';
+import { swrGenerator } from './swr.js';
+import { tanstackQueryGenerator } from './tanstack-query.js';
+import { transformersGenerator } from './transformers.js';
+import type { GeneratorDescriptor, GeneratorName } from './types.js';
+import { zodGenerator } from './zod.js';
+
+export type {
+  CustomGenerator,
+  Generator,
+  GeneratorDescriptor,
+  GeneratorInput,
+  GeneratorName,
+} from './types.js';
+
+const GENERATORS: Record<GeneratorName, GeneratorDescriptor> = {
+  // sdk is the base client; zod emits a standalone schema module importing nothing from it.
+  sdk: { run: sdkGenerator },
+  zod: { run: zodGenerator },
+  // transformers import the schema *types* from the sdk entry module (so sdk must run) and
+  // assign `Date` values to those fields, which only type-checks when the sdk types dates as `Date`.
+  transformers: { run: transformersGenerator, requires: ['sdk'], dateTypes: ['Date'] },
+  // tanstack-query wraps the sdk's exported, throw-mode operation functions — present in
+  // both runtime distributions, so no runtime restriction.
+  'tanstack-query': { run: tanstackQueryGenerator, requires: ['sdk'], errorModes: ['throw'] },
+  // swr wraps the sdk's exported, throw-mode operation functions as SWR hooks.
+  swr: { run: swrGenerator, requires: ['sdk'], errorModes: ['throw'] },
+  // mock emits a standalone MSW handlers/factories module referencing the sdk's types.
+  mock: { run: mockGenerator, requires: ['sdk'] },
+};
+
+/**
+ * A fresh registry of the built-in generators keyed by name. The plugin resolver seeds from this
+ * and adds custom generators to the copy, so mutating the result never affects the built-in table.
+ */
+export function builtinGenerators(): Map<string, GeneratorDescriptor> {
+  return new Map(Object.entries(GENERATORS));
+}
+
+/**
+ * Validate a generator selection against every selected generator's declared
+ * contract, throwing the first violation with an actionable message. Runs before
+ * any file is produced so an incompatible combination never reaches the printer.
+ */
+export function validateGenerators(
+  names: string[],
+  emit: EmitOptions,
+  registry: Map<string, GeneratorDescriptor> = builtinGenerators()
+): void {
+  const selected = new Set(names);
+  const errorMode = emit.errorMode ?? 'throw';
+  const dateType = emit.dateType ?? 'string';
+  const runtime = emit.runtime ?? 'inline';
+  for (const name of names) {
+    const descriptor = registry.get(name);
+    if (!descriptor) {
+      throw new NotSupportedError(`Unknown generator: ${name}`);
+    }
+    for (const required of descriptor.requires ?? []) {
+      if (!selected.has(required)) {
+        const fixed = [...new Set([required, ...names])].map((g) => `--generator ${g}`).join(' ');
+        throw new NotSupportedError(
+          `The "${name}" generator requires the "${required}" generator. Add it, e.g. ${fixed}.`
+        );
+      }
+    }
+    if (descriptor.errorModes && !descriptor.errorModes.includes(errorMode)) {
+      throw new NotSupportedError(
+        `The "${name}" generator does not support --error-mode "${errorMode}" (supported: ${descriptor.errorModes.join(', ')}).`
+      );
+    }
+    if (descriptor.dateTypes && !descriptor.dateTypes.includes(dateType)) {
+      throw new NotSupportedError(
+        `The "${name}" generator requires --date-type ${descriptor.dateTypes.join(' or ')} (got "${dateType}") so the runtime values match the generated types.`
+      );
+    }
+    if (descriptor.runtimes && !descriptor.runtimes.includes(runtime)) {
+      throw new NotSupportedError(
+        `The "${name}" generator does not support runtime "${runtime}" (supported: ${descriptor.runtimes.join(', ')}).`
+      );
+    }
+  }
+}
diff --git a/packages/client-generator/src/generators/mock.ts b/packages/client-generator/src/generators/mock.ts
new file mode 100644
index 0000000000..1f358625f7
--- /dev/null
+++ b/packages/client-generator/src/generators/mock.ts
@@ -0,0 +1,24 @@
+import { join } from 'node:path';
+
+import { HEADER } from '../emitters/emit-options.js';
+import { renderMockModule } from '../emitters/mock.js';
+import { anchor } from './anchor.js';
+import type { Generator } from './types.js';
+
+/**
+ * The mock generator: a standalone `<stem>.mocks.ts` module of MSW handlers and
+ * data factories baked from the spec. Imports `msw` (the consumer's dev-dep); the
+ * sdk client stays dependency-free. Output-mode-agnostic in v1 — one module beside
+ * the client. Emits nothing when there are no operations.
+ */
+export const mockGenerator: Generator = ({ model, outputPath, emit }) => {
+  const { dir, stem } = anchor(outputPath);
+  const content = renderMockModule(model, {
+    sdkModule: `./${stem}.${emit.importExt ?? 'js'}`,
+    dateType: emit.dateType,
+    mockData: emit.mockData,
+    mockSeed: emit.mockSeed,
+  });
+  if (content === '') return [];
+  return [{ path: join(dir, `${stem}.mocks.ts`), content: `${HEADER}\n\n${content}` }];
+};
diff --git a/packages/client-generator/src/generators/resolve.ts b/packages/client-generator/src/generators/resolve.ts
new file mode 100644
index 0000000000..9921a52dc8
--- /dev/null
+++ b/packages/client-generator/src/generators/resolve.ts
@@ -0,0 +1,99 @@
+// Resolves a `generators` selection (a mix of built-in names, inline custom generators, and import
+// specifiers) into a registry keyed by name plus the ordered list of names to run. This is the only
+// async, side-effecting step in the generator pipeline: a specifier that is neither a built-in nor an
+// already-registered custom name is dynamically `import()`ed (a standard Node ESM dynamic import), its
+// default (or `generator`) export validated, and registered under its declared name. Built-ins are
+// seeded fresh per call (see `builtinGenerators`), so registration never mutates the built-in table.
+
+import { isPlainObject } from '@redocly/openapi-core';
+import { isAbsolute, resolve as resolvePath } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { NotSupportedError } from '../errors.js';
+import { builtinGenerators } from './index.js';
+import type { CustomGenerator, GeneratorDescriptor } from './types.js';
+
+export type ResolvedGenerators = {
+  /** Generator names to run, in selection order. */
+  selected: string[];
+  /** Every available generator (built-ins + registered customs) keyed by name. */
+  registry: Map<string, GeneratorDescriptor>;
+};
+
+export type ResolveOptions = {
+  /** Inline custom generators (via the programmatic `generateClient` API) registered before resolution. */
+  customGenerators?: CustomGenerator[];
+  /** Directory relative-path specifiers resolve against (the config's location). Defaults to cwd. */
+  configDir?: string;
+};
+
+/**
+ * Build the run list + registry for a `generators` selection. Each entry is, in order of preference,
+ * a built-in name, an already-registered custom name, or an import specifier (path or package).
+ */
+export async function resolveGenerators(
+  entries: string[],
+  options: ResolveOptions = {}
+): Promise<ResolvedGenerators> {
+  const registry = builtinGenerators();
+  for (const custom of options.customGenerators ?? []) register(registry, custom);
+
+  const selected: string[] = [];
+  for (const entry of entries) {
+    if (registry.has(entry)) {
+      selected.push(entry);
+      continue;
+    }
+    const custom = await importGenerator(entry, options.configDir ?? process.cwd());
+    register(registry, custom);
+    selected.push(custom.name);
+  }
+  return { selected, registry };
+}
+
+/** Validate a custom generator and add it under its name, rejecting collisions. */
+function register(registry: Map<string, GeneratorDescriptor>, custom: CustomGenerator): void {
+  if (
+    !isPlainObject(custom) ||
+    typeof custom.name !== 'string' ||
+    custom.name === '' ||
+    typeof custom.run !== 'function'
+  ) {
+    throw new NotSupportedError(
+      'Invalid custom generator: expected an object with a non-empty string `name` and a `run` function (build one with `defineGenerator`).'
+    );
+  }
+  if (registry.has(custom.name)) {
+    throw new NotSupportedError(
+      `Generator name "${custom.name}" collides with an existing generator. Rename the custom generator.`
+    );
+  }
+  registry.set(custom.name, {
+    run: custom.run,
+    requires: custom.requires,
+    errorModes: custom.errorModes,
+    dateTypes: custom.dateTypes,
+    runtimes: custom.runtimes,
+  });
+}
+
+/** Dynamically import a generator from a path (resolved against `configDir`) or package specifier. */
+async function importGenerator(specifier: string, configDir: string): Promise<CustomGenerator> {
+  const isPath = specifier.startsWith('.') || isAbsolute(specifier);
+  const target = isPath ? pathToFileURL(resolvePath(configDir, specifier)).href : specifier;
+  let module: Record<string, unknown>;
+  try {
+    module = (await import(target)) as Record<string, unknown>;
+  } catch (cause) {
+    throw new NotSupportedError(
+      `Could not load generator "${specifier}": ${(cause as Error).message}`
+    );
+  }
+  const generator = module.default ?? module.generator;
+  if (generator === undefined) {
+    throw new NotSupportedError(
+      `Generator module "${specifier}" must export a generator (a default export or a \`generator\` export built with \`defineGenerator\`).`
+    );
+  }
+  return generator as CustomGenerator;
+}
diff --git a/packages/client-generator/src/generators/sdk.ts b/packages/client-generator/src/generators/sdk.ts
new file mode 100644
index 0000000000..8e60e0a329
--- /dev/null
+++ b/packages/client-generator/src/generators/sdk.ts
@@ -0,0 +1,28 @@
+import { join } from 'node:path';
+
+import { emitClientSingleFile, emitClientSplit } from '../emitters/client-assembly.js';
+import { anchor } from './anchor.js';
+import type { Generator } from './types.js';
+
+/**
+ * The default generator: the full typed client (model types + runtime + endpoints).
+ * Other generators (zod, framework hooks) emit *additional* files alongside.
+ *
+ * `single` mode writes the whole client to the `--output` path. `split` mode derives
+ * two sibling files from that anchor — `<stem>.schemas.ts` (model types, enums,
+ * const-objects, type guards; skipped when the document declares no schemas) and
+ * `<stem>.ts` (everything else, which `export *`s the schemas module).
+ */
+export const sdkGenerator: Generator = ({ model, outputPath, outputMode, emit }) => {
+  if (outputMode === 'split') {
+    const { dir, stem } = anchor(outputPath);
+    const { entry, schemas } = emitClientSplit(model, emit, stem);
+    return [
+      ...(schemas === undefined
+        ? []
+        : [{ path: join(dir, `${stem}.schemas.ts`), content: schemas }]),
+      { path: outputPath, content: entry },
+    ];
+  }
+  return [{ path: outputPath, content: emitClientSingleFile(model, emit) }];
+};
diff --git a/packages/client-generator/src/generators/swr.ts b/packages/client-generator/src/generators/swr.ts
new file mode 100644
index 0000000000..916a118ca9
--- /dev/null
+++ b/packages/client-generator/src/generators/swr.ts
@@ -0,0 +1,28 @@
+import { join } from 'node:path';
+
+import { HEADER } from '../emitters/emit-options.js';
+import { renderSwrModule } from '../emitters/swr.js';
+import { anchor } from './anchor.js';
+import type { Generator } from './types.js';
+
+/**
+ * The swr generator: a standalone `<stem>.swr.ts` module of SWR hooks wrapping the
+ * sdk operation functions — `<op>Key` + `use<Op>` (`useSWR`) per query (GET/HEAD),
+ * `use<Op>` (`useSWRMutation`) per mutation. It imports the operation functions +
+ * their `<Op>Variables` types from the sdk entry (`./<stem>.js`), so it requires the
+ * `sdk` generator and targets its throw-mode operation functions. `swr`/`swr/mutation`
+ * are the consumer's peer; the sdk client stays dependency-free.
+ *
+ * Output-mode-agnostic: `./<stem>.js` resolves to the single-file client or the
+ * multi-file barrel at the output anchor either way. Emits nothing when there are
+ * no operations.
+ */
+export const swrGenerator: Generator = ({ model, outputPath, emit }) => {
+  const { dir, stem } = anchor(outputPath);
+  const content = renderSwrModule(model, {
+    argsStyle: emit.argsStyle ?? 'flat',
+    sdkModule: `./${stem}.${emit.importExt ?? 'js'}`,
+  });
+  if (content === '') return [];
+  return [{ path: join(dir, `${stem}.swr.ts`), content: `${HEADER}\n\n${content}` }];
+};
diff --git a/packages/client-generator/src/generators/tanstack-query.ts b/packages/client-generator/src/generators/tanstack-query.ts
new file mode 100644
index 0000000000..adfd3dc5b4
--- /dev/null
+++ b/packages/client-generator/src/generators/tanstack-query.ts
@@ -0,0 +1,31 @@
+import { join } from 'node:path';
+
+import { HEADER } from '../emitters/emit-options.js';
+import { renderTanstackModule } from '../emitters/tanstack-query.js';
+import { anchor } from './anchor.js';
+import type { Generator } from './types.js';
+
+/**
+ * The tanstack-query generator: a standalone `<stem>.tanstack.ts` module of
+ * TanStack Query v5 factories that wrap the sdk operation functions —
+ * `<op>QueryKey`/`<op>Options` per query (GET/HEAD), `<op>Mutation` per mutation.
+ * It imports the operation functions + their `<Op>Variables` types from the sdk
+ * entry (`./<stem>.js`), so it requires the `sdk` generator and targets its
+ * throw-mode operation functions. The framework-agnostic `queryOptions` helper is
+ * imported from `@tanstack/${queryFramework}-query` (`react` default; the body is
+ * byte-identical across frameworks — `@tanstack/<framework>-query` is the consumer's peer).
+ *
+ * Output-mode-agnostic: `./<stem>.js` resolves to the single-file client or the
+ * multi-file barrel at the output anchor either way. Emits nothing when there are
+ * no operations.
+ */
+export const tanstackQueryGenerator: Generator = ({ model, outputPath, emit }) => {
+  const { dir, stem } = anchor(outputPath);
+  const content = renderTanstackModule(model, {
+    argsStyle: emit.argsStyle ?? 'flat',
+    sdkModule: `./${stem}.${emit.importExt ?? 'js'}`,
+    framework: emit.queryFramework ?? 'react',
+  });
+  if (content === '') return [];
+  return [{ path: join(dir, `${stem}.tanstack.ts`), content: `${HEADER}\n\n${content}` }];
+};
diff --git a/packages/client-generator/src/generators/transformers.ts b/packages/client-generator/src/generators/transformers.ts
new file mode 100644
index 0000000000..cbdb34f786
--- /dev/null
+++ b/packages/client-generator/src/generators/transformers.ts
@@ -0,0 +1,31 @@
+import { join } from 'node:path';
+
+import { HEADER } from '../emitters/emit-options.js';
+import { renderTransformersModule } from '../emitters/transformers.js';
+import { anchor } from './anchor.js';
+import type { Generator } from './types.js';
+
+/**
+ * The transformers generator: a standalone `<stem>.transformers.ts` module of
+ * `transform<Name>(data: <Name>): <Name>` functions, one per IR named schema
+ * that (recursively) carries a `date-time`/`date` field. Each walks the value
+ * and rewrites wire ISO strings to `new Date(...)` in place, so the runtime
+ * value matches the sdk's `--date-type Date` types — pair the two.
+ *
+ * Standalone — the consumer pipes responses through it
+ * (`transformPet(await getPet(id))`); the sdk client itself stays zero-dep
+ * (Date is a web standard). The transformers import only the schema TYPES from
+ * the sdk entry (`./<stem>.js`) and call each other as siblings.
+ *
+ * Output-mode-agnostic: it reads only `model.schemas` and emits a single module
+ * beside the client regardless of how the sdk partitions its files. Emits
+ * nothing when no schema has a date field (nothing to transform).
+ */
+export const transformersGenerator: Generator = ({ model, outputPath, emit }) => {
+  const { dir, stem } = anchor(outputPath);
+  const content = renderTransformersModule(model, {
+    sdkModule: `./${stem}.${emit.importExt ?? 'js'}`,
+  });
+  if (content === '') return [];
+  return [{ path: join(dir, `${stem}.transformers.ts`), content: `${HEADER}\n\n${content}` }];
+};
diff --git a/packages/client-generator/src/generators/types.ts b/packages/client-generator/src/generators/types.ts
new file mode 100644
index 0000000000..31b3ec14d4
--- /dev/null
+++ b/packages/client-generator/src/generators/types.ts
@@ -0,0 +1,72 @@
+// packages/client-generator/src/generators/types.ts
+import type { EmitOptions } from '../emitters/emit-options.js';
+import type { ErrorMode } from '../emitters/operations.js';
+import type { DateType } from '../emitters/types.js';
+import type { ApiModel } from '../intermediate-representation/model.js';
+
+/**
+ * How the generated client is partitioned across files.
+ *
+ * - `single` (default): one self-contained file.
+ * - `split`: schema types + guards in a sibling `<stem>.schemas.ts`; everything
+ *   else in the entry file, which re-exports the schemas module.
+ */
+export type OutputMode = 'single' | 'split';
+
+/** A single file the generator will write to disk. */
+export type GeneratedFile = { path: string; content: string };
+
+/** The first-party generators the registry knows. */
+export type GeneratorName = 'sdk' | 'zod' | 'tanstack-query' | 'swr' | 'transformers' | 'mock';
+
+/** Everything a generator needs to produce its files. */
+export type GeneratorInput = {
+  model: ApiModel;
+  /** The `--output` anchor path. */
+  outputPath: string;
+  /** File partitioning the generator should honor. */
+  outputMode: OutputMode;
+  /** Emit options — serverUrl, runtime, and the generator knobs (dateType, mockData, queryFramework, …); see `EmitOptions`. */
+  emit: EmitOptions;
+};
+
+/**
+ * A Generator turns the IR + options into a set of files. Each lives behind a
+ * name in the registry — the built-ins, plus custom generators registered
+ * through the plugin API (see `CustomGenerator`).
+ */
+export type Generator = (input: GeneratorInput) => GeneratedFile[];
+
+/**
+ * A generator plus its declared compatibility contract. `validateGenerators`
+ * checks these *before* anything is emitted, so an incompatible selection fails
+ * fast with an actionable message instead of producing a client that won't compile.
+ *
+ * - `requires`: other generators that must also be selected (e.g. `tanstack-query`
+ *   imports the sdk's operation functions, so it requires `sdk`).
+ * - `errorModes` / `dateTypes` / `runtimes`: the subset this generator supports;
+ *   `undefined` means "all". (`tanstack-query` wraps throw-mode functions, so it
+ *   supports only `throw` mode; `transformers` only type-checks when the sdk types
+ *   date fields as `Date`, so it supports only `dateType: 'Date'`.)
+ */
+export type GeneratorDescriptor = {
+  run: Generator;
+  // `string[]` (not `GeneratorName[]`) so a custom generator may require a built-in or another
+  // custom generator by name; built-in descriptors still type-check (their names are strings).
+  requires?: string[];
+  errorModes?: ErrorMode[];
+  dateTypes?: DateType[];
+  /** Runtime modes this generator supports; absent = compatible with both. */
+  runtimes?: ('inline' | 'package')[];
+};
+
+/**
+ * A user-authored generator (the public, experimental plugin contract): a `GeneratorDescriptor`
+ * plus a unique `name` used to select it in `generators`, to satisfy other generators' `requires`,
+ * and to detect collisions. Authors build one via `defineGenerator` from the
+ * `@redocly/client-generator` entry; the resolver registers it under `name`.
+ */
+export type CustomGenerator = GeneratorDescriptor & {
+  /** Unique name, used in `generators` selection, `requires`, and collision detection. */
+  name: string;
+};
diff --git a/packages/client-generator/src/generators/zod.ts b/packages/client-generator/src/generators/zod.ts
new file mode 100644
index 0000000000..2c93b5fa97
--- /dev/null
+++ b/packages/client-generator/src/generators/zod.ts
@@ -0,0 +1,24 @@
+import { join } from 'node:path';
+
+import { HEADER } from '../emitters/emit-options.js';
+import { renderZodModule } from '../emitters/zod.js';
+import { anchor } from './anchor.js';
+import type { Generator } from './types.js';
+
+/**
+ * The zod generator: a standalone `<stem>.zod.ts` module of Zod schemas (one
+ * `export const <Name>Schema` per IR named schema), plus runtime validation for
+ * the client — the `operationSchemas` request/response map and the `zodValidation`
+ * middleware (`use(zodValidation())`). The sdk client stays dependency-free —
+ * zod is the consumer's peer, and the module imports nothing from the client.
+ *
+ * Output-mode-agnostic: emits a single module beside the client regardless of
+ * how the sdk partitions its files. Emits nothing when the model has neither
+ * named schemas nor JSON operation bodies.
+ */
+export const zodGenerator: Generator = ({ model, outputPath }) => {
+  const content = renderZodModule(model);
+  if (content === '') return [];
+  const { dir, stem } = anchor(outputPath);
+  return [{ path: join(dir, `${stem}.zod.ts`), content: `${HEADER}\n\n${content}` }];
+};
diff --git a/packages/client-generator/src/index.ts b/packages/client-generator/src/index.ts
new file mode 100644
index 0000000000..424cfc6505
--- /dev/null
+++ b/packages/client-generator/src/index.ts
@@ -0,0 +1,57 @@
+// The package ROOT entry — what package-mode clients load at app runtime, so its static
+// import graph stays runtime-only (no `typescript`, no `@redocly/openapi-core`, no Node
+// builtins; guarded by entry-weight.test.ts). The codegen stack lives behind the dynamic
+// import inside `generateClient` and the `@redocly/client-generator/codegen` entry.
+
+export { NotSupportedError } from './errors.js';
+export { defineClientSetup } from './runtime-contract.js';
+export type {
+  ClientSetup,
+  ClientSetupConfig,
+  Middleware,
+  OperationContext,
+  RequestContext,
+  RetryConfig,
+  RetryContext,
+  RetryStrategy,
+} from './runtime-contract.js';
+// The app-facing client runtime (package-mode clients import these from the package root).
+// The setup-contract names above (Middleware, OperationContext, RequestContext, RetryConfig,
+// RetryContext, RetryStrategy) are re-exports of the same runtime types — one definition,
+// two entry points; the rest of the runtime's type surface is re-exported here.
+export { ApiError, createClient, mergeSetup } from './runtime/index.js';
+export type {
+  ApiErrorLike,
+  AuthCredentials,
+  Client,
+  ClientConfig,
+  ClientCore,
+  OperationDescriptor,
+  OpsShape,
+  ParamSpec,
+  ParseAs,
+  QueryValue,
+  RequestOptions,
+  Result,
+  SecuritySpec,
+  ServerSentEvent,
+  SseOptions,
+  TokenProvider,
+} from './runtime/index.js';
+export type { Config } from './config.js';
+// The user-facing pagination rule shapes (`Config.pagination` / `x-pagination`).
+export type { PaginationConfig, PaginationRule, PaginationStyle } from './emitters/pagination.js';
+export type { GenerateClientOptions, GenerateClientResult, LoadResult } from './types.js';
+export { mergeConfig } from './config-file.js';
+// The custom-generator authoring API (`defineGenerator` + the IR types); the
+// TypeScript-emitting toolkit lives in `@redocly/client-generator/codegen`.
+export * from './plugin.js';
+
+import type { GenerateClientOptions, GenerateClientResult } from './types.js';
+
+export async function generateClient(
+  options: GenerateClientOptions
+): Promise<GenerateClientResult> {
+  const codegen = await import('./codegen.js');
+  return codegen.generateClient(options);
+}
diff --git a/packages/client-generator/src/intermediate-representation/__tests__/build.test.ts b/packages/client-generator/src/intermediate-representation/__tests__/build.test.ts
new file mode 100644
index 0000000000..c2e55193e3
--- /dev/null
+++ b/packages/client-generator/src/intermediate-representation/__tests__/build.test.ts
@@ -0,0 +1,2031 @@
+import { logger, type Oas3Definition, type Oas3Schema } from '@redocly/openapi-core';
+
+import { NotSupportedError } from '../../errors.js';
+import { buildApiModel } from '../build.js';
+import type { OperationModel, SchemaModel } from '../model.js';
+
+/**
+ * Build a minimal Oas3Definition wrapper so each test only declares the part it
+ * cares about. Cast through `unknown` so callers may pass partial fixtures.
+ */
+function doc(partial: Partial<Oas3Definition>): Oas3Definition {
+  return {
+    openapi: '3.0.3',
+    info: { title: 'Test', version: '1.0.0' },
+    paths: {},
+    ...partial,
+  } as Oas3Definition;
+}
+
+/** Convenience: invoke buildApiModel and return the first named schema. */
+function buildSchemaOnly(schema: Oas3Schema): SchemaModel {
+  const model = buildApiModel(
+    doc({ components: { schemas: { X: schema as Oas3Schema } } } as Partial<Oas3Definition>)
+  );
+  return model.schemas[0].schema;
+}
+
+/** Convenience: invoke buildApiModel and return the only operation. */
+function buildOpOnly(input: Partial<Oas3Definition>): OperationModel {
+  const model = buildApiModel(doc(input));
+  return model.services[0].operations[0];
+}
+
+describe('buildApiModel — operationId fallback naming', () => {
+  function opsOf(paths: Record<string, unknown>): OperationModel[] {
+    return buildApiModel(doc({ paths } as Partial<Oas3Definition>)).services[0].operations;
+  }
+  const res = { '200': { description: 'ok' } };
+
+  it('synthesizes <method><PascalSegments> when operationId is absent', () => {
+    expect(opsOf({ '/pets': { get: { responses: res } } })[0].name).toBe('getPets');
+  });
+
+  it('includes path-param segments (so collection vs item stay distinct)', () => {
+    expect(opsOf({ '/pets/{petId}': { get: { responses: res } } })[0].name).toBe('getPetsPetId');
+  });
+
+  it('splits non-identifier characters in a segment into words', () => {
+    expect(opsOf({ '/pets/{pet-id}': { get: { responses: res } } })[0].name).toBe('getPetsPetId');
+  });
+
+  it('falls back to just the method for the root path', () => {
+    expect(opsOf({ '/': { get: { responses: res } } })[0].name).toBe('get');
+  });
+
+  it('keeps a declared operationId (it wins over synthesis)', () => {
+    expect(opsOf({ '/pets': { get: { operationId: 'listPets', responses: res } } })[0].name).toBe(
+      'listPets'
+    );
+  });
+
+  it('uniquifies a synthesized name that collides with a declared operationId', () => {
+    const names = opsOf({
+      '/pets': { get: { responses: res }, post: { operationId: 'getPets', responses: res } },
+    })
+      .map((o) => o.name)
+      .sort();
+    expect(names).toEqual(['getPets', 'getPets2']);
+  });
+});
+
+describe('buildApiModel — top-level metadata', () => {
+  it('reads title/version/description/serverUrl from info & servers', () => {
+    const model = buildApiModel(
+      doc({
+        info: { title: 'My API', version: '2.0.0', description: 'docs here' },
+        servers: [{ url: 'https://api.example.com' }, { url: 'https://api.backup.com' }],
+      })
+    );
+    expect(model.title).toBe('My API');
+    expect(model.version).toBe('2.0.0');
+    expect(model.description).toBe('docs here');
+    expect(model.serverUrl).toBe('https://api.example.com');
+  });
+
+  it('substitutes server-URL variables with their declared defaults', () => {
+    const model = buildApiModel(
+      doc({
+        servers: [
+          {
+            url: 'https://{env}.example.com/{basePath}',
+            variables: { env: { default: 'api' }, basePath: { default: 'v2' } },
+          },
+        ],
+      })
+    );
+    expect(model.serverUrl).toBe('https://api.example.com/v2');
+  });
+
+  it('keeps an undeclared server-URL variable as its placeholder', () => {
+    const model = buildApiModel(doc({ servers: [{ url: 'https://{env}.example.com' }] }));
+    expect(model.serverUrl).toBe('https://{env}.example.com');
+  });
+
+  it('falls back to defaults when info/servers are missing', () => {
+    const model = buildApiModel({ openapi: '3.0.3', paths: {} } as Oas3Definition);
+    expect(model.title).toBe('Api');
+    expect(model.version).toBe('0.0.0');
+    expect(model.description).toBeUndefined();
+    expect(model.serverUrl).toBe('');
+  });
+
+  it('emits an empty schemas array when components.schemas is absent', () => {
+    const model = buildApiModel(doc({}));
+    expect(model.schemas).toEqual([]);
+  });
+
+  it('tolerates documents that have no `paths` field at all', () => {
+    const model = buildApiModel({
+      openapi: '3.0.3',
+      info: { title: 't', version: '1' },
+    } as Oas3Definition);
+    expect(model.services[0].operations).toEqual([]);
+  });
+});
+
+describe('buildNamedSchemas', () => {
+  it('builds inline schemas with their description', () => {
+    const model = buildApiModel(
+      doc({
+        components: {
+          schemas: {
+            Foo: { type: 'string', description: 'a foo' } as Oas3Schema,
+          },
+        },
+      } as Partial<Oas3Definition>)
+    );
+    expect(model.schemas[0]).toEqual({
+      name: 'Foo',
+      schema: { kind: 'scalar', scalar: 'string', description: 'a foo' },
+      description: 'a foo',
+    });
+  });
+
+  it('forwards a $ref-only schema entry to its target', () => {
+    const model = buildApiModel(
+      doc({
+        components: {
+          schemas: {
+            Target: { type: 'string', description: 'target desc' } as Oas3Schema,
+            Alias: { $ref: '#/components/schemas/Target' } as unknown as Oas3Schema,
+          },
+        },
+      } as Partial<Oas3Definition>)
+    );
+    const alias = model.schemas.find((s) => s.name === 'Alias');
+    expect(alias?.schema).toMatchObject({ kind: 'scalar', scalar: 'string' });
+    expect(alias?.description).toBe('target desc');
+  });
+});
+
+describe('buildServices — paths & methods', () => {
+  it('skips falsy path items', () => {
+    const model = buildApiModel(
+      doc({ paths: { '/skip': null as unknown as never } } as Partial<Oas3Definition>)
+    );
+    expect(model.services[0].operations).toEqual([]);
+  });
+
+  it('dereferences $ref path items', () => {
+    const model = buildApiModel(
+      doc({
+        paths: {
+          '/proxy': { $ref: '#/x-stash/pathA' } as unknown as never,
+        },
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        ...({ 'x-stash': { pathA: { get: { operationId: 'opA', responses: {} } } } } as any),
+      })
+    );
+    expect(model.services[0].operations[0].name).toBe('opA');
+  });
+
+  it('iterates every HTTP method that is present', () => {
+    const make = (id: string) => ({ operationId: id, responses: {} });
+    const model = buildApiModel(
+      doc({
+        paths: {
+          '/m': {
+            get: make('g'),
+            post: make('po'),
+            put: make('pu'),
+            delete: make('d'),
+            patch: make('pa'),
+            head: make('h'),
+            options: make('o'),
+          } as never,
+        },
+      })
+    );
+    expect(model.services[0].operations.map((op) => op.method)).toEqual([
+      'get',
+      'post',
+      'put',
+      'delete',
+      'patch',
+      'head',
+      'options',
+    ]);
+  });
+
+  it('propagates path-level parameters and lets operation-level params override them', () => {
+    const op = buildOpOnly({
+      paths: {
+        '/users/{id}': {
+          parameters: [
+            { name: 'id', in: 'path', required: true, schema: { type: 'string' } },
+            { name: 'verbose', in: 'query', schema: { type: 'boolean' } },
+          ] as never,
+          get: {
+            operationId: 'getUser',
+            parameters: [
+              { name: 'id', in: 'path', required: true, schema: { type: 'integer' } },
+            ] as never,
+            responses: {},
+          },
+        } as never,
+      },
+    });
+    expect(op.pathParams.find((p) => p.name === 'id')?.schema).toEqual({
+      kind: 'scalar',
+      scalar: 'integer',
+    });
+    expect(op.queryParams.find((p) => p.name === 'verbose')).toBeTruthy();
+  });
+});
+
+describe('buildOperation — tags', () => {
+  it('carries the operation tags through to the model', () => {
+    const op = buildOpOnly({
+      paths: {
+        '/pets': {
+          get: { operationId: 'listPets', tags: ['pets', 'public'], responses: {} },
+        } as never,
+      },
+    });
+    expect(op.tags).toEqual(['pets', 'public']);
+  });
+
+  it('defaults to an empty tags array when the operation declares none', () => {
+    const op = buildOpOnly({
+      paths: { '/health': { get: { operationId: 'health', responses: {} } } as never },
+    });
+    expect(op.tags).toEqual([]);
+  });
+});
+
+describe('buildOperation — x-pagination extension', () => {
+  it('captures the x-pagination value verbatim, without validation', () => {
+    const extension = { style: 'cursor', cursorParam: 'cursor', bogus: 42 };
+    const op = buildOpOnly({
+      paths: {
+        '/orders': {
+          get: { operationId: 'listOrders', 'x-pagination': extension, responses: {} },
+        } as never,
+      },
+    });
+    expect(op.paginationExtension).toBe(extension);
+  });
+
+  it('captures a non-object x-pagination value too (validated by the emitter, not the IR)', () => {
+    const op = buildOpOnly({
+      paths: {
+        '/orders': {
+          get: { operationId: 'listOrders', 'x-pagination': 'nonsense', responses: {} },
+        } as never,
+      },
+    });
+    expect(op.paginationExtension).toBe('nonsense');
+  });
+
+  it('leaves paginationExtension absent when the operation declares none', () => {
+    const op = buildOpOnly({
+      paths: { '/orders': { get: { operationId: 'listOrders', responses: {} } } as never },
+    });
+    expect('paginationExtension' in op).toBe(false);
+  });
+});
+
+describe('buildOperation — param paths', () => {
+  it('splits parameters by their `in` location', () => {
+    const op = buildOpOnly({
+      paths: {
+        '/x/{p}': {
+          get: {
+            operationId: 'op',
+            parameters: [
+              { name: 'p', in: 'path', required: true, schema: { type: 'string' } },
+              { name: 'q', in: 'query', schema: { type: 'string' } },
+              { name: 'X-Tok', in: 'header', schema: { type: 'string' } },
+            ] as never,
+            responses: {},
+          },
+        } as never,
+      },
+    });
+    expect(op.pathParams.map((p) => p.name)).toEqual(['p']);
+    expect(op.queryParams.map((p) => p.name)).toEqual(['q']);
+    expect(op.headerParams.map((p) => p.name)).toEqual(['X-Tok']);
+  });
+
+  it('keeps cookie parameters in cookieParams', () => {
+    const op = buildOpOnly({
+      paths: {
+        '/orders/{id}': {
+          get: {
+            operationId: 'getOrder',
+            parameters: [
+              { name: 'id', in: 'path', required: true, schema: { type: 'string' } },
+              { name: 'sid', in: 'cookie', schema: { type: 'string' } },
+            ] as never,
+            responses: {},
+          },
+        } as never,
+      },
+    });
+    expect(op.pathParams.map((p) => p.name)).toEqual(['id']);
+    expect(op.cookieParams.map((p) => p.name)).toEqual(['sid']);
+  });
+
+  it('resolves a $ref requestBody', () => {
+    const op = buildOpOnly({
+      paths: {
+        '/x': {
+          post: {
+            operationId: 'create',
+            requestBody: { $ref: '#/components/requestBodies/CreateBody' } as never,
+            responses: {},
+          },
+        } as never,
+      },
+      components: {
+        requestBodies: {
+          CreateBody: {
+            required: true,
+            content: { 'application/json': { schema: { type: 'string' } } },
+          },
+        },
+      } as never,
+    });
+    expect(op.requestBody?.contentType).toBe('application/json');
+    expect(op.requestBody?.required).toBe(true);
+  });
+
+  it('omits requestBody when the operation has none', () => {
+    const op = buildOpOnly({
+      paths: {
+        '/x': { get: { operationId: 'op', responses: {} } } as never,
+      },
+    });
+    expect(op.requestBody).toBeUndefined();
+  });
+});
+
+describe('buildParameter', () => {
+  it('throws when `in` is missing', () => {
+    expect(() =>
+      buildApiModel(
+        doc({
+          paths: {
+            '/x': {
+              get: {
+                operationId: 'op',
+                parameters: [{ name: 'p', schema: { type: 'string' } }] as never,
+                responses: {},
+              },
+            } as never,
+          },
+        })
+      )
+    ).toThrow(/missing "in"/);
+  });
+
+  it('throws for an unsupported `in` value', () => {
+    expect(() =>
+      buildApiModel(
+        doc({
+          paths: {
+            '/x': {
+              get: {
+                operationId: 'op',
+                parameters: [{ name: 'p', in: 'body', schema: { type: 'string' } }] as never,
+                responses: {},
+              },
+            } as never,
+          },
+        })
+      )
+    ).toThrow(/Unsupported parameter location/);
+  });
+
+  it('produces an unknown schema when none is declared', () => {
+    const op = buildOpOnly({
+      paths: {
+        '/x/{p}': {
+          get: {
+            operationId: 'op',
+            parameters: [{ name: 'p', in: 'path', required: true }] as never,
+            responses: {},
+          },
+        } as never,
+      },
+    });
+    expect(op.pathParams[0].schema).toEqual({ kind: 'unknown' });
+  });
+
+  it('preserves $ref-typed parameter schemas', () => {
+    const op = buildOpOnly({
+      paths: {
+        '/x': {
+          get: {
+            operationId: 'op',
+            parameters: [
+              { name: 'q', in: 'query', schema: { $ref: '#/components/schemas/Id' } as never },
+            ] as never,
+            responses: {},
+          },
+        } as never,
+      },
+      components: { schemas: { Id: { type: 'string' } } as never },
+    });
+    expect(op.queryParams[0].schema).toEqual({ kind: 'ref', name: 'Id' });
+  });
+
+  it('passes through description and required', () => {
+    const op = buildOpOnly({
+      paths: {
+        '/x': {
+          get: {
+            operationId: 'op',
+            parameters: [
+              {
+                name: 'q',
+                in: 'query',
+                required: true,
+                description: 'desc',
+                schema: { type: 'string' },
+              },
+            ] as never,
+            responses: {},
+          },
+        } as never,
+      },
+    });
+    expect(op.queryParams[0]).toMatchObject({ description: 'desc', required: true });
+  });
+
+  it('captures style/explode/allowReserved on a query param', () => {
+    const op = buildOpOnly({
+      paths: {
+        '/x': {
+          get: {
+            operationId: 'op',
+            parameters: [
+              {
+                name: 'tags',
+                in: 'query',
+                style: 'pipeDelimited',
+                explode: false,
+                allowReserved: true,
+                schema: { type: 'array', items: { type: 'string' } },
+              },
+            ] as never,
+            responses: {},
+          },
+        } as never,
+      },
+    });
+    expect(op.queryParams[0]).toMatchObject({
+      style: 'pipeDelimited',
+      explode: false,
+      allowReserved: true,
+    });
+  });
+
+  it('leaves style/explode/allowReserved undefined on plain query params, unknown styles, and non-query params', () => {
+    const op = buildOpOnly({
+      paths: {
+        '/x/{p}': {
+          get: {
+            operationId: 'op',
+            parameters: [
+              { name: 'q', in: 'query', schema: { type: 'string' } },
+              { name: 'odd', in: 'query', style: 'matrix', schema: { type: 'string' } },
+              {
+                name: 'p',
+                in: 'path',
+                required: true,
+                style: 'pipeDelimited',
+                explode: false,
+                allowReserved: true,
+                schema: { type: 'string' },
+              },
+              {
+                name: 'X-Tok',
+                in: 'header',
+                style: 'pipeDelimited',
+                explode: false,
+                schema: { type: 'string' },
+              },
+            ] as never,
+            responses: {},
+          },
+        } as never,
+      },
+    });
+    const params = [op.queryParams[0], op.queryParams[1], op.pathParams[0], op.headerParams[0]];
+    expect(params.map((param) => param.style)).toEqual([
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+    ]);
+    expect(params.map((param) => param.explode)).toEqual([
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+    ]);
+    expect(params.map((param) => param.allowReserved)).toEqual([
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+    ]);
+  });
+});
+
+describe('buildRequestBody', () => {
+  const makeOp = (content: Record<string, unknown>, required = false): Partial<Oas3Definition> => ({
+    paths: {
+      '/x': {
+        post: {
+          operationId: 'op',
+          requestBody: { content, required } as never,
+          responses: {},
+        },
+      } as never,
+    },
+  });
+
+  it('returns undefined when there is no content at all', () => {
+    const op = buildOpOnly(makeOp({}));
+    expect(op.requestBody).toBeUndefined();
+  });
+
+  it('returns undefined when the requestBody has no `content` field whatsoever', () => {
+    const op = buildOpOnly({
+      paths: {
+        '/x': {
+          post: {
+            operationId: 'op',
+            requestBody: { required: true } as never,
+            responses: {},
+          },
+        } as never,
+      },
+    });
+    expect(op.requestBody).toBeUndefined();
+  });
+
+  it.each([
+    ['application/json'],
+    ['application/merge-patch+json'],
+    ['application/x-www-form-urlencoded'],
+    ['multipart/form-data'],
+  ])('prefers %s when offered alongside application/xml', (contentType) => {
+    const op = buildOpOnly(
+      makeOp({
+        'application/xml': { schema: { type: 'string' } },
+        [contentType]: { schema: { type: 'object' } },
+      })
+    );
+    expect(op.requestBody?.contentType).toBe(contentType);
+  });
+
+  it('falls back to the first available media type when no known one matches', () => {
+    const op = buildOpOnly(
+      makeOp({
+        'application/xml': { schema: { type: 'string' } },
+      })
+    );
+    expect(op.requestBody?.contentType).toBe('application/xml');
+  });
+
+  it('reads schema $ref into a ref node', () => {
+    const op = buildOpOnly({
+      paths: {
+        '/x': {
+          post: {
+            operationId: 'op',
+            requestBody: {
+              content: {
+                'application/json': { schema: { $ref: '#/components/schemas/X' } as never },
+              },
+            } as never,
+            responses: {},
+          },
+        } as never,
+      },
+      components: { schemas: { X: { type: 'string' } } as never },
+    });
+    expect(op.requestBody?.schema).toEqual({ kind: 'ref', name: 'X' });
+  });
+
+  it('produces an unknown schema when none is declared', () => {
+    const op = buildOpOnly(
+      makeOp({
+        'application/json': {},
+      })
+    );
+    expect(op.requestBody?.schema).toEqual({ kind: 'unknown' });
+  });
+
+  it('emits the inline schema when one is declared', () => {
+    const op = buildOpOnly(makeOp({ 'application/json': { schema: { type: 'string' } } }, true));
+    expect(op.requestBody?.schema).toEqual({ kind: 'scalar', scalar: 'string' });
+    expect(op.requestBody?.required).toBe(true);
+  });
+});
+
+describe('buildSuccessResponses', () => {
+  const opWithResponses = (responses: Record<string, unknown>): Partial<Oas3Definition> => ({
+    paths: {
+      '/x': {
+        get: { operationId: 'op', responses: responses as never },
+      } as never,
+    },
+  });
+
+  it('returns [] when responses is empty', () => {
+    expect(buildOpOnly(opWithResponses({})).successResponses).toEqual([]);
+  });
+
+  it('returns [] when the operation has no `responses` field at all', () => {
+    const op = buildOpOnly({
+      paths: {
+        '/x': { get: { operationId: 'op' } as never } as never,
+      },
+    });
+    expect(op.successResponses).toEqual([]);
+  });
+
+  it('uses `default` when no 2xx response exists', () => {
+    const op = buildOpOnly(
+      opWithResponses({
+        default: { content: { 'application/json': { schema: { type: 'string' } } } },
+      })
+    );
+    expect(op.successResponses[0].contentType).toBe('application/json');
+    expect(op.successResponses[0].status).toBe('default');
+  });
+
+  it('sets status to the numeric 2xx code', () => {
+    const op = buildOpOnly(
+      opWithResponses({
+        '201': { content: { 'application/json': { schema: { type: 'string' } } } },
+      })
+    );
+    expect(op.successResponses[0].status).toBe(201);
+  });
+
+  it('returns [] when neither 2xx nor default exist', () => {
+    expect(
+      buildOpOnly(
+        opWithResponses({
+          '404': { content: { 'application/json': { schema: { type: 'string' } } } },
+        })
+      ).successResponses
+    ).toEqual([]);
+  });
+
+  it('returns [] when the response object is missing/null', () => {
+    expect(buildOpOnly(opWithResponses({ '200': null })).successResponses).toEqual([]);
+  });
+
+  it('returns [] when the response has no content (204-style)', () => {
+    expect(
+      buildOpOnly(opWithResponses({ '204': { description: 'No content' } })).successResponses
+    ).toEqual([]);
+  });
+
+  it('dereferences a $ref response', () => {
+    const op = buildOpOnly({
+      paths: {
+        '/x': {
+          get: {
+            operationId: 'op',
+            responses: { '200': { $ref: '#/components/responses/Ok' } } as never,
+          },
+        } as never,
+      },
+      components: {
+        responses: {
+          Ok: { content: { 'application/json': { schema: { type: 'string' } } } },
+        } as never,
+      },
+    });
+    expect(op.successResponses[0].schema).toEqual({ kind: 'scalar', scalar: 'string' });
+  });
+
+  it('emits unknown for response media without a schema', () => {
+    const op = buildOpOnly(opWithResponses({ '200': { content: { 'application/json': {} } } }));
+    expect(op.successResponses[0].schema).toEqual({ kind: 'unknown' });
+  });
+
+  it('emits ref for response media whose schema is a $ref', () => {
+    const op = buildOpOnly({
+      paths: {
+        '/x': {
+          get: {
+            operationId: 'op',
+            responses: {
+              '200': {
+                content: {
+                  'application/json': { schema: { $ref: '#/components/schemas/X' } as never },
+                },
+              },
+            } as never,
+          },
+        } as never,
+      },
+      components: { schemas: { X: { type: 'string' } } as never },
+    });
+    expect(op.successResponses[0].schema).toEqual({ kind: 'ref', name: 'X' });
+  });
+
+  it('captures itemSchema on a text/event-stream success response', () => {
+    const op = buildOpOnly({
+      paths: {
+        '/messages': {
+          get: {
+            operationId: 'streamMessages',
+            responses: {
+              '200': {
+                description: 'ok',
+                content: {
+                  'text/event-stream': {
+                    itemSchema: { $ref: '#/components/schemas/Message' },
+                  } as never,
+                },
+              },
+            } as never,
+          },
+        } as never,
+      },
+      components: {
+        schemas: { Message: { type: 'object', properties: { text: { type: 'string' } } } } as never,
+      },
+    });
+    expect(op.successResponses[0].itemSchema).toEqual({ kind: 'ref', name: 'Message' });
+  });
+
+  it('leaves itemSchema undefined for an ordinary JSON response', () => {
+    const op = buildOpOnly({
+      paths: {
+        '/x': {
+          get: {
+            operationId: 'op',
+            responses: {
+              '200': { content: { 'application/json': { schema: { type: 'string' } } } },
+            } as never,
+          },
+        } as never,
+      },
+    });
+    expect(op.successResponses[0].itemSchema).toBeUndefined();
+  });
+});
+
+describe('buildErrorResponses', () => {
+  const opWithResponses = (responses: Record<string, unknown>): Partial<Oas3Definition> => ({
+    paths: {
+      '/x': {
+        get: { operationId: 'op', responses: responses as never },
+      } as never,
+    },
+  });
+
+  it('captures 4xx and 5xx responses, leaving successResponses for the 2xx', () => {
+    const op = buildOpOnly(
+      opWithResponses({
+        '200': { content: { 'application/json': { schema: { type: 'string' } } } },
+        '404': { content: { 'application/json': { schema: { type: 'number' } } } },
+        '500': { content: { 'application/json': { schema: { type: 'boolean' } } } },
+      })
+    );
+    expect(op.errorResponses).toEqual([
+      {
+        contentType: 'application/json',
+        schema: { kind: 'scalar', scalar: 'number' },
+        status: 404,
+      },
+      {
+        contentType: 'application/json',
+        schema: { kind: 'scalar', scalar: 'boolean' },
+        status: 500,
+      },
+    ]);
+    expect(op.successResponses).toEqual([
+      {
+        contentType: 'application/json',
+        schema: { kind: 'scalar', scalar: 'string' },
+        status: 200,
+      },
+    ]);
+  });
+
+  it('treats `default` as an error when a 2xx success also exists', () => {
+    const op = buildOpOnly(
+      opWithResponses({
+        '200': { content: { 'application/json': { schema: { type: 'string' } } } },
+        default: { content: { 'application/json': { schema: { type: 'number' } } } },
+      })
+    );
+    expect(op.errorResponses).toEqual([
+      {
+        contentType: 'application/json',
+        schema: { kind: 'scalar', scalar: 'number' },
+        status: 'default',
+      },
+    ]);
+    expect(op.successResponses).toEqual([
+      {
+        contentType: 'application/json',
+        schema: { kind: 'scalar', scalar: 'string' },
+        status: 200,
+      },
+    ]);
+  });
+
+  it('does not treat `default` as an error when no 2xx exists (success consumes it)', () => {
+    const op = buildOpOnly(
+      opWithResponses({
+        default: { content: { 'application/json': { schema: { type: 'number' } } } },
+      })
+    );
+    expect(op.successResponses).toEqual([
+      {
+        contentType: 'application/json',
+        schema: { kind: 'scalar', scalar: 'number' },
+        status: 'default',
+      },
+    ]);
+    expect(op.errorResponses).toEqual([]);
+  });
+
+  it('returns [] when there are no error responses', () => {
+    const op = buildOpOnly(
+      opWithResponses({
+        '200': { content: { 'application/json': { schema: { type: 'string' } } } },
+      })
+    );
+    expect(op.errorResponses).toEqual([]);
+  });
+
+  it('emits one entry per content type on a 4xx with multiple media types', () => {
+    const op = buildOpOnly(
+      opWithResponses({
+        '200': { content: { 'application/json': { schema: { type: 'string' } } } },
+        '400': {
+          content: {
+            'application/json': { schema: { type: 'number' } },
+            'text/plain': { schema: { type: 'string' } },
+          },
+        },
+      })
+    );
+    expect(op.errorResponses).toEqual([
+      {
+        contentType: 'application/json',
+        schema: { kind: 'scalar', scalar: 'number' },
+        status: 400,
+      },
+      { contentType: 'text/plain', schema: { kind: 'scalar', scalar: 'string' }, status: 400 },
+    ]);
+  });
+
+  it('skips a missing/null error response and one without content', () => {
+    const op = buildOpOnly(
+      opWithResponses({
+        '200': { content: { 'application/json': { schema: { type: 'string' } } } },
+        '404': null,
+        '500': { description: 'no content' },
+      })
+    );
+    expect(op.errorResponses).toEqual([]);
+  });
+
+  it('dereferences a $ref error response', () => {
+    const op = buildOpOnly({
+      paths: {
+        '/x': {
+          get: {
+            operationId: 'op',
+            responses: {
+              '200': { content: { 'application/json': { schema: { type: 'string' } } } },
+              '404': { $ref: '#/components/responses/NotFound' },
+            } as never,
+          },
+        } as never,
+      },
+      components: {
+        responses: {
+          NotFound: {
+            content: { 'application/json': { schema: { $ref: '#/components/schemas/Err' } } },
+          },
+        } as never,
+      },
+    });
+    expect(op.errorResponses).toEqual([
+      { contentType: 'application/json', schema: { kind: 'ref', name: 'Err' }, status: 404 },
+    ]);
+  });
+
+  it('sets numeric error statuses (404, 422) and `default` correctly', () => {
+    const op = buildOpOnly(
+      opWithResponses({
+        '200': { content: { 'application/json': { schema: { type: 'string' } } } },
+        '404': { content: { 'application/json': { schema: { type: 'string' } } } },
+        '422': { content: { 'application/json': { schema: { type: 'string' } } } },
+        default: { content: { 'application/json': { schema: { type: 'string' } } } },
+      })
+    );
+    expect(op.errorResponses.map((r) => r.status)).toEqual([404, 422, 'default']);
+  });
+});
+
+describe('buildSchema — every schema kind', () => {
+  it('renders oneOf as a union (preserving members with $ref)', () => {
+    const got = buildSchemaOnly({
+      oneOf: [{ $ref: '#/components/schemas/A' } as never, { type: 'number' }],
+    } as Oas3Schema);
+    expect(got).toEqual({
+      kind: 'union',
+      members: [
+        { kind: 'ref', name: 'A' },
+        { kind: 'scalar', scalar: 'number' },
+      ],
+    });
+  });
+
+  it('renders anyOf as a union too', () => {
+    const got = buildSchemaOnly({ anyOf: [{ type: 'string' }, { type: 'number' }] } as Oas3Schema);
+    expect(got.kind).toBe('union');
+  });
+
+  it('renders allOf as intersection when there are 2+ members', () => {
+    const got = buildSchemaOnly({
+      allOf: [{ type: 'string' }, { $ref: '#/components/schemas/B' } as never],
+    } as Oas3Schema);
+    expect(got).toEqual({
+      kind: 'intersection',
+      members: [
+        { kind: 'scalar', scalar: 'string' },
+        { kind: 'ref', name: 'B' },
+      ],
+    });
+  });
+
+  it('flattens allOf with a single member, using its own description if present', () => {
+    const got = buildSchemaOnly({
+      description: 'outer desc',
+      allOf: [{ type: 'string', description: 'inner' }],
+    } as Oas3Schema);
+    expect(got).toEqual({ kind: 'scalar', scalar: 'string', description: 'inner' });
+  });
+
+  it('flattens allOf with a single member, inheriting the outer description if member has none', () => {
+    const got = buildSchemaOnly({
+      description: 'outer desc',
+      allOf: [{ type: 'string' }],
+    } as Oas3Schema);
+    expect(got).toEqual({ kind: 'scalar', scalar: 'string', description: 'outer desc' });
+  });
+
+  it("folds a schema's own properties into its allOf intersection (keeps the discriminant)", () => {
+    // `allOf` does not replace sibling `properties`; the own object (here the
+    // `kind` discriminant) must be intersected with the allOf members, not dropped.
+    const got = buildSchemaOnly({
+      type: 'object',
+      properties: { kind: { type: 'string', const: 'A' } },
+      allOf: [{ $ref: '#/components/schemas/Base' } as never],
+    } as Oas3Schema);
+    expect(got).toEqual({
+      kind: 'intersection',
+      members: [
+        {
+          kind: 'object',
+          properties: [{ name: 'kind', schema: { kind: 'literal', value: 'A' }, required: false }],
+        },
+        { kind: 'ref', name: 'Base' },
+      ],
+    });
+  });
+
+  it('renders a single `type: "null"` schema as null', () => {
+    expect(buildSchemaOnly({ type: 'null' } as never)).toEqual({ kind: 'null' });
+  });
+
+  it('handles OpenAPI 3.1 array-of-types nullable as union (string | null)', () => {
+    const got = buildSchemaOnly({ type: ['string', 'null'] as never } as Oas3Schema);
+    expect(got).toEqual({
+      kind: 'union',
+      members: [{ kind: 'scalar', scalar: 'string' }, { kind: 'null' }],
+    });
+  });
+
+  it('reduces a single-element array of types to just that type', () => {
+    const got = buildSchemaOnly({ type: ['string'] as never } as Oas3Schema);
+    expect(got).toEqual({ kind: 'scalar', scalar: 'string' });
+  });
+
+  it('handles array-of-types union without null', () => {
+    const got = buildSchemaOnly({ type: ['string', 'number'] as never } as Oas3Schema);
+    expect(got.kind).toBe('union');
+  });
+
+  it('handles OpenAPI 3.0 nullable: true', () => {
+    const got = buildSchemaOnly({ type: 'string', nullable: true } as unknown as Oas3Schema);
+    expect(got).toEqual({
+      kind: 'union',
+      members: [{ kind: 'scalar', scalar: 'string' }, { kind: 'null' }],
+    });
+  });
+
+  it('renders const string/number/boolean as literal', () => {
+    expect(buildSchemaOnly({ const: 'hello' } as unknown as Oas3Schema)).toEqual({
+      kind: 'literal',
+      value: 'hello',
+    });
+    expect(buildSchemaOnly({ const: 42 } as unknown as Oas3Schema)).toEqual({
+      kind: 'literal',
+      value: 42,
+    });
+    expect(buildSchemaOnly({ const: true } as unknown as Oas3Schema)).toEqual({
+      kind: 'literal',
+      value: true,
+    });
+    // `const: false` stays a literal even though boolean enums widen (see #4) —
+    // an explicit single-value constraint, and a falsy value the branch must not drop.
+    expect(buildSchemaOnly({ type: 'boolean', const: false } as unknown as Oas3Schema)).toEqual({
+      kind: 'literal',
+      value: false,
+    });
+  });
+
+  it('throws NotSupportedError for unsupported const value types (objects)', () => {
+    expect(() => buildSchemaOnly({ const: { a: 1 } } as unknown as Oas3Schema)).toThrow(
+      NotSupportedError
+    );
+  });
+
+  it('renders enum strings with scalar=string', () => {
+    expect(buildSchemaOnly({ enum: ['a', 'b'] } as Oas3Schema)).toEqual({
+      kind: 'enum',
+      values: ['a', 'b'],
+      scalar: 'string',
+    });
+  });
+
+  it('renders enum numbers with scalar=number', () => {
+    expect(buildSchemaOnly({ enum: [1, 2] } as Oas3Schema)).toEqual({
+      kind: 'enum',
+      values: [1, 2],
+      scalar: 'number',
+    });
+  });
+
+  it('widens boolean enums to a plain boolean scalar (see #4)', () => {
+    expect(buildSchemaOnly({ enum: [true, false] } as Oas3Schema)).toEqual({
+      kind: 'scalar',
+      scalar: 'boolean',
+    });
+  });
+
+  it('widens a single-value boolean enum to boolean too (no over-narrowing to a literal)', () => {
+    expect(buildSchemaOnly({ type: 'boolean', enum: [false] } as Oas3Schema)).toEqual({
+      kind: 'scalar',
+      scalar: 'boolean',
+    });
+  });
+
+  it('renders mixed-type enums with the fallback scalar=string', () => {
+    const got = buildSchemaOnly({ enum: ['a', 1] } as Oas3Schema);
+    expect(got).toMatchObject({ kind: 'enum', scalar: 'string' });
+  });
+
+  it('throws NotSupportedError for enum entries with unsupported types', () => {
+    expect(() => buildSchemaOnly({ enum: [{ a: 1 }] } as Oas3Schema)).toThrow(NotSupportedError);
+  });
+
+  it('renders array with inline items', () => {
+    expect(buildSchemaOnly({ type: 'array', items: { type: 'string' } } as Oas3Schema)).toEqual({
+      kind: 'array',
+      items: { kind: 'scalar', scalar: 'string' },
+    });
+  });
+
+  it('renders array with $ref items', () => {
+    expect(
+      buildSchemaOnly({
+        type: 'array',
+        items: { $ref: '#/components/schemas/Y' } as never,
+      } as Oas3Schema)
+    ).toEqual({ kind: 'array', items: { kind: 'ref', name: 'Y' } });
+  });
+
+  it('renders array with missing items as array of unknown', () => {
+    expect(buildSchemaOnly({ type: 'array' } as Oas3Schema)).toEqual({
+      kind: 'array',
+      items: { kind: 'unknown' },
+    });
+  });
+
+  it('renders array with boolean items as array of unknown', () => {
+    expect(
+      buildSchemaOnly({ type: 'array', items: true as unknown as Oas3Schema } as Oas3Schema)
+    ).toEqual({ kind: 'array', items: { kind: 'unknown' } });
+  });
+
+  it('renders object with properties', () => {
+    const got = buildSchemaOnly({
+      type: 'object',
+      required: ['id'],
+      properties: {
+        id: { type: 'string' },
+        name: { type: 'string', description: 'opt' },
+      },
+    } as Oas3Schema);
+    expect(got).toEqual({
+      kind: 'object',
+      properties: [
+        { name: 'id', schema: { kind: 'scalar', scalar: 'string' }, required: true },
+        {
+          name: 'name',
+          schema: { kind: 'scalar', scalar: 'string', description: 'opt' },
+          required: false,
+          description: 'opt',
+        },
+      ],
+    });
+  });
+
+  it('renders record (additionalProperties: true) as kind record/unknown', () => {
+    expect(
+      buildSchemaOnly({ type: 'object', additionalProperties: true } as unknown as Oas3Schema)
+    ).toEqual({ kind: 'record', value: { kind: 'unknown' } });
+  });
+
+  it('renders record with $ref-valued additionalProperties', () => {
+    expect(
+      buildSchemaOnly({
+        type: 'object',
+        additionalProperties: { $ref: '#/components/schemas/Z' } as never,
+      } as Oas3Schema)
+    ).toEqual({ kind: 'record', value: { kind: 'ref', name: 'Z' } });
+  });
+
+  it('renders record with inline-valued additionalProperties', () => {
+    expect(
+      buildSchemaOnly({
+        type: 'object',
+        additionalProperties: { type: 'number' },
+      } as Oas3Schema)
+    ).toEqual({ kind: 'record', value: { kind: 'scalar', scalar: 'number' } });
+  });
+
+  it('treats a schema with `properties` (no type) as object', () => {
+    const got = buildSchemaOnly({
+      properties: { a: { type: 'string' } },
+    } as Oas3Schema);
+    expect(got.kind).toBe('object');
+  });
+
+  it('treats a schema with only `additionalProperties` (no type, no props) as record', () => {
+    const got = buildSchemaOnly({
+      additionalProperties: { type: 'string' },
+    } as Oas3Schema);
+    expect(got.kind).toBe('record');
+  });
+
+  it('renders a property-less object (no additionalProperties) as a free-form record of unknown', () => {
+    // OpenAPI defaults absent `additionalProperties` to allowed, so `type: object`
+    // with no declared properties is free-form: `{ [key: string]: unknown }`, not
+    // `{}` — the latter forbids member access on the emitted type.
+    expect(buildSchemaOnly({ type: 'object' } as Oas3Schema)).toEqual({
+      kind: 'record',
+      value: { kind: 'unknown' },
+    });
+  });
+
+  it('keeps a property-less object with `additionalProperties: false` as a closed empty object', () => {
+    // Explicitly closed — no arbitrary keys allowed — so it stays `{}` (kind object).
+    expect(
+      buildSchemaOnly({ type: 'object', additionalProperties: false } as unknown as Oas3Schema)
+    ).toEqual({ kind: 'object', properties: [] });
+  });
+
+  it('captures `readOnly: true` on object properties', () => {
+    expect(
+      buildSchemaOnly({
+        type: 'object',
+        properties: {
+          id: { type: 'string', readOnly: true },
+          name: { type: 'string' },
+        },
+      } as unknown as Oas3Schema)
+    ).toEqual({
+      kind: 'object',
+      properties: [
+        {
+          name: 'id',
+          schema: { kind: 'scalar', scalar: 'string' },
+          required: false,
+          readOnly: true,
+        },
+        { name: 'name', schema: { kind: 'scalar', scalar: 'string' }, required: false },
+      ],
+    });
+  });
+
+  it('renders scalar string/number/integer/boolean', () => {
+    expect(buildSchemaOnly({ type: 'string' } as Oas3Schema)).toEqual({
+      kind: 'scalar',
+      scalar: 'string',
+    });
+    expect(buildSchemaOnly({ type: 'number' } as Oas3Schema)).toEqual({
+      kind: 'scalar',
+      scalar: 'number',
+    });
+    expect(buildSchemaOnly({ type: 'integer' } as Oas3Schema)).toEqual({
+      kind: 'scalar',
+      scalar: 'integer',
+    });
+    expect(buildSchemaOnly({ type: 'boolean' } as Oas3Schema)).toEqual({
+      kind: 'scalar',
+      scalar: 'boolean',
+    });
+  });
+
+  it('falls back to unknown for sparsely-typed schemas (no type/props/enum/etc)', () => {
+    expect(buildSchemaOnly({ description: 'mystery' } as Oas3Schema)).toEqual({
+      kind: 'unknown',
+      description: 'mystery',
+    });
+  });
+
+  it('passes through descriptions for arrays/objects/records', () => {
+    expect(
+      buildSchemaOnly({
+        type: 'array',
+        items: { type: 'string' },
+        description: 'list',
+      } as Oas3Schema)
+    ).toMatchObject({ description: 'list' });
+  });
+});
+
+describe('buildProperties', () => {
+  it('marks $ref properties without a description', () => {
+    const got = buildSchemaOnly({
+      type: 'object',
+      properties: { ref: { $ref: '#/components/schemas/X' } as never },
+    } as Oas3Schema);
+    expect(got).toMatchObject({
+      kind: 'object',
+      properties: [{ name: 'ref', schema: { kind: 'ref', name: 'X' }, required: false }],
+    });
+  });
+});
+
+describe('resolveRef (via $ref edge cases)', () => {
+  it('rejects external $refs', () => {
+    expect(() =>
+      buildApiModel(
+        doc({
+          paths: {
+            '/x': { $ref: 'https://example.com/api.yaml' } as never,
+          },
+        })
+      )
+    ).toThrow(/External \$ref not supported/);
+  });
+
+  it('rejects refs that pass through a non-object segment', () => {
+    expect(() =>
+      buildApiModel(
+        doc({
+          paths: {
+            '/x': { $ref: '#/info/title/something' } as never,
+          },
+        })
+      )
+    ).toThrow(/Cannot resolve \$ref/);
+  });
+
+  it('rejects refs that resolve to undefined after walking through a non-object', () => {
+    expect(() =>
+      buildApiModel(
+        doc({
+          paths: {
+            '/x': { $ref: '#/components/schemas/Missing' } as never,
+          },
+        })
+      )
+    ).toThrow(/Cannot resolve \$ref/);
+  });
+
+  it('rejects refs whose last segment misses (current becomes undefined at the tail)', () => {
+    // `/info/nonexistent`: every prefix exists (info is an object), but the final lookup
+    // misses, exercising the `current === undefined` guard rather than the in-loop one.
+    expect(() =>
+      buildApiModel(
+        doc({
+          paths: {
+            '/x': { $ref: '#/info/nonexistent' } as never,
+          },
+        })
+      )
+    ).toThrow(/Cannot resolve \$ref/);
+  });
+
+  it('handles JSON-pointer escapes (~0, ~1)', () => {
+    const model = buildApiModel(
+      doc({
+        paths: {
+          '/x': { $ref: '#/x-stash/a~1b/c~0d' } as never,
+        },
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        ...({
+          'x-stash': {
+            'a/b': { 'c~d': { get: { operationId: 'esc', responses: {} } } },
+          },
+        } as any),
+      })
+    );
+    expect(model.services[0].operations[0].name).toBe('esc');
+  });
+
+  it('refName returns the input as-is when the ref has no slash', () => {
+    const got = buildSchemaOnly({
+      oneOf: [{ $ref: 'NoSlash' } as never],
+    } as Oas3Schema);
+    expect(got).toEqual({
+      kind: 'union',
+      members: [{ kind: 'ref', name: 'NoSlash' }],
+    });
+  });
+});
+
+describe('extractMetadata — validation keywords', () => {
+  it('lifts numeric constraints into metadata', () => {
+    const got = buildSchemaOnly({ type: 'integer', minimum: 1, maximum: 100 } as Oas3Schema);
+    expect(got).toEqual({
+      kind: 'scalar',
+      scalar: 'integer',
+      metadata: { minimum: 1, maximum: 100 },
+    });
+  });
+
+  it('lifts string constraints (minLength, maxLength, pattern, format) into metadata', () => {
+    const got = buildSchemaOnly({
+      type: 'string',
+      minLength: 1,
+      maxLength: 50,
+      pattern: '^[a-z]+$',
+      format: 'email',
+    } as Oas3Schema);
+    expect(got).toEqual({
+      kind: 'scalar',
+      scalar: 'string',
+      metadata: {
+        minLength: 1,
+        maxLength: 50,
+        pattern: '^[a-z]+$',
+        format: 'email',
+      },
+    });
+  });
+
+  it('lifts array constraints (minItems, maxItems, uniqueItems) into metadata', () => {
+    const got = buildSchemaOnly({
+      type: 'array',
+      items: { type: 'string' },
+      minItems: 1,
+      maxItems: 10,
+      uniqueItems: true,
+    } as Oas3Schema);
+    expect(got).toMatchObject({
+      kind: 'array',
+      metadata: { minItems: 1, maxItems: 10, uniqueItems: true },
+    });
+  });
+
+  it('lifts deprecated: true into metadata', () => {
+    const got = buildSchemaOnly({ type: 'string', deprecated: true } as Oas3Schema);
+    expect(got).toEqual({
+      kind: 'scalar',
+      scalar: 'string',
+      metadata: { deprecated: true },
+    });
+  });
+
+  it('omits the metadata field entirely when no validation keys are present', () => {
+    // Strict-equality guard: ensures we don't ratchet every schema with an empty `metadata: {}`.
+    const got = buildSchemaOnly({ type: 'string' } as Oas3Schema);
+    expect(got).toEqual({ kind: 'scalar', scalar: 'string' });
+    expect(got).not.toHaveProperty('metadata');
+  });
+
+  it('omits `deprecated` when it is explicitly false', () => {
+    // A `deprecated: false` carries no information and would just clutter JSDoc.
+    const got = buildSchemaOnly({ type: 'string', deprecated: false } as Oas3Schema);
+    expect(got).not.toHaveProperty('metadata');
+  });
+
+  it('omits `uniqueItems` when it is explicitly false', () => {
+    // Default is false; only `true` is interesting.
+    const got = buildSchemaOnly({
+      type: 'array',
+      items: { type: 'string' },
+      uniqueItems: false,
+    } as Oas3Schema);
+    expect(got).not.toHaveProperty('metadata');
+  });
+
+  it.each([
+    [
+      'passes through numeric exclusiveMinimum / exclusiveMaximum (OAS 3.1 form)',
+      { exclusiveMinimum: 0, exclusiveMaximum: 600 },
+      { exclusiveMinimum: 0, exclusiveMaximum: 600 },
+    ],
+    [
+      'normalizes OAS 3.0 boolean exclusiveMinimum=true + minimum=X to numeric exclusiveMinimum=X',
+      { minimum: 0, exclusiveMinimum: true },
+      { exclusiveMinimum: 0 },
+    ],
+    [
+      'normalizes OAS 3.0 boolean exclusiveMaximum=true + maximum=X to numeric exclusiveMaximum=X',
+      { maximum: 100, exclusiveMaximum: true },
+      { exclusiveMaximum: 100 },
+    ],
+    [
+      'drops boolean exclusiveMinimum=false (3.0 form, no-op)',
+      { minimum: 5, exclusiveMinimum: false },
+      { minimum: 5 },
+    ],
+  ])('%s', (_case, bounds, metadata) => {
+    const got = buildSchemaOnly({ type: 'integer', ...bounds } as unknown as Oas3Schema);
+    expect(got).toEqual({ kind: 'scalar', scalar: 'integer', metadata });
+  });
+
+  it('lifts metadata on inline object properties', () => {
+    const got = buildSchemaOnly({
+      type: 'object',
+      properties: {
+        name: { type: 'string', minLength: 1, maxLength: 50 } as Oas3Schema,
+      },
+    } as Oas3Schema);
+    expect(got).toMatchObject({
+      kind: 'object',
+      properties: [
+        {
+          name: 'name',
+          schema: {
+            kind: 'scalar',
+            scalar: 'string',
+            metadata: { minLength: 1, maxLength: 50 },
+          },
+        },
+      ],
+    });
+  });
+
+  it('folds a Parameter Object-level `deprecated: true` into its schema metadata', () => {
+    const op = buildOpOnly({
+      paths: {
+        '/x': {
+          get: {
+            operationId: 'op',
+            parameters: [
+              {
+                name: 'q',
+                in: 'query',
+                deprecated: true,
+                schema: { type: 'string', maxLength: 10 },
+              },
+            ] as never,
+            responses: {},
+          },
+        } as never,
+      },
+    });
+    expect(op.queryParams[0].schema).toMatchObject({
+      kind: 'scalar',
+      scalar: 'string',
+      metadata: { maxLength: 10, deprecated: true },
+    });
+  });
+
+  it("preserves the wrapper schema's metadata when a single-member allOf collapses", () => {
+    // Exercises mergeMetadata(wrapper, undefined) — the inner has no metadata of
+    // its own, so the wrapper's constraints must survive the collapse.
+    const got = buildSchemaOnly({
+      allOf: [{ type: 'string' } as Oas3Schema],
+      minLength: 5,
+    } as Oas3Schema);
+    expect(got).toEqual({
+      kind: 'scalar',
+      scalar: 'string',
+      metadata: { minLength: 5 },
+    });
+  });
+
+  it("preserves the inner schema's metadata when the wrapper has none in a single-member allOf", () => {
+    // Exercises mergeMetadata(undefined, inner).
+    const got = buildSchemaOnly({
+      allOf: [{ type: 'string', minLength: 3 } as Oas3Schema],
+    } as Oas3Schema);
+    expect(got).toEqual({
+      kind: 'scalar',
+      scalar: 'string',
+      metadata: { minLength: 3 },
+    });
+  });
+
+  it('folds a Parameter Object-level `deprecated: true` into a $ref schema metadata', () => {
+    // When the parameter's schema is a $ref, we still need somewhere to attach
+    // the param-level deprecation. The ref carries it in its own metadata so the
+    // emitter can render it at the param's call-site context.
+    const op = buildOpOnly({
+      components: {
+        schemas: { Limit: { type: 'integer', minimum: 1 } as Oas3Schema },
+      } as never,
+      paths: {
+        '/x': {
+          get: {
+            operationId: 'op',
+            parameters: [
+              {
+                name: 'limit',
+                in: 'query',
+                deprecated: true,
+                schema: { $ref: '#/components/schemas/Limit' },
+              },
+            ] as never,
+            responses: {},
+          },
+        } as never,
+      },
+    });
+    expect(op.queryParams[0].schema).toEqual({
+      kind: 'ref',
+      name: 'Limit',
+      metadata: { deprecated: true },
+    });
+  });
+});
+
+describe('buildApiModel — enum with null (OAS 3.1)', () => {
+  it('models a standalone enum containing null as <enum> | null', () => {
+    const schema = buildSchemaOnly({ enum: ['a', 'b', null] } as never);
+    expect(schema).toEqual({
+      kind: 'union',
+      members: [{ kind: 'enum', values: ['a', 'b'], scalar: 'string' }, { kind: 'null' }],
+    });
+  });
+
+  it('models an enum of only null as the null type', () => {
+    const schema = buildSchemaOnly({ enum: [null] } as never);
+    expect(schema).toEqual({ kind: 'null' });
+  });
+
+  it('does not double null when type:[string,null] and enum both carry null', () => {
+    const schema = buildSchemaOnly({
+      type: ['string', 'null'],
+      enum: ['RUNNING', 'COMPLETED', null],
+    } as never);
+    expect(schema).toEqual({
+      kind: 'union',
+      members: [
+        { kind: 'enum', values: ['RUNNING', 'COMPLETED'], scalar: 'string' },
+        { kind: 'null' },
+      ],
+    });
+  });
+
+  it('keeps a plain enum (no null) as a bare enum', () => {
+    const schema = buildSchemaOnly({ type: 'string', enum: ['a', 'b'] } as never);
+    expect(schema).toEqual({ kind: 'enum', values: ['a', 'b'], scalar: 'string' });
+  });
+
+  it('drops an all-null enum under type:[string,null], leaving string | null', () => {
+    const schema = buildSchemaOnly({ type: ['string', 'null'], enum: [null] } as never);
+    expect(schema).toEqual({
+      kind: 'union',
+      members: [{ kind: 'scalar', scalar: 'string' }, { kind: 'null' }],
+    });
+  });
+
+  it('widens a nullable boolean enum to boolean | null (see #4)', () => {
+    const schema = buildSchemaOnly({ type: ['boolean', 'null'], enum: [false, null] } as never);
+    expect(schema).toEqual({
+      kind: 'union',
+      members: [{ kind: 'scalar', scalar: 'boolean' }, { kind: 'null' }],
+    });
+  });
+});
+
+describe('buildApiModel — discriminated unions (C6.4)', () => {
+  it('captures an explicit discriminator with mapping on a oneOf union', () => {
+    const schema = buildSchemaOnly({
+      oneOf: [{ $ref: '#/components/schemas/Beverage' }, { $ref: '#/components/schemas/Dessert' }],
+      discriminator: {
+        propertyName: 'category',
+        mapping: {
+          beverage: '#/components/schemas/Beverage',
+          dessert: '#/components/schemas/Dessert',
+        },
+      },
+    } as never);
+    expect(schema).toMatchObject({
+      kind: 'union',
+      discriminator: {
+        propertyName: 'category',
+        mapping: [
+          { value: 'beverage', schemaName: 'Beverage' },
+          { value: 'dessert', schemaName: 'Dessert' },
+        ],
+      },
+    });
+  });
+
+  it('derives mapping entries from $ref member names when no explicit mapping is given', () => {
+    const schema = buildSchemaOnly({
+      oneOf: [{ $ref: '#/components/schemas/Cat' }, { $ref: '#/components/schemas/Dog' }],
+      discriminator: { propertyName: 'petType' },
+    } as never);
+    expect(schema).toMatchObject({
+      kind: 'union',
+      discriminator: {
+        propertyName: 'petType',
+        mapping: [
+          { value: 'Cat', schemaName: 'Cat' },
+          { value: 'Dog', schemaName: 'Dog' },
+        ],
+      },
+    });
+  });
+
+  it('leaves the union without a discriminator when none is declared', () => {
+    const schema = buildSchemaOnly({
+      oneOf: [{ type: 'string' }, { type: 'number' }],
+    } as never);
+    expect(schema.kind).toBe('union');
+    expect((schema as { discriminator?: unknown }).discriminator).toBeUndefined();
+  });
+
+  it('drops a redundant `unknown` member from a union and collapses to the lone real type', () => {
+    // `oneOf: [Ref, {}]` would emit `Ref | unknown`, which collapses to `unknown`
+    // in TS and destroys the type. The empty branch is dropped, leaving `Ref`.
+    expect(
+      buildSchemaOnly({ oneOf: [{ $ref: '#/components/schemas/User' }, {}] } as never)
+    ).toEqual({ kind: 'ref', name: 'User' });
+  });
+
+  it('keeps real members and drops only the unknown one', () => {
+    expect(
+      buildSchemaOnly({ oneOf: [{ type: 'string' }, { type: 'number' }, {}] } as never)
+    ).toEqual({
+      kind: 'union',
+      members: [
+        { kind: 'scalar', scalar: 'string' },
+        { kind: 'scalar', scalar: 'number' },
+      ],
+    });
+  });
+
+  it('collapses a union of only unknown members to unknown', () => {
+    expect(buildSchemaOnly({ oneOf: [{}, {}] } as never)).toEqual({ kind: 'unknown' });
+  });
+
+  it('ignores a discriminator with no propertyName', () => {
+    const schema = buildSchemaOnly({
+      oneOf: [{ $ref: '#/components/schemas/Cat' }],
+      discriminator: { mapping: { cat: '#/components/schemas/Cat' } },
+    } as never);
+    expect((schema as { discriminator?: unknown }).discriminator).toBeUndefined();
+  });
+
+  it('ignores a discriminator that yields no named targets (inline members, no mapping)', () => {
+    const schema = buildSchemaOnly({
+      oneOf: [{ type: 'object' }, { type: 'object' }],
+      discriminator: { propertyName: 'kind' },
+    } as never);
+    expect((schema as { discriminator?: unknown }).discriminator).toBeUndefined();
+  });
+});
+
+describe('buildApiModel — request body readOnly stripping', () => {
+  function postBody(schemas: Record<string, unknown>, bodySchema: unknown): OperationModel {
+    return buildOpOnly({
+      components: { schemas } as never,
+      paths: {
+        '/things': {
+          post: {
+            operationId: 'createThing',
+            requestBody: {
+              required: true,
+              content: { 'application/json': { schema: bodySchema } },
+            },
+            responses: { '201': { description: 'ok' } },
+          },
+        },
+      },
+    } as Partial<Oas3Definition>);
+  }
+
+  it('drops readOnly props from a $ref request body via Omit', () => {
+    const op = postBody(
+      {
+        Pet: {
+          type: 'object',
+          required: ['id', 'name'],
+          properties: {
+            id: { type: 'string', readOnly: true },
+            name: { type: 'string' },
+            createdAt: { type: 'string', readOnly: true },
+          },
+        },
+      },
+      { $ref: '#/components/schemas/Pet' }
+    );
+    expect(op.requestBody?.schema).toEqual({
+      kind: 'omit',
+      base: 'Pet',
+      keys: ['id', 'createdAt'],
+    });
+  });
+
+  it('collects readOnly keys through allOf members (deduped)', () => {
+    const op = postBody(
+      {
+        Base: { type: 'object', properties: { id: { type: 'string', readOnly: true } } },
+        CredentialPost: {
+          allOf: [
+            { $ref: '#/components/schemas/Base' },
+            { type: 'object', required: ['name'], properties: { name: { type: 'string' } } },
+          ],
+        },
+      },
+      { $ref: '#/components/schemas/CredentialPost' }
+    );
+    expect(op.requestBody?.schema).toEqual({
+      kind: 'omit',
+      base: 'CredentialPost',
+      keys: ['id'],
+    });
+  });
+
+  it('filters readOnly props from an inline-object request body', () => {
+    const op = postBody(
+      {},
+      {
+        type: 'object',
+        required: ['name'],
+        properties: {
+          id: { type: 'string', readOnly: true },
+          name: { type: 'string' },
+        },
+      }
+    );
+    const body = op.requestBody?.schema as { kind: string; properties: Array<{ name: string }> };
+    expect(body.kind).toBe('object');
+    expect(body.properties.map((p) => p.name)).toEqual(['name']);
+  });
+
+  it('leaves a request body unchanged when the schema has no readOnly props', () => {
+    const op = postBody(
+      { Plain: { type: 'object', properties: { name: { type: 'string' } } } },
+      { $ref: '#/components/schemas/Plain' }
+    );
+    expect(op.requestBody?.schema).toEqual({ kind: 'ref', name: 'Plain' });
+  });
+
+  it('leaves an inline-object body unchanged when it has no readOnly props', () => {
+    const op = postBody(
+      {},
+      { type: 'object', required: ['name'], properties: { name: { type: 'string' } } }
+    );
+    const body = op.requestBody?.schema as { kind: string; properties: Array<{ name: string }> };
+    expect(body.kind).toBe('object');
+    expect(body.properties.map((p) => p.name)).toEqual(['name']);
+  });
+
+  it('leaves a non-object, non-ref body (array) unchanged', () => {
+    const op = postBody({}, { type: 'array', items: { type: 'string' } });
+    expect(op.requestBody?.schema).toEqual({
+      kind: 'array',
+      items: { kind: 'scalar', scalar: 'string' },
+    });
+  });
+
+  it('handles a self-referential allOf without looping (visited guard)', () => {
+    const op = postBody(
+      {
+        Node: {
+          allOf: [
+            { type: 'object', properties: { id: { type: 'string', readOnly: true } } },
+            { $ref: '#/components/schemas/Node' },
+          ],
+        },
+      },
+      { $ref: '#/components/schemas/Node' }
+    );
+    expect(op.requestBody?.schema).toEqual({ kind: 'omit', base: 'Node', keys: ['id'] });
+  });
+
+  it('leaves a $ref body unchanged when the base schema is absent', () => {
+    const op = postBody({}, { $ref: '#/components/schemas/Ghost' });
+    expect(op.requestBody?.schema).toEqual({ kind: 'ref', name: 'Ghost' });
+  });
+});
+
+describe('buildApiModel — security (C6.6)', () => {
+  function withSchemes(
+    schemes: Record<string, unknown>,
+    opSecurity?: unknown
+  ): Partial<Oas3Definition> {
+    return {
+      components: { securitySchemes: schemes } as never,
+      security: undefined,
+      paths: {
+        '/x': {
+          get: {
+            operationId: 'op',
+            security: opSecurity,
+            responses: {},
+          },
+        } as never,
+      },
+    };
+  }
+
+  it('returns an empty securitySchemes array when none are declared', () => {
+    const model = buildApiModel(doc({}));
+    expect(model.securitySchemes).toEqual([]);
+  });
+
+  it('models oauth2 / openIdConnect / http-bearer as bearer schemes', () => {
+    const model = buildApiModel(
+      doc(
+        withSchemes({
+          OAuth2: { type: 'oauth2', flows: {} },
+          Oidc: { type: 'openIdConnect', openIdConnectUrl: 'https://x/.well-known' },
+          BearerHttp: { type: 'http', scheme: 'Bearer' },
+        })
+      )
+    );
+    expect(model.securitySchemes).toEqual([
+      { kind: 'bearer', key: 'OAuth2' },
+      { kind: 'bearer', key: 'Oidc' },
+      { kind: 'bearer', key: 'BearerHttp' },
+    ]);
+  });
+
+  it('models apiKey-in-header schemes with their header name', () => {
+    const model = buildApiModel(
+      doc(withSchemes({ ApiKey: { type: 'apiKey', in: 'header', name: 'X-API-Key' } }))
+    );
+    expect(model.securitySchemes).toEqual([
+      { kind: 'apiKeyHeader', key: 'ApiKey', headerName: 'X-API-Key' },
+    ]);
+  });
+
+  it('models http-basic as a basic scheme', () => {
+    const model = buildApiModel(doc(withSchemes({ Basic: { type: 'http', scheme: 'basic' } })));
+    expect(model.securitySchemes).toEqual([{ kind: 'basic', key: 'Basic' }]);
+  });
+
+  it('models apiKey-in-query schemes with their param name', () => {
+    const model = buildApiModel(
+      doc(withSchemes({ QueryKey: { type: 'apiKey', in: 'query', name: 'api_key' } }))
+    );
+    expect(model.securitySchemes).toEqual([
+      { kind: 'apiKeyQuery', key: 'QueryKey', paramName: 'api_key' },
+    ]);
+  });
+
+  it('models apiKey-in-cookie schemes with their cookie name and warns about browsers', () => {
+    const warn = vi.spyOn(logger, 'warn').mockImplementation(() => {});
+    const model = buildApiModel(
+      doc(withSchemes({ CookieKey: { type: 'apiKey', in: 'cookie', name: 'sid' } }))
+    );
+    expect(model.securitySchemes).toEqual([
+      { kind: 'apiKeyCookie', key: 'CookieKey', cookieName: 'sid' },
+    ]);
+    expect(warn).toHaveBeenCalledWith(
+      'generate-client: security scheme "CookieKey" sends its credential in the Cookie header, ' +
+        'which browsers ignore — cookie auth works only in server-side clients.\n'
+    );
+  });
+
+  it('skips non-injectable schemes (http without scheme, mutualTLS)', () => {
+    const model = buildApiModel(
+      doc(
+        withSchemes({
+          HttpNoScheme: { type: 'http' },
+          Mtls: { type: 'mutualTLS' },
+        })
+      )
+    );
+    expect(model.securitySchemes).toEqual([]);
+  });
+
+  it('resolves a security $ref in components.securitySchemes', () => {
+    const model = buildApiModel(
+      doc({
+        components: {
+          securitySchemes: {
+            Ref: { $ref: '#/components/x/Real' },
+          },
+          x: { Real: { type: 'http', scheme: 'bearer' } },
+        } as never,
+        paths: {},
+      })
+    );
+    expect(model.securitySchemes).toEqual([{ kind: 'bearer', key: 'Ref' }]);
+  });
+
+  it('resolves operation security to the injectable scheme keys', () => {
+    const op = buildOpOnly(
+      withSchemes({ OAuth2: { type: 'oauth2', flows: {} } }, [{ OAuth2: ['orders:read'] }])
+    );
+    expect(op.security).toEqual([['OAuth2']]);
+  });
+
+  it('treats security: [] as an explicit opt-out (no auth)', () => {
+    const op = buildOpOnly(withSchemes({ OAuth2: { type: 'oauth2', flows: {} } }, []));
+    expect(op.security).toEqual([]);
+  });
+
+  it('falls back to the document-level security default when the operation has none', () => {
+    const model = buildApiModel(
+      doc({
+        components: { securitySchemes: { OAuth2: { type: 'oauth2', flows: {} } } } as never,
+        security: [{ OAuth2: [] }] as never,
+        paths: {
+          '/x': { get: { operationId: 'op', responses: {} } } as never,
+        },
+      })
+    );
+    expect(model.services[0].operations[0].security).toEqual([['OAuth2']]);
+  });
+
+  it('skips a leading `{}` (optional-auth marker) and applies the real alternative', () => {
+    const op = buildOpOnly(
+      withSchemes(
+        { OAuth2: { type: 'oauth2', flows: {} } },
+        // "anonymous OR bearer": credentials must still be sent when configured.
+        [{}, { OAuth2: [] }]
+      )
+    );
+    expect(op.security).toEqual([['OAuth2']]);
+  });
+
+  it('keeps every OR-alternative separate, never a union across them', () => {
+    const op = buildOpOnly(
+      withSchemes(
+        {
+          OAuth2: { type: 'oauth2', flows: {} },
+          ApiKey: { type: 'apiKey', in: 'header', name: 'X-API-Key' },
+        },
+        // "bearer OR apiKey": the runtime applies whichever alternative is configured.
+        [{ OAuth2: [] }, { ApiKey: [] }]
+      )
+    );
+    expect(op.security).toEqual([['OAuth2'], ['ApiKey']]);
+  });
+
+  it('skips an alternative with a non-injectable scheme and uses the next fully-injectable one', () => {
+    const op = buildOpOnly(
+      withSchemes(
+        {
+          OAuth2: { type: 'oauth2', flows: {} },
+          ApiKey: { type: 'apiKey', in: 'header', name: 'X-API-Key' },
+          NoScheme: { type: 'http' },
+        },
+        // The first alternative needs a non-injectable scheme, so the client falls to the
+        // next alternative, whose schemes (AND — both required) are all injectable.
+        [{ NoScheme: [] }, { OAuth2: [], ApiKey: [] }]
+      )
+    );
+    expect(op.security).toEqual([['OAuth2', 'ApiKey']]);
+  });
+
+  it('returns no security when the operation references only non-injectable schemes', () => {
+    const op = buildOpOnly(withSchemes({ NoScheme: { type: 'http' } }, [{ NoScheme: [] }]));
+    expect(op.security).toEqual([]);
+  });
+});
+
+describe('extractMetadata — example/default', () => {
+  it('captures `example` and `default` on a scalar schema', () => {
+    const got = buildSchemaOnly({ type: 'string', example: 'Ada', default: 'Anon' } as never);
+    expect(got).toMatchObject({ kind: 'scalar', scalar: 'string' });
+    expect(got.metadata?.example).toBe('Ada');
+    expect(got.metadata?.default).toBe('Anon');
+  });
+
+  it('prefers `examples[0]` (OAS 3.1) when `example` is absent', () => {
+    const got = buildSchemaOnly({ type: 'string', examples: ['Grace', 'Lin'] } as never);
+    expect(got.metadata?.example).toBe('Grace');
+  });
+
+  it('captures only `default` when no example or examples are present', () => {
+    const got = buildSchemaOnly({ type: 'string', default: 'fallback' } as never);
+    expect(got.metadata?.default).toBe('fallback');
+    expect(got.metadata?.example).toBeUndefined();
+  });
+});
diff --git a/packages/client-generator/src/intermediate-representation/__tests__/normalize-swagger2.test.ts b/packages/client-generator/src/intermediate-representation/__tests__/normalize-swagger2.test.ts
new file mode 100644
index 0000000000..ef86f3f345
--- /dev/null
+++ b/packages/client-generator/src/intermediate-representation/__tests__/normalize-swagger2.test.ts
@@ -0,0 +1,331 @@
+import { normalizeSwagger2 } from '../normalize-swagger2.js';
+
+function s2(extra: Record<string, unknown>): Record<string, unknown> {
+  return { swagger: '2.0', info: { title: 'T', version: '1' }, paths: {}, ...extra };
+}
+
+describe('normalizeSwagger2 — scaffold', () => {
+  it('builds servers[0].url from schemes + host + basePath', () => {
+    const out = normalizeSwagger2(
+      s2({ schemes: ['https'], host: 'api.example.com', basePath: '/v1' }) as never
+    );
+    expect(out.servers).toEqual([{ url: 'https://api.example.com/v1' }]);
+  });
+
+  it('defaults scheme to https and tolerates missing host/basePath', () => {
+    const out = normalizeSwagger2(s2({ host: 'api.example.com' }) as never);
+    expect(out.servers).toEqual([{ url: 'https://api.example.com' }]);
+  });
+
+  it('maps definitions to components.schemas and rewrites #/definitions refs', () => {
+    const out = normalizeSwagger2(
+      s2({
+        definitions: {
+          Pet: { type: 'object', properties: { owner: { $ref: '#/definitions/Owner' } } },
+          Owner: { type: 'object', properties: { name: { type: 'string' } } },
+        },
+      }) as never
+    );
+    expect((out.components as { schemas: Record<string, unknown> }).schemas.Owner).toBeDefined();
+    const pet = (
+      out.components as { schemas: Record<string, { properties: { owner: { $ref: string } } }> }
+    ).schemas.Pet;
+    expect(pet.properties.owner.$ref).toBe('#/components/schemas/Owner');
+  });
+
+  it('maps securityDefinitions: basic→http/basic, apiKey passes through, oauth2 flow→flows', () => {
+    const out = normalizeSwagger2(
+      s2({
+        securityDefinitions: {
+          Basic: { type: 'basic' },
+          ApiKey: { type: 'apiKey', name: 'X-Key', in: 'header' },
+          OAuth: {
+            type: 'oauth2',
+            flow: 'accessCode',
+            authorizationUrl: 'https://a',
+            tokenUrl: 'https://t',
+            scopes: { read: 'r' },
+          },
+        },
+      }) as never
+    );
+    const ss = (out.components as { securitySchemes: Record<string, Record<string, unknown>> })
+      .securitySchemes;
+    expect(ss.Basic).toEqual({ type: 'http', scheme: 'basic' });
+    expect(ss.ApiKey).toEqual({ type: 'apiKey', name: 'X-Key', in: 'header' });
+    expect(ss.OAuth.type).toBe('oauth2');
+    expect((ss.OAuth.flows as Record<string, unknown>).authorizationCode).toBeDefined();
+  });
+
+  it('sets openapi: 3.0.3 and drops swagger/host/basePath/schemes/definitions/securityDefinitions', () => {
+    const out = normalizeSwagger2(
+      s2({ host: 'h', definitions: {}, securityDefinitions: {} }) as never
+    ) as unknown as Record<string, unknown>;
+    expect(out.openapi).toBe('3.0.3');
+    expect(out.swagger).toBeUndefined();
+    expect(out.host).toBeUndefined();
+    expect(out.definitions).toBeUndefined();
+    expect(out.securityDefinitions).toBeUndefined();
+  });
+});
+
+describe('normalizeSwagger2 — scaffold (extra coverage)', () => {
+  it('omits servers when host is absent', () => {
+    const out = normalizeSwagger2(s2({}) as never) as unknown as Record<string, unknown>;
+    expect(out.servers).toBeUndefined();
+  });
+
+  it('maps top-level parameters to components.parameters', () => {
+    const sharedParam = { name: 'id', in: 'path', required: true, type: 'integer' };
+    const out = normalizeSwagger2(s2({ parameters: { PetId: sharedParam } }) as never);
+    expect((out.components as { parameters: Record<string, unknown> }).parameters).toEqual({
+      PetId: sharedParam,
+    });
+  });
+
+  it('maps top-level responses to components.responses via normalizeResponses', () => {
+    const out = normalizeSwagger2(
+      s2({
+        responses: { NotFound: { description: 'not found' } },
+        produces: ['application/json'],
+      }) as never
+    );
+    // No schema on the response → passes through unchanged
+    expect((out.components as { responses: Record<string, unknown> }).responses).toEqual({
+      NotFound: { description: 'not found' },
+    });
+  });
+
+  it('falls through to default in mapSecurityScheme for unknown types', () => {
+    const out = normalizeSwagger2(
+      s2({ securityDefinitions: { Bearer: { type: 'http', scheme: 'bearer' } } }) as never
+    );
+    const ss = (out.components as { securitySchemes: Record<string, Record<string, unknown>> })
+      .securitySchemes;
+    // Unknown type → returned as-is
+    expect(ss.Bearer).toEqual({ type: 'http', scheme: 'bearer' });
+  });
+
+  it('maps oauth2 implicit flow by its original name', () => {
+    const out = normalizeSwagger2(
+      s2({
+        securityDefinitions: {
+          Implicit: {
+            type: 'oauth2',
+            flow: 'implicit',
+            authorizationUrl: 'https://a',
+            scopes: { read: 'r' },
+          },
+        },
+      }) as never
+    );
+    const ss = (out.components as { securitySchemes: Record<string, Record<string, unknown>> })
+      .securitySchemes;
+    expect((ss.Implicit.flows as Record<string, unknown>).implicit).toBeDefined();
+  });
+
+  it('maps oauth2 application flow to clientCredentials', () => {
+    const out = normalizeSwagger2(
+      s2({
+        securityDefinitions: {
+          AppFlow: {
+            type: 'oauth2',
+            flow: 'application',
+            tokenUrl: 'https://t',
+            scopes: { write: 'w' },
+          },
+        },
+      }) as never
+    );
+    const ss = (out.components as { securitySchemes: Record<string, Record<string, unknown>> })
+      .securitySchemes;
+    expect((ss.AppFlow.flows as Record<string, unknown>).clientCredentials).toBeDefined();
+  });
+
+  it('passes non-HTTP-method keys in path items through unchanged', () => {
+    const sharedParams = [{ name: 'id', in: 'path', required: true, type: 'integer' }];
+    const out = normalizeSwagger2(
+      s2({
+        paths: {
+          '/pets/{id}': {
+            parameters: sharedParams,
+            get: { operationId: 'getPet', parameters: [], responses: {} },
+          },
+        },
+      }) as never
+    );
+    const item = (out.paths as Record<string, Record<string, unknown>>)['/pets/{id}'];
+    expect(item.parameters).toEqual(sharedParams);
+  });
+});
+
+describe('normalizeSwagger2 — operations', () => {
+  function op(
+    operation: Record<string, unknown>,
+    rootConsumes?: string[],
+    rootProduces?: string[]
+  ) {
+    const out = normalizeSwagger2({
+      swagger: '2.0',
+      info: { title: 'T', version: '1' },
+      ...(rootConsumes ? { consumes: rootConsumes } : {}),
+      ...(rootProduces ? { produces: rootProduces } : {}),
+      paths: { '/x': { post: operation } },
+    } as never);
+    return (out.paths as Record<string, Record<string, Record<string, unknown>>>)['/x'].post;
+  }
+
+  it('wraps a non-body param inline type into `schema`', () => {
+    const post = op({
+      operationId: 'a',
+      parameters: [{ name: 'q', in: 'query', required: true, type: 'string' }],
+      responses: {},
+    });
+    expect((post.parameters as Array<Record<string, unknown>>)[0]).toEqual({
+      name: 'q',
+      in: 'query',
+      required: true,
+      schema: { type: 'string' },
+    });
+  });
+
+  it('converts an in:body param to requestBody using consumes[0]', () => {
+    const post = op({
+      operationId: 'a',
+      consumes: ['application/json'],
+      parameters: [
+        { name: 'b', in: 'body', required: true, schema: { $ref: '#/components/schemas/Pet' } },
+      ],
+      responses: {},
+    });
+    expect(post.requestBody).toEqual({
+      required: true,
+      content: { 'application/json': { schema: { $ref: '#/components/schemas/Pet' } } },
+    });
+    expect((post.parameters as unknown[]).length).toBe(0);
+  });
+
+  it('aggregates in:formData params into a urlencoded object requestBody', () => {
+    const post = op({
+      operationId: 'a',
+      consumes: ['application/x-www-form-urlencoded'],
+      parameters: [
+        { name: 'f1', in: 'formData', required: true, type: 'string' },
+        { name: 'f2', in: 'formData', type: 'integer' },
+      ],
+      responses: {},
+    });
+    expect(post.requestBody).toEqual({
+      required: true,
+      content: {
+        'application/x-www-form-urlencoded': {
+          schema: {
+            type: 'object',
+            required: ['f1'],
+            properties: { f1: { type: 'string' }, f2: { type: 'integer' } },
+          },
+        },
+      },
+    });
+  });
+
+  it('falls back to application/json when consumes is absent (root or op)', () => {
+    const post = op({
+      operationId: 'a',
+      parameters: [{ name: 'b', in: 'body', required: true, schema: { type: 'object' } }],
+      responses: {},
+    });
+    expect(
+      (post.requestBody as { content: Record<string, unknown> }).content['application/json']
+    ).toBeDefined();
+  });
+
+  it('wraps response.schema into content using produces[0] (root fallback)', () => {
+    const post = op(
+      {
+        operationId: 'a',
+        parameters: [],
+        responses: { '200': { description: 'ok', schema: { $ref: '#/components/schemas/Pet' } } },
+      },
+      undefined,
+      ['application/json']
+    );
+    expect(post.responses).toEqual({
+      '200': {
+        description: 'ok',
+        content: { 'application/json': { schema: { $ref: '#/components/schemas/Pet' } } },
+      },
+    });
+  });
+
+  it('leaves a response without a schema untouched (no content)', () => {
+    const post = op({
+      operationId: 'a',
+      parameters: [],
+      responses: { '204': { description: 'no content' } },
+    });
+    expect(post.responses).toEqual({ '204': { description: 'no content' } });
+  });
+
+  it('handles an operation with no responses field', () => {
+    const post = op({ operationId: 'a', parameters: [] });
+    expect(post.responses).toBeUndefined();
+  });
+
+  it('uses multipart/form-data when declared in consumes for formData params', () => {
+    const post = op({
+      operationId: 'a',
+      consumes: ['multipart/form-data'],
+      parameters: [{ name: 'file', in: 'formData', required: true, type: 'string' }],
+      responses: {},
+    });
+    expect(
+      (post.requestBody as { content: Record<string, unknown> }).content['multipart/form-data']
+    ).toBeDefined();
+  });
+
+  it('uses application/x-www-form-urlencoded when consumes is absent for formData params', () => {
+    const post = op({
+      operationId: 'a',
+      parameters: [{ name: 'f1', in: 'formData', type: 'string' }],
+      responses: {},
+    });
+    expect(
+      (post.requestBody as { content: Record<string, unknown> }).content[
+        'application/x-www-form-urlencoded'
+      ]
+    ).toBeDefined();
+  });
+
+  it('handles operation with no parameters field (undefined fallback)', () => {
+    const post = op({ operationId: 'a', responses: {} });
+    expect(post.parameters).toEqual([]);
+  });
+});
+
+describe('normalizeSwagger2 — edge cases', () => {
+  it('handles doc with no paths field (undefined fallback)', () => {
+    const doc = { swagger: '2.0', info: { title: 'T', version: '1' } };
+    const out = normalizeSwagger2(doc as never) as unknown as Record<string, unknown>;
+    expect(out.paths).toEqual({});
+  });
+
+  it('uses https when schemes array is empty', () => {
+    const out = normalizeSwagger2(s2({ schemes: [], host: 'api.example.com' }) as never);
+    expect(out.servers).toEqual([{ url: 'https://api.example.com' }]);
+  });
+
+  it('maps oauth2 with no scopes to empty object', () => {
+    const out = normalizeSwagger2(
+      s2({
+        securityDefinitions: {
+          OAuth: { type: 'oauth2', flow: 'implicit', authorizationUrl: 'https://a' },
+        },
+      }) as never
+    );
+    const ss = (out.components as { securitySchemes: Record<string, Record<string, unknown>> })
+      .securitySchemes;
+    const flows = ss.OAuth.flows as Record<string, Record<string, unknown>>;
+    expect(flows.implicit.scopes).toEqual({});
+  });
+});
diff --git a/packages/client-generator/src/intermediate-representation/__tests__/sanitize-identifiers.test.ts b/packages/client-generator/src/intermediate-representation/__tests__/sanitize-identifiers.test.ts
new file mode 100644
index 0000000000..19c33d3040
--- /dev/null
+++ b/packages/client-generator/src/intermediate-representation/__tests__/sanitize-identifiers.test.ts
@@ -0,0 +1,215 @@
+import type { ApiModel, OperationModel, SchemaModel } from '../model.js';
+import { assertSafeIdentifiers, sanitizeIdentifiers } from '../sanitize-identifiers.js';
+
+function model(schemas: ApiModel['schemas'], operations: OperationModel[] = []): ApiModel {
+  return {
+    title: 'T',
+    version: '1',
+    serverUrl: '',
+    services: [{ name: 'Default', operations }],
+    schemas,
+    securitySchemes: [],
+  };
+}
+
+function op(partial: Partial<OperationModel>): OperationModel {
+  return {
+    name: 'op',
+    method: 'get',
+    path: '/',
+    pathParams: [],
+    queryParams: [],
+    headerParams: [],
+    cookieParams: [],
+    successResponses: [],
+    errorResponses: [],
+    tags: [],
+    security: [],
+    ...partial,
+  };
+}
+
+const ref = (name: string): SchemaModel => ({ kind: 'ref', name });
+
+describe('sanitizeIdentifiers', () => {
+  it('renames a non-identifier schema name and rewrites refs that target it', () => {
+    const m = model([
+      { name: 'Bad.Name', schema: { kind: 'object', properties: [] } },
+      {
+        name: 'Holder',
+        schema: {
+          kind: 'object',
+          properties: [{ name: 'x', schema: ref('Bad.Name'), required: true }],
+        },
+      },
+    ]);
+    sanitizeIdentifiers(m);
+    expect(m.schemas[0].name).toBe('Bad_Name');
+    const holder = m.schemas[1].schema as Extract<SchemaModel, { kind: 'object' }>;
+    expect(holder.properties[0].schema).toEqual(ref('Bad_Name'));
+  });
+
+  it('leaves valid identifier names untouched', () => {
+    const m = model(
+      [{ name: 'Pet', schema: { kind: 'scalar', scalar: 'string' } }],
+      [op({ name: 'getPet' })]
+    );
+    sanitizeIdentifiers(m);
+    expect(m.schemas[0].name).toBe('Pet');
+    expect(m.services[0].operations[0].name).toBe('getPet');
+  });
+
+  it('rewrites refs through array, record, union (with and without discriminator), and intersection', () => {
+    const m = model([
+      { name: 'A.B', schema: { kind: 'object', properties: [] } },
+      { name: 'Arr', schema: { kind: 'array', items: ref('A.B') } },
+      { name: 'Rec', schema: { kind: 'record', value: ref('A.B') } },
+      {
+        name: 'Uni',
+        schema: {
+          kind: 'union',
+          members: [ref('A.B'), { kind: 'scalar', scalar: 'string' }],
+          discriminator: { propertyName: 'k', mapping: [{ value: 'a', schemaName: 'A.B' }] },
+        },
+      },
+      { name: 'Plain', schema: { kind: 'union', members: [ref('A.B'), { kind: 'null' }] } },
+      { name: 'Inter', schema: { kind: 'intersection', members: [ref('A.B')] } },
+    ]);
+    sanitizeIdentifiers(m);
+    expect((m.schemas[1].schema as Extract<SchemaModel, { kind: 'array' }>).items).toEqual(
+      ref('A_B')
+    );
+    expect((m.schemas[2].schema as Extract<SchemaModel, { kind: 'record' }>).value).toEqual(
+      ref('A_B')
+    );
+    const uni = m.schemas[3].schema as Extract<SchemaModel, { kind: 'union' }>;
+    expect(uni.members[0]).toEqual(ref('A_B'));
+    expect(uni.discriminator?.mapping[0].schemaName).toBe('A_B');
+    expect(
+      (m.schemas[5].schema as Extract<SchemaModel, { kind: 'intersection' }>).members[0]
+    ).toEqual(ref('A_B'));
+  });
+
+  it('rewrites an `omit` base that targets a renamed schema', () => {
+    const m = model([
+      { name: 'Bad.Name', schema: { kind: 'object', properties: [] } },
+      { name: 'Body', schema: { kind: 'omit', base: 'Bad.Name', keys: ['id'] } },
+    ]);
+    sanitizeIdentifiers(m);
+    expect((m.schemas[1].schema as Extract<SchemaModel, { kind: 'omit' }>).base).toBe('Bad_Name');
+  });
+
+  it('sanitizes a dangling ref whose target has no declaration', () => {
+    const m = model([{ name: 'Holder', schema: { kind: 'array', items: ref('Un.known') } }]);
+    sanitizeIdentifiers(m);
+    expect((m.schemas[0].schema as Extract<SchemaModel, { kind: 'array' }>).items).toEqual(
+      ref('Un_known')
+    );
+  });
+
+  it('uniquifies schema names that sanitize to the same identifier, refs following each', () => {
+    const m = model([
+      { name: 'A.B', schema: { kind: 'object', properties: [] } },
+      { name: 'A-B', schema: { kind: 'object', properties: [] } },
+      {
+        name: 'Holder',
+        schema: {
+          kind: 'object',
+          properties: [
+            { name: 'x', schema: ref('A.B'), required: true },
+            { name: 'y', schema: ref('A-B'), required: true },
+          ],
+        },
+      },
+    ]);
+    sanitizeIdentifiers(m);
+    expect(m.schemas[0].name).toBe('A_B');
+    expect(m.schemas[1].name).toBe('A_B_2');
+    const holder = m.schemas[2].schema as Extract<SchemaModel, { kind: 'object' }>;
+    expect(holder.properties[0].schema).toEqual(ref('A_B'));
+    expect(holder.properties[1].schema).toEqual(ref('A_B_2'));
+  });
+
+  it('renames a non-identifier security-scheme key and rewrites operation.security to match', () => {
+    const m = model([], [op({ name: 'getX', security: [['k(){};evil', 'clean']] })]);
+    m.securitySchemes = [
+      { kind: 'apiKeyHeader', key: 'k(){};evil', headerName: 'X-Api-Key' },
+      { kind: 'apiKeyHeader', key: 'clean', headerName: 'X-Other' },
+    ];
+    sanitizeIdentifiers(m);
+    expect(m.securitySchemes[0].key).toBe('k_____evil');
+    expect(m.securitySchemes[1].key).toBe('clean');
+    // The operation's security list follows the rename so the runtime literals match.
+    expect(m.services[0].operations[0].security).toEqual([['k_____evil', 'clean']]);
+  });
+
+  it('sanitizes an operation.security entry with no matching scheme', () => {
+    const m = model([], [op({ name: 'getX', security: [['gone.key']] })]);
+    sanitizeIdentifiers(m);
+    expect(m.services[0].operations[0].security).toEqual([['gone_key']]);
+  });
+
+  it('renames operations and rewrites refs in every operation slot', () => {
+    const m = model(
+      [{ name: 'A.B', schema: { kind: 'object', properties: [] } }],
+      [
+        op({
+          name: 'do-thing',
+          pathParams: [{ name: 'id', in: 'path', schema: ref('A.B'), required: true }],
+          queryParams: [{ name: 'q', in: 'query', schema: ref('A.B'), required: false }],
+          headerParams: [{ name: 'h', in: 'header', schema: ref('A.B'), required: false }],
+          requestBody: { contentType: 'application/json', schema: ref('A.B'), required: true },
+          successResponses: [
+            {
+              contentType: 'application/json',
+              schema: ref('A.B'),
+              itemSchema: ref('A.B'),
+              status: 200,
+            },
+          ],
+          errorResponses: [{ contentType: 'application/json', schema: ref('A.B'), status: 200 }],
+        }),
+      ]
+    );
+    sanitizeIdentifiers(m);
+    const o = m.services[0].operations[0];
+    expect(o.name).toBe('do_thing');
+    // The spec operationId survives the rename so user config keys can still match.
+    expect(o.specName).toBe('do-thing');
+    expect(o.pathParams[0].schema).toEqual(ref('A_B'));
+    expect(o.queryParams[0].schema).toEqual(ref('A_B'));
+    expect(o.headerParams[0].schema).toEqual(ref('A_B'));
+    expect(o.requestBody?.schema).toEqual(ref('A_B'));
+    expect(o.successResponses[0].schema).toEqual(ref('A_B'));
+    expect(o.successResponses[0].itemSchema).toEqual(ref('A_B'));
+    expect(o.errorResponses[0].schema).toEqual(ref('A_B'));
+  });
+});
+
+describe('assertSafeIdentifiers', () => {
+  it('passes for a fully sanitized model', () => {
+    const m = model(
+      [{ name: 'Pet', schema: { kind: 'object', properties: [] } }],
+      [op({ name: 'getPet' })]
+    );
+    expect(() => assertSafeIdentifiers(m)).not.toThrow();
+  });
+
+  it('throws when a schema name is not a safe identifier', () => {
+    const m = model([{ name: 'Bad.Name', schema: { kind: 'object', properties: [] } }]);
+    expect(() => assertSafeIdentifiers(m)).toThrow(/schema name .* is not a safe identifier/);
+  });
+
+  it('throws when an operation name is not a safe identifier', () => {
+    const m = model([], [op({ name: 'bad-op' })]);
+    expect(() => assertSafeIdentifiers(m)).toThrow(/operation name .* is not a safe identifier/);
+  });
+
+  it('throws when a security-scheme key is not a safe identifier', () => {
+    const m = model([]);
+    m.securitySchemes = [{ kind: 'apiKeyHeader', key: 'bad.key', headerName: 'X' }];
+    expect(() => assertSafeIdentifiers(m)).toThrow(
+      /security scheme name .* is not a safe identifier/
+    );
+  });
+});
diff --git a/packages/client-generator/src/intermediate-representation/build.ts b/packages/client-generator/src/intermediate-representation/build.ts
new file mode 100644
index 0000000000..190e880231
--- /dev/null
+++ b/packages/client-generator/src/intermediate-representation/build.ts
@@ -0,0 +1,936 @@
+import {
+  isPlainObject,
+  isRef,
+  logger,
+  type Oas3Definition,
+  type Oas3MediaType,
+  type Oas3Operation,
+  type Oas3Parameter,
+  type Oas3PathItem,
+  type Oas3Schema,
+  type Oas3Server,
+  type Oas3_1Schema,
+} from '@redocly/openapi-core';
+
+type Oas3ResponseShape = {
+  content?: Record<string, Oas3MediaType>;
+  description?: string;
+};
+
+import { NotSupportedError } from '../errors.js';
+import type {
+  ApiModel,
+  DiscriminatorModel,
+  NamedSchemaModel,
+  OperationModel,
+  ParamModel,
+  PropertyModel,
+  RequestBodyModel,
+  ResponseBodyModel,
+  ScalarKind,
+  SchemaMetadata,
+  SchemaModel,
+  SecuritySchemeModel,
+  ServiceModel,
+} from './model.js';
+import { assertSafeIdentifiers, sanitizeIdentifiers } from './sanitize-identifiers.js';
+
+type Oas3SecurityScheme = {
+  type?: string;
+  scheme?: string;
+  name?: string;
+  in?: string;
+};
+
+type SecurityRequirement = Record<string, string[]>;
+
+const HTTP_METHODS = ['get', 'post', 'put', 'delete', 'patch', 'head', 'options'] as const;
+type HttpMethod = (typeof HTTP_METHODS)[number];
+
+type Referenced<T> = T | { $ref: string };
+
+function resolveRef<T>(doc: Oas3Definition, ref: string): T {
+  if (!ref.startsWith('#/')) {
+    throw new NotSupportedError(`External $ref not supported: ${ref}`);
+  }
+  const segments = ref
+    .slice(2)
+    .split('/')
+    .map((s) => s.replace(/~1/g, '/').replace(/~0/g, '~'));
+  let current: unknown = doc;
+  for (const segment of segments) {
+    if (!isPlainObject(current) && !Array.isArray(current)) {
+      throw new NotSupportedError(`Cannot resolve $ref: ${ref}`);
+    }
+    current = (current as Record<string, unknown>)[segment];
+  }
+  if (current === undefined) {
+    throw new NotSupportedError(`Cannot resolve $ref: ${ref}`);
+  }
+  return current as T;
+}
+
+function deref<T>(doc: Oas3Definition, value: Referenced<T>): T {
+  if (isRef(value)) {
+    return resolveRef<T>(doc, value.$ref);
+  }
+  return value;
+}
+
+function refName(ref: string): string {
+  const idx = ref.lastIndexOf('/');
+  return idx >= 0 ? ref.slice(idx + 1) : ref;
+}
+
+/**
+ * Lift validation / annotation keywords off an OAS Schema Object into our
+ * neutral SchemaMetadata bag.
+ *
+ * Normalizes OAS 3.0 boolean `exclusiveMinimum` / `exclusiveMaximum` into the
+ * OAS 3.1 numeric form so downstream consumers (the emitter, in particular)
+ * have exactly one shape to handle.
+ *
+ * Returns `undefined` when nothing of interest is present. This keeps the IR
+ * uncluttered: schemas without constraints simply have no `metadata` field at
+ * all rather than an empty object, which also keeps strict-equality tests
+ * stable.
+ */
+function extractMetadata(schema: Oas3Schema): SchemaMetadata | undefined {
+  // We index into the schema with looser typing than the official @redocly types
+  // because OAS 3.1 keywords (numeric `exclusiveMinimum/Maximum`) aren't in the
+  // 3.0-focused type, and `format`/`deprecated` live in a few different places.
+  const s = schema as Record<string, unknown>;
+  const out: SchemaMetadata = {};
+
+  if (typeof s.minimum === 'number') out.minimum = s.minimum;
+  if (typeof s.maximum === 'number') out.maximum = s.maximum;
+
+  // OAS 3.0: exclusiveMinimum/Maximum are booleans paired with minimum/maximum.
+  // OAS 3.1: they are numbers and stand alone.
+  // We always emit the 3.1 numeric form. When the 3.0 boolean form is used,
+  // hoist the paired bound up and drop the inclusive form.
+  if (typeof s.exclusiveMinimum === 'number') {
+    out.exclusiveMinimum = s.exclusiveMinimum;
+  } else if (s.exclusiveMinimum === true && typeof s.minimum === 'number') {
+    out.exclusiveMinimum = s.minimum;
+    delete out.minimum;
+  }
+  if (typeof s.exclusiveMaximum === 'number') {
+    out.exclusiveMaximum = s.exclusiveMaximum;
+  } else if (s.exclusiveMaximum === true && typeof s.maximum === 'number') {
+    out.exclusiveMaximum = s.maximum;
+    delete out.maximum;
+  }
+
+  if (typeof s.minLength === 'number') out.minLength = s.minLength;
+  if (typeof s.maxLength === 'number') out.maxLength = s.maxLength;
+  if (typeof s.pattern === 'string') out.pattern = s.pattern;
+
+  if (typeof s.minItems === 'number') out.minItems = s.minItems;
+  if (typeof s.maxItems === 'number') out.maxItems = s.maxItems;
+  // `uniqueItems` defaults to false; only the affirmative case carries info.
+  if (s.uniqueItems === true) out.uniqueItems = true;
+
+  if (typeof s.format === 'string') out.format = s.format;
+  // Same idea as uniqueItems — explicit `false` is the default; don't emit it.
+  if (s.deprecated === true) out.deprecated = true;
+
+  if (s.example !== undefined) {
+    out.example = s.example;
+  } else if (Array.isArray(s.examples) && s.examples.length > 0) {
+    out.example = s.examples[0];
+  }
+  if (s.default !== undefined) out.default = s.default;
+
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+/**
+ * Build discriminator metadata for a `oneOf` / `anyOf` union, when the schema
+ * declares an explicit `discriminator`. With an explicit `mapping`, each entry
+ * pairs the discriminant value with its target schema name. Without a mapping,
+ * the OpenAPI spec says the discriminant value equals the referenced schema's
+ * name, so we derive entries from the `$ref` members.
+ *
+ * Returns `undefined` when there's no usable discriminator (no `discriminator`
+ * block, or one that yields no named targets) — the emitter then skips guards.
+ */
+function buildDiscriminator(
+  schema: Oas3Schema,
+  members: Array<Referenced<Oas3Schema>>
+): DiscriminatorModel | undefined {
+  const disc = (
+    schema as { discriminator?: { propertyName?: string; mapping?: Record<string, string> } }
+  ).discriminator;
+  if (!disc || typeof disc.propertyName !== 'string') return undefined;
+
+  const mapping: DiscriminatorModel['mapping'] = [];
+  if (disc.mapping) {
+    for (const [value, target] of Object.entries(disc.mapping)) {
+      mapping.push({ value, schemaName: refName(target) });
+    }
+  } else {
+    for (const member of members) {
+      if (isRef(member)) {
+        const name = refName(member.$ref);
+        mapping.push({ value: name, schemaName: name });
+      }
+    }
+  }
+  if (mapping.length === 0) return undefined;
+  return { propertyName: disc.propertyName, mapping };
+}
+
+/** Attach metadata to a freshly-built SchemaModel (no-op when undefined). */
+function withMetadata<T extends SchemaModel>(model: T, metadata: SchemaMetadata | undefined): T {
+  if (!metadata) return model;
+  return { ...model, metadata };
+}
+
+/** Merge two metadata bags; right wins on conflicts. Returns undefined when both are empty. */
+function mergeMetadata(
+  a: SchemaMetadata | undefined,
+  b: SchemaMetadata | undefined
+): SchemaMetadata | undefined {
+  if (!a) return b;
+  if (!b) return a;
+  return { ...a, ...b };
+}
+
+/**
+ * The first server's URL with `{variable}` templates substituted by their declared
+ * defaults (required by the spec). An undeclared variable keeps its placeholder —
+ * there is nothing valid to substitute, and the literal template is easier to spot.
+ */
+function resolveServerUrl(server: Oas3Server | undefined): string {
+  if (!server) return '';
+  return server.url.replace(
+    /\{([^{}]+)\}/g,
+    (template, variableName: string) => server.variables?.[variableName]?.default ?? template
+  );
+}
+
+export function buildApiModel(doc: Oas3Definition): ApiModel {
+  const title = doc.info?.title ?? 'Api';
+  const version = doc.info?.version ?? '0.0.0';
+  const description = doc.info?.description;
+  const serverUrl = resolveServerUrl(doc.servers?.[0]);
+
+  const schemas = buildNamedSchemas(doc);
+  const securitySchemes = buildSecuritySchemes(doc);
+  const services = buildServices(doc, securitySchemes);
+
+  const model: ApiModel = {
+    title,
+    version,
+    description,
+    serverUrl,
+    services,
+    schemas,
+    securitySchemes,
+  };
+  // Sanitize names into safe identifiers (and rewrite refs to match) BEFORE any later
+  // pass derives names from them — `stripReadOnly` builds `omit` targets from schema
+  // names, so it must see the sanitized ones.
+  sanitizeIdentifiers(model);
+  stripReadOnlyFromRequestBodies(services, schemas);
+  // Hard gate: no unsafe name may reach the printer (see sanitize-identifiers.ts).
+  assertSafeIdentifiers(model);
+
+  return model;
+}
+
+/**
+ * Drop `readOnly` (server-managed) properties from every request body, in place.
+ * OpenAPI says readOnly properties must not be sent in requests, so a create/update
+ * body should not demand `id`/`createdAt`/etc. A body that `$ref`s a named schema
+ * becomes `Omit<Name, …readOnly>` (keeping the named type); an inline object has
+ * its readOnly properties filtered out. Response types are untouched.
+ */
+function stripReadOnlyFromRequestBodies(
+  services: ApiModel['services'],
+  schemas: NamedSchemaModel[]
+): void {
+  const byName = new Map(schemas.map((s) => [s.name, s.schema] as const));
+  for (const service of services) {
+    for (const op of service.operations) {
+      if (op.requestBody) op.requestBody.schema = stripReadOnly(op.requestBody.schema, byName);
+    }
+  }
+}
+
+/**
+ * Remove `unknown` members from a union's member list. `T | unknown` is just
+ * `unknown` in TypeScript, so a typeless/empty `oneOf`/`anyOf` branch would erase
+ * the real members. When every member is `unknown`, the union is itself `unknown`.
+ */
+function dropRedundantUnknown(members: SchemaModel[]): SchemaModel[] {
+  const real = members.filter((m) => m.kind !== 'unknown');
+  return real.length > 0 ? real : [{ kind: 'unknown' }];
+}
+
+function stripReadOnly(schema: SchemaModel, byName: Map<string, SchemaModel>): SchemaModel {
+  if (schema.kind === 'ref') {
+    const keys = collectReadOnlyKeys(schema, byName, new Set());
+    return keys.length > 0 ? { kind: 'omit', base: schema.name, keys } : schema;
+  }
+  if (schema.kind === 'object') {
+    const kept = schema.properties.filter((p) => !p.readOnly);
+    return kept.length === schema.properties.length ? schema : { ...schema, properties: kept };
+  }
+  return schema;
+}
+
+/**
+ * The readOnly top-level property names of a schema, descending through `$ref`s
+ * and `allOf` (intersection) members — the shape entity schemas compose with. A
+ * `visited` set guards against recursive refs. Order-preserving and deduped.
+ */
+function collectReadOnlyKeys(
+  schema: SchemaModel,
+  byName: Map<string, SchemaModel>,
+  visited: Set<string>
+): string[] {
+  const keys: string[] = [];
+  const visit = (s: SchemaModel): void => {
+    if (s.kind === 'ref') {
+      if (visited.has(s.name)) return;
+      visited.add(s.name);
+      const target = byName.get(s.name);
+      if (target) visit(target);
+    } else if (s.kind === 'object') {
+      for (const p of s.properties) if (p.readOnly && !keys.includes(p.name)) keys.push(p.name);
+    } else if (s.kind === 'intersection') {
+      for (const member of s.members) visit(member);
+    }
+  };
+  visit(schema);
+  return keys;
+}
+
+/**
+ * Collect the security schemes the client can apply on the wire, keyed by their
+ * `components.securitySchemes` name. Bearer (`http`+`bearer`/oauth2/openIdConnect),
+ * HTTP Basic, and apiKey in header/query/cookie are all injectable. `mutualTLS`
+ * (and an `http` scheme that is neither bearer nor basic) is skipped — operations
+ * that reference only those will simply carry no auth.
+ */
+function buildSecuritySchemes(doc: Oas3Definition): SecuritySchemeModel[] {
+  const schemes = doc.components?.securitySchemes;
+  if (!schemes) return [];
+
+  const result: SecuritySchemeModel[] = [];
+  for (const [key, raw] of Object.entries(schemes)) {
+    const scheme = deref<Oas3SecurityScheme>(doc, raw as Referenced<Oas3SecurityScheme>);
+    const type = scheme.type;
+    if (type === 'oauth2' || type === 'openIdConnect') {
+      result.push({ kind: 'bearer', key });
+    } else if (type === 'http' && (scheme.scheme ?? '').toLowerCase() === 'bearer') {
+      result.push({ kind: 'bearer', key });
+    } else if (type === 'http' && (scheme.scheme ?? '').toLowerCase() === 'basic') {
+      result.push({ kind: 'basic', key });
+    } else if (type === 'apiKey' && scheme.in === 'header' && typeof scheme.name === 'string') {
+      result.push({ kind: 'apiKeyHeader', key, headerName: scheme.name });
+    } else if (type === 'apiKey' && scheme.in === 'query' && typeof scheme.name === 'string') {
+      result.push({ kind: 'apiKeyQuery', key, paramName: scheme.name });
+    } else if (type === 'apiKey' && scheme.in === 'cookie' && typeof scheme.name === 'string') {
+      // Injected via the Cookie request header, which browsers refuse to set —
+      // the credential silently goes missing there, so tell the user up front.
+      logger.warn(
+        `generate-client: security scheme "${key}" sends its credential in the Cookie header, ` +
+          `which browsers ignore — cookie auth works only in server-side clients.\n`
+      );
+      result.push({ kind: 'apiKeyCookie', key, cookieName: scheme.name });
+    }
+    // Everything else (http schemes other than bearer/basic, mutualTLS) is not
+    // injectable by the generated client — intentionally skipped.
+  }
+  return result;
+}
+
+/**
+ * Resolve the effective security for one operation into the list of injectable
+ * OR-alternatives, each an AND-set of scheme keys. The operation's own `security`
+ * overrides the document default; `security: []` opts out entirely.
+ *
+ * Every fully-injectable alternative is kept — the runtime applies exactly ONE of
+ * them (the first whose credentials are all configured), so an operation that
+ * accepts "bearer OR apiKey" works with either credential and never sends both.
+ * `{}` (the optional-auth marker) and alternatives with non-injectable schemes
+ * are skipped; an empty result means no auth is applied.
+ */
+function resolveOperationSecurity(
+  operation: Oas3Operation,
+  doc: Oas3Definition,
+  injectable: Set<string>
+): string[][] {
+  const requirements =
+    (operation as { security?: SecurityRequirement[] }).security ??
+    (doc as { security?: SecurityRequirement[] }).security;
+  if (!requirements) return [];
+
+  const alternatives: string[][] = [];
+  for (const requirement of requirements) {
+    const keys = Object.keys(requirement);
+    if (keys.length === 0) continue;
+    if (keys.every((key) => injectable.has(key))) {
+      alternatives.push([...new Set(keys)]);
+    }
+  }
+  return alternatives;
+}
+
+function buildNamedSchemas(doc: Oas3Definition): NamedSchemaModel[] {
+  const namedSchemas = doc.components?.schemas;
+  if (!namedSchemas) return [];
+
+  return Object.entries(namedSchemas).map(([name, schema]) => {
+    if (isRef(schema)) {
+      // A top-level entry that is a $ref forwards to another component.
+      const target = resolveRef<Oas3Schema>(doc, schema.$ref);
+      return {
+        name,
+        schema: buildSchema(target, `components.schemas.${name}`, doc),
+        description: target.description,
+      };
+    }
+    const built = buildSchema(schema as Oas3Schema, `components.schemas.${name}`, doc);
+    return { name, schema: built, description: schema.description };
+  });
+}
+
+function buildServices(
+  doc: Oas3Definition,
+  securitySchemes: SecuritySchemeModel[]
+): ServiceModel[] {
+  const injectable = new Set(securitySchemes.map((s) => s.key));
+
+  type Entry = {
+    method: HttpMethod;
+    path: string;
+    operation: Oas3Operation;
+    pathLevelParams: ParamModel[];
+  };
+  const entries: Entry[] = [];
+  const usedNames = new Set<string>();
+  for (const [path, pathItemRaw] of Object.entries(doc.paths ?? {})) {
+    if (!pathItemRaw) continue;
+    const pathItem = deref<Oas3PathItem>(doc, pathItemRaw);
+
+    const pathLevelParams = (pathItem.parameters ?? []).map((p) =>
+      buildParameter(deref<Oas3Parameter>(doc, p), `paths.${path}.parameters`, doc)
+    );
+
+    for (const method of HTTP_METHODS) {
+      const operation = (pathItem as Oas3PathItem)[method];
+      if (!operation) continue;
+      entries.push({ method, path, operation, pathLevelParams });
+      // Reserve every declared operationId up front so a synthesized fallback name
+      // never collides with one — declared ids always win.
+      if (operation.operationId) usedNames.add(operation.operationId);
+    }
+  }
+
+  const operations = entries.map((entry) => {
+    const name =
+      entry.operation.operationId ??
+      takeUniqueName(fallbackOperationName(entry.method, entry.path), usedNames);
+    return buildOperation(
+      entry.method,
+      entry.path,
+      entry.operation,
+      name,
+      entry.pathLevelParams,
+      doc,
+      injectable
+    );
+  });
+  return [{ name: 'Default', operations }];
+}
+
+/**
+ * Synthesize an operation name from method + path when the spec omits `operationId`:
+ * `<method><PascalCasedPathSegments>` (braces stripped; each segment split on
+ * non-identifier chars). Path-param segments are kept so a collection (`GET /pets`)
+ * and an item (`GET /pets/{id}`) stay distinct. Always a valid identifier — the
+ * lowercase `method` prefix guarantees a letter start.
+ */
+function fallbackOperationName(method: string, path: string): string {
+  const segments = path
+    .split('/')
+    .filter(Boolean)
+    .map((segment) => pascalSegment(segment.replace(/[{}]/g, '')));
+  return `${method}${segments.join('')}`;
+}
+
+function pascalSegment(segment: string): string {
+  return segment
+    .split(/[^A-Za-z0-9]+/)
+    .filter(Boolean)
+    .map((word) => word[0].toUpperCase() + word.slice(1))
+    .join('');
+}
+
+/** Return `base`, or `base2`/`base3`/… if already taken; records the result in `used`. */
+function takeUniqueName(base: string, used: Set<string>): string {
+  let name = base;
+  let suffix = 2;
+  while (used.has(name)) name = `${base}${suffix++}`;
+  used.add(name);
+  return name;
+}
+
+function buildOperation(
+  method: HttpMethod,
+  path: string,
+  operation: Oas3Operation,
+  name: string,
+  pathLevelParams: ParamModel[],
+  doc: Oas3Definition,
+  injectable: Set<string>
+): OperationModel {
+  const operationParams = (operation.parameters ?? []).map((p) =>
+    buildParameter(deref<Oas3Parameter>(doc, p), `paths.${path}.${method}.parameters`, doc)
+  );
+
+  // Operation-level parameters override path-level ones (by name + in).
+  const seen = new Set<string>();
+  const allParams: ParamModel[] = [];
+  for (const p of operationParams) {
+    seen.add(`${p.in}:${p.name}`);
+    allParams.push(p);
+  }
+  for (const p of pathLevelParams) {
+    if (!seen.has(`${p.in}:${p.name}`)) {
+      allParams.push(p);
+    }
+  }
+
+  const pathParams = allParams.filter((p) => p.in === 'path');
+  const queryParams = allParams.filter((p) => p.in === 'query');
+  const headerParams = allParams.filter((p) => p.in === 'header');
+  // Serialized into the `Cookie` header by the runtime — server-side only, since
+  // browsers own that header (same caveat as cookie-borne apiKey auth).
+  const cookieParams = allParams.filter((p) => p.in === 'cookie');
+
+  const requestBody = operation.requestBody
+    ? buildRequestBody(deref(doc, operation.requestBody), `${method} ${path}`, doc)
+    : undefined;
+
+  const successResponses = buildSuccessResponses(operation, path, doc);
+  const errorResponses = buildErrorResponses(operation, path, doc);
+  const security = resolveOperationSecurity(operation, doc, injectable);
+
+  // Extensions aren't in the @redocly operation type — read loosely, like `deprecated`.
+  const paginationExtension = (operation as unknown as Record<string, unknown>)['x-pagination'];
+
+  return {
+    name,
+    method,
+    path,
+    summary: operation.summary,
+    description: operation.description,
+    pathParams,
+    queryParams,
+    headerParams,
+    cookieParams,
+    requestBody,
+    successResponses,
+    errorResponses,
+    security,
+    tags: Array.isArray(operation.tags) ? operation.tags.filter((t) => typeof t === 'string') : [],
+    ...(paginationExtension !== undefined ? { paginationExtension } : {}),
+  };
+}
+
+function buildParameter(param: Oas3Parameter, location: string, doc: Oas3Definition): ParamModel {
+  if (!param.in) {
+    throw new NotSupportedError(`Parameter ${param.name} at ${location} is missing "in"`);
+  }
+  if (!['path', 'query', 'header', 'cookie'].includes(param.in)) {
+    throw new NotSupportedError(
+      `Unsupported parameter location "${param.in}" for ${param.name} at ${location}`
+    );
+  }
+  let schema = schemaFromSlot(param.schema, `${location}.${param.name}`, doc);
+
+  // OpenAPI lets `deprecated: true` live on the Parameter Object itself, not
+  // just on its schema. Fold it into the schema's metadata so the emitter has
+  // a single source of truth when rendering tags around this param.
+  if ((param as { deprecated?: boolean }).deprecated === true) {
+    schema = {
+      ...schema,
+      metadata: mergeMetadata(schema.metadata, { deprecated: true }),
+    };
+  }
+
+  const model: ParamModel = {
+    name: param.name,
+    in: param.in as ParamModel['in'],
+    schema,
+    required: Boolean(param.required),
+    description: param.description,
+  };
+
+  // Query-serialization hints (OpenAPI `style`/`explode`/`allowReserved`) live on the
+  // Parameter Object and aren't in the @redocly types — read them loosely, like
+  // `deprecated`. Only set them for query params, and only when present (absence ⇒
+  // the defaults, so the IR stays clean and downstream takes the default path).
+  if (model.in === 'query') {
+    const p = param as { style?: string; explode?: boolean; allowReserved?: boolean };
+    if (
+      p.style === 'form' ||
+      p.style === 'spaceDelimited' ||
+      p.style === 'pipeDelimited' ||
+      p.style === 'deepObject'
+    ) {
+      model.style = p.style;
+    }
+    if (typeof p.explode === 'boolean') model.explode = p.explode;
+    if (typeof p.allowReserved === 'boolean') model.allowReserved = p.allowReserved;
+  }
+
+  return model;
+}
+
+function buildRequestBody(
+  rb: { content?: Record<string, Oas3MediaType>; required?: boolean; description?: string },
+  location: string,
+  doc: Oas3Definition
+): RequestBodyModel | undefined {
+  const content = rb.content ?? {};
+  // Prefer JSON; fall back to first available.
+  const preferred =
+    content['application/json'] ??
+    content['application/merge-patch+json'] ??
+    content['application/x-www-form-urlencoded'] ??
+    content['multipart/form-data'] ??
+    Object.values(content)[0];
+  if (!preferred) return undefined;
+  // `preferred` is one of the values we sampled out of `content`, so its key must exist there.
+  const contentType = Object.keys(content).find((k) => content[k] === preferred)!;
+
+  const schema = schemaFromSlot(preferred.schema, `${location}.requestBody`, doc);
+  return {
+    contentType,
+    schema,
+    required: Boolean(rb.required),
+    description: rb.description,
+  };
+}
+
+function buildSuccessResponses(
+  operation: Oas3Operation,
+  path: string,
+  doc: Oas3Definition
+): ResponseBodyModel[] {
+  const responses = operation.responses ?? {};
+  const successCodes = Object.keys(responses).filter((code) => /^2\d\d$/.test(code));
+  if (successCodes.length === 0) {
+    if (responses['default']) successCodes.push('default');
+  }
+  // Pick the first success response.
+  const code = successCodes[0];
+  if (!code) return [];
+  const responseRaw = responses[code];
+  if (!responseRaw) return [];
+  const response = deref<Oas3ResponseShape>(doc, responseRaw);
+  const content = response.content;
+  if (!content) return [];
+
+  const status = code === 'default' ? 'default' : Number(code);
+  const result: ResponseBodyModel[] = [];
+  for (const [contentType, media] of Object.entries(content)) {
+    const schema = schemaFromSlot(
+      media.schema,
+      `paths.${path}.response.${code}.${contentType}`,
+      doc
+    );
+    const itemSlot = media.itemSchema;
+    const item =
+      itemSlot !== undefined
+        ? schemaFromSlot(itemSlot, `paths.${path}.response.${code}.${contentType}.itemSchema`, doc)
+        : undefined;
+    result.push(
+      item === undefined
+        ? { contentType, schema, status }
+        : { contentType, schema, status, itemSchema: item }
+    );
+  }
+  return result;
+}
+
+function buildErrorResponses(
+  operation: Oas3Operation,
+  path: string,
+  doc: Oas3Definition
+): ResponseBodyModel[] {
+  const responses = operation.responses ?? {};
+  const codes = Object.keys(responses).filter((code) => /^[45]\d\d$/.test(code));
+  // `default` is an error only when a 2xx success exists; otherwise
+  // `buildSuccessResponses` already consumes it as the success response.
+  const hasSuccess = Object.keys(responses).some((code) => /^2\d\d$/.test(code));
+  if (hasSuccess && responses['default']) codes.push('default');
+
+  const result: ResponseBodyModel[] = [];
+  for (const code of codes) {
+    const responseRaw = responses[code];
+    if (!responseRaw) continue;
+    const response = deref<Oas3ResponseShape>(doc, responseRaw);
+    const content = response.content;
+    if (!content) continue;
+    const status = code === 'default' ? 'default' : Number(code);
+    for (const [contentType, media] of Object.entries(content)) {
+      const schema = schemaFromSlot(
+        media.schema,
+        `paths.${path}.response.${code}.${contentType}`,
+        doc
+      );
+      result.push({ contentType, schema, status });
+    }
+  }
+  return result;
+}
+
+/**
+ * Decode a "schema slot" — the referenced-or-inline-or-absent schema position
+ * that recurs all over an OpenAPI document (`parameter.schema`, `media.schema`,
+ * property values, array `items`, `additionalProperties`) — into a SchemaModel.
+ *
+ * - absent (`undefined`) or a boolean JSON-Schema → `unknown` (we don't model
+ *   boolean schemas; this collapses the "missing schema" fallbacks too).
+ * - a `$ref` → a `ref` node carrying the target's local name (the IR keeps
+ *   refs un-resolved so named schemas map back to exported types).
+ * - an inline schema → recurse via `buildSchema`.
+ */
+function schemaFromSlot(
+  slot: Referenced<Oas3Schema | Oas3_1Schema> | boolean | undefined,
+  location: string,
+  doc: Oas3Definition
+): SchemaModel {
+  if (slot === undefined || typeof slot === 'boolean') return { kind: 'unknown' };
+  if (isRef(slot)) return { kind: 'ref', name: refName(slot.$ref) };
+  return buildSchema(slot as Oas3Schema, location, doc);
+}
+
+function buildSchema(schema: Oas3Schema, location: string, doc: Oas3Definition): SchemaModel {
+  // Note: every caller checks `isRef(schema)` before invoking this function, so a top-level
+  // `{$ref: ...}` never reaches here — see `buildNamedSchemas`, `buildParameter`, etc.
+  const metadata = extractMetadata(schema);
+
+  const oneOfish = schema.oneOf ?? schema.anyOf;
+  if (oneOfish) {
+    const allMembers = oneOfish.map((sub, idx) =>
+      isRef(sub)
+        ? ({ kind: 'ref', name: refName(sub.$ref) } as SchemaModel)
+        : buildSchema(sub as Oas3Schema, `${location}.[${idx}]`, doc)
+    );
+    // Drop `unknown` members (typeless/empty branches): `T | unknown` collapses to
+    // `unknown` in TS, erasing the real members. When only one real member remains,
+    // the union degenerates to it.
+    const members = dropRedundantUnknown(allMembers);
+    // Collapse to the lone member only when dropping `unknown` branches reduced the
+    // union to one — an originally single-member union is left as-is.
+    if (members.length === 1 && members.length < allMembers.length) {
+      const inner = members[0];
+      return {
+        ...inner,
+        description: inner.description ?? schema.description,
+        metadata: mergeMetadata(metadata, inner.metadata),
+      };
+    }
+    const discriminator = buildDiscriminator(schema, oneOfish);
+    return withMetadata(
+      { kind: 'union', members, discriminator, description: schema.description },
+      metadata
+    );
+  }
+
+  if (schema.allOf) {
+    const members = schema.allOf.map((sub, idx) =>
+      isRef(sub)
+        ? ({ kind: 'ref', name: refName(sub.$ref) } as SchemaModel)
+        : buildSchema(sub as Oas3Schema, `${location}.allOf[${idx}]`, doc)
+    );
+    // `allOf` does not replace sibling `properties`: a schema may declare its own
+    // object shape (often a `const` discriminant) alongside `allOf`. Fold that own
+    // object into the intersection so those properties aren't dropped.
+    const ownProperties = buildProperties(schema, location, doc);
+    if (ownProperties.length > 0) {
+      members.unshift({ kind: 'object', properties: ownProperties });
+    }
+    if (members.length === 1) {
+      // Single-member allOf collapses to its target. Preserve the wrapper's
+      // description/metadata only when the inner doesn't already have them.
+      const inner = members[0];
+      return {
+        ...inner,
+        description: inner.description ?? schema.description,
+        metadata: mergeMetadata(metadata, inner.metadata),
+      };
+    }
+    return withMetadata(
+      { kind: 'intersection', members, description: schema.description },
+      metadata
+    );
+  }
+
+  // OpenAPI 3.1 style nullable: `type: ['string', 'null']`.
+  const rawType = (schema as { type?: string | string[] }).type;
+  if (Array.isArray(rawType)) {
+    const nonNull = rawType.filter((t) => t !== 'null');
+    const hasNull = rawType.includes('null');
+    const baseMembers = nonNull.map((t) => {
+      // Strip `null` out of any `enum` before recursing: the array-type null is
+      // the single source of nullability here, so the enum branch must not add a
+      // second `null` member (and an enum of only `null` would otherwise throw).
+      const sub = { ...schema, type: t } as Oas3Schema & { enum?: unknown[] };
+      if (Array.isArray(sub.enum)) {
+        const filtered = sub.enum.filter((v) => v !== null);
+        sub.enum = filtered.length > 0 ? filtered : undefined;
+      }
+      return buildSchema(sub as Oas3Schema, location, doc);
+    });
+    if (hasNull) baseMembers.push({ kind: 'null' });
+    if (baseMembers.length === 1) {
+      return baseMembers[0];
+    }
+    return withMetadata(
+      { kind: 'union', members: baseMembers, description: schema.description },
+      metadata
+    );
+  }
+
+  // OpenAPI 3.0 nullable.
+  if ((schema as { nullable?: boolean }).nullable) {
+    const base = buildSchema(
+      { ...(schema as object), nullable: undefined } as Oas3Schema,
+      location,
+      doc
+    );
+    return {
+      kind: 'union',
+      members: [base, { kind: 'null' }],
+      description: schema.description,
+    };
+  }
+
+  if ((schema as { const?: unknown }).const !== undefined) {
+    const value = (schema as { const: unknown }).const;
+    if (typeof value !== 'string' && typeof value !== 'number' && typeof value !== 'boolean') {
+      throw new NotSupportedError(
+        `Unsupported const value at ${location}: ${JSON.stringify(value)}`
+      );
+    }
+    return withMetadata({ kind: 'literal', value, description: schema.description }, metadata);
+  }
+
+  if (schema.enum) {
+    // OAS 3.1 allows `null` among enum values. Model it as `<enum> | null` and
+    // keep the enum itself null-free so scalar inference stays simple.
+    const rawValues = schema.enum as unknown[];
+    const nonNullValues = rawValues.filter((v) => v !== null) as Array<string | number | boolean>;
+    const enumHasNull = nonNullValues.length !== rawValues.length;
+    if (nonNullValues.length === 0) {
+      return withMetadata({ kind: 'null', description: schema.description }, metadata);
+    }
+    const scalar = scalarForEnumValues(nonNullValues, location);
+    // A boolean `enum` conveys no useful narrowing: `[true, false]` is just `boolean`, and a
+    // single-value `[false]`/`[true]` is a spec quirk, not an intended literal type. Widen to
+    // `boolean` so a normal boolean field never becomes a literal. (`const: false` stays a
+    // literal — that's an explicit, deliberate single-value constraint, handled above.)
+    const base: SchemaModel =
+      scalar === 'boolean'
+        ? { kind: 'scalar', scalar: 'boolean', description: schema.description }
+        : { kind: 'enum', values: nonNullValues, scalar, description: schema.description };
+    if (enumHasNull) {
+      return withMetadata(
+        { kind: 'union', members: [base, { kind: 'null' }], description: schema.description },
+        metadata
+      );
+    }
+    return withMetadata(base, metadata);
+  }
+
+  const type = rawType;
+
+  if (type === 'null') {
+    // OAS 3.1 single null type — a value that is always `null` (e.g. a field a
+    // variant pins to null). Without this it would fall through to `unknown`.
+    return withMetadata({ kind: 'null', description: schema.description }, metadata);
+  }
+
+  if (type === 'array') {
+    const itemsRaw = (schema as { items?: Referenced<Oas3Schema> | boolean }).items;
+    const items = schemaFromSlot(itemsRaw, `${location}.items`, doc);
+    return withMetadata({ kind: 'array', items, description: schema.description }, metadata);
+  }
+
+  if (type === 'object' || schema.properties || schema.additionalProperties) {
+    const properties = buildProperties(schema, location, doc);
+    const additional = (
+      schema as { additionalProperties?: boolean | Oas3Schema | { $ref: string } }
+    ).additionalProperties;
+
+    if (properties.length === 0 && additional !== false) {
+      // A property-less object accepts arbitrary keys: OpenAPI defaults absent
+      // `additionalProperties` to allowed. Emit a record — of the declared
+      // additionalProperties schema, or `unknown` when it's absent/`true` — rather
+      // than `{}`, which in TS forbids member access. An explicit
+      // `additionalProperties: false` is closed and stays an empty object.
+      const value = schemaFromSlot(additional, `${location}.additionalProperties`, doc);
+      return withMetadata({ kind: 'record', value, description: schema.description }, metadata);
+    }
+
+    return withMetadata({ kind: 'object', properties, description: schema.description }, metadata);
+  }
+
+  if (type === 'string' || type === 'number' || type === 'integer' || type === 'boolean') {
+    return withMetadata(
+      { kind: 'scalar', scalar: type, description: schema.description },
+      metadata
+    );
+  }
+
+  // No usable type information — fall back to `unknown` instead of erroring,
+  // so generation still succeeds for sparsely-typed schemas.
+  return withMetadata({ kind: 'unknown', description: schema.description }, metadata);
+}
+
+function scalarForEnumValues(values: unknown[], location: string): ScalarKind {
+  let hasStr = false;
+  let hasNum = false;
+  let hasBool = false;
+  for (const v of values) {
+    if (typeof v === 'string') hasStr = true;
+    else if (typeof v === 'number') hasNum = true;
+    else if (typeof v === 'boolean') hasBool = true;
+    else
+      throw new NotSupportedError(
+        `Unsupported enum value type at ${location}: ${JSON.stringify(v)}`
+      );
+  }
+  if (hasStr && !hasNum && !hasBool) return 'string';
+  if (hasNum && !hasStr && !hasBool) return 'number';
+  if (hasBool && !hasStr && !hasNum) return 'boolean';
+  return 'string';
+}
+
+function buildProperties(
+  schema: Oas3Schema,
+  location: string,
+  doc: Oas3Definition
+): PropertyModel[] {
+  const props = schema.properties ?? {};
+  const required = new Set(schema.required ?? []);
+  return Object.entries(props).map(([name, sub]) => {
+    const readOnly = !isRef(sub) && (sub as { readOnly?: boolean }).readOnly === true;
+    return {
+      name,
+      schema: schemaFromSlot(sub, `${location}.${name}`, doc),
+      required: required.has(name),
+      description: (sub as { description?: string }).description,
+      ...(readOnly ? { readOnly: true } : {}),
+    };
+  });
+}
diff --git a/packages/client-generator/src/intermediate-representation/model.ts b/packages/client-generator/src/intermediate-representation/model.ts
new file mode 100644
index 0000000000..922bfa5153
--- /dev/null
+++ b/packages/client-generator/src/intermediate-representation/model.ts
@@ -0,0 +1,248 @@
+export type ScalarKind = 'string' | 'number' | 'boolean' | 'integer';
+
+/**
+ * Validation / annotation metadata pulled straight from an OpenAPI Schema Object.
+ *
+ * The renderer projects these into JSDoc tags (`@minimum 1`, `@pattern ...`, …).
+ * We deliberately do NOT enforce which keys are valid on which kind (e.g.
+ * `minLength` on a number is technically nonsense) — the spec is authoritative
+ * and the renderer just emits whatever is set. This keeps the IR cheap and lets
+ * us add new tags without ratcheting the type system.
+ *
+ * `exclusiveMinimum` / `exclusiveMaximum` are always normalized to the OAS 3.1
+ * numeric form by the builder, even when the source uses the OAS 3.0 boolean
+ * form. This means the emitter has exactly one shape to handle.
+ */
+export type SchemaMetadata = {
+  minimum?: number;
+  maximum?: number;
+  exclusiveMinimum?: number;
+  exclusiveMaximum?: number;
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  minItems?: number;
+  maxItems?: number;
+  uniqueItems?: boolean;
+  format?: string;
+  deprecated?: boolean;
+  /** A representative value for the schema, used by the mock sampler. From the
+   * source `example` field, or the first entry of `examples` (OAS 3.1 array form). */
+  example?: unknown;
+  /** The schema's `default` value, used as a sampler fallback when no example exists. */
+  default?: unknown;
+};
+
+/**
+ * Discriminator metadata for a union, used to emit `is<Member>()` type guards.
+ *
+ * `propertyName` is the discriminating property. Each `mapping` entry pairs the
+ * discriminant string `value` with the `schemaName` (a named, top-level schema)
+ * that value selects. We only retain entries that point at named schemas, since
+ * a guard must narrow to an exported type.
+ *
+ * The builder fills this from an explicit `discriminator` (with or without an
+ * explicit `mapping`); the emitter may additionally synthesize one for an
+ * *implicit* discriminator (every member constrains a shared property to a
+ * distinct `const`).
+ */
+export type DiscriminatorModel = {
+  propertyName: string;
+  mapping: Array<{ value: string; schemaName: string }>;
+};
+
+export type SchemaModel =
+  | { kind: 'scalar'; scalar: ScalarKind; description?: string; metadata?: SchemaMetadata }
+  | { kind: 'array'; items: SchemaModel; description?: string; metadata?: SchemaMetadata }
+  | { kind: 'object'; properties: PropertyModel[]; description?: string; metadata?: SchemaMetadata }
+  | { kind: 'record'; value: SchemaModel; description?: string; metadata?: SchemaMetadata }
+  | { kind: 'ref'; name: string; description?: string; metadata?: SchemaMetadata }
+  | {
+      kind: 'literal';
+      value: string | number | boolean;
+      description?: string;
+      metadata?: SchemaMetadata;
+    }
+  | {
+      kind: 'enum';
+      values: Array<string | number | boolean>;
+      scalar: ScalarKind;
+      description?: string;
+      metadata?: SchemaMetadata;
+    }
+  | {
+      kind: 'union';
+      members: SchemaModel[];
+      discriminator?: DiscriminatorModel;
+      description?: string;
+      metadata?: SchemaMetadata;
+    }
+  | {
+      kind: 'intersection';
+      members: SchemaModel[];
+      description?: string;
+      metadata?: SchemaMetadata;
+    }
+  | { kind: 'null'; description?: string; metadata?: SchemaMetadata }
+  | { kind: 'unknown'; description?: string; metadata?: SchemaMetadata }
+  /**
+   * `Omit<base, "k1" | "k2">` — a named schema with some keys removed. Built only
+   * for request bodies, where `readOnly` (server-managed) properties must not be
+   * sent. `base` is a named schema (an emitted type); `keys` are the readOnly
+   * property names dropped from it.
+   */
+  | {
+      kind: 'omit';
+      base: string;
+      keys: string[];
+      description?: string;
+      metadata?: SchemaMetadata;
+    };
+
+export type PropertyModel = {
+  name: string;
+  schema: SchemaModel;
+  required: boolean;
+  description?: string;
+  /** `readOnly: true` in the spec — server-managed; dropped from request bodies. */
+  readOnly?: boolean;
+};
+
+export type ParamModel = {
+  name: string;
+  in: 'path' | 'query' | 'header' | 'cookie';
+  schema: SchemaModel;
+  required: boolean;
+  description?: string;
+  /**
+   * OpenAPI query-serialization hints, only meaningful for query params (path/header
+   * params ignore them). Absent ⇒ the OpenAPI defaults (`form`, `explode: true`); the
+   * builder leaves them `undefined` rather than synthesizing defaults, so downstream
+   * takes the default serialization path.
+   */
+  style?: 'form' | 'spaceDelimited' | 'pipeDelimited' | 'deepObject';
+  explode?: boolean;
+  allowReserved?: boolean;
+};
+
+export type RequestBodyModel = {
+  contentType: string;
+  schema: SchemaModel;
+  required: boolean;
+  description?: string;
+};
+
+export type ResponseBodyModel = {
+  contentType: string;
+  schema: SchemaModel;
+  /**
+   * The HTTP status code this response body is declared under (`200`, `404`, …),
+   * or `'default'` for the OpenAPI `default` response.
+   */
+  status: number | 'default';
+  /**
+   * The per-item payload schema for a streaming/sequential media type (OpenAPI
+   * 3.2 `itemSchema`, e.g. on `text/event-stream`). Absent for ordinary bodies.
+   */
+  itemSchema?: SchemaModel;
+};
+
+/**
+ * A security scheme the generated client knows how to apply. Only the schemes
+ * we can actually inject on the wire are modeled:
+ *
+ * - `bearer` — `http`+`bearer`, `oauth2`, or `openIdConnect`. All of these end
+ *   up as an `Authorization: Bearer <token>` header, so they share one
+ *   `setBearer()` setter and one token slot.
+ * - `basic` — `http`+`basic`. Injected as an `Authorization: Basic <base64>`
+ *   header via the shared `setBasicAuth()` setter.
+ * - `apiKeyHeader` — `apiKey` in `header`. Each gets its own setter + slot keyed
+ *   by `key`, and injects its own `headerName`.
+ * - `apiKeyQuery` — `apiKey` in `query`. Injected as a URL query parameter named
+ *   `paramName`.
+ * - `apiKeyCookie` — `apiKey` in `cookie`. Injected into a combined `Cookie`
+ *   header under `cookieName`.
+ *
+ * `mutualTLS` (and an `http` scheme other than bearer/basic) is not injectable
+ * by the client and is skipped by the builder; an operation referencing only
+ * such schemes simply carries no auth.
+ */
+export type SecuritySchemeModel =
+  | { kind: 'bearer'; key: string }
+  | { kind: 'basic'; key: string }
+  | { kind: 'apiKeyHeader'; key: string; headerName: string }
+  | { kind: 'apiKeyQuery'; key: string; paramName: string }
+  | { kind: 'apiKeyCookie'; key: string; cookieName: string };
+
+export type OperationModel = {
+  name: string;
+  /**
+   * The spec's operationId when `name` was rewritten by identifier sanitization.
+   * User-facing config (pagination `exclude`/`operations` keys) matches this.
+   */
+  specName?: string;
+  method: 'get' | 'post' | 'put' | 'delete' | 'patch' | 'head' | 'options';
+  path: string;
+  summary?: string;
+  description?: string;
+  pathParams: ParamModel[];
+  queryParams: ParamModel[];
+  headerParams: ParamModel[];
+  /** Serialized into the `Cookie` header by the runtime — server-side only (browsers own that header). */
+  cookieParams: ParamModel[];
+  requestBody?: RequestBodyModel;
+  successResponses: ResponseBodyModel[];
+  /**
+   * The operation's declared error responses (4xx/5xx, plus `default` when a 2xx
+   * success also exists). Empty when none are declared. Consumed only by
+   * `errorMode: 'result'` output, where they type the `error` of the result shape.
+   */
+  errorResponses: ResponseBodyModel[];
+  /**
+   * The operation's OpenAPI `tags`, in declared order (empty when none). Used by
+   * multi-file output modes to group operations into per-tag files; ignored by
+   * the default single-file output.
+   */
+  tags: string[];
+  /**
+   * Effective security for this operation: the injectable OR-alternatives, each
+   * an AND-set of security-scheme keys (resolving the operation's own `security`
+   * over the document default). The runtime applies the first alternative whose
+   * credentials are all configured. An empty array means "send no credentials" —
+   * either the operation opted out via `security: []` or no applicable scheme exists.
+   */
+  security: string[][];
+  /**
+   * The operation's `x-pagination` extension value, captured VERBATIM (spec
+   * extensions are untyped). Validated by the pagination emitter, not the IR.
+   */
+  paginationExtension?: unknown;
+};
+
+export type ServiceModel = {
+  name: string;
+  operations: OperationModel[];
+};
+
+export type NamedSchemaModel = {
+  name: string;
+  schema: SchemaModel;
+  description?: string;
+};
+
+export type ApiModel = {
+  title: string;
+  version: string;
+  description?: string;
+  serverUrl: string;
+  services: ServiceModel[];
+  schemas: NamedSchemaModel[];
+  securitySchemes: SecuritySchemeModel[];
+};
+
+/** All operations across the model's services, flattened. */
+export function allOperations(
+  operationsByService: { operations: OperationModel[] }[]
+): OperationModel[] {
+  return operationsByService.flatMap((service) => service.operations);
+}
diff --git a/packages/client-generator/src/intermediate-representation/normalize-swagger2.ts b/packages/client-generator/src/intermediate-representation/normalize-swagger2.ts
new file mode 100644
index 0000000000..a7fcc18663
--- /dev/null
+++ b/packages/client-generator/src/intermediate-representation/normalize-swagger2.ts
@@ -0,0 +1,240 @@
+import { isPlainObject, type Oas3Definition } from '@redocly/openapi-core';
+
+/**
+ * Convert a Swagger 2.0 document into the OpenAPI 3.x shape the IR builder expects.
+ * All 2.0-specific quirks live here so `buildApiModel` stays 3.x-only. Operations
+ * are normalized too (body/formData → requestBody, inline param types → `schema`,
+ * `responses[].schema` + `produces` → `responses[].content`). Every `#/definitions`,
+ * `#/parameters`, `#/responses` `$ref` is rewritten to its `#/components/...` home.
+ */
+export function normalizeSwagger2(doc: Record<string, unknown>): Oas3Definition {
+  const rewritten = rewriteRefs(doc) as Record<string, unknown>;
+
+  const out: Record<string, unknown> = { ...rewritten };
+  delete out.swagger;
+  delete out.host;
+  delete out.basePath;
+  delete out.schemes;
+  delete out.definitions;
+  delete out.securityDefinitions;
+  delete out.consumes;
+  delete out.produces;
+  delete out.parameters;
+  delete out.responses;
+
+  out.openapi = '3.0.3';
+
+  const servers = buildServers(rewritten);
+  if (servers) out.servers = servers;
+
+  out.components = buildComponents(rewritten);
+
+  out.paths = normalizePaths(
+    (rewritten.paths as Record<string, unknown>) ?? {},
+    (rewritten.consumes as string[] | undefined) ?? undefined,
+    (rewritten.produces as string[] | undefined) ?? undefined
+  );
+
+  return out as unknown as Oas3Definition;
+}
+
+function buildServers(doc: Record<string, unknown>): Array<{ url: string }> | undefined {
+  const host = doc.host as string | undefined;
+  const basePath = (doc.basePath as string | undefined) ?? '';
+  const scheme = ((doc.schemes as string[] | undefined) ?? ['https'])[0] ?? 'https';
+  if (!host) return undefined;
+  return [{ url: `${scheme}://${host}${basePath}` }];
+}
+
+function buildComponents(doc: Record<string, unknown>): Record<string, unknown> {
+  const components: Record<string, unknown> = {};
+  if (doc.definitions) components.schemas = doc.definitions;
+  if (doc.parameters) components.parameters = doc.parameters;
+  if (doc.responses)
+    components.responses = normalizeResponses(doc.responses as Record<string, unknown>, undefined);
+  const securityDefinitions = doc.securityDefinitions as
+    | Record<string, Record<string, unknown>>
+    | undefined;
+  if (securityDefinitions) {
+    const securitySchemes: Record<string, unknown> = {};
+    for (const [key, scheme] of Object.entries(securityDefinitions)) {
+      securitySchemes[key] = mapSecurityScheme(scheme);
+    }
+    components.securitySchemes = securitySchemes;
+  }
+  return components;
+}
+
+function mapSecurityScheme(scheme: Record<string, unknown>): Record<string, unknown> {
+  switch (scheme.type) {
+    case 'basic':
+      return { type: 'http', scheme: 'basic' };
+    case 'apiKey':
+      return { type: 'apiKey', name: scheme.name, in: scheme.in };
+    case 'oauth2': {
+      const flowName =
+        scheme.flow === 'accessCode'
+          ? 'authorizationCode'
+          : scheme.flow === 'application'
+            ? 'clientCredentials'
+            : (scheme.flow as string);
+      const flow: Record<string, unknown> = { scopes: scheme.scopes ?? {} };
+      if (scheme.authorizationUrl) flow.authorizationUrl = scheme.authorizationUrl;
+      if (scheme.tokenUrl) flow.tokenUrl = scheme.tokenUrl;
+      return { type: 'oauth2', flows: { [flowName]: flow } };
+    }
+    default:
+      return scheme;
+  }
+}
+
+/** Deep-clone `node`, rewriting Swagger-2 local `$ref` pointers to their 3.x homes. */
+function rewriteRefs(node: unknown): unknown {
+  if (Array.isArray(node)) return node.map(rewriteRefs);
+  if (isPlainObject(node)) {
+    const out: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(node as Record<string, unknown>)) {
+      if (key === '$ref' && typeof value === 'string') {
+        out.$ref = value
+          .replace('#/definitions/', '#/components/schemas/')
+          .replace('#/parameters/', '#/components/parameters/')
+          .replace('#/responses/', '#/components/responses/');
+      } else {
+        out[key] = rewriteRefs(value);
+      }
+    }
+    return out;
+  }
+  return node;
+}
+
+const DEFAULT_CONSUMES = 'application/json';
+const DEFAULT_PRODUCES = 'application/json';
+const NON_SCHEMA_PARAM_KEYS = new Set([
+  'name',
+  'in',
+  'required',
+  'description',
+  'deprecated',
+  'allowEmptyValue',
+  'collectionFormat',
+]);
+
+function normalizePaths(
+  paths: Record<string, unknown>,
+  rootConsumes?: string[],
+  rootProduces?: string[]
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [path, itemRaw] of Object.entries(paths)) {
+    const item = itemRaw as Record<string, unknown>;
+    const newItem: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(item)) {
+      if (!isHttpMethod(key)) {
+        newItem[key] = value;
+        continue;
+      }
+      newItem[key] = normalizeOperation(
+        value as Record<string, unknown>,
+        rootConsumes,
+        rootProduces
+      );
+    }
+    out[path] = newItem;
+  }
+  return out;
+}
+
+function isHttpMethod(key: string): boolean {
+  return ['get', 'put', 'post', 'delete', 'options', 'head', 'patch'].includes(key.toLowerCase());
+}
+
+function normalizeOperation(
+  operation: Record<string, unknown>,
+  rootConsumes?: string[],
+  rootProduces?: string[]
+): Record<string, unknown> {
+  const consumes = (operation.consumes as string[] | undefined) ?? rootConsumes;
+  const produces = (operation.produces as string[] | undefined) ?? rootProduces;
+  const params = (operation.parameters as Array<Record<string, unknown>> | undefined) ?? [];
+
+  const bodyParam = params.find((p) => p.in === 'body');
+  const formDataParams = params.filter((p) => p.in === 'formData');
+  const otherParams = params
+    .filter((p) => p.in !== 'body' && p.in !== 'formData')
+    .map(normalizeParameter);
+
+  const out: Record<string, unknown> = { ...operation, parameters: otherParams };
+  delete out.consumes;
+  delete out.produces;
+
+  const contentType = consumes?.[0] ?? DEFAULT_CONSUMES;
+  if (bodyParam) {
+    out.requestBody = {
+      required: Boolean(bodyParam.required),
+      content: { [contentType]: { schema: bodyParam.schema } },
+    };
+  } else if (formDataParams.length > 0) {
+    const properties: Record<string, unknown> = {};
+    const required: string[] = [];
+    for (const p of formDataParams) {
+      properties[p.name as string] = paramSchema(p);
+      if (p.required) required.push(p.name as string);
+    }
+    const schema: Record<string, unknown> = { type: 'object', properties };
+    if (required.length > 0) schema.required = required;
+    // form-urlencoded unless a multipart consumes is declared.
+    const formType =
+      consumes?.find((c) => c === 'multipart/form-data') ??
+      consumes?.[0] ??
+      'application/x-www-form-urlencoded';
+    out.requestBody = {
+      required: required.length > 0,
+      content: { [formType]: { schema } },
+    };
+  }
+
+  if (operation.responses) {
+    out.responses = normalizeResponses(operation.responses as Record<string, unknown>, produces);
+  }
+  return out;
+}
+
+/** A Swagger-2 simple parameter carries its schema inline; OAS3 nests it under `schema`. */
+function normalizeParameter(param: Record<string, unknown>): Record<string, unknown> {
+  const base: Record<string, unknown> = {};
+  const schema: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(param)) {
+    if (NON_SCHEMA_PARAM_KEYS.has(key)) base[key] = value;
+    else schema[key] = value;
+  }
+  base.schema = schema;
+  return base;
+}
+
+/** The schema half of a formData/simple param (everything except the param-level keys). */
+function paramSchema(param: Record<string, unknown>): Record<string, unknown> {
+  const schema: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(param)) {
+    if (!NON_SCHEMA_PARAM_KEYS.has(key)) schema[key] = value;
+  }
+  return schema;
+}
+
+function normalizeResponses(
+  responses: Record<string, unknown>,
+  produces?: string[]
+): Record<string, unknown> {
+  const contentType = produces?.[0] ?? DEFAULT_PRODUCES;
+  const out: Record<string, unknown> = {};
+  for (const [code, responseRaw] of Object.entries(responses)) {
+    const response = responseRaw as Record<string, unknown>;
+    if (response.schema === undefined) {
+      out[code] = response;
+      continue;
+    }
+    const { schema, ...rest } = response;
+    out[code] = { ...rest, content: { [contentType]: { schema } } };
+  }
+  return out;
+}
diff --git a/packages/client-generator/src/intermediate-representation/sanitize-identifiers.ts b/packages/client-generator/src/intermediate-representation/sanitize-identifiers.ts
new file mode 100644
index 0000000000..3eccc8788d
--- /dev/null
+++ b/packages/client-generator/src/intermediate-representation/sanitize-identifiers.ts
@@ -0,0 +1,157 @@
+import { logger } from '@redocly/openapi-core';
+
+import { isSafeIdentifier, uniqueIdent } from '../emitters/identifier.js';
+import type { ApiModel, OperationModel, SchemaModel } from './model.js';
+
+/**
+ * Coerce every document-derived name that lands in a TypeScript *declaration*
+ * slot — schema type names, operation (function) names — into a valid, unique JS
+ * identifier, and rewrite every reference to a renamed schema to match.
+ *
+ * This is a security boundary, not a nicety. `ts.factory.createIdentifier` prints
+ * its text verbatim with no validation, so a spec name like
+ * `foo(){};globalThis.x=1;export async function bar` would emit as executable
+ * top-level code in every consumer of the generated client. Sanitizing here, once,
+ * means no raw name reaches the printer regardless of which emitter consumes it.
+ *
+ * Valid identifiers pass through unchanged, so well-formed specs are byte-for-byte
+ * unaffected; only `-`/`.`/space/reserved-word/hostile names are rewritten (with a
+ * warning). `assertSafeIdentifiers` is the belt-and-suspenders gate that fails the
+ * build if any name still slips through — it should never fire after this pass.
+ */
+export function sanitizeIdentifiers(model: ApiModel): void {
+  // Schema names share TypeScript's *type* namespace; operation names its *value*
+  // namespace. Keep separate `used` sets so a function and a type may share a name.
+  const schemaNames = new Set<string>();
+  const renamed = new Map<string, string>();
+  for (const schema of model.schemas) {
+    const safe = uniqueIdent(schema.name, schemaNames);
+    if (safe !== schema.name) {
+      renamed.set(schema.name, safe);
+      warnRename('schema', schema.name, safe);
+      schema.name = safe;
+    }
+  }
+
+  // Security-scheme keys feed the apiKey setter name (`setApiKey<Key>`, built with a
+  // first-char-only pascalCase) and the runtime's security-matching string literals.
+  // Sanitize so the setter is a valid identifier, then rewrite each operation's
+  // `security` list with the same map so the literals still match.
+  const schemeKeys = new Set<string>();
+  const renamedKeys = new Map<string, string>();
+  for (const scheme of model.securitySchemes) {
+    const safe = uniqueIdent(scheme.key, schemeKeys);
+    if (safe !== scheme.key) {
+      renamedKeys.set(scheme.key, safe);
+      warnRename('security scheme', scheme.key, safe);
+      scheme.key = safe;
+    }
+  }
+
+  // A reference to a renamed schema/scheme must follow it; an unknown/dangling name is
+  // still sanitized standalone so it can never carry an injection payload.
+  const fixRef = (name: string): string => renamed.get(name) ?? sanitizeRef(name);
+  const fixKey = (key: string): string => renamedKeys.get(key) ?? sanitizeRef(key);
+  for (const schema of model.schemas) rewriteRefs(schema.schema, fixRef);
+
+  const operationNames = new Set<string>();
+  for (const service of model.services) {
+    for (const op of service.operations) {
+      const safe = uniqueIdent(op.name, operationNames);
+      if (safe !== op.name) {
+        warnRename('operation', op.name, safe);
+        op.specName = op.name;
+        op.name = safe;
+      }
+      rewriteOperationRefs(op, fixRef);
+      op.security = op.security.map((alternative) => alternative.map(fixKey));
+    }
+  }
+}
+
+/**
+ * Throw if any declaration name is still not a safe identifier — a generator bug, not
+ * bad input.
+ *
+ * This gates the three names that land *directly* in a binding slot from the model:
+ * schema names, security-scheme keys, and operation names. Identifiers an emitter
+ * *derives* from these — path-parameter binding names (`uniqueIdent`) and enum
+ * const-object keys (`isIdentifier`-gated) — are sanitized at their point of use,
+ * not here, so they stay safe even though this gate does not re-check them.
+ */
+export function assertSafeIdentifiers(model: ApiModel): void {
+  for (const schema of model.schemas) {
+    if (!isSafeIdentifier(schema.name)) throw unsafe('schema', schema.name);
+  }
+  for (const scheme of model.securitySchemes) {
+    // The key drives `setApiKey<Key>`, so it must be a safe identifier.
+    if (!isSafeIdentifier(scheme.key)) throw unsafe('security scheme', scheme.key);
+  }
+  for (const service of model.services) {
+    for (const op of service.operations) {
+      if (!isSafeIdentifier(op.name)) throw unsafe('operation', op.name);
+    }
+  }
+}
+
+function unsafe(kind: string, name: string): Error {
+  return new Error(
+    `Internal error: ${kind} name ${JSON.stringify(name)} is not a safe identifier after sanitization.`
+  );
+}
+
+/** Sanitize a ref/`omit` target that has no matching declaration (rare: a dangling $ref). */
+function sanitizeRef(name: string): string {
+  // No uniqueness context here; a throwaway set yields a pure, deterministic sanitize.
+  return uniqueIdent(name, new Set());
+}
+
+function warnRename(kind: string, from: string, to: string): void {
+  logger.warn(
+    `generate-client: ${kind} name ${JSON.stringify(from)} is not a valid TypeScript identifier; using ${JSON.stringify(to)}.\n`
+  );
+}
+
+/** Rewrite `ref`/`omit`/discriminator targets in a schema subtree via `fixRef` (mutates). */
+function rewriteRefs(schema: SchemaModel, fixRef: (name: string) => string): void {
+  switch (schema.kind) {
+    case 'ref':
+      schema.name = fixRef(schema.name);
+      break;
+    case 'omit':
+      schema.base = fixRef(schema.base);
+      break;
+    case 'array':
+      rewriteRefs(schema.items, fixRef);
+      break;
+    case 'record':
+      rewriteRefs(schema.value, fixRef);
+      break;
+    case 'object':
+      for (const prop of schema.properties) rewriteRefs(prop.schema, fixRef);
+      break;
+    case 'union':
+      for (const member of schema.members) rewriteRefs(member, fixRef);
+      if (schema.discriminator) {
+        for (const entry of schema.discriminator.mapping)
+          entry.schemaName = fixRef(entry.schemaName);
+      }
+      break;
+    case 'intersection':
+      for (const member of schema.members) rewriteRefs(member, fixRef);
+      break;
+    // scalar / literal / enum / null / unknown carry no schema references.
+  }
+}
+
+function rewriteOperationRefs(op: OperationModel, fixRef: (name: string) => string): void {
+  for (const p of op.pathParams) rewriteRefs(p.schema, fixRef);
+  for (const p of op.queryParams) rewriteRefs(p.schema, fixRef);
+  for (const p of op.headerParams) rewriteRefs(p.schema, fixRef);
+  for (const p of op.cookieParams) rewriteRefs(p.schema, fixRef);
+  if (op.requestBody) rewriteRefs(op.requestBody.schema, fixRef);
+  for (const r of [...op.successResponses, ...op.errorResponses]) {
+    rewriteRefs(r.schema, fixRef);
+    if (r.itemSchema) rewriteRefs(r.itemSchema, fixRef);
+  }
+}
diff --git a/packages/client-generator/src/loader.ts b/packages/client-generator/src/loader.ts
new file mode 100644
index 0000000000..74d8f27ea3
--- /dev/null
+++ b/packages/client-generator/src/loader.ts
@@ -0,0 +1,22 @@
+import {
+  bundle,
+  createConfig,
+  detectSpec,
+  type Config,
+  type Oas3Definition,
+} from '@redocly/openapi-core';
+
+import type { LoadResult } from './types.js';
+
+export async function loadSpec(ref: string, config?: Config): Promise<LoadResult> {
+  const cfg = config ?? (await createConfig({}));
+  // We do NOT pass `dereference: true` — the IR builder needs `$ref` preserved so it can map
+  // response/parameter schemas back to named `components.schemas` entries.
+  // Validation (shape, OpenAPI version) is delegated to `bundle()`, which throws clear messages.
+  const result = await bundle({ ref, config: cfg });
+  const parsed = result.bundle.parsed;
+  return {
+    document: parsed as unknown as Oas3Definition,
+    version: detectSpec(parsed),
+  };
+}
diff --git a/packages/client-generator/src/plugin.ts b/packages/client-generator/src/plugin.ts
new file mode 100644
index 0000000000..5c48eb2117
--- /dev/null
+++ b/packages/client-generator/src/plugin.ts
@@ -0,0 +1,70 @@
+// The custom-generator authoring API — the EXPERIMENTAL plugin surface, re-exported from the
+// package root (`@redocly/client-generator`).
+//
+// ⚠️ Experimental: this surface (the IR types and the codegen toolkit re-exported here) may change
+// between minor versions until it is stabilized. Pin your version if you depend on it.
+//
+// A custom generator is `(GeneratorInput) => GeneratedFile[]` plus a `name`; select it in
+// `generators` by name (inline via `customGenerators`) or by import specifier (path/package). It
+// receives the same spec-agnostic IR (`model`) the built-in generators consume, and may use the same
+// TypeScript-emitting toolkit re-exported below, so a plugin is a first-class peer of `sdk`/`zod`/…
+// The generated client stays dependency-free: a plugin's output is its own file(s), and its runtime
+// libraries are peers of the consumer's app, never of the client.
+//
+//   // my-generator.ts
+//   import { defineGenerator } from '@redocly/client-generator';
+//   // AST toolkit, when string-building isn't enough:
+//   // import { ts, printStatements } from '@redocly/client-generator/codegen';
+//   export default defineGenerator({
+//     name: 'route-map',
+//     requires: ['sdk'],
+//     run({ model, outputPath }) {
+//       const routes = model.services.flatMap((s) => s.operations)
+//         .map((op) => `  ${op.name}: '${op.method.toUpperCase()} ${op.path}',`).join('\n');
+//       return [{ path: outputPath.replace(/\.ts$/, '.routes.ts'),
+//                 content: `export const routes = {\n${routes}\n} as const;\n` }];
+//     },
+//   });
+
+import type { CustomGenerator } from './generators/types.js';
+
+/**
+ * Identity helper for authoring a custom generator with full type inference and one validation
+ * choke-point. `export default defineGenerator({ name, run, … })`. Returns its argument unchanged.
+ *
+ * @experimental The plugin API may change between minor versions until stabilized.
+ */
+export function defineGenerator(generator: CustomGenerator): CustomGenerator {
+  return generator;
+}
+
+// --- The authoring contract + the data a generator receives -----------------------------------
+export type {
+  CustomGenerator,
+  GeneratedFile,
+  Generator,
+  GeneratorInput,
+  GeneratorName,
+  OutputMode,
+} from './generators/types.js';
+export type { ArgsStyle, ErrorMode } from './emitters/operations.js';
+export type { DateType } from './emitters/types.js';
+
+// --- The intermediate representation (the `model` a generator walks) ---------------------------
+export type {
+  ApiModel,
+  NamedSchemaModel,
+  OperationModel,
+  ParamModel,
+  PropertyModel,
+  RequestBodyModel,
+  ResponseBodyModel,
+  ScalarKind,
+  SchemaMetadata,
+  SchemaModel,
+  ServiceModel,
+} from './intermediate-representation/model.js';
+
+// The TypeScript-emitting toolkit (`ts`, `printStatements`, `operationSignature`, …) is
+// exported from `@redocly/client-generator/codegen` — it loads `typescript`, which the
+// runtime-only package root must not reach statically.
diff --git a/packages/client-generator/src/runtime-contract.ts b/packages/client-generator/src/runtime-contract.ts
new file mode 100644
index 0000000000..ba149069e0
--- /dev/null
+++ b/packages/client-generator/src/runtime-contract.ts
@@ -0,0 +1,46 @@
+// The public, spec-independent runtime contract a publisher's `--setup` file imports.
+// These are the runtime's own types (src/runtime/types.ts) — the very module the
+// generated client embeds (inline) or imports (package) — so the contract cannot
+// drift from the generated output.
+
+import type { Middleware, RequestContext, RetryConfig } from './runtime/types.js';
+
+export type {
+  Middleware,
+  OperationContext,
+  RequestContext,
+  RetryConfig,
+  RetryContext,
+  RetryStrategy,
+} from './runtime/types.js';
+
+/**
+ * The spec-independent subset of a client's `ClientConfig` a publisher may bake in
+ * (everything except the spec-derived `auth`).
+ */
+export type ClientSetupConfig = {
+  serverUrl?: string;
+  headers?:
+    | Record<string, string>
+    | (() => Record<string, string> | Promise<Record<string, string>>);
+  fetch?: typeof fetch;
+  onRequest?: (ctx: RequestContext) => void | Promise<void>;
+  onResponse?: (
+    response: Response,
+    ctx: RequestContext
+  ) => Response | void | Promise<Response | void>;
+  onError?: (error: Error, ctx: RequestContext) => Error;
+  retry?: RetryConfig;
+};
+
+export type ClientSetup = { config?: ClientSetupConfig; middleware?: Middleware[] };
+
+/**
+ * Identity helper for authoring a `--setup` module: gives full type inference and a stable
+ * call the baker recognises. `export default defineClientSetup({ config, middleware })`.
+ *
+ * @experimental The setup API may change between minor versions until stabilized.
+ */
+export function defineClientSetup(setup: ClientSetup): ClientSetup {
+  return setup;
+}
diff --git a/packages/client-generator/src/runtime/__tests__/auth.test.ts b/packages/client-generator/src/runtime/__tests__/auth.test.ts
new file mode 100644
index 0000000000..37ab4676d8
--- /dev/null
+++ b/packages/client-generator/src/runtime/__tests__/auth.test.ts
@@ -0,0 +1,84 @@
+import { resolveAuth } from '../auth.js';
+
+const bearer = [[{ scheme: 's', kind: 'bearer' }]] as const;
+
+describe('resolveAuth', () => {
+  it('applies bearer (incl. async TokenProvider), basic, and apiKey in header/query/cookie', async () => {
+    expect((await resolveAuth(bearer, { auth: { bearer: 't1' } })).headers.Authorization).toBe(
+      'Bearer t1'
+    );
+    expect(
+      (await resolveAuth(bearer, { auth: { bearer: async () => 't2' } })).headers.Authorization
+    ).toBe('Bearer t2');
+
+    const basic = await resolveAuth([[{ scheme: 'b', kind: 'basic' }]], {
+      auth: { basic: { username: 'u', password: 'p' } },
+    });
+    expect(basic.headers.Authorization).toBe(`Basic ${btoa('u:p')}`);
+
+    const key = await resolveAuth(
+      [
+        [
+          { scheme: 'h', kind: 'apiKey', name: 'X-Key', in: 'header' },
+          { scheme: 'q', kind: 'apiKey', name: 'k', in: 'query' },
+          { scheme: 'c', kind: 'apiKey', name: 'sid', in: 'cookie' },
+          { scheme: 'c2', kind: 'apiKey', name: 'ses', in: 'cookie' },
+        ],
+      ],
+      { auth: { apiKey: { h: 'H', q: 'Q', c: 'C', c2: 'D' } } }
+    );
+    expect(key.headers['X-Key']).toBe('H');
+    expect(key.query.k).toBe('Q');
+    expect(key.headers.Cookie).toBe('sid=C; ses=D');
+  });
+
+  it('applies the first OR-alternative whose credentials are all configured', async () => {
+    const bearerOrApiKey = [
+      [{ scheme: 's', kind: 'bearer' }],
+      [{ scheme: 'k', kind: 'apiKey', name: 'X-Key', in: 'header' }],
+    ] as const;
+
+    // Only the SECOND alternative is configured: it must be applied, not skipped.
+    const keyOnly = await resolveAuth(bearerOrApiKey, { auth: { apiKey: { k: 'K' } } });
+    expect(keyOnly.headers['X-Key']).toBe('K');
+    expect(keyOnly.headers.Authorization).toBeUndefined();
+
+    // Both configured: the first alternative wins, never a union across alternatives.
+    const both = await resolveAuth(bearerOrApiKey, {
+      auth: { bearer: 't', apiKey: { k: 'K' } },
+    });
+    expect(both.headers.Authorization).toBe('Bearer t');
+    expect(both.headers['X-Key']).toBeUndefined();
+  });
+
+  it('encodes non-Latin-1 basic credentials (bare btoa would throw InvalidCharacterError)', async () => {
+    const basic = await resolveAuth([[{ scheme: 'b', kind: 'basic' }]], {
+      auth: { basic: { username: 'usér', password: 'på§s' } },
+    });
+    expect(basic.headers.Authorization).toBe(
+      `Basic ${Buffer.from('usér:på§s', 'utf-8').toString('base64')}`
+    );
+  });
+
+  it('percent-encodes cookie credentials so reserved characters cannot break the header', async () => {
+    const key = await resolveAuth([[{ scheme: 'c', kind: 'apiKey', name: 'sid', in: 'cookie' }]], {
+      auth: { apiKey: { c: 'a b;c=d' } },
+    });
+    expect(key.headers.Cookie).toBe('sid=a%20b%3Bc%3Dd');
+  });
+
+  it('skips schemes with no configured credential', async () => {
+    const out = await resolveAuth(
+      [
+        [
+          ...bearer[0],
+          { scheme: 'b', kind: 'basic' },
+          { scheme: 'k', kind: 'apiKey', name: 'X', in: 'header' },
+        ],
+      ],
+      {}
+    );
+    expect(out.headers).toEqual({});
+    expect(out.query).toEqual({});
+  });
+});
diff --git a/packages/client-generator/src/runtime/__tests__/create-client.test.ts b/packages/client-generator/src/runtime/__tests__/create-client.test.ts
new file mode 100644
index 0000000000..0b191dc225
--- /dev/null
+++ b/packages/client-generator/src/runtime/__tests__/create-client.test.ts
@@ -0,0 +1,531 @@
+import { createClientCore } from '../create-client.js';
+import { ApiError } from '../errors.js';
+import { items as paginateItems, pages as paginatePages } from '../paginate.js';
+import type { OperationDescriptor } from '../types.js';
+
+const OPS = {
+  getOrder: {
+    id: 'getOrder',
+    method: 'GET',
+    path: '/orders/{orderId}',
+    params: [
+      { name: 'orderId', in: 'path' },
+      { name: 'expand', in: 'query' },
+      { name: 'X-Trace', in: 'header' },
+    ],
+    tags: ['Orders'],
+  },
+  createPet: {
+    id: 'createPet',
+    method: 'post',
+    path: '/pets',
+    body: { contentType: 'application/json' },
+  },
+  listRaw: {
+    id: 'listRaw',
+    method: 'GET',
+    path: '/raw',
+    responseKind: 'text',
+    params: [{ name: 'filter', in: 'query', style: 'pipeDelimited', explode: false }],
+  },
+  secured: {
+    id: 'secured',
+    method: 'GET',
+    path: '/private',
+    security: [[{ scheme: 's', kind: 'bearer' }]],
+  },
+  stream: {
+    id: 'stream',
+    method: 'GET',
+    path: '/events',
+    responseKind: 'sse',
+    sseDataKind: 'json',
+  },
+  search: {
+    id: 'search',
+    method: 'GET',
+    path: '/search',
+    params: [
+      { name: 'ids', in: 'query', explode: false },
+      { name: 'path', in: 'query', allowReserved: true },
+    ],
+  },
+  streamPlain: { id: 'streamPlain', method: 'GET', path: '/plain-events', responseKind: 'sse' },
+  listOrders: {
+    id: 'listOrders',
+    method: 'GET',
+    path: '/orders',
+    params: [
+      { name: 'cursor', in: 'query' },
+      { name: 'limit', in: 'query' },
+    ],
+    pagination: { style: 'cursor', param: 'cursor', nextCursor: '/nextCursor', items: '/orders' },
+  },
+  configure: {
+    id: 'configure',
+    method: 'GET',
+    path: '/configure-op',
+    // Paginated AND colliding with a core member — the core member must still win.
+    pagination: { style: 'page', param: 'page', items: '/rows' },
+  },
+} satisfies Record<string, OperationDescriptor>;
+
+interface Ops {
+  getOrder: {
+    args: { orderId: string; params?: { expand?: string }; headers?: Record<string, unknown> };
+    result: { id: string };
+  };
+  createPet: { args: { body: { name: string } }; result: { id: string } };
+  listRaw: { args: { params?: { filter?: string[] } }; result: string };
+  search: { args: { params?: { ids?: string[]; path?: string } }; result: string };
+  secured: { args: Record<string, never>; result: string };
+  stream: { args: { body?: { topic: string } }; result: { n: number }; kind: 'sse' };
+  streamPlain: { args: Record<string, never>; result: string; kind: 'sse' };
+  listOrders: {
+    args: { params?: { cursor?: string; limit?: number } };
+    result: { orders: Array<{ id: string }>; nextCursor?: string };
+    item: { id: string };
+  };
+  configure: { args: Record<string, never>; result: string };
+  [k: string]: { args: object; result: unknown; kind?: 'sse'; item?: unknown };
+}
+
+const jsonOk = (body: unknown) =>
+  new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  });
+
+function spy(responses: Response[]) {
+  const calls: Array<{ url: string; init: RequestInit }> = [];
+  const fetchImpl = (async (url: string, init: RequestInit) => {
+    calls.push({ url, init });
+    return responses.shift()!;
+  }) as unknown as typeof fetch;
+  return { calls, fetchImpl };
+}
+
+describe('createClientCore', () => {
+  it('names every operation closure after its operationId (plain, paginated, and sse)', () => {
+    const client = createClientCore<Ops>(OPS, { serverUrl: 'https://x' });
+    expect(client.getOrder.name).toBe('getOrder');
+    expect(client.listOrders.name).toBe('listOrders');
+    expect(client.stream.name).toBe('stream');
+  });
+
+  it('routes args: path substitution + query + body + header slot; methods survive destructuring', async () => {
+    const { calls, fetchImpl } = spy([jsonOk({ id: 'o1' }), jsonOk({ id: 'p1' })]);
+    const client = createClientCore<Ops>(OPS, { serverUrl: 'https://x', fetch: fetchImpl });
+    const { getOrder, createPet } = client;
+
+    expect(
+      await getOrder({
+        orderId: 'a/b',
+        params: { expand: 'items' },
+        headers: { 'X-Trace': 7, 'X-Skip': null },
+      })
+    ).toEqual({ id: 'o1' });
+    expect(calls[0].url).toBe('https://x/orders/a%2Fb?expand=items');
+    expect((calls[0].init.headers as Record<string, string>)['X-Trace']).toBe('7');
+    expect('X-Skip' in (calls[0].init.headers as Record<string, string>)).toBe(false);
+    expect(calls[0].init.method).toBe('GET');
+
+    await createPet({ body: { name: 'Rex' } });
+    expect(calls[1].init.method).toBe('POST'); // method upper-cased from the descriptor
+    expect(JSON.parse(calls[1].init.body as string)).toEqual({ name: 'Rex' });
+  });
+
+  it('serializes cookie params into the Cookie header, joined after injected auth cookies', async () => {
+    const ops = {
+      withCookie: {
+        id: 'withCookie',
+        method: 'GET',
+        path: '/ctx',
+        params: [{ name: 'orgContext', in: 'cookie' }],
+        security: [[{ scheme: 'session', kind: 'apiKey', name: 'sid', in: 'cookie' }]],
+      },
+    } satisfies Record<string, OperationDescriptor>;
+    const { calls, fetchImpl } = spy([jsonOk({ ok: true })]);
+    const client = createClientCore<{
+      withCookie: { args: { cookies?: { orgContext?: string } }; result: { ok: boolean } };
+      [k: string]: { args: object; result: unknown };
+    }>(
+      ops,
+      { serverUrl: 'https://x', fetch: fetchImpl },
+      { resolveAuth: async () => ({ headers: { Cookie: 'sid=abc' }, query: {} }) }
+    );
+    await client.withCookie({ cookies: { orgContext: 'org 1;x' } });
+    expect((calls[0].init.headers as Record<string, string>).Cookie).toBe(
+      'sid=abc; orgContext=org%201%3Bx'
+    );
+  });
+
+  it('honors descriptor query styles and responseKind (text) + per-call parseAs override', async () => {
+    const { calls, fetchImpl } = spy([
+      new Response('plain', { headers: { 'content-type': 'text/plain' } }),
+      jsonOk(['x']),
+    ]);
+    const client = createClientCore<Ops>(OPS, { serverUrl: 'https://x', fetch: fetchImpl });
+
+    expect(await client.listRaw({ params: { filter: ['a', 'b'] } })).toBe('plain');
+    expect(calls[0].url).toBe('https://x/raw?filter=a|b');
+
+    // parseAs overrides the descriptor's kind at runtime.
+    expect(await client.listRaw({}, { parseAs: 'json' })).toEqual(['x']);
+  });
+
+  it('resolves OpenAPI style defaults: explode:false alone comma-joins, allowReserved alone skips encoding', async () => {
+    const { calls, fetchImpl } = spy([jsonOk('s')]);
+    const client = createClientCore<Ops>(OPS, { serverUrl: 'https://x', fetch: fetchImpl });
+    await client.search({ params: { ids: ['a', 'b'], path: 'a/b' } });
+    expect(calls[0].url).toBe('https://x/search?ids=a,b&path=a/b');
+  });
+
+  it('throw mode: non-ok becomes ApiError threaded through onError', async () => {
+    const { fetchImpl } = spy([
+      new Response('{"title":"x"}', {
+        status: 500,
+        headers: { 'content-type': 'application/json' },
+      }),
+    ]);
+    const client = createClientCore<Ops>(OPS, { fetch: fetchImpl, serverUrl: 'https://x' });
+    client.use(
+      { onRequest: () => {} }, // no onError — skipped by the error chain
+      { onError: (e) => new Error(`wrapped:${(e as { status: number }).status}`) }
+    );
+    await expect(client.getOrder({ orderId: '1' })).rejects.toThrow('wrapped:500');
+  });
+
+  it('result mode: non-ok returns { error }, ok returns { data } — without throwing', async () => {
+    const { fetchImpl } = spy([
+      new Response('{"title":"x"}', {
+        status: 500,
+        headers: { 'content-type': 'application/json' },
+      }),
+      jsonOk({ id: 'ok' }),
+    ]);
+    const client = createClientCore<Ops>(OPS, {
+      fetch: fetchImpl,
+      serverUrl: 'https://x',
+      errorMode: 'result',
+    });
+    const bad = (await client.getOrder({ orderId: '1' })) as unknown as {
+      error: { title: string };
+      response: Response;
+    };
+    expect(bad.error).toEqual({ title: 'x' });
+    expect(bad.response.status).toBe(500);
+    const good = (await client.getOrder({ orderId: '1' })) as unknown as { data: { id: string } };
+    expect(good.data).toEqual({ id: 'ok' });
+  });
+
+  it('auth capability merges resolved headers/query before the request; auth setters feed it', async () => {
+    const { calls, fetchImpl } = spy([jsonOk('ok'), jsonOk('ok'), jsonOk('ok')]);
+    const client = createClientCore<Ops>(
+      OPS,
+      { fetch: fetchImpl, serverUrl: 'https://x' },
+      {
+        resolveAuth: async (_security, config) => {
+          const headers: Record<string, string> = {};
+          if (config.auth?.bearer) headers.Authorization = `Bearer ${config.auth.bearer as string}`;
+          return { headers, query: { sig: 'v' } };
+        },
+      }
+    );
+    client.auth.bearer('T');
+    await client.secured({});
+    expect((calls[0].init.headers as Record<string, string>).Authorization).toBe('Bearer T');
+    expect(calls[0].url).toBe('https://x/private?sig=v');
+
+    client.auth.basic('u', 'p');
+    client.auth.apiKey('k', 'v');
+    await client.secured({});
+    expect(calls[1].url).toContain('sig=v');
+
+    // Ops without security skip resolveAuth entirely.
+    await client.getOrder({ orderId: '1' });
+    expect((calls[2].init.headers as Record<string, string>).Authorization).toBeUndefined();
+  });
+
+  it('configure({ auth }) merges into existing credentials instead of replacing them', async () => {
+    const seen: Array<Record<string, unknown>> = [];
+    const { fetchImpl } = spy([jsonOk('ok'), jsonOk('ok'), jsonOk('ok')]);
+    const client = createClientCore<Ops>(
+      OPS,
+      { fetch: fetchImpl, serverUrl: 'https://x' },
+      {
+        resolveAuth: async (_security, config) => {
+          seen.push({ ...(config.auth ?? {}) });
+          return { headers: {}, query: {} };
+        },
+      }
+    );
+    client.auth.basic('u', 'p');
+    client.auth.apiKey('k', 'v');
+    await client.secured({});
+
+    // Only `bearer` — basic/apiKey must survive (no `auth.apiKey`, so the apiKey slot is untouched).
+    client.configure({ auth: { bearer: 'B' } });
+    await client.secured({});
+    expect(seen[1]).toEqual({
+      basic: { username: 'u', password: 'p' },
+      apiKey: { k: 'v' },
+      bearer: 'B',
+    });
+
+    // A new apiKey scheme merges per key, keeping the earlier one.
+    client.configure({ auth: { apiKey: { k2: 'v2' } } });
+    await client.secured({});
+    expect(seen[2]).toEqual({
+      basic: { username: 'u', password: 'p' },
+      apiKey: { k: 'v', k2: 'v2' },
+      bearer: 'B',
+    });
+  });
+
+  it('header precedence: caller init.headers beats header params, which beat injected auth', async () => {
+    const { calls, fetchImpl } = spy([jsonOk('ok'), jsonOk({ id: '1' })]);
+    const client = createClientCore<Ops>(
+      OPS,
+      { fetch: fetchImpl, serverUrl: 'https://x' },
+      {
+        resolveAuth: async () => ({
+          headers: { Authorization: 'Bearer injected' },
+          query: {},
+        }),
+      }
+    );
+    // Caller overrides injected auth.
+    await client.secured({}, { headers: { Authorization: 'Bearer mine' } });
+    expect((calls[0].init.headers as Record<string, string>).Authorization).toBe('Bearer mine');
+
+    // Caller overrides the explicit header-param slot too.
+    await client.getOrder(
+      { orderId: '1', headers: { 'X-Trace': 'from-args' } },
+      { headers: { 'X-Trace': 'from-caller' } }
+    );
+    expect((calls[1].init.headers as Record<string, string>)['X-Trace']).toBe('from-caller');
+  });
+
+  it('configure() ignores errorMode — the generate-time mode cannot be flipped at runtime', async () => {
+    const { fetchImpl } = spy([
+      new Response('{"title":"x"}', {
+        status: 500,
+        headers: { 'content-type': 'application/json' },
+      }),
+    ]);
+    const client = createClientCore<Ops>(OPS, { fetch: fetchImpl, serverUrl: 'https://x' });
+    client.configure({ errorMode: 'result' });
+    await expect(client.getOrder({ orderId: '1' })).rejects.toMatchObject({ status: 500 });
+  });
+
+  it('sse ops dispatch to the sse capability (with prepared url + body); absent capability throws sync', async () => {
+    const seenUrls: string[] = [];
+    const seenKinds: string[] = [];
+    const seenBodies: unknown[] = [];
+    async function* fake(
+      _config: unknown,
+      _op: unknown,
+      prepare: () => Promise<{ url: string; init: unknown; body?: unknown }>,
+      dataKind: string
+    ): AsyncGenerator<{ data: { n: number } }> {
+      const { url, body } = await prepare();
+      seenUrls.push(url);
+      seenKinds.push(dataKind);
+      seenBodies.push(body);
+      yield { data: { n: 1 } };
+    }
+    const withCap = createClientCore<Ops>(OPS, { serverUrl: 'https://x' }, { sse: fake as never });
+    const events = [];
+    for await (const ev of withCap.stream({ body: { topic: 'orders' } })) events.push(ev);
+    expect(events).toEqual([{ data: { n: 1 } }]);
+    expect(seenBodies[0]).toEqual({ topic: 'orders' });
+
+    // A bare call (no args) on an op without sseDataKind → dataKind defaults to 'text'.
+    for await (const _ of withCap.streamPlain()) void _;
+    expect(seenUrls).toEqual(['https://x/events', 'https://x/plain-events']);
+    expect(seenKinds).toEqual(['json', 'text']);
+
+    const noCap = createClientCore<Ops>(OPS, { serverUrl: 'https://x' });
+    expect(() => noCap.stream({})).toThrow(/capability/i);
+  });
+
+  it('paginated ops gain .pages/.items dispatching to the capability; others get neither', async () => {
+    const seen: unknown[] = [];
+    const paginate = {
+      pages: async function* (
+        call: (args?: object, init?: object) => Promise<unknown>,
+        spec: unknown,
+        args?: object,
+        init?: object
+      ): AsyncGenerator<unknown> {
+        seen.push(['pages', spec, args, init]);
+        yield await call(args, init); // the method passed in performs the real request
+      },
+      items: async function* (
+        _call: unknown,
+        spec: { style: string },
+        args?: object,
+        init?: object
+      ): AsyncGenerator<unknown> {
+        seen.push(['items', spec.style, args, init]);
+        yield { id: 'o9' };
+      },
+    };
+    const { calls, fetchImpl } = spy([jsonOk({ orders: [{ id: 'o1' }] })]);
+    const client = createClientCore<Ops>(
+      OPS,
+      { serverUrl: 'https://x', fetch: fetchImpl },
+      { paginate: paginate as never }
+    );
+
+    expect(typeof client.listOrders.pages).toBe('function');
+    expect(typeof client.listOrders.items).toBe('function');
+    expect((client.getOrder as unknown as Record<string, unknown>).pages).toBeUndefined();
+    expect((client.getOrder as unknown as Record<string, unknown>).items).toBeUndefined();
+
+    const args = { params: { limit: 2 } };
+    const init = { headers: { 'X-Trace': '1' } };
+    const yielded = [];
+    for await (const page of client.listOrders.pages(args, init)) yielded.push(page);
+    expect(yielded).toEqual([{ orders: [{ id: 'o1' }] }]);
+    expect(calls[0].url).toBe('https://x/orders?limit=2');
+    expect(seen[0]).toEqual(['pages', OPS.listOrders.pagination, args, init]);
+
+    for await (const item of client.listOrders.items()) expect(item).toEqual({ id: 'o9' });
+    expect(seen[1]).toEqual(['items', 'cursor', undefined, undefined]); // bare call: no args/init
+  });
+
+  it('result mode: .pages/.items iterate RAW pages (the envelope is unwrapped before the pointers)', async () => {
+    const page1 = { orders: [{ id: 'o1' }, { id: 'o2' }], nextCursor: 'c2' };
+    const page2 = { orders: [{ id: 'o3' }] };
+    const { calls, fetchImpl } = spy([
+      jsonOk(page1),
+      jsonOk(page2),
+      jsonOk(page1),
+      jsonOk(page2),
+      jsonOk(page2),
+    ]);
+    const client = createClientCore<Ops>(
+      OPS,
+      { serverUrl: 'https://x', fetch: fetchImpl, errorMode: 'result' },
+      { paginate: { pages: paginatePages, items: paginateItems } }
+    );
+
+    const pages = [];
+    for await (const page of client.listOrders.pages()) pages.push(page);
+    expect(pages).toEqual([page1, page2]); // raw pages, never { data, error, response }
+    expect(calls.map((c) => c.url)).toEqual(['https://x/orders', 'https://x/orders?cursor=c2']);
+
+    const items = [];
+    for await (const item of client.listOrders.items()) items.push(item);
+    expect(items).toEqual([{ id: 'o1' }, { id: 'o2' }, { id: 'o3' }]);
+
+    // The one-shot call keeps the result-mode envelope.
+    const envelope = (await client.listOrders()) as unknown as { data: unknown };
+    expect(envelope.data).toEqual(page2);
+  });
+
+  it('result mode: a successful bodyless page (204) stops iteration cleanly, no bogus ApiError', async () => {
+    // A 204 page parses to `data: undefined` with `error: undefined` — success, not failure.
+    // The pointers miss on `undefined`, so iteration stops; it must NOT throw.
+    const { fetchImpl } = spy([
+      jsonOk({ orders: [{ id: 'o1' }], nextCursor: 'c2' }),
+      new Response(null, { status: 204 }),
+    ]);
+    const client = createClientCore<Ops>(
+      OPS,
+      { serverUrl: 'https://x', fetch: fetchImpl, errorMode: 'result' },
+      { paginate: { pages: paginatePages, items: paginateItems } }
+    );
+    const items = [];
+    for await (const item of client.listOrders.items()) items.push(item);
+    expect(items).toEqual([{ id: 'o1' }]);
+  });
+
+  it('result mode: a failed page aborts iteration by throwing ApiError; onError is not invoked', async () => {
+    const { fetchImpl } = spy([
+      jsonOk({ orders: [{ id: 'o1' }], nextCursor: 'c2' }),
+      new Response('{"title":"boom"}', {
+        status: 500,
+        statusText: 'Server Error',
+        headers: { 'content-type': 'application/json' },
+      }),
+    ]);
+    const client = createClientCore<Ops>(
+      OPS,
+      { serverUrl: 'https://x', fetch: fetchImpl, errorMode: 'result' },
+      { paginate: { pages: paginatePages, items: paginateItems } }
+    );
+    let hookCalled = false;
+    client.use({
+      onError: (error) => {
+        hookCalled = true;
+        return error;
+      },
+    });
+
+    const seen: unknown[] = [];
+    const error = await (async () => {
+      for await (const item of client.listOrders.items()) seen.push(item);
+    })().catch((e: unknown) => e);
+    expect(seen).toEqual([{ id: 'o1' }]); // pages before the failure still arrive
+    expect(error).toBeInstanceOf(ApiError);
+    expect(error).toMatchObject({
+      status: 500,
+      statusText: 'Server Error',
+      body: { title: 'boom' }, // the envelope's decoded error rides along
+    });
+    expect(hookCalled).toBe(false); // the onError middleware hook is throw-mode-only
+  });
+
+  it('unwired paginate capability: .pages/.items throw a descriptive error synchronously', async () => {
+    const { fetchImpl } = spy([jsonOk({ orders: [] })]);
+    const noCap = createClientCore<Ops>(OPS, { serverUrl: 'https://x', fetch: fetchImpl });
+    expect(() => noCap.listOrders.pages()).toThrow(
+      'Pagination capability not wired: cannot iterate operation "listOrders"'
+    );
+    expect(() => noCap.listOrders.items()).toThrow(/capability/i);
+    // The plain one-shot call still works without the capability.
+    expect(await noCap.listOrders()).toEqual({ orders: [] });
+  });
+
+  it('a paginated op colliding with a core member still loses to the core', () => {
+    const client = createClientCore<Ops>(OPS, {});
+    expect(() => client.configure({ serverUrl: 'https://x' })).not.toThrow();
+    expect((client.configure as unknown as Record<string, unknown>).pages).toBeUndefined();
+  });
+
+  it('core members win over a colliding operation name; configure merges; use appends without mutating caller arrays', async () => {
+    const mine: never[] = [];
+    const client = createClientCore<Ops>(OPS, { middleware: mine });
+    client.configure({ serverUrl: 'https://later' }); // the core member, not the colliding op
+    client.use({ onRequest: () => {} });
+    expect(mine.length).toBe(0);
+
+    // use() also tolerates a configure() that reset middleware to undefined.
+    client.configure({ middleware: undefined });
+    client.use({ onRequest: () => {} });
+
+    // The merged serverUrl is actually used.
+    const { calls, fetchImpl } = spy([jsonOk({ id: '1' })]);
+    client.configure({ fetch: fetchImpl });
+    await client.getOrder({ orderId: '1' });
+    expect(calls[0].url).toBe('https://later/orders/1');
+  });
+
+  it('defaults args to {} so no-input operations can be called bare', async () => {
+    const { calls, fetchImpl } = spy([jsonOk('s')]);
+    const client = createClientCore<Ops>(OPS, { fetch: fetchImpl, serverUrl: 'https://x' });
+    await client.secured();
+    expect(calls[0].url).toBe('https://x/private');
+  });
+
+  it('works without any initial config: serverUrl falls back to a relative URL', async () => {
+    const { calls, fetchImpl } = spy([jsonOk({ id: '1' })]);
+    const client = createClientCore<Ops>(OPS);
+    client.configure({ fetch: fetchImpl });
+    await client.getOrder({ orderId: '1' });
+    expect(calls[0].url).toBe('/orders/1');
+  });
+});
diff --git a/packages/client-generator/src/runtime/__tests__/errors.test.ts b/packages/client-generator/src/runtime/__tests__/errors.test.ts
new file mode 100644
index 0000000000..c62f5194ee
--- /dev/null
+++ b/packages/client-generator/src/runtime/__tests__/errors.test.ts
@@ -0,0 +1,31 @@
+import { ApiError, abortError } from '../errors.js';
+
+describe('ApiError', () => {
+  it('carries url/status/statusText/body and a readable message', () => {
+    const err = new ApiError('https://x/api', 404, 'Not Found', { title: 'gone' });
+    expect(err).toBeInstanceOf(Error);
+    expect(err.url).toBe('https://x/api');
+    expect(err.status).toBe(404);
+    expect(err.statusText).toBe('Not Found');
+    expect(err.body).toEqual({ title: 'gone' });
+    expect(err.message).toContain('404');
+    expect(err.name).toBe('ApiError');
+  });
+});
+
+describe('abortError', () => {
+  it('returns the signal reason when it is an Error', () => {
+    const controller = new AbortController();
+    const reason = new Error('caller reason');
+    controller.abort(reason);
+    expect(abortError(controller.signal)).toBe(reason);
+  });
+
+  it('falls back to a DOMException AbortError otherwise', () => {
+    const controller = new AbortController();
+    controller.abort('a string reason');
+    const err = abortError(controller.signal);
+    expect(err).toBeInstanceOf(DOMException);
+    expect((err as DOMException).name).toBe('AbortError');
+  });
+});
diff --git a/packages/client-generator/src/runtime/__tests__/index.test.ts b/packages/client-generator/src/runtime/__tests__/index.test.ts
new file mode 100644
index 0000000000..40ab8c577f
--- /dev/null
+++ b/packages/client-generator/src/runtime/__tests__/index.test.ts
@@ -0,0 +1,165 @@
+import { defineClientSetup, type Middleware } from '../../runtime-contract.js';
+import { ApiError, createClient, mergeSetup, type OperationDescriptor } from '../index.js';
+
+const OPS = {
+  upload: {
+    id: 'upload',
+    method: 'POST',
+    path: '/up',
+    body: { contentType: 'multipart/form-data', multipart: true },
+  },
+  secured: {
+    id: 'secured',
+    method: 'GET',
+    path: '/private',
+    security: [[{ scheme: 's', kind: 'bearer' }]],
+  },
+  stream: {
+    id: 'stream',
+    method: 'GET',
+    path: '/events',
+    responseKind: 'sse',
+    sseDataKind: 'json',
+  },
+  listOrders: {
+    id: 'listOrders',
+    method: 'GET',
+    path: '/orders',
+    params: [{ name: 'cursor', in: 'query' }],
+    pagination: { style: 'cursor', param: 'cursor', nextCursor: '/nextCursor', items: '/orders' },
+  },
+} satisfies Record<string, OperationDescriptor>;
+
+interface Ops {
+  upload: { args: { body: { file: string } }; result: unknown };
+  secured: { args: Record<string, never>; result: unknown };
+  stream: { args: Record<string, never>; result: { n: number }; kind: 'sse' };
+  listOrders: {
+    args: { params?: { cursor?: string } };
+    result: { orders: Array<{ id: string }>; nextCursor?: string };
+    item: { id: string };
+  };
+  [k: string]: { args: object; result: unknown; kind?: 'sse'; item?: unknown };
+}
+
+describe('public surface', () => {
+  it('createClient wires all capabilities: multipart, auth, and sse work without manual caps', async () => {
+    const calls: Array<{ url: string; init: RequestInit }> = [];
+    const fetchImpl = (async (url: string, init: RequestInit) => {
+      calls.push({ url, init });
+      if (url.endsWith('/events')) {
+        return new Response(new TextEncoder().encode('data: {"n":1}\n\n'), {
+          status: 200,
+          headers: { 'content-type': 'text/event-stream' },
+        });
+      }
+      return new Response('{}', { status: 200, headers: { 'content-type': 'application/json' } });
+    }) as unknown as typeof fetch;
+
+    const client = createClient<Ops>(OPS, { serverUrl: 'https://x', fetch: fetchImpl });
+
+    await client.upload({ body: { file: 'f' } });
+    expect(calls[0].init.body).toBeInstanceOf(FormData);
+
+    client.auth.bearer('T');
+    await client.secured();
+    expect((calls[1].init.headers as Record<string, string>).Authorization).toBe('Bearer T');
+
+    const events = [];
+    for await (const ev of client.stream({}, { reconnect: false })) events.push(ev.data);
+    expect(events).toEqual([{ n: 1 }]);
+  });
+
+  it('createClient wires the paginate capability: .items walks cursor pages end-to-end', async () => {
+    const pagesByCursor: Record<string, unknown> = {
+      first: { orders: [{ id: 'o1' }, { id: 'o2' }], nextCursor: 'c2' },
+      c2: { orders: [{ id: 'o3' }] },
+    };
+    const urls: string[] = [];
+    const fetchImpl = (async (url: string) => {
+      urls.push(url);
+      const cursor = new URL(url).searchParams.get('cursor') ?? 'first';
+      return new Response(JSON.stringify(pagesByCursor[cursor]), {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+      });
+    }) as unknown as typeof fetch;
+    const client = createClient<Ops>(OPS, { serverUrl: 'https://x', fetch: fetchImpl });
+
+    const ids: string[] = [];
+    for await (const order of client.listOrders.items()) ids.push(order.id);
+    expect(ids).toEqual(['o1', 'o2', 'o3']);
+    expect(urls).toEqual(['https://x/orders', 'https://x/orders?cursor=c2']);
+
+    const pageSizes: number[] = [];
+    for await (const page of client.listOrders.pages()) pageSizes.push(page.orders.length);
+    expect(pageSizes).toEqual([2, 1]);
+  });
+
+  it('mergeSetup: config wins per-field; middleware composes setup-first', () => {
+    const setup = {
+      config: { serverUrl: 'https://baked', retry: { retries: 3 } },
+      middleware: [{ onRequest: () => {} }],
+    };
+    const merged = mergeSetup(setup, {
+      serverUrl: 'https://mine',
+      middleware: [{ onResponse: () => {} }],
+    });
+    expect(merged.serverUrl).toBe('https://mine');
+    expect(merged.retry).toEqual({ retries: 3 });
+    expect(merged.middleware!.length).toBe(2);
+    expect(merged.middleware![0].onRequest).toBeDefined(); // baked first
+  });
+
+  it('mergeSetup tolerates an absent setup and absent config', () => {
+    expect(mergeSetup(undefined)).toEqual({ middleware: [] });
+  });
+
+  it('accepts a contract-typed setup from defineClientSetup (assignability pin)', () => {
+    // Compiles only while runtime-contract types stay assignable to the runtime's.
+    const setup = defineClientSetup({
+      config: { serverUrl: 'https://baked', retry: { retries: 2 } },
+      middleware: [
+        {
+          onRequest: (ctx) => {
+            ctx.headers['X-Op'] = ctx.operation.id;
+          },
+        },
+      ],
+    });
+    const merged = mergeSetup(setup, {});
+    expect(merged.serverUrl).toBe('https://baked');
+    expect(merged.middleware).toHaveLength(1);
+  });
+
+  it('narrowed createClient: literal ctx.operation, contract middleware and mergeSetup accepted', () => {
+    // The generated wiring's shape: literal type args + a mergeSetup-produced (base) config.
+    const narrowed = createClient<Ops, 'upload' | 'secured' | 'stream'>(
+      OPS,
+      mergeSetup(defineClientSetup({ config: { serverUrl: 'https://baked' } }), {})
+    );
+    // A contract-typed (base) middleware is accepted by the narrowed use().
+    const contractMiddleware: Middleware = {
+      onRequest: (ctx) => {
+        ctx.headers['X-Op'] = ctx.operation.id;
+      },
+    };
+    narrowed.use(contractMiddleware);
+    expect(typeof narrowed.upload).toBe('function');
+
+    const _typeOnly = (): void => {
+      narrowed.use({
+        onRequest: (ctx) => {
+          expectTypeOf(ctx.operation.id).toEqualTypeOf<'upload' | 'secured' | 'stream'>();
+          // @ts-expect-error a misspelled operationId has no overlap with the literal union
+          if (ctx.operation.id === 'uploda') return;
+        },
+      });
+    };
+    void _typeOnly;
+  });
+
+  it('exports ApiError', () => {
+    expect(new ApiError('u', 500, 'x', null)).toBeInstanceOf(Error);
+  });
+});
diff --git a/packages/client-generator/src/runtime/__tests__/multipart.test.ts b/packages/client-generator/src/runtime/__tests__/multipart.test.ts
new file mode 100644
index 0000000000..55b1afeea0
--- /dev/null
+++ b/packages/client-generator/src/runtime/__tests__/multipart.test.ts
@@ -0,0 +1,29 @@
+import { toFormData } from '../multipart.js';
+
+describe('toFormData', () => {
+  it('serializes fields per the port rules', () => {
+    const fd = toFormData({
+      file: new Blob(['x']),
+      name: 'n',
+      when: new Date('2026-01-02T03:04:05Z'),
+      tags: ['a', 'b'],
+      meta: { k: 'v' },
+      price: 42,
+      skip: undefined,
+      gone: null,
+    });
+    expect(fd.get('file')).toBeInstanceOf(Blob);
+    expect(fd.get('name')).toBe('n');
+    expect(fd.get('when')).toBe('2026-01-02T03:04:05.000Z');
+    expect(fd.getAll('tags')).toEqual(['a', 'b']);
+    expect(fd.get('meta')).toBe('{"k":"v"}');
+    expect(fd.get('price')).toBe('42');
+    expect(fd.has('skip')).toBe(false);
+    expect(fd.has('gone')).toBe(false);
+  });
+
+  it('skips null/undefined items inside arrays', () => {
+    const fd = toFormData({ tags: ['a', null, undefined, 'b'] });
+    expect(fd.getAll('tags')).toEqual(['a', 'b']);
+  });
+});
diff --git a/packages/client-generator/src/runtime/__tests__/paginate.test.ts b/packages/client-generator/src/runtime/__tests__/paginate.test.ts
new file mode 100644
index 0000000000..00145039ea
--- /dev/null
+++ b/packages/client-generator/src/runtime/__tests__/paginate.test.ts
@@ -0,0 +1,263 @@
+import { items, pages, resolvePointer } from '../paginate.js';
+import type { PaginationSpec, RequestOptions } from '../types.js';
+
+const CURSOR: PaginationSpec = {
+  style: 'cursor',
+  param: 'cursor',
+  nextCursor: '/nextCursor',
+  items: '/orders',
+};
+const OFFSET: PaginationSpec = { style: 'offset', param: 'offset', items: '/orders' };
+const PAGE: PaginationSpec = { style: 'page', param: 'page', items: '/orders' };
+
+/** A fetch-free call stub: replies from `data` by call index, recording every args/init. */
+function stub(data: unknown[]) {
+  const calls: Array<{ args?: Record<string, unknown>; init?: RequestOptions }> = [];
+  const call = async (args?: Record<string, unknown>, init?: RequestOptions) => {
+    calls.push({ args, init });
+    return data[calls.length - 1];
+  };
+  const sentParams = (name: string) =>
+    calls.map((c) => (c.args?.params as Record<string, unknown> | undefined)?.[name]);
+  return { calls, call, sentParams };
+}
+
+async function collect<T>(gen: AsyncGenerator<T>): Promise<T[]> {
+  const out: T[] = [];
+  for await (const value of gen) out.push(value);
+  return out;
+}
+
+describe('resolvePointer', () => {
+  const doc = {
+    'menu/items': { 'size~tall': 'latte' },
+    orders: [{ id: 'o1' }, { id: 'o2' }],
+  };
+
+  it('walks objects and arrays, unescaping ~1 then ~0', () => {
+    expect(resolvePointer(doc, '/menu~1items/size~0tall')).toBe('latte');
+    expect(resolvePointer(doc, '/orders/1/id')).toBe('o2');
+  });
+
+  it('returns the whole document for the empty pointer', () => {
+    expect(resolvePointer(doc, '')).toBe(doc);
+  });
+
+  it('requires a leading slash', () => {
+    expect(resolvePointer(doc, 'orders')).toBeUndefined();
+  });
+
+  it('returns undefined on any miss instead of throwing', () => {
+    expect(resolvePointer(doc, '/missing')).toBeUndefined();
+    expect(resolvePointer(doc, '/orders/9/id')).toBeUndefined();
+    // Array tokens must be canonical indices: no leading zeros, no '-', no words.
+    expect(resolvePointer(doc, '/orders/01')).toBeUndefined();
+    expect(resolvePointer(doc, '/orders/-')).toBeUndefined();
+    expect(resolvePointer(doc, '/orders/first')).toBeUndefined();
+  });
+
+  it('returns undefined when traversing into a non-object', () => {
+    expect(resolvePointer('espresso', '/length')).toBeUndefined();
+    expect(resolvePointer(null, '/orders')).toBeUndefined();
+    expect(resolvePointer({ total: 42 }, '/total/amount')).toBeUndefined();
+  });
+});
+
+describe('pages — cursor style', () => {
+  it('follows nextCursor across pages and always yields the last page', async () => {
+    const data = [
+      { orders: [{ id: 'o1' }, { id: 'o2' }], nextCursor: 'c2' },
+      { orders: [{ id: 'o3' }], nextCursor: 'c3' },
+      { orders: [{ id: 'o4' }] }, // no nextCursor — final page, still yielded
+    ];
+    const { call, sentParams } = stub(data);
+    expect(await collect(pages(call, CURSOR))).toEqual(data);
+    expect(sentParams('cursor')).toEqual([undefined, 'c2', 'c3']);
+  });
+
+  it.each([null, ''])('stops when the next cursor resolves to %j', async (last) => {
+    const data = [
+      { orders: [{ id: 'o1' }], nextCursor: 'c2' },
+      { orders: [{ id: 'o2' }], nextCursor: last },
+    ];
+    const { call, calls } = stub(data);
+    expect(await collect(pages(call, CURSOR))).toEqual(data);
+    expect(calls).toHaveLength(2);
+  });
+
+  it('stops on a false hasMore flag without the extra empty request, ignoring a non-null cursor', async () => {
+    const spec: PaginationSpec = { ...CURSOR, hasMore: '/pageInfo/hasNextPage' };
+    const data = [
+      { orders: [{ id: 'o1' }], nextCursor: 'c2', pageInfo: { hasNextPage: true } },
+      // Connection-style last page: the cursor is still non-null, only the flag says stop.
+      { orders: [{ id: 'o2' }], nextCursor: 'c3', pageInfo: { hasNextPage: false } },
+    ];
+    const { call, calls } = stub(data);
+    expect(await collect(pages(call, spec))).toEqual(data);
+    expect(calls).toHaveLength(2);
+  });
+
+  it('falls back to the cursor stop rule when the hasMore pointer misses', async () => {
+    const spec: PaginationSpec = { ...CURSOR, hasMore: '/pageInfo/hasNextPage' };
+    const data = [{ orders: [{ id: 'o1' }], nextCursor: 'c2' }, { orders: [{ id: 'o2' }] }];
+    const { call, calls } = stub(data);
+    expect(await collect(pages(call, spec))).toEqual(data);
+    expect(calls).toHaveLength(2);
+  });
+
+  it('resumes from a caller-provided cursor, preserving other params', async () => {
+    const data = [{ orders: [{ id: 'o3' }] }];
+    const { call, calls } = stub(data);
+    await collect(pages(call, CURSOR, { params: { cursor: 'c2', limit: 5 } }));
+    expect(calls[0].args?.params).toEqual({ cursor: 'c2', limit: 5 });
+  });
+
+  it('advances through numeric cursors end-to-end', async () => {
+    const data = [
+      { orders: [{ id: 'o1' }], nextCursor: 2 },
+      { orders: [{ id: 'o2' }], nextCursor: 3 },
+      { orders: [{ id: 'o3' }] },
+    ];
+    const { call, sentParams } = stub(data);
+    expect(await collect(pages(call, CURSOR))).toEqual(data);
+    expect(sentParams('cursor')).toEqual([undefined, 2, 3]);
+  });
+
+  it('throws when the next cursor is neither a string nor a number (hostile server)', async () => {
+    // A fresh object every page would never compare equal — without this guard the
+    // did-not-advance check could not catch the infinite loop.
+    const data = [{ orders: [{ id: 'o1' }], nextCursor: { token: 'c2' } }];
+    const { call } = stub(data);
+    await expect(collect(pages(call, CURSOR))).rejects.toThrow(
+      'Pagination cursor at /nextCursor is not a string or number'
+    );
+  });
+
+  it('throws when the operation returns the same cursor twice in a row', async () => {
+    const data = [
+      { orders: [{ id: 'o1' }], nextCursor: 'c2' },
+      { orders: [{ id: 'o1' }], nextCursor: 'c2' },
+    ];
+    const { call } = stub(data);
+    await expect(collect(pages(call, CURSOR))).rejects.toThrow(
+      'Pagination did not advance: operation returned the same cursor twice'
+    );
+  });
+
+  it('never mutates the caller args; each request gets a fresh params clone', async () => {
+    const data = [{ orders: [{ id: 'o1' }], nextCursor: 'c2' }, { orders: [] }];
+    const args = { params: { limit: 2 }, headers: { 'X-Trace': '1' } };
+    const snapshot = structuredClone(args);
+    const { call, calls } = stub(data);
+    await collect(pages(call, CURSOR, args));
+    expect(args).toEqual(snapshot);
+    expect(calls[0].args?.params).not.toBe(args.params);
+    expect(calls[1].args?.params).not.toBe(calls[0].args?.params);
+  });
+
+  it('forwards the same init (incl. AbortSignal) to every call', async () => {
+    const data = [{ orders: [], nextCursor: 'c2' }, { orders: [] }];
+    const init: RequestOptions = { signal: new AbortController().signal };
+    const { call, calls } = stub(data);
+    await collect(pages(call, CURSOR, {}, init));
+    expect(calls).toHaveLength(2);
+    for (const c of calls) expect(c.init).toBe(init);
+  });
+});
+
+describe('pages — offset style', () => {
+  it('starts at 0 and advances by each page item count; an empty page stops after being yielded', async () => {
+    const data = [
+      { orders: ['a', 'b'] },
+      { orders: ['c', 'd'] },
+      { orders: ['e'] },
+      { orders: [] },
+    ];
+    const { call, sentParams } = stub(data);
+    expect(await collect(pages(call, OFFSET))).toEqual(data);
+    expect(sentParams('offset')).toEqual([0, 2, 4, 5]);
+  });
+
+  it('starts at the caller offset when provided', async () => {
+    const data = [{ orders: ['k'] }, { orders: [] }];
+    const { call, sentParams } = stub(data);
+    await collect(pages(call, OFFSET, { params: { offset: 10 } }));
+    expect(sentParams('offset')).toEqual([10, 11]);
+  });
+
+  it('coerces a string offset to a number so advancing adds instead of concatenating', async () => {
+    const data = [{ orders: ['k', 'm'] }, { orders: [] }];
+    const { call, sentParams } = stub(data);
+    // A string offset (common from URL/form input): `'10' + 2` would be `'102'` without coercion.
+    await collect(pages(call, OFFSET, { params: { offset: '10' } }));
+    expect(sentParams('offset')).toEqual([10, 12]);
+  });
+
+  it('falls back to the default start when the offset param is not a number', async () => {
+    const data = [{ orders: ['k'] }, { orders: [] }];
+    const { call, sentParams } = stub(data);
+    await collect(pages(call, OFFSET, { params: { offset: 'not-a-number' } }));
+    expect(sentParams('offset')).toEqual([0, 1]);
+  });
+
+  it('stops when the items pointer misses', async () => {
+    const data = [{ total: 0 }];
+    const { call, calls } = stub(data);
+    expect(await collect(pages(call, OFFSET))).toEqual(data);
+    expect(calls).toHaveLength(1);
+  });
+});
+
+describe('pages — page style', () => {
+  it('starts at 1 and increments by 1 until an empty page', async () => {
+    const data = [{ orders: ['a', 'b'] }, { orders: ['c'] }, { orders: [] }];
+    const { call, sentParams } = stub(data);
+    expect(await collect(pages(call, PAGE))).toEqual(data);
+    expect(sentParams('page')).toEqual([1, 2, 3]);
+  });
+
+  it('starts at the caller page number when provided', async () => {
+    const data = [{ orders: ['x'] }, { orders: [] }];
+    const { call, sentParams } = stub(data);
+    await collect(pages(call, PAGE, { params: { page: 5 } }));
+    expect(sentParams('page')).toEqual([5, 6]);
+  });
+});
+
+describe('items', () => {
+  it('flattens each page through the items pointer', async () => {
+    const data = [
+      { orders: [{ id: 'o1' }, { id: 'o2' }], nextCursor: 'c2' },
+      { orders: [{ id: 'o3' }] },
+    ];
+    const { call } = stub(data);
+    expect(await collect(items(call, CURSOR))).toEqual([{ id: 'o1' }, { id: 'o2' }, { id: 'o3' }]);
+  });
+
+  it('cursor style: a page whose items pointer misses yields nothing but pagination continues', async () => {
+    const data = [
+      { orders: [{ id: 'o1' }], nextCursor: 'c2' },
+      { nextCursor: 'c3' }, // no items array — skipped, cursor keeps advancing
+      { orders: [{ id: 'o2' }] },
+    ];
+    const { call, calls } = stub(data);
+    expect(await collect(items(call, CURSOR))).toEqual([{ id: 'o1' }, { id: 'o2' }]);
+    expect(calls).toHaveLength(3);
+  });
+
+  it('offset style: a missing items pointer stops the iteration', async () => {
+    const data = [{ orders: ['a'] }, { note: 'sold out' }];
+    const { call, calls } = stub(data);
+    expect(await collect(items(call, OFFSET))).toEqual(['a']);
+    expect(calls).toHaveLength(2);
+  });
+
+  it('forwards args and init to the underlying pages', async () => {
+    const data = [{ orders: ['a'] }, { orders: [] }];
+    const init: RequestOptions = { headers: { 'X-Trace': '1' } };
+    const { call, calls, sentParams } = stub(data);
+    await collect(items(call, PAGE, { params: { limit: 1 } }, init));
+    expect(sentParams('limit')).toEqual([1, 1]);
+    for (const c of calls) expect(c.init).toBe(init);
+  });
+});
diff --git a/packages/client-generator/src/runtime/__tests__/parse.test.ts b/packages/client-generator/src/runtime/__tests__/parse.test.ts
new file mode 100644
index 0000000000..cf3d555ae4
--- /dev/null
+++ b/packages/client-generator/src/runtime/__tests__/parse.test.ts
@@ -0,0 +1,87 @@
+import { parse, readError } from '../parse.js';
+
+const json = (body: unknown, status = 200) =>
+  new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } });
+
+describe('parse', () => {
+  it('void and 204 return undefined', async () => {
+    expect(await parse(json({ a: 1 }), 'void')).toBeUndefined();
+    expect(await parse(new Response(null, { status: 204 }), 'json')).toBeUndefined();
+  });
+
+  it('explicit kinds decode accordingly', async () => {
+    expect(await parse(json({ a: 1 }), 'json')).toEqual({ a: 1 });
+    expect(await parse(new Response('hi'), 'text')).toBe('hi');
+    expect(await parse(new Response('x'), 'blob')).toBeInstanceOf(Blob);
+    expect(await parse(new Response('x'), 'arrayBuffer')).toBeInstanceOf(ArrayBuffer);
+    const stream = await parse(new Response('x'), 'stream');
+    expect(stream).toBeInstanceOf(ReadableStream);
+  });
+
+  it('reads multipart bodies as FormData', async () => {
+    const fd = new FormData();
+    fd.append('a', '1');
+    const out = (await parse(new Response(fd), 'formData')) as FormData;
+    expect(out).toBeInstanceOf(FormData);
+    expect(out.get('a')).toBe('1');
+  });
+
+  it('auto negotiates by content-type: json, then text/*, then blob', async () => {
+    expect(await parse(json({ a: 1 }), 'auto')).toEqual({ a: 1 });
+    expect(
+      await parse(new Response('plain', { headers: { 'content-type': 'text/plain' } }), 'auto')
+    ).toBe('plain');
+    expect(
+      await parse(
+        new Response('bin', { headers: { 'content-type': 'application/octet-stream' } }),
+        'auto'
+      )
+    ).toBeInstanceOf(Blob);
+    // No content-type header at all → Blob fallback.
+    const headerless = new Response('x');
+    headerless.headers.delete('content-type');
+    expect(await parse(headerless, 'auto')).toBeInstanceOf(Blob);
+  });
+
+  it('auto matches content-type case-insensitively (Text/Plain, application/JSON)', async () => {
+    expect(
+      await parse(new Response('plain', { headers: { 'content-type': 'Text/Plain' } }), 'auto')
+    ).toBe('plain');
+    expect(
+      await parse(
+        new Response('{"a":1}', { headers: { 'content-type': 'application/JSON' } }),
+        'auto'
+      )
+    ).toEqual({ a: 1 });
+  });
+});
+
+describe('readError', () => {
+  it('reads a JSON error body, falls back to text', async () => {
+    expect(await readError(json({ title: 'bad' }, 400))).toEqual({ title: 'bad' });
+    expect(
+      await readError(
+        new Response('oops', { status: 500, headers: { 'content-type': 'text/plain' } })
+      )
+    ).toBe('oops');
+  });
+
+  it('returns undefined when the declared-JSON body does not parse', async () => {
+    const broken = new Response('not-json', {
+      status: 500,
+      headers: { 'content-type': 'application/json' },
+    });
+    expect(await readError(broken)).toBeUndefined();
+  });
+
+  it('returns undefined on a content-type-less body whose read fails', async () => {
+    const body = new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.error(new Error('boom'));
+      },
+    });
+    const failing = new Response(body, { status: 500 });
+    failing.headers.delete('content-type');
+    expect(await readError(failing)).toBeUndefined();
+  });
+});
diff --git a/packages/client-generator/src/runtime/__tests__/retry.test.ts b/packages/client-generator/src/runtime/__tests__/retry.test.ts
new file mode 100644
index 0000000000..b4c3a4b563
--- /dev/null
+++ b/packages/client-generator/src/runtime/__tests__/retry.test.ts
@@ -0,0 +1,86 @@
+import { defaultRetryOn, retryDelay, sleep } from '../retry.js';
+import type { RetryContext } from '../types.js';
+
+const ctx = (method: string, part: Partial<RetryContext>): RetryContext => ({
+  attempt: 1,
+  request: { url: 'u', method, headers: {}, operation: { id: 'x', path: '/x', tags: [] } },
+  ...part,
+});
+
+describe('defaultRetryOn', () => {
+  it('retries idempotent methods on transport errors and transient statuses', () => {
+    expect(defaultRetryOn(ctx('GET', { error: new Error('net') }))).toBe(true);
+    expect(defaultRetryOn(ctx('get', { error: new Error('net') }))).toBe(true); // case-insensitive
+    expect(defaultRetryOn(ctx('DELETE', { response: new Response(null, { status: 503 }) }))).toBe(
+      true
+    );
+  });
+
+  it('never retries POST/PATCH; never retries non-transient statuses', () => {
+    expect(defaultRetryOn(ctx('POST', { error: new Error('net') }))).toBe(false);
+    expect(defaultRetryOn(ctx('PATCH', { response: new Response(null, { status: 503 }) }))).toBe(
+      false
+    );
+    expect(defaultRetryOn(ctx('GET', { response: new Response(null, { status: 400 }) }))).toBe(
+      false
+    );
+  });
+});
+
+describe('retryDelay', () => {
+  it('honors Retry-After seconds over the computed backoff', () => {
+    expect(retryDelay({ retryDelay: 100, jitter: false }, 1, '2')).toBe(2000);
+  });
+
+  it('honors an HTTP-date Retry-After (clamped at 0 for past dates)', () => {
+    const past = new Date(Date.now() - 60_000).toUTCString();
+    expect(retryDelay({ jitter: false }, 1, past)).toBe(0);
+    const future = new Date(Date.now() + 5_000).toUTCString();
+    const delay = retryDelay({ jitter: false }, 1, future);
+    expect(delay).toBeGreaterThan(0);
+    expect(delay).toBeLessThanOrEqual(5_000);
+  });
+
+  it('falls through an unparseable Retry-After to the backoff', () => {
+    expect(retryDelay({ retryDelay: 100, jitter: false }, 1, 'not-a-date-or-number')).toBe(100);
+  });
+
+  it('exponential doubles per attempt; fixed stays constant (jitter off)', () => {
+    expect(retryDelay({ retryDelay: 100, jitter: false }, 3, null)).toBe(400);
+    expect(retryDelay({ retryDelay: 100, retryStrategy: 'fixed', jitter: false }, 3, null)).toBe(
+      100
+    );
+    // Defaults: base 1000, exponential.
+    expect(retryDelay({ jitter: false }, 2, null)).toBe(2000);
+  });
+
+  it('full jitter stays within [0, computed]', () => {
+    const d = retryDelay({ retryDelay: 100 }, 3, null);
+    expect(d).toBeGreaterThanOrEqual(0);
+    expect(d).toBeLessThanOrEqual(400);
+  });
+});
+
+describe('sleep', () => {
+  it('resolves after the delay', async () => {
+    await expect(sleep(1)).resolves.toBeUndefined();
+  });
+
+  it('rejects immediately when the signal is already aborted', async () => {
+    const controller = new AbortController();
+    controller.abort(new Error('pre-aborted'));
+    await expect(sleep(5000, controller.signal)).rejects.toThrow('pre-aborted');
+  });
+
+  it('rejects when the signal aborts mid-sleep', async () => {
+    const controller = new AbortController();
+    const p = sleep(5000, controller.signal);
+    controller.abort(new Error('stop'));
+    await expect(p).rejects.toThrow('stop');
+  });
+
+  it('resolves normally when a signal is present but never aborts', async () => {
+    const controller = new AbortController();
+    await expect(sleep(1, controller.signal)).resolves.toBeUndefined();
+  });
+});
diff --git a/packages/client-generator/src/runtime/__tests__/send.test.ts b/packages/client-generator/src/runtime/__tests__/send.test.ts
new file mode 100644
index 0000000000..a05ba3f80e
--- /dev/null
+++ b/packages/client-generator/src/runtime/__tests__/send.test.ts
@@ -0,0 +1,369 @@
+import { middlewareChain, send } from '../send.js';
+import type { ClientConfig, RequestContext } from '../types.js';
+
+const op = { id: 'createPet', path: '/pets', tags: [] as string[] };
+const ok = () =>
+  new Response('[]', { status: 200, headers: { 'content-type': 'application/json' } });
+
+function fetchSpy(responses: Array<Response | Error>) {
+  const calls: Array<{ url: string; init: RequestInit }> = [];
+  const fetchImpl = (async (url: string, init: RequestInit) => {
+    calls.push({ url, init });
+    const next = responses.shift()!;
+    if (next instanceof Error) throw next;
+    return next;
+  }) as unknown as typeof fetch;
+  return { calls, fetchImpl };
+}
+
+describe('send', () => {
+  it('serializes the body AFTER onRequest so middleware mutations are sent', async () => {
+    const { calls, fetchImpl } = fetchSpy([ok()]);
+    const config: ClientConfig = {
+      fetch: fetchImpl,
+      middleware: [
+        {
+          onRequest: (ctx: RequestContext) => {
+            (ctx.body as { name: string }).name = 'Mutated';
+          },
+        },
+      ],
+    };
+    await send(config, op, 'https://x/pets', { method: 'POST' }, { name: 'Rex' }, false, {});
+    expect(JSON.parse(calls[0].init.body as string)).toEqual({ name: 'Mutated' });
+    expect((calls[0].init.headers as Record<string, string>)['Content-Type']).toBe(
+      'application/json'
+    );
+  });
+
+  it('passes string/FormData/URLSearchParams/binary bodies through untouched', async () => {
+    const { calls, fetchImpl } = fetchSpy([ok(), ok(), ok(), ok()]);
+    const config: ClientConfig = { fetch: fetchImpl };
+    await send(config, op, 'u', { method: 'POST' }, 'raw-string', false, {});
+    expect(calls[0].init.body).toBe('raw-string');
+    const fd = new FormData();
+    await send(config, op, 'u', { method: 'POST' }, fd, false, {});
+    expect(calls[1].init.body).toBe(fd);
+    const usp = new URLSearchParams('a=1');
+    await send(config, op, 'u', { method: 'POST' }, usp, false, {});
+    expect(calls[2].init.body).toBe(usp);
+    const bytes = new Uint8Array([1, 2]);
+    await send(config, op, 'u', { method: 'POST' }, bytes, false, {});
+    expect(calls[3].init.body).toBe(bytes);
+  });
+
+  it('keeps an explicit Content-Type instead of forcing application/json', async () => {
+    const { calls, fetchImpl } = fetchSpy([ok()]);
+    await send(
+      { fetch: fetchImpl },
+      op,
+      'u',
+      { method: 'POST', headers: { 'content-type': 'application/vnd.custom+json' } },
+      { a: 1 },
+      false,
+      {}
+    );
+    const headers = calls[0].init.headers as Record<string, string>;
+    expect(headers['content-type']).toBe('application/vnd.custom+json');
+    expect(headers['Content-Type']).toBeUndefined();
+  });
+
+  it('runs onResponse in reverse order (onion) and lets it replace the response', async () => {
+    const order: string[] = [];
+    const { fetchImpl } = fetchSpy([ok()]);
+    const config: ClientConfig = {
+      fetch: fetchImpl,
+      middleware: [
+        {
+          onResponse: () => {
+            order.push('A');
+          },
+        },
+        {
+          onResponse: () => {
+            order.push('B');
+            return new Response('replaced');
+          },
+        },
+      ],
+    };
+    const { response } = await send(
+      config,
+      op,
+      'https://x/pets',
+      { method: 'GET' },
+      undefined,
+      false,
+      {}
+    );
+    expect(order).toEqual(['B', 'A']);
+    expect(await response.text()).toBe('replaced');
+  });
+
+  it('cancels the abandoned original body when onResponse replaces the response', async () => {
+    let cancelled = false;
+    const body = new ReadableStream<Uint8Array>({
+      cancel() {
+        cancelled = true;
+      },
+    });
+    const { fetchImpl } = fetchSpy([new Response(body, { status: 200 })]);
+    const { response } = await send(
+      { fetch: fetchImpl, onResponse: () => new Response('replaced', { status: 201 }) },
+      op,
+      'u',
+      { method: 'GET' },
+      undefined,
+      false,
+      {}
+    );
+    expect(cancelled).toBe(true);
+    expect(response.status).toBe(201);
+  });
+
+  it('retries an idempotent request on 503, drains the abandoned body, and honors Retry-After=0', async () => {
+    const drained = vi.fn().mockResolvedValue(undefined);
+    const bad = new Response('busy', { status: 503, headers: { 'retry-after': '0' } });
+    Object.defineProperty(bad, 'body', { value: { cancel: drained } });
+    const { calls, fetchImpl } = fetchSpy([bad, ok()]);
+    const { response } = await send(
+      { fetch: fetchImpl, retry: { retries: 1, jitter: false } },
+      op,
+      'https://x/pets',
+      { method: 'GET' },
+      undefined,
+      false,
+      {}
+    );
+    expect(response.status).toBe(200);
+    expect(calls.length).toBe(2);
+    expect(drained).toHaveBeenCalled();
+  });
+
+  it('retries a transport error and merges per-call retry over the config policy', async () => {
+    const { calls, fetchImpl } = fetchSpy([new Error('ECONNRESET'), ok()]);
+    const { response } = await send(
+      { fetch: fetchImpl, retry: { retries: 0 } },
+      op,
+      'u',
+      { method: 'GET', retry: { retries: 2, retryDelay: 1, jitter: false } },
+      undefined,
+      false,
+      {}
+    );
+    expect(response.status).toBe(200);
+    expect(calls.length).toBe(2);
+  });
+
+  it('rethrows a transport error when retries are exhausted', async () => {
+    const { fetchImpl } = fetchSpy([new Error('down'), new Error('down')]);
+    await expect(
+      send(
+        { fetch: fetchImpl, retry: { retries: 1, retryDelay: 1, jitter: false } },
+        op,
+        'u',
+        { method: 'GET' },
+        undefined,
+        false,
+        {}
+      )
+    ).rejects.toThrow('down');
+  });
+
+  it('does not retry POST by default; retries when a custom retryOn opts in', async () => {
+    const first = fetchSpy([new Response(null, { status: 503 }), ok()]);
+    const out1 = await send(
+      { fetch: first.fetchImpl, retry: { retries: 2, jitter: false } },
+      op,
+      'u',
+      { method: 'POST' },
+      undefined,
+      false,
+      {}
+    );
+    expect(out1.response.status).toBe(503);
+    expect(first.calls.length).toBe(1);
+
+    const second = fetchSpy([new Response(null, { status: 503 }), ok()]);
+    const out2 = await send(
+      {
+        fetch: second.fetchImpl,
+        retry: { retries: 2, retryDelay: 1, jitter: false, retryOn: () => true },
+      },
+      op,
+      'u',
+      { method: 'POST' },
+      undefined,
+      false,
+      {}
+    );
+    expect(out2.response.status).toBe(200);
+  });
+
+  it('resolves async config.headers once and merges per-call headers over them', async () => {
+    const { calls, fetchImpl } = fetchSpy([ok()]);
+    await send(
+      { fetch: fetchImpl, headers: async () => ({ 'X-A': 'from-config', 'X-B': 'kept' }) },
+      op,
+      'u',
+      { method: 'GET', headers: { 'X-A': 'per-call' } },
+      undefined,
+      false,
+      {}
+    );
+    const headers = calls[0].init.headers as Record<string, string>;
+    expect(headers['X-A']).toBe('per-call');
+    expect(headers['X-B']).toBe('kept');
+    expect(headers.Accept).toBe('application/json');
+  });
+
+  it('honors per-call headers given as a Headers instance or entry pairs (not just a record)', async () => {
+    const { calls, fetchImpl } = fetchSpy([ok(), ok()]);
+    await send(
+      { fetch: fetchImpl },
+      op,
+      'u',
+      { method: 'GET', headers: new Headers({ 'X-Trace': 'from-headers-instance' }) },
+      undefined,
+      false,
+      {}
+    );
+    // Header names round-trip lowercased through `Headers`; HTTP treats them case-insensitively.
+    expect((calls[0].init.headers as Record<string, string>)['x-trace']).toBe(
+      'from-headers-instance'
+    );
+
+    await send(
+      { fetch: fetchImpl },
+      op,
+      'u',
+      { method: 'GET', headers: [['X-Trace', 'from-pairs']] },
+      undefined,
+      false,
+      {}
+    );
+    expect((calls[1].init.headers as Record<string, string>)['X-Trace']).toBe('from-pairs');
+  });
+
+  it('merges a plain-object config.headers too', async () => {
+    const { calls, fetchImpl } = fetchSpy([ok()]);
+    await send(
+      { fetch: fetchImpl, headers: { 'X-S': 'static' } },
+      op,
+      'u',
+      { method: 'GET' },
+      undefined,
+      false,
+      {}
+    );
+    expect((calls[0].init.headers as Record<string, string>)['X-S']).toBe('static');
+  });
+
+  it('multipart body uses the wired capability after onRequest; throws without it', async () => {
+    const { calls, fetchImpl } = fetchSpy([ok()]);
+    await send({ fetch: fetchImpl }, op, 'u', { method: 'POST' }, { orgId: '1' }, true, {
+      serializeMultipart: (b) => {
+        const fd = new FormData();
+        fd.append('orgId', String((b as { orgId: string }).orgId));
+        return fd;
+      },
+    });
+    expect(calls[0].init.body).toBeInstanceOf(FormData);
+    await expect(
+      send({ fetch: fetchImpl }, op, 'u', { method: 'POST' }, { a: 1 }, true, {})
+    ).rejects.toThrow(/capability/i);
+  });
+
+  it('throws abortError when the signal is already aborted', async () => {
+    const controller = new AbortController();
+    controller.abort(new Error('gone'));
+    const { fetchImpl } = fetchSpy([ok()]);
+    await expect(
+      send(
+        { fetch: fetchImpl },
+        op,
+        'u',
+        { method: 'GET', signal: controller.signal },
+        undefined,
+        false,
+        {}
+      )
+    ).rejects.toThrow('gone');
+  });
+
+  it('falls back to the global fetch when config.fetch is not set', async () => {
+    const globalFetch = vi.fn().mockResolvedValue(ok());
+    vi.stubGlobal('fetch', globalFetch);
+    try {
+      const { response } = await send(
+        {},
+        op,
+        'https://x/pets',
+        { method: 'GET' },
+        undefined,
+        false,
+        {}
+      );
+      expect(response.status).toBe(200);
+      expect(globalFetch).toHaveBeenCalledOnce();
+    } finally {
+      vi.unstubAllGlobals();
+    }
+  });
+
+  it('ignores a drain failure on the abandoned retry body (e.g. already locked)', async () => {
+    const bad = new Response('busy', { status: 503, headers: { 'retry-after': '0' } });
+    bad.body!.getReader(); // lock the stream so cancel() rejects
+    const { calls, fetchImpl } = fetchSpy([bad, ok()]);
+    const { response } = await send(
+      { fetch: fetchImpl, retry: { retries: 1, jitter: false } },
+      op,
+      'https://x/pets',
+      { method: 'GET' },
+      undefined,
+      false,
+      {}
+    );
+    expect(response.status).toBe(200);
+    expect(calls.length).toBe(2);
+  });
+
+  it('defaults the method to GET in the request context', async () => {
+    const seen: string[] = [];
+    const { fetchImpl } = fetchSpy([ok()]);
+    await send(
+      {
+        fetch: fetchImpl,
+        middleware: [
+          {
+            onRequest: (ctx) => {
+              seen.push(ctx.method);
+            },
+          },
+        ],
+      },
+      op,
+      'u',
+      {},
+      undefined,
+      false,
+      {}
+    );
+    expect(seen).toEqual(['GET']);
+  });
+});
+
+describe('middlewareChain', () => {
+  it('folds the single config hooks in as an implicit FIRST middleware', () => {
+    const onRequest = vi.fn();
+    const chain = middlewareChain({ onRequest, middleware: [{ onRequest: vi.fn() }] });
+    expect(chain.length).toBe(2);
+    expect(chain[0].onRequest).toBe(onRequest);
+  });
+
+  it('is just config.middleware when no single hooks are set', () => {
+    const mw = { onRequest: vi.fn() };
+    expect(middlewareChain({ middleware: [mw] })).toEqual([mw]);
+    expect(middlewareChain({})).toEqual([]);
+  });
+});
diff --git a/packages/client-generator/src/runtime/__tests__/sse.test.ts b/packages/client-generator/src/runtime/__tests__/sse.test.ts
new file mode 100644
index 0000000000..a53d717e18
--- /dev/null
+++ b/packages/client-generator/src/runtime/__tests__/sse.test.ts
@@ -0,0 +1,345 @@
+import { parseSseFrame, sse, SseParseError } from '../sse.js';
+import type { SseOptions } from '../types.js';
+
+const enc = new TextEncoder();
+function streamResponse(chunks: string[], opts: { status?: number } = {}) {
+  const body = new ReadableStream<Uint8Array>({
+    start(controller) {
+      for (const chunk of chunks) controller.enqueue(enc.encode(chunk));
+      controller.close();
+    },
+  });
+  return new Response(body, {
+    status: opts.status ?? 200,
+    headers: { 'content-type': 'text/event-stream' },
+  });
+}
+const op = { id: 'stream', path: '/events', tags: [] as string[] };
+/** A fixed-auth `prepare` thunk (the stream re-invokes it per connect). */
+const prep =
+  (url: string, init: SseOptions = {}) =>
+  async () => ({ url, init });
+
+describe('parseSseFrame', () => {
+  it('parses event/id/retry and multi-line data (joined with \\n); json dataKind parses', () => {
+    const ev = parseSseFrame('event: tick\nid: 7\nretry: 250\ndata: {"n":1}', 'json');
+    expect(ev).toEqual({ event: 'tick', id: '7', retry: 250, data: { n: 1 } });
+    const multi = parseSseFrame('data: line1\ndata: line2', 'text');
+    expect(multi?.data).toBe('line1\nline2');
+  });
+
+  it('handles bare field names, no-space values, and invalid retry', () => {
+    const ev = parseSseFrame('data\nretry: soon', 'text');
+    expect(ev).toEqual({ event: undefined, data: '', id: undefined, retry: undefined });
+    expect(parseSseFrame('data:tight', 'text')?.data).toBe('tight');
+  });
+
+  it('returns undefined for comment-only frames and ignores unknown fields', () => {
+    expect(parseSseFrame(': keepalive', 'text')).toBeUndefined();
+    expect(parseSseFrame('foo: bar\ndata: x', 'text')?.data).toBe('x');
+  });
+
+  it('throws SseParseError (not a generic error) when json data is malformed', () => {
+    expect(() => parseSseFrame('data: {not json', 'json')).toThrow(SseParseError);
+    // text dataKind never parses, so the same payload is returned verbatim.
+    expect(parseSseFrame('data: {not json', 'text')?.data).toBe('{not json');
+  });
+});
+
+describe('sse', () => {
+  it('yields events and FLUSHES a final frame that lacks a trailing separator', async () => {
+    const fetchImpl = (async () =>
+      streamResponse(['data: a\n\n', 'id: 9\nretry: 5\ndata: final'])) as unknown as typeof fetch;
+    const seen: unknown[] = [];
+    for await (const ev of sse(
+      { fetch: fetchImpl },
+      op,
+      prep('https://x/events', { reconnect: false }),
+      'text'
+    )) {
+      seen.push(ev.data);
+    }
+    expect(seen).toEqual(['a', 'final']);
+  });
+
+  it('skips comment-only frames mid-stream and flushes a plain (no id/retry) final frame', async () => {
+    const fetchImpl = (async () =>
+      streamResponse(['data: a\n\n', ': ping\n\n', 'data: tail'])) as unknown as typeof fetch;
+    const seen: unknown[] = [];
+    for await (const ev of sse({ fetch: fetchImpl }, op, prep('u', { reconnect: false }), 'text')) {
+      seen.push(ev.data);
+    }
+    expect(seen).toEqual(['a', 'tail']);
+  });
+
+  it('splits frames on mixed CR/LF double line endings, not just matching pairs', async () => {
+    // `\n\r\n` and `\r\n\r` are valid double-boundaries per the SSE spec.
+    const fetchImpl = (async () =>
+      streamResponse(['data: a\n\r\ndata: b\r\n\rdata: c\n\n'])) as unknown as typeof fetch;
+    const seen: unknown[] = [];
+    for await (const ev of sse({ fetch: fetchImpl }, op, prep('u', { reconnect: false }), 'text')) {
+      seen.push(ev.data);
+    }
+    expect(seen).toEqual(['a', 'b', 'c']);
+  });
+
+  it('surfaces a malformed JSON payload as SseParseError and does NOT reconnect', async () => {
+    let calls = 0;
+    const fetchImpl = (async () => {
+      calls++;
+      return streamResponse(['data: {bad json\n\n']);
+    }) as unknown as typeof fetch;
+    await expect(async () => {
+      // `reconnect` defaults to true; a parse error must still surface, not loop forever.
+      for await (const _ of sse({ fetch: fetchImpl }, op, prep('u', {}), 'json')) void _;
+    }).rejects.toBeInstanceOf(SseParseError);
+    expect(calls).toBe(1);
+  });
+
+  it('reconnects after a drop, resuming with Last-Event-ID', async () => {
+    const headersSeen: Array<Record<string, string>> = [];
+    let call = 0;
+    const fetchImpl = (async (_url: string, init: RequestInit) => {
+      headersSeen.push({ ...(init.headers as Record<string, string>) });
+      call++;
+      if (call === 1) {
+        // enqueue in start, error in pull: the chunk is read first, THEN the stream drops
+        const body = new ReadableStream<Uint8Array>({
+          start(controller) {
+            controller.enqueue(enc.encode('id: 5\ndata: one\n\n'));
+          },
+          pull(controller) {
+            controller.error(new Error('drop'));
+          },
+        });
+        return new Response(body, { status: 200 });
+      }
+      return streamResponse(['data: two\n\n']);
+    }) as unknown as typeof fetch;
+    const seen: unknown[] = [];
+    for await (const ev of sse(
+      { fetch: fetchImpl },
+      op,
+      prep('u', { reconnectDelay: 1 }),
+      'text'
+    )) {
+      seen.push(ev.data);
+      if (seen.length === 2) break;
+    }
+    expect(seen).toEqual(['one', 'two']);
+    expect(headersSeen[1]['Last-Event-ID']).toBe('5');
+  });
+
+  it('sends the request body on connect and again on reconnect (POST streams)', async () => {
+    const bodiesSeen: unknown[] = [];
+    let call = 0;
+    const fetchImpl = (async (_url: string, init: RequestInit) => {
+      bodiesSeen.push(init.body);
+      call++;
+      if (call === 1) {
+        const body = new ReadableStream<Uint8Array>({
+          start(controller) {
+            controller.enqueue(enc.encode('data: one\n\n'));
+          },
+          pull(controller) {
+            controller.error(new Error('drop'));
+          },
+        });
+        return new Response(body, { status: 200 });
+      }
+      return streamResponse(['data: two\n\n']);
+    }) as unknown as typeof fetch;
+    const prepare = async () => ({
+      url: 'u',
+      init: { method: 'POST', reconnectDelay: 1 } as SseOptions,
+      body: { q: 'x' },
+    });
+    const seen: unknown[] = [];
+    for await (const ev of sse({ fetch: fetchImpl }, op, prepare, 'text')) {
+      seen.push(ev.data);
+      if (seen.length === 2) break;
+    }
+    expect(seen).toEqual(['one', 'two']);
+    expect(bodiesSeen).toEqual(['{"q":"x"}', '{"q":"x"}']);
+  });
+
+  it('re-runs prepare on reconnect so a refreshed credential is sent (not the frozen one)', async () => {
+    const authSeen: Array<string | undefined> = [];
+    let token = 't1';
+    let call = 0;
+    const fetchImpl = (async (_url: string, init: RequestInit) => {
+      authSeen.push((init.headers as Record<string, string>)?.Authorization);
+      call++;
+      if (call === 1) {
+        const body = new ReadableStream<Uint8Array>({
+          start(c) {
+            c.enqueue(enc.encode('data: one\n\n'));
+          },
+          pull(c) {
+            c.error(new Error('drop'));
+          },
+        });
+        return new Response(body, { status: 200 });
+      }
+      return streamResponse(['data: two\n\n']);
+    }) as unknown as typeof fetch;
+    // A refresh-style provider: each (re)connect re-reads the current token.
+    const prepare = async () => {
+      const init: SseOptions = {
+        reconnectDelay: 1,
+        headers: { Authorization: `Bearer ${token}` },
+      };
+      token = 't2';
+      return { url: 'u', init };
+    };
+    const seen: unknown[] = [];
+    for await (const ev of sse({ fetch: fetchImpl }, op, prepare, 'text')) {
+      seen.push(ev.data);
+      if (seen.length === 2) break;
+    }
+    expect(seen).toEqual(['one', 'two']);
+    expect(authSeen).toEqual(['Bearer t1', 'Bearer t2']); // reconnect used the fresh token
+  });
+
+  it('honors the server retry: field for the backoff base and reconnects on empty bodies', async () => {
+    let call = 0;
+    const fetchImpl = (async () => {
+      call++;
+      if (call === 1) {
+        const body = new ReadableStream<Uint8Array>({
+          start(controller) {
+            controller.enqueue(enc.encode('retry: 1\ndata: first\n\n'));
+          },
+          pull(controller) {
+            controller.error(new Error('drop'));
+          },
+        });
+        return new Response(body, { status: 200 });
+      }
+      return streamResponse(['data: second\n\n']);
+    }) as unknown as typeof fetch;
+    const seen: unknown[] = [];
+    for await (const ev of sse({ fetch: fetchImpl }, op, prep('u', {}), 'text')) {
+      seen.push(ev.data);
+      if (seen.length === 2) break;
+    }
+    expect(seen).toEqual(['first', 'second']);
+  });
+
+  it('throws ApiError on a non-2xx initial response (no reconnect loop)', async () => {
+    const bad = (async () => new Response('nope', { status: 500 })) as unknown as typeof fetch;
+    await expect(
+      (async () => {
+        for await (const _ of sse({ fetch: bad }, op, prep('u', {}), 'text')) void _;
+      })()
+    ).rejects.toMatchObject({ status: 500 });
+  });
+
+  it('propagates transport errors when reconnect is off', async () => {
+    const failing = (async () => {
+      throw new Error('net down');
+    }) as unknown as typeof fetch;
+    await expect(
+      (async () => {
+        for await (const _ of sse({ fetch: failing }, op, prep('u', { reconnect: false }), 'text'))
+          void _;
+      })()
+    ).rejects.toThrow('net down');
+  });
+
+  it('returns cleanly on a pre-aborted signal and on a body-less response', async () => {
+    const controller = new AbortController();
+    controller.abort();
+    const okFetch = (async () => streamResponse(['data: x\n\n'])) as unknown as typeof fetch;
+    const seen: unknown[] = [];
+    for await (const ev of sse(
+      { fetch: okFetch },
+      op,
+      prep('u', { signal: controller.signal }),
+      'text'
+    )) {
+      seen.push(ev);
+    }
+    expect(seen).toEqual([]);
+
+    const noBody = (async () => {
+      const r = new Response(null, { status: 200 });
+      Object.defineProperty(r, 'body', { value: null });
+      return r;
+    }) as unknown as typeof fetch;
+    const seen2: unknown[] = [];
+    for await (const ev of sse({ fetch: noBody }, op, prep('u', {}))) seen2.push(ev); // dataKind defaults to 'text'
+    expect(seen2).toEqual([]);
+  });
+
+  it('ends cleanly when the signal aborts during streaming (no reconnect attempt)', async () => {
+    const controller = new AbortController();
+    const fetchImpl = (async () => {
+      const body = new ReadableStream<Uint8Array>({
+        start(c) {
+          c.enqueue(enc.encode('data: one\n\n'));
+        },
+        pull(c) {
+          c.error(new Error('drop'));
+        },
+      });
+      return new Response(body, { status: 200 });
+    }) as unknown as typeof fetch;
+    const seen: unknown[] = [];
+    for await (const ev of sse(
+      { fetch: fetchImpl },
+      op,
+      prep('u', { signal: controller.signal }),
+      'text'
+    )) {
+      seen.push(ev.data);
+      controller.abort(); // the subsequent read error must be treated as an abort, not a drop
+    }
+    expect(seen).toEqual(['one']);
+  });
+
+  it('ends cleanly when the signal aborts during the reconnect backoff (default 1s base)', async () => {
+    const random = vi.spyOn(Math, 'random').mockReturnValue(0.5); // deterministic 500ms backoff
+    try {
+      const controller = new AbortController();
+      const failing = (async () => {
+        setTimeout(() => controller.abort(), 10); // abort while sse sleeps before reconnecting
+        throw new Error('net down');
+      }) as unknown as typeof fetch;
+      const seen: unknown[] = [];
+      for await (const ev of sse(
+        { fetch: failing },
+        op,
+        prep('u', { signal: controller.signal }),
+        'text'
+      )) {
+        seen.push(ev);
+      }
+      expect(seen).toEqual([]);
+    } finally {
+      random.mockRestore();
+    }
+  });
+
+  it('guards against unbounded frames (no delimiter past 1 MiB) and does NOT reconnect on them', async () => {
+    const big = 'data: ' + 'x'.repeat(1_100_000); // no trailing delimiter, single chunk
+    let calls = 0;
+    const fetchImpl = (async () => {
+      calls++;
+      const body = new ReadableStream<Uint8Array>({
+        start(controller) {
+          controller.enqueue(enc.encode(big));
+          // keep the stream open so `done` stays false after the big chunk
+        },
+      });
+      return new Response(body, { status: 200 });
+    }) as unknown as typeof fetch;
+    await expect(
+      (async () => {
+        // `reconnect` defaults to true; the guard must surface, not loop forever.
+        for await (const _ of sse({ fetch: fetchImpl }, op, prep('u', {}), 'text')) void _;
+      })()
+    ).rejects.toBeInstanceOf(SseParseError);
+    expect(calls).toBe(1);
+  });
+});
diff --git a/packages/client-generator/src/runtime/__tests__/types.test.ts b/packages/client-generator/src/runtime/__tests__/types.test.ts
new file mode 100644
index 0000000000..161641b429
--- /dev/null
+++ b/packages/client-generator/src/runtime/__tests__/types.test.ts
@@ -0,0 +1,195 @@
+import type {
+  Client,
+  ClientConfig,
+  Middleware,
+  OperationContext,
+  OperationDescriptor,
+  RequestContext,
+  RequestOptions,
+  Result,
+  ServerSentEvent,
+  SseOptions,
+} from '../types.js';
+
+interface TestOps {
+  requiredArgs: { args: { orderId: string }; result: { id: string } };
+  optionalArgs: { args: { params?: { limit?: number } }; result: string[] };
+  streaming: { args: Record<string, never>; result: { text: string }; kind: 'sse' };
+  listOrders: {
+    args: { params?: { cursor?: string; limit?: number } };
+    result: { orders: Array<{ id: string }>; nextCursor?: string };
+    item: { id: string };
+  };
+  listCafeOrders: { args: { cafeId: string }; result: { orders: string[] }; item: string };
+  [key: string]: { args: object; result: unknown; kind?: 'sse'; item?: unknown };
+}
+
+describe('Client<Ops> mapped type', () => {
+  it('types methods, optionality, and sse per the Ops entry', () => {
+    // Runtime stub — expectTypeOf reads only the static type, but property access must not throw.
+    const client = { auth: {} } as unknown as Client<TestOps>;
+
+    expectTypeOf(client.requiredArgs).toBeCallableWith({ orderId: 'ord_1' });
+    expectTypeOf(client.requiredArgs).toBeCallableWith({ orderId: 'ord_1' }, { parseAs: 'json' });
+    expectTypeOf(client.requiredArgs).returns.resolves.toEqualTypeOf<{ id: string }>();
+
+    // All-optional args → the args object itself is optional.
+    expectTypeOf(client.optionalArgs).toBeCallableWith();
+    expectTypeOf(client.optionalArgs).toBeCallableWith({ params: { limit: 5 } });
+    expectTypeOf(client.optionalArgs).returns.resolves.toEqualTypeOf<string[]>();
+
+    // SSE entries return typed async generators and take SseOptions.
+    expectTypeOf(client.streaming).returns.toEqualTypeOf<
+      AsyncGenerator<ServerSentEvent<{ text: string }>>
+    >();
+    expectTypeOf(client.streaming).toBeCallableWith({}, { reconnect: false } satisfies SseOptions);
+
+    // Core members are always present.
+    expectTypeOf(client.configure).toBeFunction();
+    expectTypeOf(client.use).toBeFunction();
+    expectTypeOf(client.auth.bearer).toBeCallableWith('token');
+    expectTypeOf(client.auth.basic).toBeCallableWith('user', 'pass');
+    expectTypeOf(client.auth.apiKey).toBeCallableWith('scheme', 'key');
+
+    const _typeOnly = (): void => {
+      // @ts-expect-error required args cannot be omitted
+      void client.requiredArgs();
+    };
+    void _typeOnly;
+  });
+
+  it('paginated entries (with `item`) gain typed .pages/.items; other ops expose neither', () => {
+    // Runtime stub with .pages/.items present so property access does not throw.
+    const paginated = Object.assign(() => {}, { pages: () => {}, items: () => {} });
+    const client = {
+      auth: {},
+      listOrders: paginated,
+      listCafeOrders: paginated,
+    } as unknown as Client<TestOps>;
+
+    // The one-shot method is unchanged; .pages yields the result, .items the item type.
+    expectTypeOf(client.listOrders).toBeCallableWith({ params: { cursor: 'c2' } });
+    expectTypeOf(client.listOrders.pages).returns.toEqualTypeOf<
+      AsyncGenerator<{ orders: Array<{ id: string }>; nextCursor?: string }>
+    >();
+    expectTypeOf(client.listOrders.items).returns.toEqualTypeOf<AsyncGenerator<{ id: string }>>();
+
+    // Args optionality mirrors the method's own: all-optional → callable bare.
+    expectTypeOf(client.listOrders.pages).toBeCallableWith();
+    expectTypeOf(client.listOrders.items).toBeCallableWith(
+      { params: { limit: 5 } },
+      { parseAs: 'json' }
+    );
+    expectTypeOf(client.listCafeOrders.items).toBeCallableWith({ cafeId: 'c1' });
+    expectTypeOf(client.listCafeOrders.items).returns.toEqualTypeOf<AsyncGenerator<string>>();
+
+    const _typeOnly = (): void => {
+      // @ts-expect-error non-paginated operations have no .pages
+      void client.requiredArgs.pages;
+      // @ts-expect-error non-paginated operations have no .items
+      void client.optionalArgs.items;
+      // @ts-expect-error required args cannot be omitted on .items either
+      void client.listCafeOrders.items();
+    };
+    void _typeOnly;
+  });
+
+  it('result-mode paginated entries (with `page`) yield RAW pages; the method keeps the envelope', () => {
+    type OrderPage = { orders: Array<{ id: string }>; nextCursor?: string };
+    interface ResultOps {
+      listOrders: {
+        args: { params?: { cursor?: string } };
+        result: Result<OrderPage, { title: string }>;
+        item: { id: string };
+        page: OrderPage;
+      };
+      [key: string]: {
+        args: object;
+        result: unknown;
+        kind?: 'sse';
+        item?: unknown;
+        page?: unknown;
+      };
+    }
+    const client = {
+      auth: {},
+      listOrders: Object.assign(() => {}, { pages: () => {}, items: () => {} }),
+    } as unknown as Client<ResultOps>;
+
+    // The one-shot call still returns the Result envelope…
+    expectTypeOf(client.listOrders).returns.resolves.toEqualTypeOf<
+      Result<OrderPage, { title: string }>
+    >();
+    // …while .pages() yields the RAW page type and .items() the item type.
+    expectTypeOf(client.listOrders.pages).returns.toEqualTypeOf<AsyncGenerator<OrderPage>>();
+    expectTypeOf(client.listOrders.items).returns.toEqualTypeOf<AsyncGenerator<{ id: string }>>();
+  });
+
+  it('paginated descriptor literals satisfy OperationDescriptor', () => {
+    const op = {
+      id: 'listOrders',
+      method: 'GET',
+      path: '/orders',
+      params: [{ name: 'cursor', in: 'query' }],
+      pagination: {
+        style: 'cursor',
+        param: 'cursor',
+        limitParam: 'limit',
+        nextCursor: '/nextCursor',
+        items: '/orders',
+      },
+    } as const satisfies OperationDescriptor;
+    expect(op.pagination.style).toBe('cursor');
+  });
+
+  it('descriptor literals satisfy OperationDescriptor', () => {
+    const op = {
+      id: 'getOrder',
+      method: 'GET',
+      path: '/orders/{orderId}',
+      params: [{ name: 'orderId', in: 'path' }],
+      security: [[{ scheme: 'bearerAuth', kind: 'bearer' }]],
+    } as const satisfies OperationDescriptor;
+    expect(op.id).toBe('getOrder');
+  });
+
+  it('narrows ctx.operation to the literal unions on a narrowed client', () => {
+    type Narrow = OperationContext<'listPets' | 'getPet', '/pets' | '/pets/{id}', 'pets'>;
+    const client = { auth: {} } as unknown as Client<TestOps, Narrow>;
+
+    // Type-only: `use` narrows the callback ctx; a base (contract-shaped) middleware
+    // and a base config stay accepted (contravariance of the callback params).
+    const _typeOnly = (): void => {
+      client.use({
+        onRequest: (ctx) => {
+          expectTypeOf(ctx.operation.id).toEqualTypeOf<'listPets' | 'getPet'>();
+          expectTypeOf(ctx.operation.path).toEqualTypeOf<'/pets' | '/pets/{id}'>();
+          expectTypeOf(ctx.operation.tags).toEqualTypeOf<'pets'[]>();
+          // @ts-expect-error a misspelled operationId has no overlap with the literal union
+          if (ctx.operation.id === 'listPetss') return;
+        },
+      });
+      const baseMiddleware: Middleware = { onRequest: (ctx) => void ctx.operation.id };
+      client.use(baseMiddleware);
+      const baseConfig: ClientConfig = { middleware: [baseMiddleware] };
+      client.configure(baseConfig);
+    };
+    void _typeOnly;
+
+    // The narrowed context stays assignable to the base shape (covariance).
+    expectTypeOf<RequestContext<Narrow>>().toExtend<RequestContext>();
+    expectTypeOf<ClientConfig>().toExtend<ClientConfig<Narrow>>();
+  });
+
+  it('Result discriminates on error', () => {
+    // When error is present, data is typed undefined (and vice versa).
+    expectTypeOf<
+      Extract<Result<string, { title: string }>, { error: { title: string } }>['data']
+    >().toEqualTypeOf<undefined>();
+    expectTypeOf<
+      Extract<Result<string, { title: string }>, { error: undefined }>['data']
+    >().toEqualTypeOf<string>();
+    const init: RequestOptions = { retry: { retries: 1 }, parseAs: 'auto' };
+    expect(init.parseAs).toBe('auto');
+  });
+});
diff --git a/packages/client-generator/src/runtime/__tests__/url.test.ts b/packages/client-generator/src/runtime/__tests__/url.test.ts
new file mode 100644
index 0000000000..3e5c668f2c
--- /dev/null
+++ b/packages/client-generator/src/runtime/__tests__/url.test.ts
@@ -0,0 +1,125 @@
+import { buildUrl, encodeReserved, substitutePath } from '../url.js';
+
+describe('substitutePath', () => {
+  it('substitutes and encodes path params', () => {
+    expect(substitutePath('/orders/{orderId}/items/{itemId}', { orderId: 'a/b', itemId: 42 })).toBe(
+      '/orders/a%2Fb/items/42'
+    );
+  });
+
+  it('throws on a missing param', () => {
+    expect(() => substitutePath('/orders/{orderId}', {})).toThrow(/orderId/);
+  });
+});
+
+describe('encodeReserved', () => {
+  it('keeps the RFC-3986 reserved set literal while encoding the rest', () => {
+    expect(encodeReserved("a/b?c#d[e]@f!g$h&i'j(k)l*m+n,o;p=q r")).toBe(
+      "a/b?c#d[e]@f!g$h&i'j(k)l*m+n,o;p=q%20r"
+    );
+  });
+});
+
+describe('buildUrl', () => {
+  it('trims any run of trailing slashes in linear time', () => {
+    expect(buildUrl('https://x///', '/p')).toBe('https://x/p');
+    // Adversarial many-slash input must not blow up (the old regex was quadratic).
+    const start = Date.now();
+    expect(buildUrl('https://x' + '/'.repeat(100_000), '/p')).toBe('https://x/p');
+    expect(Date.now() - start).toBeLessThan(1_000);
+  });
+
+  const base = 'https://api.example.com/';
+
+  it('trims trailing slashes and appends the path; no query → no ?', () => {
+    expect(buildUrl(base, '/menu')).toBe('https://api.example.com/menu');
+    expect(buildUrl(base, '/menu', {})).toBe('https://api.example.com/menu');
+  });
+
+  it('default form+explode repeats arrays, skips null/undefined (top level and in arrays)', () => {
+    expect(
+      buildUrl(base, '/m', {
+        tags: ['a', 'b', null, undefined],
+        skip: undefined,
+        gone: null,
+        limit: 5,
+      })
+    ).toBe('https://api.example.com/m?tags=a&tags=b&limit=5');
+  });
+
+  it('object values without a spec serialize as deepObject brackets, skipping empty entries', () => {
+    expect(buildUrl(base, '/m', { f: { color: 'red', size: 'L', none: null } })).toBe(
+      'https://api.example.com/m?f%5Bcolor%5D=red&f%5Bsize%5D=L'
+    );
+  });
+
+  it('form explode=true with allowReserved emits raw pairs; without it appends params', () => {
+    expect(
+      buildUrl(
+        base,
+        '/m',
+        { t: ['a/b', 'c'] },
+        { t: { style: 'form', explode: true, allowReserved: true } }
+      )
+    ).toBe('https://api.example.com/m?t=a/b&t=c');
+    expect(buildUrl(base, '/m', { t: ['a b'] }, { t: { style: 'form', explode: true } })).toBe(
+      'https://api.example.com/m?t=a+b'
+    );
+  });
+
+  it('delimited styles use LITERAL delimiters with encoded values', () => {
+    expect(buildUrl(base, '/m', { t: ['a', 'b'] }, { t: { style: 'form', explode: false } })).toBe(
+      'https://api.example.com/m?t=a,b'
+    );
+    expect(
+      buildUrl(base, '/m', { t: ['a b', 'c'] }, { t: { style: 'pipeDelimited', explode: false } })
+    ).toBe('https://api.example.com/m?t=a%20b|c');
+    expect(
+      buildUrl(base, '/m', { t: ['a', 'c'] }, { t: { style: 'spaceDelimited', explode: false } })
+    ).toBe('https://api.example.com/m?t=a%20c');
+    expect(
+      buildUrl(
+        base,
+        '/m',
+        { t: ['a/b'] },
+        { t: { style: 'pipeDelimited', explode: false, allowReserved: true } }
+      )
+    ).toBe('https://api.example.com/m?t=a/b');
+  });
+
+  it('objects with a spec serialize as brackets (allowReserved switches to raw pairs)', () => {
+    expect(
+      buildUrl(
+        base,
+        '/m',
+        { f: { a: '1', skip: null } },
+        { f: { style: 'deepObject', explode: true } }
+      )
+    ).toBe('https://api.example.com/m?f%5Ba%5D=1');
+    expect(
+      buildUrl(
+        base,
+        '/m',
+        { f: { a: 'x/y' } },
+        { f: { style: 'deepObject', explode: true, allowReserved: true } }
+      )
+    ).toBe('https://api.example.com/m?f[a]=x/y');
+  });
+
+  it('scalars with a spec: allowReserved raw vs encoded append; skipped when null', () => {
+    expect(
+      buildUrl(
+        base,
+        '/m',
+        { filter: 'a/b' },
+        { filter: { style: 'form', explode: true, allowReserved: true } }
+      )
+    ).toBe('https://api.example.com/m?filter=a/b');
+    expect(
+      buildUrl(base, '/m', { filter: 'a b' }, { filter: { style: 'form', explode: true } })
+    ).toBe('https://api.example.com/m?filter=a+b');
+    expect(
+      buildUrl(base, '/m', { filter: null }, { filter: { style: 'form', explode: true } })
+    ).toBe('https://api.example.com/m');
+  });
+});
diff --git a/packages/client-generator/src/runtime/auth.ts b/packages/client-generator/src/runtime/auth.ts
new file mode 100644
index 0000000000..78113a4c15
--- /dev/null
+++ b/packages/client-generator/src/runtime/auth.ts
@@ -0,0 +1,64 @@
+import type { ClientConfig, SecuritySpec, TokenProvider } from './types.js';
+
+/** Resolve a credential: a literal passes through; a function is awaited per request. */
+async function resolveToken(provider: TokenProvider): Promise<string> {
+  return typeof provider === 'function' ? await provider() : provider;
+}
+
+/** UTF-8-safe base64: bare `btoa` throws on non-Latin-1 credentials (RFC 7617 allows UTF-8). */
+function encodeBase64(text: string): string {
+  let binary = '';
+  for (const byte of new TextEncoder().encode(text)) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+
+/** Whether a credential for this scheme is configured on the instance. */
+function isConfigured(scheme: SecuritySpec, config: ClientConfig): boolean {
+  if (scheme.kind === 'apiKey') return config.auth?.apiKey?.[scheme.scheme] !== undefined;
+  if (scheme.kind === 'bearer') return config.auth?.bearer !== undefined;
+  return config.auth?.basic !== undefined;
+}
+
+/**
+ * Build the auth headers/query for one operation's `security` OR-alternatives from the
+ * instance credentials (`config.auth`) — capability module, wired into `createClient`.
+ * The first alternative whose schemes (an AND-set) are all configured is applied, so
+ * "bearer OR apiKey" works with either credential and never sends both. When none is
+ * fully configured, the first alternative's configured schemes are still sent (the
+ * server rejects the request, mirroring the previous behavior).
+ * Cookie-borne apiKeys fold into a single `Cookie` header joined with `; `.
+ */
+export async function resolveAuth(
+  security: readonly (readonly SecuritySpec[])[],
+  config: ClientConfig
+): Promise<{ headers: Record<string, string>; query: Record<string, string> }> {
+  const alternative =
+    security.find((schemes) => schemes.every((scheme) => isConfigured(scheme, config))) ??
+    security[0] ??
+    [];
+  const headers: Record<string, string> = {};
+  const query: Record<string, string> = {};
+  const cookies: string[] = [];
+  for (const scheme of alternative) {
+    if (scheme.kind === 'apiKey') {
+      const provider = config.auth?.apiKey?.[scheme.scheme];
+      if (provider === undefined) continue;
+      const value = await resolveToken(provider);
+      if (scheme.in === 'header') headers[scheme.name] = value;
+      else if (scheme.in === 'query') query[scheme.name] = value;
+      // Cookie values may contain reserved characters (`;`, `=`, space, …); percent-encode
+      // so the credential can't break the `Cookie` header syntax.
+      else cookies.push(`${scheme.name}=${encodeURIComponent(value)}`);
+    } else if (scheme.kind === 'bearer') {
+      const provider = config.auth?.bearer;
+      if (provider !== undefined) headers.Authorization = `Bearer ${await resolveToken(provider)}`;
+    } else {
+      const basic = config.auth?.basic;
+      if (basic !== undefined) {
+        headers.Authorization = `Basic ${encodeBase64(`${basic.username}:${basic.password}`)}`;
+      }
+    }
+  }
+  if (cookies.length > 0) headers.Cookie = cookies.join('; ');
+  return { headers, query };
+}
diff --git a/packages/client-generator/src/runtime/create-client.ts b/packages/client-generator/src/runtime/create-client.ts
new file mode 100644
index 0000000000..612c48b1c8
--- /dev/null
+++ b/packages/client-generator/src/runtime/create-client.ts
@@ -0,0 +1,348 @@
+import { ApiError } from './errors.js';
+import { parse, readError } from './parse.js';
+import { middlewareChain, send, toHeaderRecord, type SendCapabilities } from './send.js';
+import type {
+  ApiErrorLike,
+  Client,
+  ClientConfig,
+  Middleware,
+  OperationContext,
+  OperationDescriptor,
+  OpsShape,
+  PaginationSpec,
+  ParseAs,
+  QueryValue,
+  RequestOptions,
+  SecuritySpec,
+  ServerSentEvent,
+  SseOptions,
+  TokenProvider,
+} from './types.js';
+import { buildUrl, substitutePath, type QueryStyle } from './url.js';
+
+/**
+ * The optional behaviors `createClientCore` can dispatch to but never statically
+ * imports. The package's public `createClient` wires the full set; the future
+ * inline-mode assembler wires only the capabilities a spec needs.
+ */
+export type Capabilities = SendCapabilities & {
+  resolveAuth?: (
+    security: readonly (readonly SecuritySpec[])[],
+    config: ClientConfig
+  ) => Promise<{ headers: Record<string, string>; query: Record<string, string> }>;
+  sse?: (
+    config: ClientConfig,
+    op: OperationContext,
+    // Re-preparing per (re)connect (not a frozen url/init) lets a refresh-style
+    // TokenProvider issue a fresh credential after a dropped stream reconnects.
+    prepare: () => Promise<{ url: string; init: SseOptions }>,
+    dataKind: 'json' | 'text'
+  ) => AsyncGenerator<ServerSentEvent<unknown>>;
+  paginate?: {
+    pages: (
+      call: (args?: OperationArgs, init?: RequestOptions) => Promise<unknown>,
+      spec: PaginationSpec,
+      args?: OperationArgs,
+      init?: RequestOptions
+    ) => AsyncGenerator<unknown>;
+    items: (
+      call: (args?: OperationArgs, init?: RequestOptions) => Promise<unknown>,
+      spec: PaginationSpec,
+      args?: OperationArgs,
+      init?: RequestOptions
+    ) => AsyncGenerator<unknown>;
+  };
+};
+
+/** The grouped args wire shape: path params by name plus the `params`/`body`/`headers`/`cookies` slots. */
+export type OperationArgs = {
+  params?: Record<string, QueryValue>;
+  body?: unknown;
+  headers?: Record<string, unknown>;
+  cookies?: Record<string, unknown>;
+} & Record<string, unknown>;
+
+/** The response reader implied by the descriptor (before any per-call `parseAs` override). */
+function kindFor(op: OperationDescriptor): ParseAs | 'void' {
+  if (op.responseKind === 'void' || op.responseKind === 'blob' || op.responseKind === 'text') {
+    return op.responseKind;
+  }
+  return 'auto';
+}
+
+/** Route the grouped args by the descriptor: path values, query object, body, extra headers, cookies. */
+function splitArgs(op: OperationDescriptor, args: OperationArgs) {
+  const path: Record<string, unknown> = {};
+  for (const param of op.params ?? []) {
+    if (param.in === 'path') path[param.name] = args[param.name];
+  }
+  return {
+    path,
+    query: args.params,
+    body: args.body,
+    headers: args.headers,
+    cookies: args.cookies,
+  };
+}
+
+/**
+ * The query-serialization hints for the descriptor's query params. A spec is built only
+ * when the param deviates from the OpenAPI defaults (`form` + `explode: true`, encoded),
+ * and always fully resolved — so `explode: false` or `allowReserved` alone (no `style`)
+ * are honored, and an omitted `explode` keeps the exploded default.
+ */
+function queryStyles(op: OperationDescriptor): Record<string, QueryStyle> | undefined {
+  let styles: Record<string, QueryStyle> | undefined;
+  for (const param of op.params ?? []) {
+    if (param.in !== 'query') continue;
+    const deviates =
+      (param.style !== undefined && param.style !== 'form') ||
+      param.explode === false ||
+      param.allowReserved === true;
+    if (!deviates) continue;
+    styles ??= {};
+    styles[param.name] = {
+      style: param.style ?? 'form',
+      explode: param.explode ?? true,
+      allowReserved: param.allowReserved,
+    };
+  }
+  return styles;
+}
+
+/** Stringify caller-supplied extra headers, skipping empty entries. */
+function stringHeaders(headers: Record<string, unknown> | undefined): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [key, value] of Object.entries(headers ?? {})) {
+    if (value !== undefined && value !== null) out[key] = String(value);
+  }
+  return out;
+}
+
+/** Build the request pieces an attempt needs: the final URL and the merged per-call init. */
+async function prepareRequest(
+  config: ClientConfig,
+  op: OperationDescriptor,
+  args: OperationArgs,
+  init: RequestOptions | SseOptions,
+  caps: Capabilities
+): Promise<{ url: string; init: RequestOptions; body: unknown }> {
+  const { path, query, body, headers, cookies } = splitArgs(op, args);
+  const authed: { headers: Record<string, string>; query: Record<string, string> } =
+    op.security?.length && caps.resolveAuth
+      ? await caps.resolveAuth(op.security, config)
+      : { headers: {}, query: {} };
+  // Cookie params join the auth-injected cookies in one `Cookie` header (values
+  // percent-encoded, like auth cookies). Server-side only — browsers own the header.
+  const cookiePairs = Object.entries(cookies ?? {})
+    .filter(([, value]) => value !== undefined && value !== null)
+    .map(([cookieName, value]) => `${cookieName}=${encodeURIComponent(String(value))}`);
+  if (cookiePairs.length > 0) {
+    authed.headers.Cookie = [authed.headers.Cookie, ...cookiePairs].filter(Boolean).join('; ');
+  }
+  const fullQuery: Record<string, QueryValue> = { ...query, ...authed.query };
+  const url = buildUrl(
+    config.serverUrl ?? '',
+    substitutePath(op.path, path),
+    Object.keys(fullQuery).length > 0 ? fullQuery : undefined,
+    queryStyles(op)
+  );
+  const mergedInit: RequestOptions = {
+    ...init,
+    method: op.method.toUpperCase(),
+    // Precedence, lowest → highest (later spreads win): injected auth → explicit
+    // header params → caller `init.headers` — the caller always overrides both.
+    headers: {
+      ...authed.headers,
+      ...stringHeaders(headers),
+      ...toHeaderRecord(init.headers),
+    },
+  };
+  return { url, init: mergedInit, body };
+}
+
+/** One non-SSE call: send, then branch on the configured error mode. */
+async function execute(
+  config: ClientConfig,
+  op: OperationDescriptor,
+  args: OperationArgs,
+  init: RequestOptions,
+  caps: Capabilities
+): Promise<unknown> {
+  const prepared = await prepareRequest(config, op, args, init, caps);
+  const opCtx: OperationContext = { id: op.id, path: op.path, tags: [...(op.tags ?? [])] };
+  const { parseAs, ...sendInit } = prepared.init;
+  const { response, context } = await send(
+    config,
+    opCtx,
+    prepared.url,
+    sendInit,
+    prepared.body,
+    op.body?.multipart === true,
+    caps
+  );
+  const readKind = parseAs ?? kindFor(op);
+  if (config.errorMode === 'result') {
+    if (!response.ok) {
+      return { data: undefined, error: await readError(response), response };
+    }
+    return { data: await parse(response, readKind), error: undefined, response };
+  }
+  if (!response.ok) {
+    let error: globalThis.Error = new ApiError(
+      context.url,
+      response.status,
+      response.statusText,
+      await readError(response)
+    );
+    // Thread the error through each middleware's onError in turn (each may replace it).
+    for (const mw of middlewareChain(config)) {
+      if (mw.onError) error = await mw.onError(error as ApiErrorLike, context);
+    }
+    throw error;
+  }
+  return parse(response, readKind);
+}
+
+/** The paginate capability, or a descriptive throw when a paginated op is iterated unwired. */
+function paginateCapability(caps: Capabilities, op: OperationDescriptor) {
+  if (!caps.paginate) {
+    throw new Error(`Pagination capability not wired: cannot iterate operation "${op.id}"`);
+  }
+  return caps.paginate;
+}
+
+/**
+ * The per-page call the iterators drive: the method itself in throw mode; in result
+ * mode a wrapper that unwraps the `{ data, error, response }` envelope — the page
+ * pointers are data-rooted — rethrowing a failed page as `ApiError` (iteration is
+ * error-mode-agnostic; the throw-mode-only `onError` middleware hook is not invoked).
+ */
+function pageCall(
+  method: (args?: OperationArgs, init?: RequestOptions) => Promise<unknown>,
+  config: ClientConfig
+) {
+  if (config.errorMode !== 'result') return method;
+  return async (args?: OperationArgs, init?: RequestOptions) => {
+    const envelope = (await method(args, init)) as {
+      data: unknown;
+      error: unknown;
+      response: Response;
+    };
+    // Failure is `!response.ok` — NOT `data === undefined`: a successful bodyless page
+    // (204/void) also parses to undefined data, and a failed page's `error` can be
+    // undefined too (unreadable body). The pointers then miss on the undefined data
+    // and iteration stops cleanly, which is the correct semantics for an empty page.
+    if (!envelope.response.ok) {
+      const { response } = envelope;
+      throw new ApiError(response.url, response.status, response.statusText, envelope.error);
+    }
+    return envelope.data;
+  };
+}
+
+/**
+ * Build a typed instance client over operation descriptors: one real bound method per
+ * operation (attached by a construction-time loop — no Proxy), plus the core members
+ * (`configure`/`use`/`auth`), which are assigned AFTER the loop so they win any name
+ * collision with an operation. All behavior dispatches through the capability seam.
+ */
+export function createClientCore<
+  Ops extends OpsShape,
+  Id extends string = string,
+  Path extends string = string,
+  Tag extends string = string,
+>(
+  operations: Record<string, OperationDescriptor>,
+  initial: ClientConfig<OperationContext<Id, Path, Tag>> = {},
+  caps: Capabilities = {}
+): Client<Ops, OperationContext<Id, Path, Tag>> {
+  // The literal-union narrowing is a compile-time DX contract only; internally the
+  // runtime works with the base (string-typed) context. One cast at this boundary —
+  // `ClientConfig<Narrow>` is not assignable to `ClientConfig` (middleware ctx
+  // params are contravariant).
+  const given = initial as ClientConfig;
+  // Private mutable config; the middleware array is copied so `use()` never mutates the caller's.
+  const config: ClientConfig = { ...given, middleware: [...(given.middleware ?? [])] };
+  const client = {} as Record<string, unknown>;
+
+  for (const [name, op] of Object.entries(operations)) {
+    if (op.responseKind === 'sse') {
+      const method = (args: OperationArgs = {}, init: SseOptions = {}) => {
+        if (!caps.sse) {
+          throw new Error(`SSE capability not wired: cannot stream operation "${op.id}"`);
+        }
+        const stream = caps.sse;
+        return (async function* () {
+          const opCtx: OperationContext = { id: op.id, path: op.path, tags: [...(op.tags ?? [])] };
+          // A thunk the stream re-runs on every (re)connect, so auth (which `prepareRequest`
+          // resolves) is refreshed per attempt rather than frozen at the first connect.
+          const prepare = async () => {
+            const prepared = await prepareRequest(config, op, args, init, caps);
+            return { url: prepared.url, init: prepared.init as SseOptions, body: prepared.body };
+          };
+          yield* stream(config, opCtx, prepare, op.sseDataKind ?? 'text');
+        })();
+      };
+      // Consumers key off the function reference (cache keys, `OPERATIONS[fn.name]`), so
+      // each closure carries its operationId instead of an inferred binding name.
+      Object.defineProperty(method, 'name', { value: name });
+      client[name] = method;
+    } else {
+      const method = (args: OperationArgs = {}, init: RequestOptions = {}) =>
+        execute(config, op, args, init, caps);
+      Object.defineProperty(method, 'name', { value: name });
+      const spec = op.pagination;
+      // Paginated ops keep their one-shot call and gain `.pages`/`.items`, dispatching
+      // through the capability seam (like SSE: absent capability throws descriptively).
+      // Iteration is error-mode-agnostic: the iterators' pointers are data-rooted, so on
+      // a result-mode client (`errorMode` is fixed at construction — `configure()`
+      // ignores it) each page's envelope is unwrapped before it reaches the capability.
+      // A failed page aborts iteration by throwing ApiError, even on result-mode
+      // clients; the `onError` middleware hook (throw-mode-only) is not invoked.
+      client[name] = spec
+        ? Object.assign(method, {
+            pages: (args?: OperationArgs, init?: RequestOptions) =>
+              paginateCapability(caps, op).pages(pageCall(method, config), spec, args, init),
+            items: (args?: OperationArgs, init?: RequestOptions) =>
+              paginateCapability(caps, op).items(pageCall(method, config), spec, args, init),
+          })
+        : method;
+    }
+  }
+
+  // Core members are assigned AFTER the operation loop — they win over colliding op names.
+  client.configure = (next: ClientConfig): void => {
+    // `errorMode` is fixed at generate time (it shapes the static types); flipping it at
+    // runtime would silently desync return shapes from `Client<Ops>`, so it is ignored.
+    const { errorMode: _fixed, auth, ...rest } = next;
+    Object.assign(config, rest);
+    // `auth` merges into existing credentials (like the `auth.*` setters) rather than
+    // replacing wholesale — so `configure({ auth: { bearer } })` keeps a previously set
+    // basic/apiKey. `apiKey` merges per scheme.
+    if (auth) {
+      config.auth = {
+        ...config.auth,
+        ...auth,
+        ...(auth.apiKey ? { apiKey: { ...config.auth?.apiKey, ...auth.apiKey } } : {}),
+      };
+    }
+  };
+  client.use = (...middleware: Middleware[]): void => {
+    // Reassign (don't push) so a caller-provided `middleware` array isn't mutated.
+    config.middleware = [...(config.middleware ?? []), ...middleware];
+  };
+  client.auth = {
+    bearer(token: TokenProvider): void {
+      config.auth = { ...config.auth, bearer: token };
+    },
+    basic(username: string, password: string): void {
+      config.auth = { ...config.auth, basic: { username, password } };
+    },
+    apiKey(scheme: string, value: TokenProvider): void {
+      config.auth = { ...config.auth, apiKey: { ...config.auth?.apiKey, [scheme]: value } };
+    },
+  };
+
+  return client as Client<Ops, OperationContext<Id, Path, Tag>>;
+}
diff --git a/packages/client-generator/src/runtime/errors.ts b/packages/client-generator/src/runtime/errors.ts
new file mode 100644
index 0000000000..a08cc058de
--- /dev/null
+++ b/packages/client-generator/src/runtime/errors.ts
@@ -0,0 +1,24 @@
+/** The error thrown (throw mode) for a non-2xx response, carrying the decoded error body. */
+export class ApiError extends Error {
+  public readonly url: string;
+  public readonly status: number;
+  public readonly statusText: string;
+  public readonly body: unknown;
+  constructor(url: string, status: number, statusText: string, body: unknown) {
+    super(`Request failed with status ${status}`);
+    this.name = 'ApiError';
+    this.url = url;
+    this.status = status;
+    this.statusText = statusText;
+    this.body = body;
+  }
+}
+
+/** The error to throw for an aborted request: the caller's abort reason when it is an Error. */
+// `globalThis.Error` (not bare `Error`) so a spec schema named `Error` cannot shadow it
+// when this module is embedded alongside generated types (inline mode).
+export function abortError(signal: AbortSignal): globalThis.Error {
+  const reason = (signal as { reason?: unknown }).reason;
+  if (reason instanceof Error) return reason;
+  return new DOMException('The operation was aborted.', 'AbortError');
+}
diff --git a/packages/client-generator/src/runtime/index.ts b/packages/client-generator/src/runtime/index.ts
new file mode 100644
index 0000000000..465d02af20
--- /dev/null
+++ b/packages/client-generator/src/runtime/index.ts
@@ -0,0 +1,41 @@
+import { resolveAuth } from './auth.js';
+import { createClientCore } from './create-client.js';
+import { toFormData } from './multipart.js';
+import { items, pages } from './paginate.js';
+import { sse } from './sse.js';
+import type {
+  Client,
+  ClientConfig,
+  OperationContext,
+  OperationDescriptor,
+  OpsShape,
+} from './types.js';
+
+/**
+ * The public client factory for package-mode generated clients: `createClientCore`
+ * with the full capability set wired (multipart, auth, SSE, pagination). The capability seam
+ * itself stays internal — the future inline assembler wires only what a spec needs.
+ * The trailing string params carry the generated literal unions
+ * (`OperationId`/`OperationPath`/`OperationTag`) into `ctx.operation` for
+ * middleware targeting; their defaults keep spec-independent callers untyped.
+ */
+export function createClient<
+  Ops extends OpsShape,
+  Id extends string = string,
+  Path extends string = string,
+  Tag extends string = string,
+>(
+  operations: Record<string, OperationDescriptor>,
+  config?: ClientConfig<OperationContext<Id, Path, Tag>>
+): Client<Ops, OperationContext<Id, Path, Tag>> {
+  return createClientCore<Ops, Id, Path, Tag>(operations, config, {
+    serializeMultipart: toFormData,
+    resolveAuth,
+    sse,
+    paginate: { pages, items },
+  });
+}
+
+export { ApiError } from './errors.js';
+export { mergeSetup } from './setup.js';
+export type * from './types.js';
diff --git a/packages/client-generator/src/runtime/multipart.ts b/packages/client-generator/src/runtime/multipart.ts
new file mode 100644
index 0000000000..7c4da05341
--- /dev/null
+++ b/packages/client-generator/src/runtime/multipart.ts
@@ -0,0 +1,22 @@
+/**
+ * Serialize a plain object into `FormData` for a typed `multipart/form-data` body
+ * (capability module — wired into `createClient`, never imported by the send core).
+ * `Blob`/`File` and strings pass through; `Date`s become ISO strings; arrays append
+ * one field per item; other objects are JSON-encoded; everything else is stringified.
+ * `undefined`/`null` entries are skipped.
+ */
+export function toFormData(body: Record<string, unknown>): FormData {
+  const fd = new FormData();
+  const append = (key: string, value: unknown): void => {
+    if (value === undefined || value === null) return;
+    if (value instanceof Blob || typeof value === 'string') fd.append(key, value);
+    else if (value instanceof Date) fd.append(key, value.toISOString());
+    else if (Object(value) === value) fd.append(key, JSON.stringify(value));
+    else fd.append(key, String(value));
+  };
+  for (const [key, value] of Object.entries(body)) {
+    if (Array.isArray(value)) for (const item of value) append(key, item);
+    else append(key, value);
+  }
+  return fd;
+}
diff --git a/packages/client-generator/src/runtime/paginate.ts b/packages/client-generator/src/runtime/paginate.ts
new file mode 100644
index 0000000000..2674836fac
--- /dev/null
+++ b/packages/client-generator/src/runtime/paginate.ts
@@ -0,0 +1,112 @@
+import type { OperationArgs } from './create-client.js';
+import type { PaginationSpec, QueryValue, RequestOptions } from './types.js';
+
+/**
+ * Auto-pagination (capability module — wired into `createClient`, dispatched by the
+ * method's `.pages()`/`.items()`): walk an operation's pages by advancing the descriptor's
+ * `param` query parameter, per its `style`. The caller's args are never mutated — each
+ * request gets a fresh `params` clone — and `init` is forwarded to every call.
+ *
+ * Iteration is error-mode-agnostic: `call` always resolves to the RAW page (on a
+ * result-mode client the attachment unwraps the envelope first), so a failed page
+ * aborts iteration by throwing `ApiError`, even on result-mode clients; the `onError`
+ * middleware hook (throw-mode-only) is not invoked.
+ */
+
+/**
+ * Resolve an RFC 6901 JSON pointer (`~1` → `/`, `~0` → `~`) against a value.
+ * The empty pointer is the whole document; anything else must start with `/`.
+ * Returns `undefined` on any miss (bad token, absent key, non-object step) — never throws.
+ */
+export function resolvePointer(value: unknown, pointer: string): unknown {
+  if (pointer === '') return value;
+  if (!pointer.startsWith('/')) return undefined;
+  let current = value;
+  for (const token of pointer.slice(1).split('/')) {
+    const key = token.replaceAll('~1', '/').replaceAll('~0', '~');
+    if (Array.isArray(current)) {
+      if (!/^(0|[1-9]\d*)$/.test(key)) return undefined;
+      current = current[Number(key)];
+    } else if (Object(current) === current && key in (current as object)) {
+      current = (current as Record<string, unknown>)[key];
+    } else {
+      return undefined;
+    }
+  }
+  return current;
+}
+
+/**
+ * Iterate an operation's full page results. Every page is yielded before the stop
+ * condition is evaluated, so the last page always arrives. Cursor style resumes from a
+ * caller-provided `params[spec.param]`, stops when the optional `hasMore` pointer
+ * resolves to `false` or when `nextCursor` resolves to `undefined`/`null`/`''`, and
+ * throws if the next cursor is not a string or number, or
+ * if the same cursor comes back twice in a row (infinite-loop guards). Offset/page
+ * styles advance by item count / by one and stop when
+ * the `items` pointer misses or the array is empty.
+ */
+export async function* pages<TPage>(
+  call: (args?: OperationArgs, init?: RequestOptions) => Promise<TPage>,
+  spec: PaginationSpec,
+  args: OperationArgs = {},
+  init?: RequestOptions
+): AsyncGenerator<TPage> {
+  if (spec.style === 'cursor') {
+    let cursor: unknown = args.params?.[spec.param];
+    while (true) {
+      const params = { ...args.params };
+      if (cursor !== undefined) params[spec.param] = cursor as QueryValue;
+      const page = await call({ ...args, params }, init);
+      yield page;
+      // Connection-style APIs keep a non-null cursor on the last page and signal the
+      // end via a boolean flag — honor it before the cursor check to skip the
+      // follow-up empty request. Strictly `false`: a missing pointer falls through.
+      if (spec.hasMore !== undefined && resolvePointer(page, spec.hasMore) === false) return;
+      const next = resolvePointer(page, spec.nextCursor!);
+      if (next === undefined || next === null || next === '') return;
+      if (typeof next !== 'string' && typeof next !== 'number') {
+        // A fresh non-scalar cursor never compares equal, so without this guard a lying
+        // server would slip past the did-not-advance check into an infinite loop.
+        throw new Error(`Pagination cursor at ${spec.nextCursor} is not a string or number`);
+      }
+      if (next === cursor) {
+        throw new Error('Pagination did not advance: operation returned the same cursor twice');
+      }
+      cursor = next;
+    }
+  } else {
+    // Coerce the starting position to a number: a caller may pass `params[spec.param]` as a
+    // string (common from URL/form input), and `+=` on a string would concatenate.
+    const start = args.params?.[spec.param];
+    const fallback = spec.style === 'page' ? 1 : 0;
+    let position = start === undefined || Number.isNaN(Number(start)) ? fallback : Number(start);
+    while (true) {
+      const page = await call(
+        { ...args, params: { ...args.params, [spec.param]: position } },
+        init
+      );
+      yield page;
+      const pageItems = resolvePointer(page, spec.items);
+      if (!Array.isArray(pageItems) || pageItems.length === 0) return;
+      position += spec.style === 'page' ? 1 : pageItems.length;
+    }
+  }
+}
+
+/**
+ * Iterate the operation's individual items: each page's `items` pointer, flattened.
+ * A cursor-style page whose pointer misses yields nothing but pagination continues;
+ * for offset/page styles a miss has already stopped `pages`.
+ */
+export async function* items<TItem>(
+  call: (args?: OperationArgs, init?: RequestOptions) => Promise<unknown>,
+  spec: PaginationSpec,
+  args?: OperationArgs,
+  init?: RequestOptions
+): AsyncGenerator<TItem> {
+  for await (const page of pages(call, spec, args, init)) {
+    const pageItems = resolvePointer(page, spec.items);
+    if (Array.isArray(pageItems)) yield* pageItems as TItem[];
+  }
+}
diff --git a/packages/client-generator/src/runtime/parse.ts b/packages/client-generator/src/runtime/parse.ts
new file mode 100644
index 0000000000..31069ef21b
--- /dev/null
+++ b/packages/client-generator/src/runtime/parse.ts
@@ -0,0 +1,30 @@
+import type { ParseAs } from './types.js';
+
+/**
+ * Read the response body per `kind`. `'auto'` negotiates from the content type
+ * (JSON, then `text/*`, then Blob); `'void'` and `204` responses read nothing.
+ */
+export async function parse(response: Response, kind: ParseAs | 'void'): Promise<unknown> {
+  if (kind === 'void' || response.status === 204) return undefined;
+  if (kind === 'stream') return response.body;
+  if (kind === 'blob') return response.blob();
+  if (kind === 'arrayBuffer') return response.arrayBuffer();
+  if (kind === 'formData') return response.formData();
+  if (kind === 'text') return response.text();
+  if (kind === 'json') return response.json();
+  // 'auto' — negotiate from the response's content type (case-insensitively:
+  // `Text/Plain` and `application/JSON` are valid per RFC 9110).
+  const contentType = (response.headers.get('content-type') ?? '').toLowerCase();
+  if (contentType.includes('json')) return response.json();
+  if (contentType.startsWith('text/')) return response.text();
+  return response.blob();
+}
+
+/** Best-effort decode of a non-2xx body (JSON when declared, else text; undefined on failure). */
+export async function readError(response: Response): Promise<unknown> {
+  const contentType = response.headers.get('content-type') ?? '';
+  if (contentType.toLowerCase().includes('json')) {
+    return response.json().catch(() => undefined);
+  }
+  return response.text().catch(() => undefined);
+}
diff --git a/packages/client-generator/src/runtime/retry.ts b/packages/client-generator/src/runtime/retry.ts
new file mode 100644
index 0000000000..d1d6648108
--- /dev/null
+++ b/packages/client-generator/src/runtime/retry.ts
@@ -0,0 +1,50 @@
+import { abortError } from './errors.js';
+import type { RetryConfig, RetryContext } from './types.js';
+
+const IDEMPOTENT_METHODS = new Set(['GET', 'HEAD', 'PUT', 'DELETE', 'OPTIONS']);
+const TRANSIENT_STATUS = new Set([408, 429, 500, 502, 503, 504]);
+
+/**
+ * The default retry predicate: idempotent methods only, on a transport error or a
+ * transient status. A custom `retryOn` fully replaces this (no method check kept).
+ */
+export function defaultRetryOn(ctx: RetryContext): boolean {
+  if (!IDEMPOTENT_METHODS.has(ctx.request.method.toUpperCase())) return false;
+  return ctx.response === undefined || TRANSIENT_STATUS.has(ctx.response.status);
+}
+
+/**
+ * The delay before the next attempt: a `Retry-After` header (seconds or HTTP-date)
+ * wins; otherwise fixed/exponential backoff over `retryDelay`, with full jitter
+ * unless `jitter === false`.
+ */
+export function retryDelay(retry: RetryConfig, attempt: number, retryAfter: string | null): number {
+  if (retryAfter) {
+    const seconds = Number(retryAfter);
+    if (!Number.isNaN(seconds)) return seconds * 1000;
+    const when = Date.parse(retryAfter);
+    if (!Number.isNaN(when)) return Math.max(0, when - Date.now());
+  }
+  const base = retry.retryDelay ?? 1000;
+  const raw = retry.retryStrategy === 'fixed' ? base : base * Math.pow(2, attempt - 1);
+  return retry.jitter === false ? raw : Math.random() * raw;
+}
+
+/** Abort-aware sleep: resolves after `ms`, rejects with the abort reason immediately on abort. */
+export function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(abortError(signal));
+      return;
+    }
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(abortError(signal as AbortSignal));
+    };
+    const timer = setTimeout(() => {
+      if (signal) signal.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+    if (signal) signal.addEventListener('abort', onAbort, { once: true });
+  });
+}
diff --git a/packages/client-generator/src/runtime/send.ts b/packages/client-generator/src/runtime/send.ts
new file mode 100644
index 0000000000..edf4806c65
--- /dev/null
+++ b/packages/client-generator/src/runtime/send.ts
@@ -0,0 +1,164 @@
+import { abortError } from './errors.js';
+import { defaultRetryOn, retryDelay, sleep } from './retry.js';
+import type {
+  ClientConfig,
+  Middleware,
+  OperationContext,
+  RequestContext,
+  RequestOptions,
+  RetryConfig,
+} from './types.js';
+
+/**
+ * Optional behaviors the send core can use but never statically imports — wired by
+ * `createClient` (the same seam the future inline-mode assembler relies on).
+ */
+export type SendCapabilities = {
+  /** Serialize a typed multipart body (a plain object) to FormData. */
+  serializeMultipart?: (body: Record<string, unknown>) => FormData;
+};
+
+/**
+ * Normalize a caller's `HeadersInit` (plain record, `Headers` instance, or entry pairs)
+ * to a plain record — spreading a `Headers` or an array contributes no entries.
+ */
+export function toHeaderRecord(headers: HeadersInit | undefined): Record<string, string> {
+  if (headers === undefined) return {};
+  if (headers instanceof Headers) {
+    const record: Record<string, string> = {};
+    headers.forEach((value, key) => {
+      record[key] = value;
+    });
+    return record;
+  }
+  if (Array.isArray(headers)) return Object.fromEntries(headers);
+  return headers;
+}
+
+/**
+ * The effective middleware chain for a request: the single `onRequest`/`onResponse`/
+ * `onError` config hooks as one implicit first middleware, then `config.middleware`.
+ */
+export function middlewareChain(config: ClientConfig): Middleware[] {
+  const single =
+    config.onRequest || config.onResponse || config.onError
+      ? [{ onRequest: config.onRequest, onResponse: config.onResponse, onError: config.onError }]
+      : [];
+  return [...single, ...(config.middleware ?? [])];
+}
+
+/**
+ * The fetch core shared by every operation: default + config + per-call headers, the
+ * `onRequest` chain (BEFORE body serialization, so mutations are sent), body
+ * serialization (JSON, or FormData via the multipart capability), the retry loop
+ * (idempotent-only defaults, `Retry-After`, abandoned-body drain), and the reverse
+ * `onResponse` onion. Returns the final response plus the request context.
+ */
+export async function send(
+  config: ClientConfig,
+  op: OperationContext,
+  url: string,
+  init: RequestOptions,
+  body: unknown | undefined,
+  multipart: boolean,
+  caps: SendCapabilities
+): Promise<{ response: Response; context: RequestContext }> {
+  const { retry: callRetry, ...fetchInit } = init;
+  const retry: RetryConfig = { ...config.retry, ...callRetry };
+  const extra = typeof config.headers === 'function' ? await config.headers() : config.headers;
+  const headers: Record<string, string> = {
+    Accept: 'application/json',
+    ...extra,
+    ...toHeaderRecord(fetchInit.headers),
+  };
+  const context: RequestContext = {
+    url,
+    method: fetchInit.method ?? 'GET',
+    headers,
+    body,
+    operation: op,
+  };
+  const middleware = middlewareChain(config);
+  for (const mw of middleware) if (mw.onRequest) await mw.onRequest(context);
+  // Serialize AFTER onRequest so body mutations (case conversion, enveloping, signing) take effect.
+  let payload: BodyInit | undefined;
+  if (context.body !== undefined) {
+    const value = context.body;
+    const isBinary =
+      value instanceof Blob ||
+      value instanceof ArrayBuffer ||
+      ArrayBuffer.isView(value as ArrayBufferView);
+    const isFormData = typeof FormData !== 'undefined' && value instanceof FormData;
+    const isURLSearchParams = value instanceof URLSearchParams;
+    if (isFormData || isURLSearchParams || isBinary || typeof value === 'string') {
+      payload = value as BodyInit;
+    } else if (multipart) {
+      if (!caps.serializeMultipart) {
+        throw new Error('Multipart capability not wired: cannot serialize the request body');
+      }
+      payload = caps.serializeMultipart(value as Record<string, unknown>);
+    } else {
+      payload = JSON.stringify(value);
+      if (!('Content-Type' in context.headers) && !('content-type' in context.headers)) {
+        context.headers['Content-Type'] = 'application/json';
+      }
+    }
+  }
+  const doFetch = config.fetch ?? fetch;
+  const maxAttempts = 1 + (retry.retries ?? 0);
+  const retryOn = retry.retryOn ?? defaultRetryOn;
+  const signal = fetchInit.signal ?? undefined;
+
+  let attempt = 0;
+  while (true) {
+    attempt++;
+    if (signal?.aborted) throw abortError(signal);
+    let response: Response;
+    try {
+      response = await doFetch(context.url, {
+        ...fetchInit,
+        method: context.method,
+        headers: context.headers,
+        body: payload,
+      });
+    } catch (error) {
+      if (
+        attempt < maxAttempts &&
+        !signal?.aborted &&
+        (await retryOn({ attempt, request: context, error }))
+      ) {
+        await sleep(retryDelay(retry, attempt, null), signal);
+        continue;
+      }
+      throw error;
+    }
+    // Reverse order: the last-registered middleware wraps closest to the network (onion).
+    for (let i = middleware.length - 1; i >= 0; i--) {
+      const onResponse = middleware[i].onResponse;
+      if (onResponse) {
+        const replaced = await onResponse(response, context);
+        if (replaced && replaced !== response) {
+          // Cancel the abandoned original's body — like the retry path, an unread body
+          // keeps its connection checked out under Node/undici.
+          await response.body?.cancel().catch(() => undefined);
+          response = replaced;
+        }
+      }
+    }
+    if (
+      !response.ok &&
+      attempt < maxAttempts &&
+      !signal?.aborted &&
+      (await retryOn({ attempt, request: context, response }))
+    ) {
+      const retryAfter = response.headers.get('retry-after');
+      // Drain the abandoned response body before the next attempt: an unread body
+      // keeps the connection checked out (and can stall the pool) under Node/undici
+      // and other strict HTTP clients. Ignore errors (e.g. a middleware already read it).
+      await response.body?.cancel().catch(() => undefined);
+      await sleep(retryDelay(retry, attempt, retryAfter), signal);
+      continue;
+    }
+    return { response, context };
+  }
+}
diff --git a/packages/client-generator/src/runtime/setup.ts b/packages/client-generator/src/runtime/setup.ts
new file mode 100644
index 0000000000..4c5e1c0153
--- /dev/null
+++ b/packages/client-generator/src/runtime/setup.ts
@@ -0,0 +1,17 @@
+import type { ClientConfig, Middleware } from './types.js';
+
+/**
+ * Merge a publisher's baked setup (`defineClientSetup({...})`) with the app's config:
+ * app config fields win per-field over baked defaults, while middleware composes —
+ * baked middleware runs first, then the app's.
+ */
+export function mergeSetup(
+  setup: { config?: ClientConfig; middleware?: Middleware[] } | undefined,
+  config: ClientConfig = {}
+): ClientConfig {
+  return {
+    ...setup?.config,
+    ...config,
+    middleware: [...(setup?.middleware ?? []), ...(config.middleware ?? [])],
+  };
+}
diff --git a/packages/client-generator/src/runtime/sse.ts b/packages/client-generator/src/runtime/sse.ts
new file mode 100644
index 0000000000..a7ae2383a3
--- /dev/null
+++ b/packages/client-generator/src/runtime/sse.ts
@@ -0,0 +1,165 @@
+import { ApiError } from './errors.js';
+import { readError } from './parse.js';
+import { sleep } from './retry.js';
+import { send, toHeaderRecord } from './send.js';
+import type { ClientConfig, OperationContext, ServerSentEvent, SseOptions } from './types.js';
+
+/**
+ * A frame delimiter: two consecutive line terminators (each CR, LF, or CRLF, per the SSE
+ * spec — so mixed endings like `\n\r\n` are valid boundaries, not just matching pairs).
+ */
+const FRAME_DELIMITER = /(?:\r\n|\r|\n){2}/;
+
+/**
+ * A terminally malformed event stream — unparseable JSON `data` or an unbounded frame.
+ * A stable bad payload, not a dropped connection, so the stream never reconnects on it.
+ */
+export class SseParseError extends Error {}
+
+/**
+ * Consume a `text/event-stream` operation as typed events (capability module — wired
+ * into `createClient`). Auto-reconnects on dropped connections, resuming from the last
+ * seen event id via `Last-Event-ID` (backoff: the server's `retry:` value, then
+ * `reconnectDelay`, then 1s — exponential with jitter, capped at 30s). A clean stream
+ * end flushes a trailing frame and finishes; `break`/abort end the iterator cleanly.
+ */
+export async function* sse<T>(
+  config: ClientConfig,
+  op: OperationContext,
+  prepare: () => Promise<{ url: string; init: SseOptions; body?: unknown }>,
+  dataKind: 'json' | 'text' = 'text'
+): AsyncGenerator<ServerSentEvent<T>> {
+  let lastEventId: string | undefined;
+  let serverRetry: number | undefined;
+  let failures = 0;
+  while (true) {
+    // Re-prepare each attempt so a refresh-style TokenProvider yields a fresh credential
+    // on reconnect (the auth is baked into `url` query + `init.headers`). `reconnect`,
+    // `reconnectDelay`, and `signal` come from the caller's original options unchanged.
+    const { url, init, body: requestBody } = await prepare();
+    const { reconnect = true, reconnectDelay, ...rest } = init;
+    const signal = rest.signal ?? undefined;
+    if (signal?.aborted) return;
+    const headers: Record<string, string> = {
+      Accept: 'text/event-stream',
+      ...toHeaderRecord(rest.headers),
+    };
+    const sendHeaders =
+      lastEventId === undefined ? headers : { ...headers, 'Last-Event-ID': lastEventId };
+    try {
+      const { response } = await send(
+        config,
+        op,
+        url,
+        { ...rest, method: rest.method ?? 'GET', headers: sendHeaders },
+        requestBody,
+        false,
+        {}
+      );
+      if (!response.ok) {
+        const errorBody = await readError(response);
+        throw new ApiError(url, response.status, response.statusText, errorBody);
+      }
+      failures = 0;
+      const body = response.body;
+      if (!body) return;
+      const reader = body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = '';
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+          buffer += done ? decoder.decode() : decoder.decode(value, { stream: true });
+          let match: RegExpMatchArray | null;
+          while ((match = buffer.match(FRAME_DELIMITER)) !== null) {
+            const index = match.index!;
+            const raw = buffer.slice(0, index);
+            buffer = buffer.slice(index + match[0].length);
+            const event = parseSseFrame(raw, dataKind);
+            if (event) {
+              if (event.id !== undefined) lastEventId = event.id;
+              if (event.retry !== undefined) serverRetry = event.retry;
+              yield event as ServerSentEvent<T>;
+            }
+          }
+          if (done) {
+            // Stream closed cleanly. Flush a final event that arrived without a trailing
+            // delimiter, then finish — a clean end is not a dropped connection, so do not reconnect.
+            const event = buffer.length > 0 ? parseSseFrame(buffer, dataKind) : undefined;
+            if (event) {
+              if (event.id !== undefined) lastEventId = event.id;
+              if (event.retry !== undefined) serverRetry = event.retry;
+              yield event as ServerSentEvent<T>;
+            }
+            return;
+          }
+          // Bound memory: a server that never sends a frame delimiter would otherwise
+          // grow `buffer` without limit. 1 MiB is far above any real SSE frame.
+          if (buffer.length > 1048576) {
+            throw new SseParseError('SSE frame exceeded 1048576 characters without a delimiter');
+          }
+        }
+      } finally {
+        await reader.cancel().catch(() => undefined);
+      }
+    } catch (error) {
+      if (signal?.aborted) return;
+      // A non-OK HTTP response (4xx/5xx) or an unparseable JSON payload is a definitive
+      // error, not a transient drop — surface it instead of reconnecting in a loop (a
+      // stable bad payload would otherwise reconnect forever).
+      if (error instanceof ApiError || error instanceof SseParseError) throw error;
+      // A transport failure (connect/DNS/reset) when opening the request, or a mid-stream
+      // read error, is a dropped connection: fall through to backoff/reconnect when enabled.
+      if (!reconnect) throw error;
+    }
+    // Only the swallowed-drop path reaches here: reconnect is on and the signal not aborted.
+    failures++;
+    const base = serverRetry ?? reconnectDelay ?? 1000;
+    const delay = Math.min(base * Math.pow(2, failures - 1), 30_000);
+    try {
+      await sleep(Math.random() * delay, signal);
+    } catch {
+      return; // sleep rejects only on abort — end the iterator cleanly
+    }
+  }
+}
+
+/** Parse one raw SSE frame (its lines) into an event; returns undefined for comment-only frames. */
+export function parseSseFrame(
+  raw: string,
+  dataKind: 'json' | 'text'
+): ServerSentEvent<unknown> | undefined {
+  let event: string | undefined;
+  const dataLines: string[] = [];
+  let id: string | undefined;
+  let retry: number | undefined;
+  let sawField = false;
+  for (const line of raw.split(/\r\n|\n|\r/)) {
+    if (line === '' || line.startsWith(':')) continue;
+    const colon = line.indexOf(':');
+    const field = colon === -1 ? line : line.slice(0, colon);
+    let val = colon === -1 ? '' : line.slice(colon + 1);
+    if (val.startsWith(' ')) val = val.slice(1);
+    sawField = true;
+    if (field === 'event') event = val;
+    else if (field === 'data') dataLines.push(val);
+    else if (field === 'id') id = val;
+    else if (field === 'retry') {
+      const n = Number(val);
+      if (!Number.isNaN(n)) retry = n;
+    }
+  }
+  if (!sawField) return undefined;
+  const dataText = dataLines.join('\n');
+  let data: unknown = dataText;
+  if (dataKind === 'json' && dataText !== '') {
+    try {
+      data = JSON.parse(dataText);
+    } catch (error) {
+      throw new SseParseError(
+        `Failed to parse SSE event data as JSON: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  return { event, data, id, retry };
+}
diff --git a/packages/client-generator/src/runtime/types.ts b/packages/client-generator/src/runtime/types.ts
new file mode 100644
index 0000000000..797b3650bb
--- /dev/null
+++ b/packages/client-generator/src/runtime/types.ts
@@ -0,0 +1,258 @@
+/**
+ * The public type surface of the client runtime — `@redocly/client-generator`'s
+ * app-facing runtime module. Pure types, no runtime code (excluded from coverage).
+ * The generator emits `OPERATIONS` literals typed
+ * `satisfies Record<string, OperationDescriptor>` against this module, so an
+ * incompatible runtime/generated pair fails the consumer's build (the semver skew guard).
+ */
+
+/** How one operation parameter is sent: its location plus OpenAPI query-serialization hints. */
+export type ParamSpec = {
+  name: string;
+  in: 'path' | 'query' | 'header' | 'cookie';
+  style?: 'form' | 'spaceDelimited' | 'pipeDelimited' | 'deepObject';
+  explode?: boolean;
+  allowReserved?: boolean;
+};
+
+/** One security scheme, denormalized onto the operation (`scheme` names the spec's scheme). */
+export type SecuritySpec =
+  | { scheme: string; kind: 'bearer' | 'basic' }
+  | { scheme: string; kind: 'apiKey'; name: string; in: 'header' | 'query' | 'cookie' };
+
+/**
+ * How to auto-iterate a paginated operation (drives its `.pages()`/`.items()` members).
+ * `nextCursor` and `items` are RFC 6901 JSON pointers into the page (response) value.
+ */
+export type PaginationSpec = {
+  style: 'cursor' | 'offset' | 'page';
+  /** The query param the iterator advances: the cursor (`cursor`) or number (`offset`/`page`). */
+  param: string;
+  /** Optional page-size query param (recorded for tooling; never set by the runtime). */
+  limitParam?: string;
+  /** Cursor style only: pointer to the next cursor in the page. */
+  nextCursor?: string;
+  /** Cursor style only: optional pointer to a boolean "more pages" flag — `false` stops iteration. */
+  hasMore?: string;
+  /** Pointer to the page's item array. */
+  items: string;
+};
+
+/** The frozen data contract between generated code and the runtime: one operation's wire shape. */
+export type OperationDescriptor = {
+  id: string;
+  method: string;
+  path: string;
+  tags?: readonly string[];
+  params?: readonly ParamSpec[];
+  /** `multipart: true` marks a typed object body serialized to FormData by the runtime. */
+  body?: { contentType: string; multipart?: boolean };
+  /** Defaults to `'json'` (content-type negotiation on parse). */
+  responseKind?: 'json' | 'text' | 'blob' | 'void' | 'sse';
+  sseDataKind?: 'json' | 'text';
+  /** OR-alternatives, each an AND-set: the runtime applies the first fully-configured one. */
+  security?: readonly (readonly SecuritySpec[])[];
+  pagination?: PaginationSpec;
+};
+
+/** A query value: scalars, arrays of scalars, or objects (serialized as deepObject brackets). */
+export type QueryValue =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | Array<string | number | boolean | null | undefined>
+  | Record<string, unknown>;
+
+/** A credential: a literal, or a (possibly async) function resolved per request (refresh flows). */
+export type TokenProvider = string | (() => string | Promise<string>);
+
+/** Per-instance credentials, keyed by the scheme kinds the runtime can inject. */
+export type AuthCredentials = {
+  bearer?: TokenProvider;
+  basic?: { username: string; password: string };
+  apiKey?: Record<string, TokenProvider>;
+};
+
+/** Backoff shape: 'fixed' = constant delay; 'exponential' = doubling per attempt. */
+export type RetryStrategy = 'fixed' | 'exponential';
+
+/**
+ * The operation's identity, exposed to middleware for targeting (`ctx.operation`).
+ * Generated clients instantiate the type parameters with the spec's literal unions
+ * (`OperationId`/`OperationPath`/`OperationTag`) so a misspelled operation id in a
+ * middleware comparison fails to compile; the string defaults keep every
+ * spec-independent consumer (`runtime-contract.ts`, the runtime internals) working
+ * with the base shape. `tags` stays mutable (`Tag[]`) so setup-contract types
+ * (byte-locked to generated output) remain assignable through middleware callbacks.
+ */
+export type OperationContext<
+  Id extends string = string,
+  Path extends string = string,
+  Tag extends string = string,
+> = { id: Id; path: Path; tags: Tag[] };
+
+/** The mutable request context threaded through the middleware chain. */
+export type RequestContext<Op extends OperationContext = OperationContext> = {
+  url: string;
+  method: string;
+  headers: Record<string, string>;
+  body?: unknown;
+  operation: Op;
+};
+
+/** The failed attempt handed to a custom `retryOn`: exactly one of `response`/`error` is set. */
+export type RetryContext<Op extends OperationContext = OperationContext> = {
+  attempt: number;
+  request: RequestContext<Op>;
+  response?: Response;
+  error?: unknown;
+};
+
+/** Opt-in retry policy; a per-call override merges field-by-field over the config policy. */
+export type RetryConfig<Op extends OperationContext = OperationContext> = {
+  retries?: number;
+  retryDelay?: number;
+  retryStrategy?: RetryStrategy;
+  jitter?: boolean;
+  retryOn?: (ctx: RetryContext<Op>) => boolean | Promise<boolean>;
+};
+
+/**
+ * Structural stand-in for the runtime's ApiError so this module stays import-free
+ * (pure types); the real `ApiError` class is assignable to it.
+ */
+export type ApiErrorLike = globalThis.Error & {
+  url: string;
+  status: number;
+  statusText: string;
+  body: unknown;
+};
+
+/** One interceptor: any subset of the three hooks. */
+export type Middleware<Op extends OperationContext = OperationContext> = {
+  onRequest?: (ctx: RequestContext<Op>) => void | Promise<void>;
+  onResponse?: (
+    response: Response,
+    ctx: RequestContext<Op>
+  ) => Response | void | Promise<Response | void>;
+  /** Throw mode only: may map/replace the error. */
+  // `globalThis.Error` so a spec schema named `Error` cannot shadow it in inline mode.
+  onError?: (
+    error: ApiErrorLike,
+    ctx: RequestContext<Op>
+  ) => globalThis.Error | Promise<globalThis.Error>;
+};
+
+/** Client configuration: transport, defaults, retry policy, middleware, and credentials. */
+export type ClientConfig<Op extends OperationContext = OperationContext> = {
+  serverUrl?: string;
+  fetch?: typeof fetch;
+  headers?:
+    | Record<string, string>
+    | (() => Record<string, string> | Promise<Record<string, string>>);
+  retry?: RetryConfig<Op>;
+  middleware?: Middleware<Op>[];
+  auth?: AuthCredentials;
+  /** Fixed at generate time by the generator (`'throw'` when omitted); `configure()` ignores it. */
+  errorMode?: 'throw' | 'result';
+  onRequest?: Middleware<Op>['onRequest'];
+  onResponse?: Middleware<Op>['onResponse'];
+  onError?: Middleware<Op>['onError'];
+};
+
+/** Response readers for the per-call `parseAs` override. */
+export type ParseAs = 'auto' | 'json' | 'text' | 'blob' | 'arrayBuffer' | 'formData' | 'stream';
+
+/** Per-call options: standard `RequestInit` plus a retry override and a forced reader. */
+export type RequestOptions = RequestInit & { retry?: RetryConfig; parseAs?: ParseAs };
+
+/** Per-call options for an SSE stream; reconnect defaults to true. */
+export type SseOptions = RequestInit & { reconnect?: boolean; reconnectDelay?: number };
+
+/** A single decoded Server-Sent Event with its payload typed from the spec. */
+export type ServerSentEvent<T> = { event?: string; data: T; id?: string; retry?: number };
+
+/** Result-mode return shape: exactly one of `data`/`error` is set. */
+export type Result<TData, TError> =
+  | { data: TData; error: undefined; response: Response }
+  | { data: undefined; error: TError; response: Response };
+
+/**
+ * The generated `Ops` type's shape: per-operation args/result, plus `kind: 'sse'` for
+ * streams and, for paginated operations, `item` (the page's element type) and — on
+ * result-mode clients only — `page` (the RAW page type `.pages()` yields, since
+ * iteration unwraps the `Result` envelope the one-shot `result` carries).
+ */
+export type OpsShape = Record<
+  string,
+  { args: object; result: unknown; kind?: 'sse'; item?: unknown; page?: unknown }
+>;
+
+/** The always-present client members (assigned after the operation loop — they win collisions). */
+export type ClientCore<Op extends OperationContext = OperationContext> = {
+  /** Merge into the config; note `middleware` REPLACES the chain (use `use()` to compose). */
+  configure(config: ClientConfig<Op>): void;
+  /** Append interceptors (composes with baked/publisher middleware). */
+  use(...middleware: Middleware<Op>[]): void;
+  auth: {
+    bearer(token: TokenProvider): void;
+    basic(username: string, password: string): void;
+    apiKey(scheme: string, value: TokenProvider): void;
+  };
+};
+
+/**
+ * The standard TypeScript optionality probe: `{}` has no required members, so
+ * `{} extends A` is true exactly when every member of `A` is optional.
+ */
+// oxlint-disable-next-line typescript/no-empty-object-type
+type NoRequiredKeys<A> = {} extends A ? true : false;
+
+/**
+ * The page type `.pages()` yields: the RAW page declared by `page` (the generator
+ * writes it only on result-mode paginated entries, whose `result` is the envelope),
+ * or the method's own `result` (throw mode — already the raw page).
+ */
+type PageOf<Entry extends OpsShape[string]> = Entry extends { page: unknown }
+  ? Entry['page']
+  : Entry['result'];
+
+/**
+ * The auto-pagination members intersected onto a paginated method — present exactly when
+ * the Ops entry declares `item` (the generator writes it only for paginated operations).
+ * Args optionality mirrors the method's own; `unknown` otherwise (identity under `&`).
+ * Iteration is error-mode-agnostic: `.pages()`/`.items()` yield raw pages/items, and a
+ * failed page aborts iteration by throwing `ApiError`, even on result-mode clients; the
+ * `onError` middleware hook (throw-mode-only) is not invoked.
+ */
+type Paginated<Entry extends OpsShape[string]> = 'item' extends keyof Entry
+  ? NoRequiredKeys<Entry['args']> extends true
+    ? {
+        pages(args?: Entry['args'], init?: RequestOptions): AsyncGenerator<PageOf<Entry>>;
+        items(args?: Entry['args'], init?: RequestOptions): AsyncGenerator<Entry['item']>;
+      }
+    : {
+        pages(args: Entry['args'], init?: RequestOptions): AsyncGenerator<PageOf<Entry>>;
+        items(args: Entry['args'], init?: RequestOptions): AsyncGenerator<Entry['item']>;
+      }
+  : unknown;
+
+/** The typed instance client: one bound method per operation plus the core members. */
+export type Client<Ops extends OpsShape, Op extends OperationContext = OperationContext> = {
+  [K in keyof Ops]: Ops[K] extends { kind: 'sse' }
+    ? NoRequiredKeys<Ops[K]['args']> extends true
+      ? (
+          args?: Ops[K]['args'],
+          init?: SseOptions
+        ) => AsyncGenerator<ServerSentEvent<Ops[K]['result']>>
+      : (
+          args: Ops[K]['args'],
+          init?: SseOptions
+        ) => AsyncGenerator<ServerSentEvent<Ops[K]['result']>>
+    : (NoRequiredKeys<Ops[K]['args']> extends true
+        ? (args?: Ops[K]['args'], init?: RequestOptions) => Promise<Ops[K]['result']>
+        : (args: Ops[K]['args'], init?: RequestOptions) => Promise<Ops[K]['result']>) &
+        Paginated<Ops[K]>;
+} & ClientCore<Op>;
diff --git a/packages/client-generator/src/runtime/url.ts b/packages/client-generator/src/runtime/url.ts
new file mode 100644
index 0000000000..bdc4ae2e62
--- /dev/null
+++ b/packages/client-generator/src/runtime/url.ts
@@ -0,0 +1,104 @@
+import type { ParamSpec, QueryValue } from './types.js';
+
+/**
+ * The RESOLVED OpenAPI serialization spec for one query parameter — callers apply the
+ * OpenAPI defaults (`style: 'form'`, `explode: true`) before building one.
+ */
+export type QueryStyle = {
+  style: NonNullable<ParamSpec['style']>;
+  explode: boolean;
+  allowReserved?: boolean;
+};
+
+/**
+ * Encode everything except the RFC-3986 reserved set, for `allowReserved: true` params —
+ * `filter=a/b` survives instead of `filter=a%2Fb`.
+ */
+export function encodeReserved(value: string): string {
+  return encodeURIComponent(value).replace(
+    /%(3A|2F|3F|23|5B|5D|40|21|24|26|27|28|29|2A|2B|2C|3B|3D)/g,
+    (match) => decodeURIComponent(match)
+  );
+}
+
+/** Substitute `{name}` template segments with encoded values; a missing value is a caller bug. */
+export function substitutePath(template: string, values: Record<string, unknown>): string {
+  return template.replace(/\{([^{}]+)\}/g, (_match, name: string) => {
+    const value = values[name];
+    if (value === undefined) throw new Error(`Missing path parameter "${name}"`);
+    return encodeURIComponent(String(value));
+  });
+}
+
+/**
+ * Build the request URL: `serverUrl` (trailing slash trimmed) + path + serialized query.
+ * Query parameters honor their OpenAPI `style`/`explode`/`allowReserved` (from `styles`);
+ * without a spec, arrays repeat the key (`form`+`explode`), objects serialize as
+ * `deepObject` brackets, and `null`/`undefined` entries are skipped.
+ */
+export function buildUrl(
+  serverUrl: string,
+  path: string,
+  query?: Record<string, QueryValue>,
+  styles?: Record<string, QueryStyle>
+): string {
+  // Trim trailing slashes with a scan, not `/\/+$/` — an anchored `+` regex is
+  // quadratic on adversarial many-slash input (the server URL is caller data).
+  let end = serverUrl.length;
+  while (end > 0 && serverUrl.charCodeAt(end - 1) === 47 /* '/' */) end--;
+  const url = serverUrl.slice(0, end) + path;
+  if (!query) return url;
+  const params = new URLSearchParams();
+  const raw: string[] = [];
+  for (const [key, value] of Object.entries(query)) {
+    if (value === undefined || value === null) continue;
+    const spec = styles?.[key];
+    if (!spec) {
+      if (Array.isArray(value)) {
+        for (const v of value) {
+          if (v !== undefined && v !== null) params.append(key, String(v));
+        }
+      } else if (Object(value) === value) {
+        // Object-valued query params use `deepObject` style: key[subKey]=subValue.
+        for (const [subKey, subValue] of Object.entries(value)) {
+          if (subValue !== undefined && subValue !== null) {
+            params.append(`${key}[${subKey}]`, String(subValue));
+          }
+        }
+      } else {
+        params.append(key, String(value));
+      }
+      continue;
+    }
+    if (Array.isArray(value)) {
+      const items = value.filter((v) => v !== undefined && v !== null).map(String);
+      if (spec.style === 'form' && spec.explode) {
+        for (const v of items) {
+          if (spec.allowReserved) raw.push(`${key}=${encodeReserved(v)}`);
+          else params.append(key, v);
+        }
+      } else {
+        // Delimited styles put the LITERAL delimiter on the wire; only the
+        // values are encoded. `%20` (not `+`) is the literal space delimiter.
+        const delim =
+          spec.style === 'pipeDelimited' ? '|' : spec.style === 'spaceDelimited' ? '%20' : ',';
+        const enc = spec.allowReserved ? encodeReserved : encodeURIComponent;
+        raw.push(`${encodeURIComponent(key)}=${items.map(enc).join(delim)}`);
+      }
+    } else if (Object(value) === value) {
+      // `deepObject` (and any object spec, for now): key[subKey]=subValue.
+      for (const [subKey, subValue] of Object.entries(value)) {
+        if (subValue !== undefined && subValue !== null) {
+          if (spec.allowReserved) raw.push(`${key}[${subKey}]=${encodeReserved(String(subValue))}`);
+          else params.append(`${key}[${subKey}]`, String(subValue));
+        }
+      }
+    } else if (spec.allowReserved) {
+      raw.push(`${key}=${encodeReserved(String(value))}`);
+    } else {
+      params.append(key, String(value));
+    }
+  }
+  const qs = [params.toString(), ...raw].filter(Boolean).join('&');
+  return qs ? `${url}?${qs}` : url;
+}
diff --git a/packages/client-generator/src/types.ts b/packages/client-generator/src/types.ts
new file mode 100644
index 0000000000..69768570a6
--- /dev/null
+++ b/packages/client-generator/src/types.ts
@@ -0,0 +1,122 @@
+import type { Config as RedoclyConfig, Oas3Definition, detectSpec } from '@redocly/openapi-core';
+
+import type { ArgsStyle } from './emitters/emit-options.js';
+import type { PaginationConfig } from './emitters/pagination.js';
+import type { CustomGenerator, OutputMode } from './generators/types.js';
+
+export type GenerateClientOptions = {
+  /** Path or URL to the OpenAPI document (or an `apis:` alias from `redocly.yaml`). */
+  api: string;
+  output: string;
+  /** Resolved Redocly config for spec loading. */
+  config?: RedoclyConfig;
+  /**
+   * How the generated client is partitioned across files. Defaults to `single`
+   * (one self-contained file).
+   */
+  outputMode?: OutputMode;
+  /**
+   * How operation inputs are passed to each generated function/method:
+   * `'flat'` (default) spreads path params as positional args followed by
+   * `params`/`body`/`headers` slots; `'grouped'` bundles every input into a single
+   * `args` object. The per-call `init` argument stays separate in both styles.
+   */
+  argsStyle?: ArgsStyle;
+  /**
+   * Override the BASE URL inlined into the generated runtime. When omitted,
+   * the value is derived from `servers[0].url` in the source OpenAPI document.
+   * Validation (e.g. `new URL(value)`) is the caller's responsibility — the
+   * CLI handler validates before calling.
+   */
+  serverUrl?: string;
+  /**
+   * How named string enums are emitted. `'const-object'` (default) emits a
+   * runtime `as const` companion object alongside the union type; `'union'`
+   * emits only the string-literal union.
+   */
+  enumStyle?: 'union' | 'const-object';
+  /**
+   * Error-handling shape of the generated client. `'throw'` (default) throws
+   * `ApiError` on non-2xx responses; `'result'` returns a discriminated
+   * `{ data, error, response }` whose `error` is typed from the spec's 4xx/5xx
+   * response bodies.
+   */
+  errorMode?: 'throw' | 'result';
+  /**
+   * How `format: date-time`/`date` string fields are typed. `'string'` (default)
+   * keeps the ISO wire shape; `'Date'` emits a `Date` reference. Opt-in — pair with
+   * the `transformers` generator so the runtime value matches the type. The
+   * generated client stays zero-dep (`Date` is a web standard).
+   */
+  dateType?: 'string' | 'Date';
+  /**
+   * TanStack Query adapter the `tanstack-query` generator imports from
+   * (`@tanstack/${queryFramework}-query`). Defaults to `'react'`; only the import
+   * specifier changes — the emitted factory module is byte-identical across frameworks.
+   */
+  queryFramework?: 'react' | 'vue' | 'svelte' | 'solid';
+  /**
+   * How the `mock` generator produces data. `'baked'` (default) inlines deterministic
+   * literals (zero-dep, contract-faithful); `'faker'` emits `@faker-js/faker` calls for
+   * realistic data — making `@faker-js/faker` the consumer's dev-dep. Factory signatures
+   * are identical across modes, so a consumer can flip this without changing call sites.
+   */
+  mockData?: 'baked' | 'faker';
+  /**
+   * Seed for faker-mode mocks. When set, the mock module emits a top-level
+   * `faker.seed(<n>)` so generated data is reproducible across runs. Ignored in baked mode.
+   */
+  mockSeed?: number;
+  /**
+   * Generators to run, in order. Defaults to `['sdk']`. Each entry is a built-in name
+   * (`sdk`/`zod`/`tanstack-query`/`swr`/`transformers`/`mock`), the `name` of an inline
+   * `customGenerators` entry, or an import specifier (a path or package) for a custom generator.
+   */
+  generators?: string[];
+  /**
+   * Inline custom generators (the experimental plugin API), registered before resolution so they
+   * can be selected in `generators` by `name`. Authored with `defineGenerator` from
+   * `@redocly/client-generator`. Path/package specifiers in `generators` don't need this.
+   */
+  customGenerators?: CustomGenerator[];
+  /**
+   * Directory that relative-path generator specifiers resolve against (typically the config file's
+   * location). Defaults to the current working directory.
+   */
+  configDir?: string;
+  /**
+   * Path to a publisher setup module (`export default defineClientSetup({ config, middleware })`)
+   * baked into the generated client. Resolved against `configDir`. Works across all output modes.
+   */
+  setup?: string;
+  /** Runtime distribution: 'inline' (default, self-contained) | 'package' (imports @redocly/client-generator). */
+  runtime?: 'inline' | 'package';
+  /** Extension in generated relative imports. `'js'` (default) suits tsc and bundlers;
+   * `'ts'` suits runtimes that resolve specifiers literally, like Node's built-in
+   * type stripping (`node client.ts`). */
+  importExt?: 'js' | 'ts';
+  /**
+   * Auto-pagination rules: a convention rule (applied to every operation it
+   * structurally fits), per-operation overrides, and `exclude`d operationIds —
+   * resolved together with each operation's `x-pagination` extension (per-op config >
+   * extension > convention). Paginated operations gain typed `.pages()`/`.items()`
+   * iterators. Verified statically: an explicit rule that doesn't fit its operation
+   * fails generation.
+   */
+  pagination?: PaginationConfig;
+};
+
+export type GenerateClientResult = {
+  /** The `--output` anchor path (the entry file in multi-file modes). */
+  outputPath: string;
+  /** Total bytes written across every generated file. */
+  bytes: number;
+  /** Every file written to disk (single-element in `single` mode). */
+  files: Array<{ path: string; bytes: number }>;
+};
+
+export type LoadResult = {
+  document: Oas3Definition;
+  /** The detected input spec version (e.g. 'oas2', 'oas3_0', 'oas3_1', 'oas3_2'). */
+  version: ReturnType<typeof detectSpec>;
+};
diff --git a/packages/client-generator/tsconfig.json b/packages/client-generator/tsconfig.json
new file mode 100644
index 0000000000..17a936f1cd
--- /dev/null
+++ b/packages/client-generator/tsconfig.json
@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib",
+    "strict": true
+  },
+  "references": [{ "path": "../core" }],
+  "include": ["src/**/*.ts"],
+  "exclude": ["lib", "**/__tests__", "**/*.test.ts"]
+}
diff --git a/packages/core/src/__tests__/__snapshots__/redocly-yaml.test.ts.snap b/packages/core/src/__tests__/__snapshots__/redocly-yaml.test.ts.snap
index 9bc1696492..9f6e7038ee 100644
--- a/packages/core/src/__tests__/__snapshots__/redocly-yaml.test.ts.snap
+++ b/packages/core/src/__tests__/__snapshots__/redocly-yaml.test.ts.snap
@@ -211,6 +211,151 @@ exports[`createConfigTypes > matches snapshot for the default config schema 1`]
       "severity",
     ],
   },
+  "Client": {
+    "properties": {
+      "argsStyle": {
+        "enum": [
+          "flat",
+          "grouped",
+        ],
+      },
+      "dateType": {
+        "enum": [
+          "string",
+          "Date",
+        ],
+      },
+      "enumStyle": {
+        "enum": [
+          "union",
+          "const-object",
+        ],
+      },
+      "errorMode": {
+        "enum": [
+          "throw",
+          "result",
+        ],
+      },
+      "generators": {
+        "items": {
+          "type": "string",
+        },
+        "type": "array",
+      },
+      "importExt": {
+        "enum": [
+          "js",
+          "ts",
+        ],
+      },
+      "mockData": {
+        "enum": [
+          "baked",
+          "faker",
+        ],
+      },
+      "mockSeed": {
+        "type": "number",
+      },
+      "outputMode": {
+        "enum": [
+          "single",
+          "split",
+        ],
+      },
+      "pagination": "ClientPagination",
+      "queryFramework": {
+        "enum": [
+          "react",
+          "vue",
+          "svelte",
+          "solid",
+        ],
+      },
+      "runtime": {
+        "enum": [
+          "inline",
+          "package",
+        ],
+      },
+      "serverUrl": {
+        "type": "string",
+      },
+      "setup": {
+        "type": "string",
+      },
+    },
+  },
+  "ClientPagination": {
+    "properties": {
+      "cursorParam": {
+        "type": "string",
+      },
+      "exclude": {
+        "items": {
+          "type": "string",
+        },
+        "type": "array",
+      },
+      "hasMore": {
+        "type": "string",
+      },
+      "items": {
+        "type": "string",
+      },
+      "limitParam": {
+        "type": "string",
+      },
+      "nextCursor": {
+        "type": "string",
+      },
+      "offsetParam": {
+        "type": "string",
+      },
+      "operations": {
+        "additionalProperties": [Function],
+        "name": "ClientPaginationRuleMap",
+        "properties": {},
+      },
+      "style": {
+        "enum": [
+          "cursor",
+          "offset",
+          "page",
+        ],
+      },
+    },
+  },
+  "ClientPaginationRule": {
+    "properties": {
+      "cursorParam": {
+        "type": "string",
+      },
+      "hasMore": {
+        "type": "string",
+      },
+      "items": {
+        "type": "string",
+      },
+      "limitParam": {
+        "type": "string",
+      },
+      "nextCursor": {
+        "type": "string",
+      },
+      "offsetParam": {
+        "type": "string",
+      },
+      "style": {
+        "enum": [
+          "cursor",
+          "offset",
+          "page",
+        ],
+      },
+    },
+  },
   "ConfigApis": {
     "additionalProperties": "ConfigApisProperties",
     "description": "The \`apis\` configuration section is used when a project contains multiple API descriptions to set up different rules and settings for individual APIs. It allows defining specific configurations for each API, which must be identified by a unique name.",
@@ -235,6 +380,10 @@ exports[`createConfigTypes > matches snapshot for the default config schema 1`]
       "async3Decorators": "Decorators",
       "async3Preprocessors": "Preprocessors",
       "async3Rules": "Rules",
+      "client": "Client",
+      "clientOutput": {
+        "type": "string",
+      },
       "decorators": "Decorators",
       "extends": {
         "description": "Use extends to inherit rules and their configurations from other rulesets.",
@@ -378,6 +527,7 @@ exports[`createConfigTypes > matches snapshot for the default config schema 1`]
       "catalogClassic": {
         "type": "object",
       },
+      "client": "Client",
       "codeSnippet": "rootRedoclyConfigSchema.codeSnippet",
       "colorMode": "rootRedoclyConfigSchema.colorMode",
       "corsProxy": "rootRedoclyConfigSchema.corsProxy",
diff --git a/packages/core/src/config/config-resolvers.ts b/packages/core/src/config/config-resolvers.ts
index 8fe4da69d1..019c3a4741 100644
--- a/packages/core/src/config/config-resolvers.ts
+++ b/packages/core/src/config/config-resolvers.ts
@@ -57,6 +57,37 @@ export type ConfigOptions = {
   customExtends?: string[];
 };
 
+// Mirrors @redocly/client-generator's `mergeConfig` layering: fields override one by one,
+// and the nested `pagination` block stays additive — `operations` merge by id, `exclude`
+// lists union — so a per-api block that sets only overrides keeps the shared convention.
+function mergeClientBlocks(
+  base: Record<string, unknown>,
+  overrides: Record<string, unknown>
+): Record<string, unknown> {
+  const merged = { ...base, ...overrides };
+  const basePagination = base.pagination;
+  const overridePagination = overrides.pagination;
+  if (isPlainObject(basePagination) && isPlainObject(overridePagination)) {
+    const pagination: Record<string, unknown> = { ...basePagination, ...overridePagination };
+    if (basePagination.operations || overridePagination.operations) {
+      pagination.operations = {
+        ...(isPlainObject(basePagination.operations) ? basePagination.operations : {}),
+        ...(isPlainObject(overridePagination.operations) ? overridePagination.operations : {}),
+      };
+    }
+    if (Array.isArray(basePagination.exclude) || Array.isArray(overridePagination.exclude)) {
+      pagination.exclude = [
+        ...new Set([
+          ...(Array.isArray(basePagination.exclude) ? basePagination.exclude : []),
+          ...(Array.isArray(overridePagination.exclude) ? overridePagination.exclude : []),
+        ]),
+      ];
+    }
+    merged.pagination = pagination;
+  }
+  return merged;
+}
+
 export async function resolveConfig({
   rawConfigDocument,
   configPath,
@@ -122,7 +153,13 @@ export async function resolveConfig({
     bundledConfig.apis = Object.fromEntries(
       Object.entries(bundledConfig.apis).map(([key, apiConfig]) => {
         const mergedConfig = mergeExtends([bundledConfig, apiConfig]);
-        return [key, { ...apiConfig, ...mergedConfig }];
+        // Like the governance sections above, a per-api `client` block layers field by
+        // field over the top-level one instead of replacing it.
+        const client =
+          isPlainObject(bundledConfig.client) && isPlainObject(apiConfig.client)
+            ? { client: mergeClientBlocks(bundledConfig.client, apiConfig.client) }
+            : {};
+        return [key, { ...apiConfig, ...mergedConfig, ...client }];
       })
     );
   }
diff --git a/packages/core/src/config/types.ts b/packages/core/src/config/types.ts
index 6ce0d690ea..ee30647d17 100644
--- a/packages/core/src/config/types.ts
+++ b/packages/core/src/config/types.ts
@@ -272,18 +272,28 @@ export type ResolveConfig = {
 
 export type Telemetry = 'on' | 'off';
 
+export type ClientGeneratorConfig = Record<string, unknown>;
+
+export type ClientGeneratorApiConfig = {
+  client?: ClientGeneratorConfig;
+  clientOutput?: string;
+};
+
 export type RawUniversalApiConfig = ApiConfig &
-  RawGovernanceConfig & {
+  RawGovernanceConfig &
+  ClientGeneratorApiConfig & {
     plugins?: (string | Plugin)[];
   };
 
-export type ResolvedApiConfig = ApiConfig & Required<ResolvedGovernanceConfig>;
+export type ResolvedApiConfig = ApiConfig &
+  Required<ResolvedGovernanceConfig> &
+  ClientGeneratorApiConfig;
 
 export type RawUniversalConfig = Omit<RedoclyConfig, 'apis' | 'plugins'> &
   RawGovernanceConfig & {
     plugins?: (string | Plugin)[];
     apis?: Record<string, RawUniversalApiConfig>;
-
+    client?: ClientGeneratorConfig;
     resolve?: RawResolveConfig;
     telemetry?: Telemetry;
   };
diff --git a/packages/core/src/types/redocly-yaml.ts b/packages/core/src/types/redocly-yaml.ts
index c078ab4c42..d8ecb55dff 100644
--- a/packages/core/src/types/redocly-yaml.ts
+++ b/packages/core/src/types/redocly-yaml.ts
@@ -308,6 +308,7 @@ const createConfigRoot = (nodeTypes: Record<string, NodeType>): NodeType => ({
     ...nodeTypes.rootRedoclyConfigSchema.properties,
     ...ConfigGovernance.properties,
     apis: 'ConfigApis', // Override apis with internal format
+    client: 'Client',
     telemetry: { enum: ['on', 'off'] },
     resolve: {
       properties: {
@@ -331,6 +332,8 @@ const createConfigApisProperties = (nodeTypes: Record<string, NodeType>): NodeTy
   properties: {
     ...nodeTypes['rootRedoclyConfigSchema.apis_additionalProperties']?.properties,
     ...omit(ConfigGovernance.properties, ['plugins']), // plugins are not allowed in apis
+    client: 'Client',
+    clientOutput: { type: 'string' },
   },
 });
 
@@ -345,6 +348,46 @@ const ConfigHTTP: NodeType = {
   },
 };
 
+const Client: NodeType = {
+  properties: {
+    generators: { type: 'array', items: { type: 'string' } },
+    argsStyle: { enum: ['flat', 'grouped'] },
+    serverUrl: { type: 'string' },
+    outputMode: { enum: ['single', 'split'] },
+    runtime: { enum: ['inline', 'package'] },
+    importExt: { enum: ['js', 'ts'] },
+    enumStyle: { enum: ['union', 'const-object'] },
+    errorMode: { enum: ['throw', 'result'] },
+    dateType: { enum: ['string', 'Date'] },
+    queryFramework: { enum: ['react', 'vue', 'svelte', 'solid'] },
+    mockData: { enum: ['baked', 'faker'] },
+    mockSeed: { type: 'number' },
+    setup: { type: 'string' },
+    pagination: 'ClientPagination',
+  },
+};
+
+// Style-conditional field requirements are enforced by the generator with richer messages.
+const ClientPaginationRule: NodeType = {
+  properties: {
+    style: { enum: ['cursor', 'offset', 'page'] },
+    cursorParam: { type: 'string' },
+    nextCursor: { type: 'string' },
+    hasMore: { type: 'string' },
+    offsetParam: { type: 'string' },
+    limitParam: { type: 'string' },
+    items: { type: 'string' },
+  },
+};
+
+const ClientPagination: NodeType = {
+  properties: {
+    ...ClientPaginationRule.properties,
+    exclude: { type: 'array', items: { type: 'string' } },
+    operations: mapOf('ClientPaginationRule'),
+  },
+};
+
 const Rules: NodeType = {
   properties: {},
   description:
@@ -741,6 +784,9 @@ const CoreConfigTypes: Record<string, NodeType> = {
   ConfigApis,
   ConfigGovernance,
   ConfigHTTP,
+  Client,
+  ClientPagination,
+  ClientPaginationRule,
   Where,
   BuiltinRule,
   CustomRule,
diff --git a/tests/e2e/generate-client/args-grouped.test.ts b/tests/e2e/generate-client/args-grouped.test.ts
new file mode 100644
index 0000000000..0ec1662d3e
--- /dev/null
+++ b/tests/e2e/generate-client/args-grouped.test.ts
@@ -0,0 +1,79 @@
+/**
+ * E2E for `--args-style grouped`: instead of flat positional call sugar, the
+ * operations are exported by destructuring the client (`export const { getOrderById,
+ * ... } = client;`), so every operation takes the grouped args object (path params,
+ * query `params`, `body`, header `headers`) with the per-call request `init` as a
+ * separate trailing argument — the client method signature itself.
+ *
+ * The generated single file must compile under strict `tsc` with
+ * `--noUnusedLocals`, which proves the grouped members line up with the
+ * `<Op>Variables` aliases. Uses cafe.yaml because it exercises path params,
+ * query params, request bodies, header params, and auth together.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { generate, tscBin } from './helpers.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const fixture = join(__dirname, 'fixtures/cafe.yaml');
+
+describe('generate-client end-to-end (--args-style grouped)', () => {
+  let workDir = '';
+  let entry = '';
+
+  beforeAll(() => {
+    workDir = mkdtempSync(join(tmpdir(), 'args-grouped-client-'));
+    entry = join(workDir, 'client.ts');
+  });
+
+  afterAll(() => {
+    if (workDir && existsSync(workDir)) {
+      rmSync(workDir, { recursive: true, force: true });
+    }
+  });
+
+  test('exports the operations by destructuring the client (grouped args = client methods)', () => {
+    generate(fixture, entry, ['--args-style', 'grouped']);
+    expect(existsSync(entry)).toBe(true);
+
+    const src = readFileSync(entry, 'utf-8');
+
+    // Grouped mode re-exports the client methods directly — one destructure export.
+    expect(src).toMatch(/export const \{ [^}]*getOrderById[^}]* \} = client;/);
+    // The grouped `<Op>Variables` aliases are still emitted for consumers.
+    expect(src).toContain('export type GetOrderByIdVariables = {');
+    // getOrderById's grouped args carry the path param as a member in Ops.
+    expect(src).toMatch(/getOrderById: \{\s*args: \{[\s\S]*?orderId: string;/);
+
+    // No flat positional sugar leaks through in grouped mode.
+    expect(src).not.toContain('export const getOrderById = (orderId: string');
+  }, 90_000);
+
+  test('the grouped-style client type-checks under strict mode with no unused locals', () => {
+    expect(existsSync(entry), 'generation test must run first').toBe(true);
+
+    const tsc = spawnSync(
+      tscBin,
+      [
+        '--noEmit',
+        '--strict',
+        '--noUnusedLocals',
+        '--target',
+        'ES2020',
+        '--module',
+        'esnext',
+        '--moduleResolution',
+        'bundler',
+        '--lib',
+        'ES2020,DOM',
+        entry,
+      ],
+      { encoding: 'utf-8', cwd: workDir }
+    );
+    expect(tsc.status, `tsc errors:\n${tsc.stdout}\n${tsc.stderr}`).toBe(0);
+  }, 90_000);
+});
diff --git a/tests/e2e/generate-client/auth.test.ts b/tests/e2e/generate-client/auth.test.ts
new file mode 100644
index 0000000000..22acd8a1b2
--- /dev/null
+++ b/tests/e2e/generate-client/auth.test.ts
@@ -0,0 +1,134 @@
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { outdent } from 'outdent';
+
+import { generate, runConsumer, strictTypecheck } from './helpers.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const fixture = join(__dirname, 'fixtures', 'auth.yaml');
+
+/** Generate a single-file client and assert strict `tsc` accepts it. */
+function generateSingleFile(): string {
+  const dir = mkdtempSync(join(tmpdir(), 'ots-auth-'));
+  const out = join(dir, 'client.ts');
+  generate(fixture, out);
+  expect(existsSync(out)).toBe(true);
+  const generated = readFileSync(out, 'utf-8');
+  strictTypecheck(dir, ['client.ts']);
+  rmSync(dir, { recursive: true, force: true });
+  return generated;
+}
+
+describe('generate-client auth breadth (auth.yaml)', () => {
+  it('emits all five injectable scheme kinds and strict-tsc accepts the single-file client', () => {
+    const generated = generateSingleFile();
+
+    // Token machinery for the resolvable (bearer + apiKey) schemes lives in the embedded runtime.
+    expect(generated).toContain('export type TokenProvider');
+    expect(generated).toContain('async function resolveAuth(');
+    expect(generated).toContain('async function resolveToken(');
+
+    // One setter per scheme kind, as instance-bound sugar. Three apiKey schemes (none sole) → keyed names.
+    expect(generated).toContain('export const setBearer = client.auth.bearer;');
+    expect(generated).toContain('export const setBasicAuth = client.auth.basic;');
+    expect(generated).toContain(
+      'export const setApiKeyQueryKey = (value: TokenProvider) => client.auth.apiKey("QueryKey", value);'
+    );
+    expect(generated).toContain(
+      'export const setApiKeyHeaderKey = (value: TokenProvider) => client.auth.apiKey("HeaderKey", value);'
+    );
+    expect(generated).toContain(
+      'export const setApiKeyCookieKey = (value: TokenProvider) => client.auth.apiKey("CookieKey", value);'
+    );
+
+    // Per-kind injection inside resolveAuth, driven by the descriptors' security specs.
+    expect(generated).toContain('headers.Authorization = `Bearer ${await resolveToken(provider)}`');
+    expect(generated).toContain(
+      'headers.Authorization = `Basic ${encodeBase64(`${basic.username}:${basic.password}`)}`'
+    );
+    expect(generated).toContain("if (scheme.in === 'header') headers[scheme.name] = value;");
+    expect(generated).toContain("else if (scheme.in === 'query') query[scheme.name] = value;");
+    expect(generated).toContain(
+      'else cookies.push(`${scheme.name}=${encodeURIComponent(value)}`);'
+    );
+
+    // Per-instance credentials type + ClientConfig field.
+    expect(generated).toContain('export type AuthCredentials = {');
+    expect(generated).toContain('auth?: AuthCredentials;');
+
+    // Every scheme kind is denormalized onto its operation descriptor.
+    expect(generated).toContain('security: [[{ scheme: "Bearer", kind: "bearer" }]]');
+    expect(generated).toContain('security: [[{ scheme: "Basic", kind: "basic" }]]');
+    expect(generated).toContain(
+      'security: [[{ scheme: "QueryKey", kind: "apiKey", name: "api_key", in: "query" }]]'
+    );
+    expect(generated).toContain(
+      'security: [[{ scheme: "CookieKey", kind: "apiKey", name: "sid", in: "cookie" }]]'
+    );
+    expect(generated).toContain(
+      'security: [[{ scheme: "HeaderKey", kind: "apiKey", name: "X-Key", in: "header" }]]'
+    );
+  }, 60_000);
+
+  it('strict-tsc accepts the split two-file client (guards multi-file auth)', () => {
+    // Split mode derives its folder from a `.ts` entry path, so --output
+    // must still point at a file; the generator emits the schemas file beside it.
+    const dir = mkdtempSync(join(tmpdir(), 'ots-auth-split-'));
+    generate(fixture, join(dir, 'client.ts'), ['--output-mode', 'split']);
+    strictTypecheck(dir);
+    rmSync(dir, { recursive: true, force: true });
+  }, 60_000);
+
+  // Behavioral check on a real wire. The cafe mock-server harness is bound to
+  // cafe.yaml and heavy to clone, so we drive the generated client against a tiny
+  // throwaway http server instead — enough to prove (a) an async `setBearer`
+  // token function resolves through the runtime's auth capability onto the
+  // `Authorization` header and (b) a query-key scheme lands `api_key=` in the URL.
+  it('async setBearer resolves onto Authorization and query-key lands in the URL', () => {
+    // The driver owns its own throwaway http server (and points the client at it
+    // via configure({ serverUrl })), so a single `runConsumer` runs the whole behavioral
+    // probe — the server can't be starved by the test process's blocking spawn.
+    const dir = mkdtempSync(join(tmpdir(), 'ots-auth-run-'));
+    const out = join(dir, 'client.ts');
+    generate(fixture, out);
+
+    const captured = runConsumer(
+      dir,
+      outdent`
+        import * as http from 'node:http';
+        import { configure, getBearer, getQuery, setBearer, setApiKeyQueryKey } from './client.js';
+
+        const captured: Array<{ url: string; auth?: string }> = [];
+        const server = http.createServer((req, res) => {
+          captured.push({ url: req.url ?? '', auth: req.headers['authorization'] as string | undefined });
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ id: 'x' }));
+        });
+
+        async function main() {
+          await new Promise<void>((r) => server.listen(0, '127.0.0.1', r));
+          const port = (server.address() as { port: number }).port;
+          configure({ serverUrl: 'http://127.0.0.1:' + port });
+          setBearer(async () => 'tok');
+          await getBearer();
+          setApiKeyQueryKey('secret-key');
+          await getQuery({ limit: 5 });
+          await new Promise<void>((r) => server.close(() => r()));
+          process.stdout.write(JSON.stringify(captured));
+        }
+        main().then(() => process.exit(0)).catch((e) => { console.error(e); process.exit(1); });
+      `
+    ) as Array<{ url: string; auth?: string }>;
+    rmSync(dir, { recursive: true, force: true });
+
+    const bearerReq = captured.find((c) => c.url.startsWith('/bearer'));
+    expect(bearerReq, JSON.stringify(captured)).toBeDefined();
+    expect(bearerReq!.auth).toBe('Bearer tok');
+
+    const queryReq = captured.find((c) => c.url.startsWith('/query'));
+    expect(queryReq, JSON.stringify(captured)).toBeDefined();
+    expect(queryReq!.url).toContain('api_key=secret-key');
+  }, 90_000);
+});
diff --git a/tests/e2e/generate-client/base-consumer/.gitignore b/tests/e2e/generate-client/base-consumer/.gitignore
new file mode 100644
index 0000000000..35d9162694
--- /dev/null
+++ b/tests/e2e/generate-client/base-consumer/.gitignore
@@ -0,0 +1,2 @@
+# Generated fresh by the owning suite in beforeAll; excluded from the root typecheck.
+api.ts
diff --git a/tests/e2e/generate-client/base-consumer/index-cancel.ts b/tests/e2e/generate-client/base-consumer/index-cancel.ts
new file mode 100644
index 0000000000..f011811716
--- /dev/null
+++ b/tests/e2e/generate-client/base-consumer/index-cancel.ts
@@ -0,0 +1,22 @@
+import { getSlowPet } from './api.js';
+
+async function main(): Promise<void> {
+  const controller = new AbortController();
+  const promise = getSlowPet(1, { signal: controller.signal });
+  setTimeout(() => controller.abort(), 100);
+  try {
+    await promise;
+    process.stdout.write('NOT_CANCELLED\n');
+  } catch (error) {
+    if (error instanceof Error) {
+      process.stdout.write(`CANCELLED:${error.name}\n`);
+      return;
+    }
+    process.stdout.write(`CANCELLED:UNKNOWN\n`);
+  }
+}
+
+main().catch((error) => {
+  process.stderr.write(`UNHANDLED: ${error instanceof Error ? error.message : String(error)}\n`);
+  process.exit(1);
+});
diff --git a/tests/e2e/generate-client/base-consumer/index.ts b/tests/e2e/generate-client/base-consumer/index.ts
new file mode 100644
index 0000000000..08f9b3b2df
--- /dev/null
+++ b/tests/e2e/generate-client/base-consumer/index.ts
@@ -0,0 +1,23 @@
+import { createPet, getPetById, listPets } from './api.js';
+
+async function main(): Promise<void> {
+  const pet = await getPetById(1);
+
+  // deepObject query param: the object is serialized as filter[name]=…&filter[status]=…
+  const filtered = await listPets({ filter: { name: 'rex', status: 'available' } });
+
+  // Bucket C: the create body is `Omit<Pet, "id">`, so the readOnly server-assigned
+  // `id` is neither required nor accepted — this call compiles without it.
+  const created = await createPet({ name: 'rex', status: 'available' });
+
+  // Bucket B: `metadata` is a free-form record (`{ [key: string]: unknown }`), so an
+  // arbitrary key is accessible. Were it emitted as `{}`, this line would not compile.
+  const note = pet.metadata?.['note'] ?? null;
+
+  process.stdout.write(JSON.stringify({ pet, filtered, created, note }) + '\n');
+}
+
+main().catch((error) => {
+  process.stderr.write(`UNHANDLED: ${error instanceof Error ? error.message : String(error)}\n`);
+  process.exit(1);
+});
diff --git a/tests/e2e/generate-client/base-consumer/package.json b/tests/e2e/generate-client/base-consumer/package.json
new file mode 100644
index 0000000000..ff38f8cb36
--- /dev/null
+++ b/tests/e2e/generate-client/base-consumer/package.json
@@ -0,0 +1,6 @@
+{
+  "name": "base-consumer",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module"
+}
diff --git a/tests/e2e/generate-client/base-consumer/redocly-mock-server.d.ts b/tests/e2e/generate-client/base-consumer/redocly-mock-server.d.ts
new file mode 100644
index 0000000000..d38248043a
--- /dev/null
+++ b/tests/e2e/generate-client/base-consumer/redocly-mock-server.d.ts
@@ -0,0 +1,33 @@
+// Ambient declarations for @redocly/mock-server.
+// The published package ships only a bundled dist/bin.js with no .d.ts files,
+// so we describe just the subset of the public API the test harness uses.
+
+declare module '@redocly/mock-server' {
+  export interface MockServerRequest {
+    readonly path: string;
+    readonly method: string;
+    readonly query?: string;
+    readonly headers: Record<string, string>;
+    getBody(): Promise<Buffer | undefined>;
+  }
+
+  export interface MockServerResponse {
+    statusCode: number;
+    headers?: Record<string, string>;
+    body?: Buffer;
+  }
+
+  export type MockServerRequestHandler = (
+    request: MockServerRequest
+  ) => Promise<MockServerResponse>;
+
+  export interface MockServerUserConfig {
+    strictExamples?: boolean;
+    errorIfForcedExampleNotFound?: boolean;
+  }
+
+  export function createMockServer(
+    definitionInput: string | Record<string, unknown>,
+    userConfig?: MockServerUserConfig
+  ): Promise<MockServerRequestHandler>;
+}
diff --git a/tests/e2e/generate-client/base-consumer/server.ts b/tests/e2e/generate-client/base-consumer/server.ts
new file mode 100644
index 0000000000..77e1c19fe0
--- /dev/null
+++ b/tests/e2e/generate-client/base-consumer/server.ts
@@ -0,0 +1,115 @@
+import {
+  createMockServer,
+  type MockServerRequest,
+  type MockServerRequestHandler,
+} from '@redocly/mock-server';
+import * as http from 'node:http';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+type LogEntry = { method: string; url: string };
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SPEC_PATH = join(__dirname, '..', 'fixtures', 'base.yaml');
+const PORT = Number.parseInt(process.env.BASE_SERVER_PORT ?? '3102', 10);
+
+const requestLog: LogEntry[] = [];
+
+async function readBody(req: http.IncomingMessage): Promise<Buffer | undefined> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of req) {
+    chunks.push(chunk as Buffer);
+  }
+  return chunks.length > 0 ? Buffer.concat(chunks) : undefined;
+}
+
+function toMockRequest(req: http.IncomingMessage, body: Buffer | undefined): MockServerRequest {
+  const { pathname, search } = new URL(req.url ?? '/', 'http://localhost');
+  const headers: Record<string, string> = {};
+  for (const [name, value] of Object.entries(req.headers)) {
+    if (typeof value === 'string') {
+      headers[name.toLowerCase()] = value;
+    } else if (Array.isArray(value)) {
+      headers[name.toLowerCase()] = value.join(',');
+    }
+  }
+  return {
+    path: pathname,
+    method: req.method ?? 'GET',
+    query: search !== '' ? search : undefined,
+    headers,
+    getBody: () => Promise.resolve(body),
+  };
+}
+
+let handler: MockServerRequestHandler;
+
+const server = http.createServer(async (req, res) => {
+  const method = req.method ?? 'GET';
+  const url = req.url ?? '';
+
+  if (url === '/__test__/ready') {
+    res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' });
+    res.end('ready');
+    return;
+  }
+  if (url === '/__test__/log') {
+    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+    res.end(JSON.stringify(requestLog));
+    return;
+  }
+
+  requestLog.push({ method, url });
+
+  const { pathname } = new URL(url, 'http://localhost');
+
+  // The cancellation operation needs a response slow enough to abort mid-flight.
+  // mock-server replies instantly, so this path is held open here instead of
+  // being delegated to it.
+  if (method === 'GET' && /^\/pets\/\d+\/cancel-test$/.test(pathname)) {
+    let aborted = false;
+    req.on('close', () => {
+      aborted = true;
+    });
+    const timer = setTimeout(() => {
+      if (aborted) return;
+      res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+      res.end(JSON.stringify({ id: 1, name: 'Slow', status: 'available' }));
+    }, 30_000);
+    res.on('close', () => clearTimeout(timer));
+    return;
+  }
+
+  const body = await readBody(req);
+  try {
+    const response = await handler(toMockRequest(req, body));
+    res.writeHead(response.statusCode, response.headers ?? {});
+    res.end(response.body);
+  } catch (error) {
+    res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+    res.end(JSON.stringify({ error: 'mock-server failed' }));
+  }
+});
+
+async function main(): Promise<void> {
+  handler = await createMockServer(SPEC_PATH);
+  server.listen(PORT, () => {
+    process.stdout.write(`READY ${PORT}\n`);
+  });
+}
+
+const shutdown = (): void => {
+  server.close(() => {
+    process.exit(0);
+  });
+};
+
+process.on('SIGTERM', shutdown);
+process.on('SIGINT', shutdown);
+
+main().catch((error) => {
+  process.stderr.write(
+    `base mock server failed to start: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`
+  );
+  process.exit(1);
+});
diff --git a/tests/e2e/generate-client/base-consumer/tsconfig.json b/tests/e2e/generate-client/base-consumer/tsconfig.json
new file mode 100644
index 0000000000..3e2badaaea
--- /dev/null
+++ b/tests/e2e/generate-client/base-consumer/tsconfig.json
@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "target": "es2022",
+    "lib": ["ES2022", "DOM"],
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "types": ["node"]
+  },
+  "include": ["./**/*.ts"]
+}
diff --git a/tests/e2e/generate-client/base.test.ts b/tests/e2e/generate-client/base.test.ts
new file mode 100644
index 0000000000..d5973551c9
--- /dev/null
+++ b/tests/e2e/generate-client/base.test.ts
@@ -0,0 +1,143 @@
+import { spawnSync, type ChildProcess } from 'node:child_process';
+import { existsSync, readFileSync, rmSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { generate, killServer, repoRoot, startServer } from './helpers.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const fixture = join(__dirname, 'fixtures/base.yaml');
+const consumerDir = join(__dirname, 'base-consumer');
+const generatedFile = join(consumerDir, 'api.ts');
+const serverScript = join(consumerDir, 'server.ts');
+const indexScript = join(consumerDir, 'index.ts');
+const cancelScript = join(consumerDir, 'index-cancel.ts');
+
+const SERVER_PORT = 3102;
+const SERVER_BASE = `http://127.0.0.1:${SERVER_PORT}`;
+
+describe('generate-client base consumer (single-file output)', () => {
+  let serverProcess: ChildProcess | undefined;
+
+  beforeAll(async () => {
+    if (existsSync(generatedFile)) {
+      rmSync(generatedFile, { force: true });
+    }
+
+    serverProcess = await startServer(
+      serverScript,
+      consumerDir,
+      { BASE_SERVER_PORT: String(SERVER_PORT) },
+      SERVER_BASE,
+      'base-server'
+    );
+  }, 30_000);
+
+  afterAll(async () => {
+    if (serverProcess) {
+      await killServer(serverProcess);
+    }
+  });
+
+  test('end-to-end: generate single file, type-check, run, assert real call', async () => {
+    generate(fixture, generatedFile);
+
+    expect(existsSync(generatedFile)).toBe(true);
+    const generated = readFileSync(generatedFile, 'utf-8');
+    expect(generated).toContain('export type Pet');
+    expect(generated).toContain('export class ApiError');
+    // The descriptor wiring with the embedded runtime, plus flat call sugar per operation.
+    expect(generated).toContain('// ─── Embedded runtime');
+    expect(generated).toContain('as const satisfies Record<string, OperationDescriptor>');
+    expect(generated).toContain('export const { configure, use } = client;');
+    expect(generated).toContain('export const getPetById = (');
+    expect(generated).toContain('export const getSlowPet = (');
+    expect(generated).toContain('export const listPets = (');
+    // The spec's server URL is baked into the client instance.
+    expect(generated).toContain(
+      'export const client = createClient<Ops, OperationId, OperationPath, string>(OPERATIONS, { serverUrl: "http://localhost:3102" });'
+    );
+    // An OAS 3.1 enum that includes null renders as a nullable union.
+    expect(generated).toMatch(/status\?:\s*\("available" \| "pending" \| "sold"\) \| null;/);
+    // A free-form object (`type: object`, no properties) renders as a record, not `{}`.
+    expect(generated).toMatch(/metadata\?:\s*Record<string, unknown>;/);
+    // readOnly `id` is dropped from the create body via Omit (the response Pet keeps it).
+    expect(generated).toContain('export type CreatePetBody = Omit<Pet, "id">;');
+    // The readOnly `id` carries the `readonly` modifier on the model (for OmitReadOnly<T>).
+    expect(generated).toMatch(/readonly id\?: number;/);
+    // A oneOf with an empty branch keeps the real type — no `| unknown` collapse.
+    expect(generated).toMatch(/owner\?:\s*string;/);
+    expect(generated).not.toContain('| unknown');
+    // OAS 3.1 single null type renders as `null`, not `unknown`.
+    expect(generated).toMatch(/deletedAt\?:\s*null;/);
+    // A discriminated union nested as array items emits guards narrowing the members.
+    expect(generated).toContain(
+      'export function isPetBulkSuccessItem(value: PetBulkSuccessItem | PetBulkErrorItem): value is PetBulkSuccessItem {'
+    );
+    expect(generated).toContain(
+      'export function isPetBulkErrorItem(value: PetBulkSuccessItem | PetBulkErrorItem): value is PetBulkErrorItem {'
+    );
+    // A schema with its own properties AND allOf keeps the own discriminant.
+    expect(generated).toContain('export type ExtendedPet =');
+    expect(generated).toMatch(/kind:\s*"extended";/);
+    expect(generated).toContain('} & Pet;');
+
+    const typecheckResult = spawnSync('npx', ['tsc', '--noEmit', '-p', consumerDir], {
+      encoding: 'utf-8',
+      cwd: repoRoot,
+    });
+    expect(
+      typecheckResult.status,
+      `tsc --noEmit failed:\nstdout:\n${typecheckResult.stdout}\nstderr:\n${typecheckResult.stderr}`
+    ).toBe(0);
+
+    const runResult = spawnSync('npx', ['tsx', indexScript], {
+      encoding: 'utf-8',
+      cwd: consumerDir,
+    });
+    expect(
+      runResult.status,
+      `consumer stdout:\n${runResult.stdout}\nstderr:\n${runResult.stderr}`
+    ).toBe(0);
+    const parsed = JSON.parse(runResult.stdout.trim()) as {
+      pet: { id: number; name: string };
+      filtered: Array<{ id: number; name: string }>;
+      created: { name: string };
+    };
+    expect(typeof parsed.pet.id).toBe('number');
+    expect(typeof parsed.pet.name).toBe('string');
+    expect(Array.isArray(parsed.filtered)).toBe(true);
+    // Bucket C round-trip: createPet ran with a body that omits the readOnly `id`.
+    expect(typeof parsed.created.name).toBe('string');
+
+    const logResponse = await fetch(`${SERVER_BASE}/__test__/log`);
+    const log = (await logResponse.json()) as Array<{ method: string; url: string }>;
+    expect(log).toContainEqual({ method: 'GET', url: '/pets/1' });
+    expect(log).toContainEqual({ method: 'POST', url: '/pets' });
+    expect(
+      log.some(
+        (e) =>
+          e.method === 'GET' &&
+          e.url.startsWith('/pets?') &&
+          e.url.includes('filter%5Bname%5D=rex') &&
+          e.url.includes('filter%5Bstatus%5D=available')
+      ),
+      `deepObject query not found in log:\n${JSON.stringify(log, null, 2)}`
+    ).toBe(true);
+  }, 60_000);
+
+  test('cancel: AbortController aborts the underlying request', async () => {
+    expect(existsSync(generatedFile), 'previous test must have produced api.ts').toBe(true);
+
+    const cancelResult = spawnSync('npx', ['tsx', cancelScript], {
+      encoding: 'utf-8',
+      cwd: consumerDir,
+      timeout: 15_000,
+    });
+    expect(
+      cancelResult.status,
+      `cancel stdout:\n${cancelResult.stdout}\nstderr:\n${cancelResult.stderr}`
+    ).toBe(0);
+    expect(cancelResult.stdout.trim()).toBe('CANCELLED:AbortError');
+  }, 30_000);
+});
diff --git a/tests/e2e/generate-client/cafe-consumer/.gitignore b/tests/e2e/generate-client/cafe-consumer/.gitignore
new file mode 100644
index 0000000000..35d9162694
--- /dev/null
+++ b/tests/e2e/generate-client/cafe-consumer/.gitignore
@@ -0,0 +1,2 @@
+# Generated fresh by the owning suite in beforeAll; excluded from the root typecheck.
+api.ts
diff --git a/tests/e2e/generate-client/cafe-consumer/index-configure.ts b/tests/e2e/generate-client/cafe-consumer/index-configure.ts
new file mode 100644
index 0000000000..9a7f2013c2
--- /dev/null
+++ b/tests/e2e/generate-client/cafe-consumer/index-configure.ts
@@ -0,0 +1,59 @@
+import { configure, listMenuItems } from './api.js';
+
+type StepResult = { kind: 'ok'; name: string } | { kind: 'err'; name: string; error: string };
+
+function requireEnv(name: string): string {
+  const value = process.env[name];
+  if (!value) {
+    process.stderr.write(
+      `${name} env var required for the configure({ serverUrl }) mid-flight test\n`
+    );
+    process.exit(1);
+  }
+  return value;
+}
+
+const liveBase = requireEnv('CAFE_BASE');
+
+// Port 1 is reserved/unassigned — any connect attempt fails fast (ECONNREFUSED / ENOTFOUND).
+// We use it as the "obviously unreachable" base to prove serverUrl actually moved.
+const UNREACHABLE = 'http://127.0.0.1:1';
+
+async function step(name: string, run: () => Promise<unknown>): Promise<StepResult> {
+  try {
+    await run();
+    return { kind: 'ok', name };
+  } catch (error) {
+    return {
+      kind: 'err',
+      name,
+      error: error instanceof Error ? `${error.name}: ${error.message}` : String(error),
+    };
+  }
+}
+
+async function main(): Promise<void> {
+  const results: StepResult[] = [];
+
+  // 1) Baseline: the file was generated with --server-url ${CAFE_BASE}, so the first
+  //    call should succeed against the mock server.
+  results.push(await step('initial-call-against-mock', () => listMenuItems({ limit: 1 })));
+
+  // 2) Flip serverUrl to an unreachable host. The same operation should now fail to
+  //    connect. This is the proof that configure() actually mutated the instance config.
+  configure({ serverUrl: UNREACHABLE });
+  results.push(
+    await step('call-after-configure-to-unreachable', () => listMenuItems({ limit: 1 }))
+  );
+
+  // 3) Flip serverUrl back to the live mock and confirm the config restored cleanly.
+  configure({ serverUrl: liveBase });
+  results.push(await step('call-after-configure-restored', () => listMenuItems({ limit: 1 })));
+
+  process.stdout.write(JSON.stringify(results, null, 2) + '\n');
+}
+
+main().catch((error) => {
+  process.stderr.write(`UNHANDLED: ${error instanceof Error ? error.message : String(error)}\n`);
+  process.exit(1);
+});
diff --git a/tests/e2e/generate-client/cafe-consumer/index.ts b/tests/e2e/generate-client/cafe-consumer/index.ts
new file mode 100644
index 0000000000..e5a0ad2b7e
--- /dev/null
+++ b/tests/e2e/generate-client/cafe-consumer/index.ts
@@ -0,0 +1,187 @@
+import {
+  ApiError,
+  createOrder,
+  deleteMenuItem,
+  deleteOrder,
+  getMenuItemPhoto,
+  getOrderById,
+  getRevenue,
+  listMenuItems,
+  listOrderItems,
+  listOrders,
+  registerOAuth2Client,
+  setApiKey,
+  setBearer,
+  updateOrder,
+  createMenuItem,
+  isBeverage,
+  isDessert,
+  OrderStatus,
+} from './api.js';
+
+type StepResult =
+  | { kind: 'ok'; name: string; data: unknown }
+  | { kind: 'err'; name: string; error: string };
+
+async function step(name: string, run: () => Promise<unknown>): Promise<StepResult> {
+  try {
+    const data = await run();
+    return { kind: 'ok', name, data };
+  } catch (error) {
+    return {
+      kind: 'err',
+      name,
+      error: error instanceof Error ? `${error.name}: ${error.message}` : String(error),
+    };
+  }
+}
+
+async function main(): Promise<void> {
+  const results: StepResult[] = [];
+
+  // Set credentials once. Every OAuth2/bearer operation now sends
+  // `Authorization: Bearer <token>`, and every ApiKey operation sends the
+  // `X-API-Key` header. Operations declared `security: []` send neither.
+  setBearer('test-bearer-token');
+  setApiKey('test-api-key');
+
+  results.push(
+    await step('listMenuItems', () =>
+      listMenuItems({ after: 'cursor1', limit: 5, sort: '-name', search: 'coffee' })
+    )
+  );
+
+  results.push(
+    await step('createMenuItem', () => {
+      const form = new FormData();
+      form.append('name', 'Latte');
+      form.append('price', '400');
+      form.append('category', 'beverage');
+      form.append('volume', '250');
+      form.append('containsCaffeine', 'true');
+      return createMenuItem(form);
+    })
+  );
+
+  results.push(
+    await step('deleteMenuItem', () => deleteMenuItem('prd_01h1s5z6vf2mm1mz3hevnn9va7'))
+  );
+
+  results.push(
+    await step('getMenuItemPhoto', async () => {
+      const result = await getMenuItemPhoto('prd_01h1s5z6vf2mm1mz3hevnn9va7', {
+        photoSize: 'medium',
+      });
+      if (result instanceof Blob) {
+        return { kind: 'blob', size: result.size, type: result.type };
+      }
+      return { kind: 'text', value: result };
+    })
+  );
+
+  results.push(await step('listOrders', () => listOrders({ filter: 'status:placed', limit: 5 })));
+
+  results.push(
+    await step('createOrder', () =>
+      createOrder({
+        customerName: 'Ada Lovelace',
+        orderItems: [{ menuItemId: 'prd_01h1s5z6vf2mm1mz3hevnn9va7', quantity: 2 }],
+      })
+    )
+  );
+
+  results.push(
+    await step('getOrderById', () =>
+      getOrderById('ord_01h1s5z6vf2mm1mz3hevnn9va7', {
+        'X-Request-Id': '11111111-2222-3333-4444-555555555555',
+      })
+    )
+  );
+
+  results.push(
+    await step('updateOrder', () =>
+      updateOrder('ord_01h1s5z6vf2mm1mz3hevnn9va7', { status: OrderStatus.completed })
+    )
+  );
+
+  results.push(await step('deleteOrder', () => deleteOrder('ord_01h1s5z6vf2mm1mz3hevnn9va7')));
+
+  results.push(
+    await step('listOrderItems', () =>
+      listOrderItems({ filter: 'orderId:ord_01h1s5z6vf2mm1mz3hevnn9va7' })
+    )
+  );
+
+  results.push(
+    await step('getRevenue', () => getRevenue({ startDate: '2026-01-01', endDate: '2026-01-31' }))
+  );
+
+  results.push(
+    await step('registerOAuth2Client', () =>
+      registerOAuth2Client({
+        name: 'demo-client',
+        scopes: ['menu:read', 'orders:read'],
+        grantTypes: ['client_credentials'],
+      })
+    )
+  );
+
+  // Narrow a MenuItem from a real server response with the discriminated-union
+  // type guards and confirm they agree with the raw discriminant.
+  results.push(
+    await step('menuItemGuards', async () => {
+      const list = await listMenuItems({});
+      const item = list.items[0];
+      const category = (item as { category?: string }).category;
+      const beverage = isBeverage(item);
+      const dessert = isDessert(item);
+      return {
+        category,
+        isBeverage: beverage,
+        isDessert: dessert,
+        // Guards must agree with the actual discriminant, and exactly one holds.
+        agree: beverage === (category === 'beverage') && dessert === (category === 'dessert'),
+        exclusive: beverage !== dessert,
+      };
+    })
+  );
+
+  // Negative: error path returns ApiError.
+  results.push(
+    await step('error-path', async () => {
+      try {
+        await fetch('http://127.0.0.1:0/'); // Trigger fetch failure type.
+      } catch {
+        /* no-op */
+      }
+      try {
+        // Hit /__test__/boom by reaching through the generated runtime indirectly:
+        // we don't have a generated function for it, so we use the public ApiError shape via a raw fetch.
+        const response = await fetch(
+          `${process.env.CAFE_BASE ?? 'http://127.0.0.1:3101'}/__test__/boom`
+        );
+        if (!response.ok) {
+          throw new ApiError(
+            response.url,
+            response.status,
+            response.statusText,
+            await response.json()
+          );
+        }
+        return { unreachable: true };
+      } catch (error) {
+        if (error instanceof ApiError) {
+          return { apiError: true, status: error.status, statusText: error.statusText };
+        }
+        throw error;
+      }
+    })
+  );
+
+  process.stdout.write(JSON.stringify(results, null, 2) + '\n');
+}
+
+main().catch((error) => {
+  process.stderr.write(`UNHANDLED: ${error instanceof Error ? error.message : String(error)}\n`);
+  process.exit(1);
+});
diff --git a/tests/e2e/generate-client/cafe-consumer/package.json b/tests/e2e/generate-client/cafe-consumer/package.json
new file mode 100644
index 0000000000..469a68d40e
--- /dev/null
+++ b/tests/e2e/generate-client/cafe-consumer/package.json
@@ -0,0 +1,5 @@
+{
+  "name": "cafe-consumer",
+  "private": true,
+  "type": "module"
+}
diff --git a/tests/e2e/generate-client/cafe-consumer/redocly-mock-server.d.ts b/tests/e2e/generate-client/cafe-consumer/redocly-mock-server.d.ts
new file mode 100644
index 0000000000..d38248043a
--- /dev/null
+++ b/tests/e2e/generate-client/cafe-consumer/redocly-mock-server.d.ts
@@ -0,0 +1,33 @@
+// Ambient declarations for @redocly/mock-server.
+// The published package ships only a bundled dist/bin.js with no .d.ts files,
+// so we describe just the subset of the public API the test harness uses.
+
+declare module '@redocly/mock-server' {
+  export interface MockServerRequest {
+    readonly path: string;
+    readonly method: string;
+    readonly query?: string;
+    readonly headers: Record<string, string>;
+    getBody(): Promise<Buffer | undefined>;
+  }
+
+  export interface MockServerResponse {
+    statusCode: number;
+    headers?: Record<string, string>;
+    body?: Buffer;
+  }
+
+  export type MockServerRequestHandler = (
+    request: MockServerRequest
+  ) => Promise<MockServerResponse>;
+
+  export interface MockServerUserConfig {
+    strictExamples?: boolean;
+    errorIfForcedExampleNotFound?: boolean;
+  }
+
+  export function createMockServer(
+    definitionInput: string | Record<string, unknown>,
+    userConfig?: MockServerUserConfig
+  ): Promise<MockServerRequestHandler>;
+}
diff --git a/tests/e2e/generate-client/cafe-consumer/server.ts b/tests/e2e/generate-client/cafe-consumer/server.ts
new file mode 100644
index 0000000000..fce4fa3806
--- /dev/null
+++ b/tests/e2e/generate-client/cafe-consumer/server.ts
@@ -0,0 +1,149 @@
+import {
+  createMockServer,
+  type MockServerRequest,
+  type MockServerRequestHandler,
+} from '@redocly/mock-server';
+import * as http from 'node:http';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+type LogEntry = {
+  method: string;
+  url: string;
+  contentType: string | undefined;
+  body: string;
+  headers: Record<string, string>;
+};
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SPEC_PATH = join(__dirname, '..', 'fixtures', 'cafe.yaml');
+const PORT = Number.parseInt(process.env.CAFE_SERVER_PORT ?? '3101', 10);
+
+const requestLog: LogEntry[] = [];
+
+async function readBody(req: http.IncomingMessage): Promise<Buffer | undefined> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of req) {
+    chunks.push(chunk as Buffer);
+  }
+  return chunks.length > 0 ? Buffer.concat(chunks) : undefined;
+}
+
+// @redocly/mock-server's request shape is decoupled from Node's `http` types,
+// so we adapt the IncomingMessage to the small interface the mock handler expects.
+// We also inject benign auth headers when missing: cafe.yaml has OAuth2 and ApiKey
+// requirements on most operations, but the generated client doesn't ship credentials
+// in tests. Mock-server's auth checks are presence-only, so a dummy bearer/api-key
+// is enough to satisfy them without changing what the consumer actually sends.
+function toMockRequest(req: http.IncomingMessage, body: Buffer | undefined): MockServerRequest {
+  const { pathname, search } = new URL(req.url ?? '/', 'http://localhost');
+  const headers: Record<string, string> = {};
+  for (const [name, value] of Object.entries(req.headers)) {
+    if (typeof value === 'string') {
+      headers[name.toLowerCase()] = value;
+    } else if (Array.isArray(value)) {
+      headers[name.toLowerCase()] = value.join(',');
+    }
+  }
+  if (!headers['authorization']) {
+    headers['authorization'] = 'Bearer test-token';
+  }
+  if (!headers['x-api-key']) {
+    headers['x-api-key'] = 'test-key';
+  }
+  // POST /menu is multipart/form-data with a typed schema (number, boolean), but
+  // FormData transmits everything as strings, so mock-server's body validation rejects
+  // the request. We force a 201 example response, which the test contract already covers
+  // by asserting on the (logged) multipart payload the consumer sent.
+  if (pathname === '/menu' && (req.method ?? 'GET').toUpperCase() === 'POST') {
+    headers['x-redocly-response-status'] = '201';
+  }
+  return {
+    path: pathname,
+    method: req.method ?? 'GET',
+    query: search !== '' ? search : undefined,
+    headers,
+    getBody: () => Promise.resolve(body),
+  };
+}
+
+let handler: MockServerRequestHandler;
+
+const server = http.createServer(async (req, res) => {
+  const method = req.method ?? 'GET';
+  const url = req.url ?? '';
+
+  // Test-only utility endpoints. These bypass the mock server entirely so the
+  // test harness can probe readiness, inspect the request log, and exercise
+  // the generated ApiError path without relying on spec semantics.
+  if (url === '/__test__/ready') {
+    res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' });
+    res.end('ready');
+    return;
+  }
+  if (url === '/__test__/log') {
+    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+    res.end(JSON.stringify(requestLog));
+    return;
+  }
+  if (url === '/__test__/log/clear' && method === 'POST') {
+    requestLog.length = 0;
+    res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' });
+    res.end('cleared');
+    return;
+  }
+  if (url === '/__test__/boom' && method === 'GET') {
+    res.writeHead(500, { 'Content-Type': 'application/problem+json; charset=utf-8' });
+    res.end(JSON.stringify({ type: 'about:blank', title: 'Boom', status: 500 }));
+    return;
+  }
+
+  const body = await readBody(req);
+  const loggedHeaders: Record<string, string> = {};
+  for (const [name, value] of Object.entries(req.headers)) {
+    if (typeof value === 'string') {
+      loggedHeaders[name.toLowerCase()] = value;
+    } else if (Array.isArray(value)) {
+      loggedHeaders[name.toLowerCase()] = value.join(',');
+    }
+  }
+  requestLog.push({
+    method,
+    url,
+    contentType: req.headers['content-type'],
+    body: body ? body.toString('utf8') : '',
+    headers: loggedHeaders,
+  });
+
+  try {
+    const response = await handler(toMockRequest(req, body));
+    res.writeHead(response.statusCode, response.headers ?? {});
+    res.end(response.body);
+  } catch (error) {
+    res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+    res.end(JSON.stringify({ error: 'mock-server failed' }));
+  }
+});
+
+async function main(): Promise<void> {
+  handler = await createMockServer(SPEC_PATH);
+  server.listen(PORT, () => {
+    process.stdout.write(`READY ${PORT}\n`);
+  });
+}
+
+const shutdown = (): void => {
+  server.close(() => {
+    process.exit(0);
+  });
+};
+
+process.on('SIGTERM', shutdown);
+process.on('SIGINT', shutdown);
+
+main().catch((error) => {
+  process.stderr.write(
+    `cafe mock server failed to start: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`
+  );
+  process.exit(1);
+});
diff --git a/tests/e2e/generate-client/cafe-consumer/tsconfig.json b/tests/e2e/generate-client/cafe-consumer/tsconfig.json
new file mode 100644
index 0000000000..3e2badaaea
--- /dev/null
+++ b/tests/e2e/generate-client/cafe-consumer/tsconfig.json
@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "target": "es2022",
+    "lib": ["ES2022", "DOM"],
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "types": ["node"]
+  },
+  "include": ["./**/*.ts"]
+}
diff --git a/tests/e2e/generate-client/cafe.snapshot.ts b/tests/e2e/generate-client/cafe.snapshot.ts
new file mode 100644
index 0000000000..47bec4ff48
--- /dev/null
+++ b/tests/e2e/generate-client/cafe.snapshot.ts
@@ -0,0 +1,1990 @@
+// Generated by @redocly/client-generator — do not edit by hand.
+// Source: OpenAPI document. Re-run `redocly generate-client` to update.
+
+/**
+ * Redocly Cafe (v1.0.0)
+ * Demo API for cafe operators (not customers) to manage menus, orders, and revenue.
+ * Create API credentials and try it yourself in a realistic OpenAPI workflow.
+ * 
+ */
+
+export type Page = {
+    /**
+     * Use with the `after` query parameter to load the next page of data.
+     * When `null`, there is no data.
+     * The cursor is opaque and internal structure is subject to change.
+     */
+    endCursor: string | null;
+    /**
+     * Use with the `before` query parameter to load the previous page of data.
+     * When `null`, there is no data.
+     * The cursor is opaque and internal structure is subject to change.
+     */
+    startCursor: string | null;
+    /**
+     * Indicates if there is a next page with items.
+     */
+    hasNextPage: boolean;
+    /**
+     * Indicates if there is a previous page with items.
+     */
+    hasPrevPage: boolean;
+    /**
+     * Value showing how many items are in the page limit.
+     * @minimum 1
+     * @maximum 100
+     */
+    limit: number;
+    /**
+     * Count of items across all pages.
+     * @minimum 0
+     */
+    total: number;
+};
+
+export type MenuBaseItem = {
+    /**
+     * Created date.
+     * @format date-time
+     */
+    readonly createdAt: string;
+    /**
+     * Updated date.
+     * @format date-time
+     */
+    readonly updatedAt: string;
+    /**
+     * Menu item ID. Unique identifier prefixed with `prd_`.
+     * @pattern ^prd_[0-9abcdefghjkmnpqrstvwxyz]{26}$
+     */
+    readonly id: string;
+    /**
+     * Entity name.
+     */
+    readonly object: "menuItem";
+    /**
+     * Menu item name.
+     * @minLength 1
+     * @maxLength 50
+     */
+    name: string;
+    /**
+     * Price in cents.
+     * @minimum 0
+     */
+    price: number;
+    /**
+     * Photo of the menu item. Must be a PNG image and less than 1MB.
+     * @format binary
+     */
+    photo?: Blob | null;
+    /**
+     * Photo URL of the menu item.
+     * @format uri
+     */
+    readonly photoUrl?: string;
+    photoTextDescription?: string | null;
+};
+
+export type Beverage = {
+    /**
+     * Menu item category.
+     */
+    category: "beverage";
+    /**
+     * Size of the beverage in milliliters.
+     * @exclusiveMinimum 0
+     */
+    volume: number;
+    /**
+     * Indicates if the beverage contains caffeine.
+     */
+    containsCaffeine: boolean;
+} & MenuBaseItem;
+
+export type Dessert = {
+    /**
+     * Menu item category.
+     */
+    category: "dessert";
+    /**
+     * Amount of calories.
+     * @exclusiveMinimum 0
+     */
+    calories: number;
+} & MenuBaseItem;
+
+export type MenuItem = Beverage | Dessert;
+
+export type MenuItemList = {
+    /**
+     * Entity name.
+     */
+    object: "list";
+    page: Page;
+    items: MenuItem[];
+};
+
+export type Error = {
+    /**
+     * URI reference that identifies the problem type.
+     * @format uri-reference
+     */
+    type: string;
+    /**
+     * Short summary of the problem type.
+     */
+    title: string;
+    /**
+     * HTTP status code generated by the origin server for this occurrence of the problem.
+     * @minimum 100
+     * @exclusiveMaximum 600
+     * @format int32
+     */
+    status: number;
+    /**
+     * URI reference that identifies the specific occurrence of the problem, e.g. by adding a fragment identifier or sub-path to the problem type.
+     * May be used to locate the root of this problem in the source code.
+     * @format uri-reference
+     */
+    instance?: string;
+    /**
+     * Additional error details.
+     */
+    details?: Record<string, unknown>;
+};
+
+/**
+ * Order status.
+ */
+export type OrderStatus = "placed" | "preparing" | "completed" | "canceled";
+
+export const OrderStatus = {
+    placed: "placed",
+    preparing: "preparing",
+    completed: "completed",
+    canceled: "canceled"
+} as const;
+
+export type Order = {
+    /**
+     * Order ID. Unique identifier prefixed with `ord_`.
+     * @pattern ^ord_[0-9abcdefghjkmnpqrstvwxyz]{26}$
+     * @format ulid
+     */
+    readonly id?: string;
+    /**
+     * Entity name.
+     */
+    readonly object?: "order";
+    /**
+     * Name of the customer who placed the order.
+     * Must start and end with a letter, and can contain letters, spaces, hyphens, and apostrophes (e.g., "John Doe", "Mary-Jane", "O'Brien").
+     * @minLength 1
+     * @maxLength 100
+     * @pattern ^[A-Za-z]+(?:[\s'-][A-Za-z]+)*$
+     */
+    customerName: string;
+    readonly status?: OrderStatus;
+    /**
+     * Total order price in cents.
+     * @minimum 0
+     */
+    readonly totalPrice?: number;
+    /**
+     * Created date.
+     * @format date-time
+     */
+    readonly createdAt?: string;
+    /**
+     * Updated date.
+     * @format date-time
+     */
+    readonly updatedAt?: string;
+    /**
+     * List of items to include in the order.
+     * @minItems 1
+     */
+    orderItems: {
+        /**
+         * ID of the menu item to add to the order.
+         * @format ulid
+         */
+        menuItemId: string;
+        /**
+         * Quantity of the menu item.
+         * @minimum 1
+         */
+        quantity: number;
+        /**
+         * Discount amount in cents (absolute value).
+         * @minimum 0
+         */
+        discount?: number;
+        /**
+         * Optional comment for the order item (e.g., "No sugar").
+         * @maxLength 500
+         */
+        comment?: string;
+    }[];
+};
+
+export type OrderList = {
+    /**
+     * Entity name.
+     */
+    object: "list";
+    page: Page;
+    items: Order[];
+};
+
+export type OrderItem = {
+    /**
+     * ID of the menu item to add to the order.
+     */
+    menuItemId: string;
+    /**
+     * Menu item that is part of the order.
+     */
+    readonly menuItem?: MenuItem;
+    /**
+     * Quantity of the menu item.
+     * @minimum 1
+     */
+    quantity: number;
+    /**
+     * Discount amount in cents (absolute value).
+     * @minimum 0
+     */
+    discount?: number;
+    /**
+     * Optional comment for the order item (e.g., "No sugar").
+     * @maxLength 500
+     */
+    comment?: string;
+};
+
+/**
+ * Revenue statistics for a given date range.
+ */
+export type RevenueStatistics = {
+    /**
+     * Total revenue in cents from completed orders.
+     * @minimum 0
+     * @format float
+     */
+    revenue: number;
+    /**
+     * Average order amount in cents (calculated from completed orders only).
+     * @minimum 0
+     * @format float
+     */
+    averageOrderAmount: number;
+    /**
+     * Total number of orders (all statuses) in the date range.
+     * @minimum 0
+     */
+    totalOrders: number;
+    /**
+     * Number of placed orders.
+     * @minimum 0
+     */
+    placedOrders: number;
+    /**
+     * Number of preparing orders.
+     * @minimum 0
+     */
+    preparingOrders: number;
+    /**
+     * Number of completed orders.
+     * @minimum 0
+     */
+    completedOrders: number;
+    /**
+     * Number of canceled orders.
+     * @minimum 0
+     */
+    canceledOrders: number;
+    /**
+     * Start date of the revenue calculation period.
+     * @format date
+     */
+    startDate: string;
+    /**
+     * End date of the revenue calculation period.
+     * @format date
+     */
+    endDate: string;
+};
+
+export type RegisterClientObject = {
+    /**
+     * Client name.
+     */
+    name: string;
+    /**
+     * List of redirect URIs (optional, defaults to empty array).
+     */
+    redirectUris?: string[];
+    /**
+     * List of scopes.
+     */
+    scopes?: ("menu:read" | "menu:write" | "orders:read" | "orders:write")[];
+    /**
+     * List of grant types.
+     */
+    grantTypes?: ("authorization_code" | "client_credentials")[];
+};
+
+/**
+ * OAuth2 client registration response. Per RFC 7591, includes the client identifier, secret, timestamps, and all registered client metadata.
+ */
+export type OAuth2Client = {
+    /**
+     * Client identifier issued by the authorization server.
+     */
+    clientId: string;
+    /**
+     * Client secret issued by the authorization server.
+     */
+    clientSecret: string;
+    /**
+     * Time when the client_id is issued, represented as seconds since epoch (RFC7591).
+     * @format int64
+     */
+    clientIdIssuedAt: number;
+    /**
+     * Time at which the client_secret expires, represented as seconds since epoch. 0 indicates the secret does not expire (RFC 7591).
+     * @format int64
+     */
+    clientSecretExpiresAt: number;
+    /**
+     * Client name (registered metadata).
+     */
+    name?: string;
+    /**
+     * List of redirect URIs (registered metadata).
+     */
+    redirectUris?: string[];
+    /**
+     * URL of the client configuration endpoint for managing this client registration (RFC 7592).
+     * @format uri
+     */
+    registrationClientUri: string;
+    /**
+     * Access token to be used at the client configuration endpoint for managing this client registration (RFC 7592).
+     */
+    registrationAccessToken: string;
+    /**
+     * List of scopes (registered metadata).
+     */
+    scopes?: ("menu:read" | "menu:write" | "orders:read" | "orders:write")[];
+    /**
+     * List of grant types (registered metadata).
+     */
+    grantTypes?: ("authorization_code" | "client_credentials")[];
+};
+
+export type OrderNotification = {
+    /**
+     * Unique order identifier.
+     */
+    orderId: string;
+    orderStatus: OrderStatus;
+    /**
+     * When the event occurred.
+     * @format date-time
+     */
+    timestamp: string;
+};
+
+/**
+ * Narrow a `MenuItem` to `Beverage` via its `category` discriminant.
+ */
+export function isBeverage(value: MenuItem): value is Beverage {
+    return (value as Record<string, unknown>)["category"] === "beverage";
+}
+
+/**
+ * Narrow a `MenuItem` to `Dessert` via its `category` discriminant.
+ */
+export function isDessert(value: MenuItem): value is Dessert {
+    return (value as Record<string, unknown>)["category"] === "dessert";
+}
+
+export type ListMenuItemsResult = MenuItemList;
+
+export type ListMenuItemsParams = {
+    /**
+     * Use the `endCursor` as a value for the `after` parameter to get the next page.
+     */
+    after?: string;
+    /**
+     * Use the `startCursor` as a value for the `before` parameter to get the next page.
+     */
+    before?: string;
+    /**
+     * To sort by id in descending order use `-id`.
+     * To sort by id in ascending order use `id`.
+     */
+    sort?: string;
+    /**
+     * Filters the collection items using space-separated `field:value` pairs.
+     *
+     * **Format:** `field1:value1 field2:value2`
+     *
+     * **Supported operators:**
+     * - `field:value` - Exact match
+     * - `field:value1,value2` - Match any of the comma-separated values (OR)
+     * - Time ranges: Use `30d` (30 days), `7d` (7 days), `1h` (1 hour), etc.
+     *
+     * **Examples:**
+     * - `status:placed` - Filter by single status.
+     * - `status:placed,completed` - Filter by multiple statuses.
+     * - `createdAt:30d` - Filter orders created in the last 30 days.
+     * - `orderId:ord_01h1s5z6vf2mm1mz3hevnn9va7` - Filter by specific order ID.
+     * - `status:placed createdAt:7d` - Combine multiple filters.
+     */
+    filter?: string;
+    /**
+     * Performs a case-insensitive text search across relevant fields in the collection.
+     *
+     * **Fields searched depend on the endpoint:**
+     * - **Menu items:** `name`, `photoTextDescription`
+     * - **Orders:** `customerName`, `id`
+     *
+     * Returns items where any of the searchable fields contain the search term as a substring.
+     */
+    search?: string;
+    /**
+     * Use to return a number of results per page.
+     * If there is more data, use in combination with `after` to page through the data.
+     * @minimum 1
+     * @maximum 100
+     */
+    limit?: number;
+};
+
+export type ListMenuItemsVariables = {
+    params?: ListMenuItemsParams;
+};
+
+export type CreateMenuItemResult = MenuItem;
+
+export type CreateMenuItemBody = FormData;
+
+export type CreateMenuItemVariables = {
+    body: CreateMenuItemBody;
+};
+
+export type DeleteMenuItemResult = void;
+
+export type DeleteMenuItemVariables = {
+    /**
+     * ID of the menu item to retrieve.
+     * @pattern ^prd_[0-9abcdefghjkmnpqrstvwxyz]{26}$
+     */
+    menuItemId: string;
+};
+
+export type GetMenuItemPhotoResult = Blob | string;
+
+export type GetMenuItemPhotoParams = {
+    /**
+     * Photo size to retrieve.
+     */
+    photoSize?: "thumbnail" | "medium" | "large";
+};
+
+export type GetMenuItemPhotoVariables = {
+    /**
+     * ID of the menu item to retrieve.
+     * @pattern ^prd_[0-9abcdefghjkmnpqrstvwxyz]{26}$
+     */
+    menuItemId: string;
+    params?: GetMenuItemPhotoParams;
+};
+
+export type ListOrdersResult = OrderList;
+
+export type ListOrdersParams = {
+    /**
+     * Filters the collection items using space-separated `field:value` pairs.
+     *
+     * **Format:** `field1:value1 field2:value2`
+     *
+     * **Supported operators:**
+     * - `field:value` - Exact match
+     * - `field:value1,value2` - Match any of the comma-separated values (OR)
+     * - Time ranges: Use `30d` (30 days), `7d` (7 days), `1h` (1 hour), etc.
+     *
+     * **Examples:**
+     * - `status:placed` - Filter by single status.
+     * - `status:placed,completed` - Filter by multiple statuses.
+     * - `createdAt:30d` - Filter orders created in the last 30 days.
+     * - `orderId:ord_01h1s5z6vf2mm1mz3hevnn9va7` - Filter by specific order ID.
+     * - `status:placed createdAt:7d` - Combine multiple filters.
+     */
+    filter?: string;
+    /**
+     * To sort by id in descending order use `-id`.
+     * To sort by id in ascending order use `id`.
+     */
+    sort?: string;
+    /**
+     * Use to return a number of results per page.
+     * If there is more data, use in combination with `after` to page through the data.
+     * @minimum 1
+     * @maximum 100
+     */
+    limit?: number;
+    /**
+     * Use the `endCursor` as a value for the `after` parameter to get the next page.
+     */
+    after?: string;
+    /**
+     * Use the `startCursor` as a value for the `before` parameter to get the next page.
+     */
+    before?: string;
+    /**
+     * Performs a case-insensitive text search across relevant fields in the collection.
+     *
+     * **Fields searched depend on the endpoint:**
+     * - **Menu items:** `name`, `photoTextDescription`
+     * - **Orders:** `customerName`, `id`
+     *
+     * Returns items where any of the searchable fields contain the search term as a substring.
+     */
+    search?: string;
+};
+
+export type ListOrdersVariables = {
+    params?: ListOrdersParams;
+};
+
+export type CreateOrderResult = Order;
+
+export type CreateOrderBody = Omit<Order, "id" | "object" | "status" | "totalPrice" | "createdAt" | "updatedAt">;
+
+export type CreateOrderVariables = {
+    body: CreateOrderBody;
+};
+
+export type GetOrderByIdResult = Order;
+
+export type GetOrderByIdHeaders = {
+    /**
+     * Optional client-supplied correlation ID, echoed in logs and traces.
+     * @format uuid
+     */
+    "X-Request-Id"?: string;
+};
+
+export type GetOrderByIdVariables = {
+    /**
+     * ID of the order to retrieve.
+     * @pattern ^ord_[0-9abcdefghjkmnpqrstvwxyz]{26}$
+     */
+    orderId: string;
+    headers?: GetOrderByIdHeaders;
+};
+
+export type DeleteOrderResult = void;
+
+export type DeleteOrderVariables = {
+    /**
+     * ID of the order to retrieve.
+     * @pattern ^ord_[0-9abcdefghjkmnpqrstvwxyz]{26}$
+     */
+    orderId: string;
+};
+
+export type UpdateOrderResult = Order;
+
+export type UpdateOrderBody = {
+    status: OrderStatus;
+};
+
+export type UpdateOrderVariables = {
+    /**
+     * ID of the order to retrieve.
+     * @pattern ^ord_[0-9abcdefghjkmnpqrstvwxyz]{26}$
+     */
+    orderId: string;
+    body?: UpdateOrderBody;
+};
+
+export type ListOrderItemsResult = OrderItem[];
+
+export type ListOrderItemsParams = {
+    /**
+     * Filters the collection items using space-separated `field:value` pairs.
+     *
+     * **Format:** `field1:value1 field2:value2`
+     *
+     * **Supported operators:**
+     * - `field:value` - Exact match
+     * - `field:value1,value2` - Match any of the comma-separated values (OR)
+     * - Time ranges: Use `30d` (30 days), `7d` (7 days), `1h` (1 hour), etc.
+     *
+     * **Examples:**
+     * - `status:placed` - Filter by single status.
+     * - `status:placed,completed` - Filter by multiple statuses.
+     * - `createdAt:30d` - Filter orders created in the last 30 days.
+     * - `orderId:ord_01h1s5z6vf2mm1mz3hevnn9va7` - Filter by specific order ID.
+     * - `status:placed createdAt:7d` - Combine multiple filters.
+     */
+    filter?: string;
+};
+
+export type ListOrderItemsVariables = {
+    params?: ListOrderItemsParams;
+};
+
+export type GetRevenueResult = RevenueStatistics;
+
+export type GetRevenueParams = {
+    /**
+     * Start date for the revenue calculation period (ISO 8601 datetime format).
+     * Defaults to 30 days ago if not provided.
+     * @format date
+     */
+    startDate?: string;
+    /**
+     * End date for the revenue calculation period (ISO 8601 datetime format).
+     * Defaults to current time if not provided.
+     * @format date
+     */
+    endDate?: string;
+};
+
+export type GetRevenueVariables = {
+    params?: GetRevenueParams;
+};
+
+export type RegisterOAuth2ClientResult = OAuth2Client;
+
+export type RegisterOAuth2ClientBody = RegisterClientObject;
+
+export type RegisterOAuth2ClientVariables = {
+    body: RegisterOAuth2ClientBody;
+};
+
+/**
+ * Per-operation `args`/`result` shapes (plus `kind: 'sse'` for event streams) — the
+ * type-level companion of `OPERATIONS` that gives `createClient<Ops>` its typed methods.
+ */
+export type Ops = {
+    listMenuItems: {
+        args: {
+            params?: ListMenuItemsParams;
+        };
+        result: ListMenuItemsResult;
+    };
+    createMenuItem: {
+        args: {
+            body: CreateMenuItemBody;
+        };
+        result: CreateMenuItemResult;
+    };
+    deleteMenuItem: {
+        args: {
+            /**
+             * ID of the menu item to retrieve.
+             * @pattern ^prd_[0-9abcdefghjkmnpqrstvwxyz]{26}$
+             */
+            menuItemId: string;
+        };
+        result: DeleteMenuItemResult;
+    };
+    getMenuItemPhoto: {
+        args: {
+            /**
+             * ID of the menu item to retrieve.
+             * @pattern ^prd_[0-9abcdefghjkmnpqrstvwxyz]{26}$
+             */
+            menuItemId: string;
+            params?: GetMenuItemPhotoParams;
+        };
+        result: GetMenuItemPhotoResult;
+    };
+    listOrders: {
+        args: {
+            params?: ListOrdersParams;
+        };
+        result: ListOrdersResult;
+    };
+    createOrder: {
+        args: {
+            body: CreateOrderBody;
+        };
+        result: CreateOrderResult;
+    };
+    getOrderById: {
+        args: {
+            /**
+             * ID of the order to retrieve.
+             * @pattern ^ord_[0-9abcdefghjkmnpqrstvwxyz]{26}$
+             */
+            orderId: string;
+            headers?: GetOrderByIdHeaders;
+        };
+        result: GetOrderByIdResult;
+    };
+    deleteOrder: {
+        args: {
+            /**
+             * ID of the order to retrieve.
+             * @pattern ^ord_[0-9abcdefghjkmnpqrstvwxyz]{26}$
+             */
+            orderId: string;
+        };
+        result: DeleteOrderResult;
+    };
+    updateOrder: {
+        args: {
+            /**
+             * ID of the order to retrieve.
+             * @pattern ^ord_[0-9abcdefghjkmnpqrstvwxyz]{26}$
+             */
+            orderId: string;
+            body?: UpdateOrderBody;
+        };
+        result: UpdateOrderResult;
+    };
+    listOrderItems: {
+        args: {
+            params?: ListOrderItemsParams;
+        };
+        result: ListOrderItemsResult;
+    };
+    getRevenue: {
+        args: {
+            params?: GetRevenueParams;
+        };
+        result: GetRevenueResult;
+    };
+    registerOAuth2Client: {
+        args: {
+            body: RegisterOAuth2ClientBody;
+        };
+        result: RegisterOAuth2ClientResult;
+    };
+};
+
+/**
+ * The wire-shape descriptor for every operation, keyed by operationId — the data the
+ * runtime routes requests by. Also minification-safe static metadata (method, path,
+ * tags) for cache keys, tracing span names, and request logging.
+ */
+export const OPERATIONS = {
+    listMenuItems: { id: "listMenuItems", method: "GET", path: "/menu", tags: ["Products"], params: [{ name: "after", in: "query" }, { name: "before", in: "query" }, { name: "sort", in: "query" }, { name: "filter", in: "query" }, { name: "search", in: "query" }, { name: "limit", in: "query" }] },
+    createMenuItem: { id: "createMenuItem", method: "POST", path: "/menu", tags: ["Products"], body: { contentType: "multipart/form-data" }, security: [[{ scheme: "OAuth2", kind: "bearer" }]] },
+    deleteMenuItem: { id: "deleteMenuItem", method: "DELETE", path: "/menu/{menuItemId}", tags: ["Products"], params: [{ name: "menuItemId", in: "path" }], responseKind: "void", security: [[{ scheme: "OAuth2", kind: "bearer" }]] },
+    getMenuItemPhoto: { id: "getMenuItemPhoto", method: "GET", path: "/menu-item-images/{menuItemId}", tags: ["Products"], params: [{ name: "menuItemId", in: "path" }, { name: "photoSize", in: "query" }], responseKind: "blob" },
+    listOrders: { id: "listOrders", method: "GET", path: "/orders", tags: ["Orders"], params: [{ name: "filter", in: "query" }, { name: "sort", in: "query" }, { name: "limit", in: "query" }, { name: "after", in: "query" }, { name: "before", in: "query" }, { name: "search", in: "query" }], security: [[{ scheme: "OAuth2", kind: "bearer" }]] },
+    createOrder: { id: "createOrder", method: "POST", path: "/orders", tags: ["Orders"], body: { contentType: "application/json" }, security: [[{ scheme: "OAuth2", kind: "bearer" }]] },
+    getOrderById: { id: "getOrderById", method: "GET", path: "/orders/{orderId}", tags: ["Orders"], params: [{ name: "orderId", in: "path" }, { name: "X-Request-Id", in: "header" }], security: [[{ scheme: "OAuth2", kind: "bearer" }]] },
+    deleteOrder: { id: "deleteOrder", method: "DELETE", path: "/orders/{orderId}", tags: ["Orders"], params: [{ name: "orderId", in: "path" }], responseKind: "void", security: [[{ scheme: "OAuth2", kind: "bearer" }]] },
+    updateOrder: { id: "updateOrder", method: "PATCH", path: "/orders/{orderId}", tags: ["Orders"], params: [{ name: "orderId", in: "path" }], body: { contentType: "application/json" }, security: [[{ scheme: "OAuth2", kind: "bearer" }]] },
+    listOrderItems: { id: "listOrderItems", method: "GET", path: "/order-items", tags: ["Orders"], params: [{ name: "filter", in: "query" }], security: [[{ scheme: "OAuth2", kind: "bearer" }]] },
+    getRevenue: { id: "getRevenue", method: "GET", path: "/revenue", tags: ["Statistics"], params: [{ name: "startDate", in: "query" }, { name: "endDate", in: "query" }], security: [[{ scheme: "ApiKey", kind: "apiKey", name: "X-API-Key", in: "header" }]] },
+    registerOAuth2Client: { id: "registerOAuth2Client", method: "POST", path: "/oauth2/register", tags: ["Authorization"], body: { contentType: "application/json" } }
+} as const satisfies Record<string, OperationDescriptor>;
+
+export type OperationId = keyof typeof OPERATIONS;
+
+export type OperationPath = (typeof OPERATIONS)[OperationId]["path"];
+
+export type OperationTag = Extract<(typeof OPERATIONS)[OperationId], {
+    tags: readonly string[];
+}>["tags"][number];
+
+// ─── Embedded runtime (@redocly/client-generator, assembled per this API's needs) ───
+
+/**
+ * The public type surface of the client runtime — `@redocly/client-generator`'s
+ * app-facing runtime module. Pure types, no runtime code (excluded from coverage).
+ * The generator emits `OPERATIONS` literals typed
+ * `satisfies Record<string, OperationDescriptor>` against this module, so an
+ * incompatible runtime/generated pair fails the consumer's build (the semver skew guard).
+ */
+
+/** How one operation parameter is sent: its location plus OpenAPI query-serialization hints. */
+export type ParamSpec = {
+  name: string;
+  in: 'path' | 'query' | 'header' | 'cookie';
+  style?: 'form' | 'spaceDelimited' | 'pipeDelimited' | 'deepObject';
+  explode?: boolean;
+  allowReserved?: boolean;
+};
+
+/** One security scheme, denormalized onto the operation (`scheme` names the spec's scheme). */
+export type SecuritySpec =
+  | { scheme: string; kind: 'bearer' | 'basic' }
+  | { scheme: string; kind: 'apiKey'; name: string; in: 'header' | 'query' | 'cookie' };
+
+/**
+ * How to auto-iterate a paginated operation (drives its `.pages()`/`.items()` members).
+ * `nextCursor` and `items` are RFC 6901 JSON pointers into the page (response) value.
+ */
+export type PaginationSpec = {
+  style: 'cursor' | 'offset' | 'page';
+  /** The query param the iterator advances: the cursor (`cursor`) or number (`offset`/`page`). */
+  param: string;
+  /** Optional page-size query param (recorded for tooling; never set by the runtime). */
+  limitParam?: string;
+  /** Cursor style only: pointer to the next cursor in the page. */
+  nextCursor?: string;
+  /** Cursor style only: optional pointer to a boolean "more pages" flag — `false` stops iteration. */
+  hasMore?: string;
+  /** Pointer to the page's item array. */
+  items: string;
+};
+
+/** The frozen data contract between generated code and the runtime: one operation's wire shape. */
+export type OperationDescriptor = {
+  id: string;
+  method: string;
+  path: string;
+  tags?: readonly string[];
+  params?: readonly ParamSpec[];
+  /** `multipart: true` marks a typed object body serialized to FormData by the runtime. */
+  body?: { contentType: string; multipart?: boolean };
+  /** Defaults to `'json'` (content-type negotiation on parse). */
+  responseKind?: 'json' | 'text' | 'blob' | 'void' | 'sse';
+  sseDataKind?: 'json' | 'text';
+  /** OR-alternatives, each an AND-set: the runtime applies the first fully-configured one. */
+  security?: readonly (readonly SecuritySpec[])[];
+  pagination?: PaginationSpec;
+};
+
+/** A query value: scalars, arrays of scalars, or objects (serialized as deepObject brackets). */
+export type QueryValue =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | Array<string | number | boolean | null | undefined>
+  | Record<string, unknown>;
+
+/** A credential: a literal, or a (possibly async) function resolved per request (refresh flows). */
+export type TokenProvider = string | (() => string | Promise<string>);
+
+/** Per-instance credentials, keyed by the scheme kinds the runtime can inject. */
+export type AuthCredentials = {
+  bearer?: TokenProvider;
+  basic?: { username: string; password: string };
+  apiKey?: Record<string, TokenProvider>;
+};
+
+/** Backoff shape: 'fixed' = constant delay; 'exponential' = doubling per attempt. */
+export type RetryStrategy = 'fixed' | 'exponential';
+
+/**
+ * The operation's identity, exposed to middleware for targeting (`ctx.operation`).
+ * Generated clients instantiate the type parameters with the spec's literal unions
+ * (`OperationId`/`OperationPath`/`OperationTag`) so a misspelled operation id in a
+ * middleware comparison fails to compile; the string defaults keep every
+ * spec-independent consumer (`runtime-contract.ts`, the runtime internals) working
+ * with the base shape. `tags` stays mutable (`Tag[]`) so setup-contract types
+ * (byte-locked to generated output) remain assignable through middleware callbacks.
+ */
+export type OperationContext<
+  Id extends string = string,
+  Path extends string = string,
+  Tag extends string = string,
+> = { id: Id; path: Path; tags: Tag[] };
+
+/** The mutable request context threaded through the middleware chain. */
+export type RequestContext<Op extends OperationContext = OperationContext> = {
+  url: string;
+  method: string;
+  headers: Record<string, string>;
+  body?: unknown;
+  operation: Op;
+};
+
+/** The failed attempt handed to a custom `retryOn`: exactly one of `response`/`error` is set. */
+export type RetryContext<Op extends OperationContext = OperationContext> = {
+  attempt: number;
+  request: RequestContext<Op>;
+  response?: Response;
+  error?: unknown;
+};
+
+/** Opt-in retry policy; a per-call override merges field-by-field over the config policy. */
+export type RetryConfig<Op extends OperationContext = OperationContext> = {
+  retries?: number;
+  retryDelay?: number;
+  retryStrategy?: RetryStrategy;
+  jitter?: boolean;
+  retryOn?: (ctx: RetryContext<Op>) => boolean | Promise<boolean>;
+};
+
+/**
+ * Structural stand-in for the runtime's ApiError so this module stays import-free
+ * (pure types); the real `ApiError` class is assignable to it.
+ */
+export type ApiErrorLike = globalThis.Error & {
+  url: string;
+  status: number;
+  statusText: string;
+  body: unknown;
+};
+
+/** One interceptor: any subset of the three hooks. */
+export type Middleware<Op extends OperationContext = OperationContext> = {
+  onRequest?: (ctx: RequestContext<Op>) => void | Promise<void>;
+  onResponse?: (
+    response: Response,
+    ctx: RequestContext<Op>
+  ) => Response | void | Promise<Response | void>;
+  /** Throw mode only: may map/replace the error. */
+  // `globalThis.Error` so a spec schema named `Error` cannot shadow it in inline mode.
+  onError?: (
+    error: ApiErrorLike,
+    ctx: RequestContext<Op>
+  ) => globalThis.Error | Promise<globalThis.Error>;
+};
+
+/** Client configuration: transport, defaults, retry policy, middleware, and credentials. */
+export type ClientConfig<Op extends OperationContext = OperationContext> = {
+  serverUrl?: string;
+  fetch?: typeof fetch;
+  headers?:
+    | Record<string, string>
+    | (() => Record<string, string> | Promise<Record<string, string>>);
+  retry?: RetryConfig<Op>;
+  middleware?: Middleware<Op>[];
+  auth?: AuthCredentials;
+  /** Fixed at generate time by the generator (`'throw'` when omitted); `configure()` ignores it. */
+  errorMode?: 'throw' | 'result';
+  onRequest?: Middleware<Op>['onRequest'];
+  onResponse?: Middleware<Op>['onResponse'];
+  onError?: Middleware<Op>['onError'];
+};
+
+/** Response readers for the per-call `parseAs` override. */
+export type ParseAs = 'auto' | 'json' | 'text' | 'blob' | 'arrayBuffer' | 'formData' | 'stream';
+
+/** Per-call options: standard `RequestInit` plus a retry override and a forced reader. */
+export type RequestOptions = RequestInit & { retry?: RetryConfig; parseAs?: ParseAs };
+
+/** Per-call options for an SSE stream; reconnect defaults to true. */
+export type SseOptions = RequestInit & { reconnect?: boolean; reconnectDelay?: number };
+
+/** A single decoded Server-Sent Event with its payload typed from the spec. */
+export type ServerSentEvent<T> = { event?: string; data: T; id?: string; retry?: number };
+
+/** Result-mode return shape: exactly one of `data`/`error` is set. */
+export type Result<TData, TError> =
+  | { data: TData; error: undefined; response: Response }
+  | { data: undefined; error: TError; response: Response };
+
+/**
+ * The generated `Ops` type's shape: per-operation args/result, plus `kind: 'sse'` for
+ * streams and, for paginated operations, `item` (the page's element type) and — on
+ * result-mode clients only — `page` (the RAW page type `.pages()` yields, since
+ * iteration unwraps the `Result` envelope the one-shot `result` carries).
+ */
+export type OpsShape = Record<
+  string,
+  { args: object; result: unknown; kind?: 'sse'; item?: unknown; page?: unknown }
+>;
+
+/** The always-present client members (assigned after the operation loop — they win collisions). */
+export type ClientCore<Op extends OperationContext = OperationContext> = {
+  /** Merge into the config; note `middleware` REPLACES the chain (use `use()` to compose). */
+  configure(config: ClientConfig<Op>): void;
+  /** Append interceptors (composes with baked/publisher middleware). */
+  use(...middleware: Middleware<Op>[]): void;
+  auth: {
+    bearer(token: TokenProvider): void;
+    basic(username: string, password: string): void;
+    apiKey(scheme: string, value: TokenProvider): void;
+  };
+};
+
+/**
+ * The standard TypeScript optionality probe: `{}` has no required members, so
+ * `{} extends A` is true exactly when every member of `A` is optional.
+ */
+// oxlint-disable-next-line typescript/no-empty-object-type
+type NoRequiredKeys<A> = {} extends A ? true : false;
+
+/**
+ * The page type `.pages()` yields: the RAW page declared by `page` (the generator
+ * writes it only on result-mode paginated entries, whose `result` is the envelope),
+ * or the method's own `result` (throw mode — already the raw page).
+ */
+type PageOf<Entry extends OpsShape[string]> = Entry extends { page: unknown }
+  ? Entry['page']
+  : Entry['result'];
+
+/**
+ * The auto-pagination members intersected onto a paginated method — present exactly when
+ * the Ops entry declares `item` (the generator writes it only for paginated operations).
+ * Args optionality mirrors the method's own; `unknown` otherwise (identity under `&`).
+ * Iteration is error-mode-agnostic: `.pages()`/`.items()` yield raw pages/items, and a
+ * failed page aborts iteration by throwing `ApiError`, even on result-mode clients; the
+ * `onError` middleware hook (throw-mode-only) is not invoked.
+ */
+type Paginated<Entry extends OpsShape[string]> = 'item' extends keyof Entry
+  ? NoRequiredKeys<Entry['args']> extends true
+    ? {
+        pages(args?: Entry['args'], init?: RequestOptions): AsyncGenerator<PageOf<Entry>>;
+        items(args?: Entry['args'], init?: RequestOptions): AsyncGenerator<Entry['item']>;
+      }
+    : {
+        pages(args: Entry['args'], init?: RequestOptions): AsyncGenerator<PageOf<Entry>>;
+        items(args: Entry['args'], init?: RequestOptions): AsyncGenerator<Entry['item']>;
+      }
+  : unknown;
+
+/** The typed instance client: one bound method per operation plus the core members. */
+export type Client<Ops extends OpsShape, Op extends OperationContext = OperationContext> = {
+  [K in keyof Ops]: Ops[K] extends { kind: 'sse' }
+    ? NoRequiredKeys<Ops[K]['args']> extends true
+      ? (
+          args?: Ops[K]['args'],
+          init?: SseOptions
+        ) => AsyncGenerator<ServerSentEvent<Ops[K]['result']>>
+      : (
+          args: Ops[K]['args'],
+          init?: SseOptions
+        ) => AsyncGenerator<ServerSentEvent<Ops[K]['result']>>
+    : (NoRequiredKeys<Ops[K]['args']> extends true
+        ? (args?: Ops[K]['args'], init?: RequestOptions) => Promise<Ops[K]['result']>
+        : (args: Ops[K]['args'], init?: RequestOptions) => Promise<Ops[K]['result']>) &
+        Paginated<Ops[K]>;
+} & ClientCore<Op>;
+
+/** The error thrown (throw mode) for a non-2xx response, carrying the decoded error body. */
+export class ApiError extends Error {
+  public readonly url: string;
+  public readonly status: number;
+  public readonly statusText: string;
+  public readonly body: unknown;
+  constructor(url: string, status: number, statusText: string, body: unknown) {
+    super(`Request failed with status ${status}`);
+    this.name = 'ApiError';
+    this.url = url;
+    this.status = status;
+    this.statusText = statusText;
+    this.body = body;
+  }
+}
+
+/** The error to throw for an aborted request: the caller's abort reason when it is an Error. */
+// `globalThis.Error` (not bare `Error`) so a spec schema named `Error` cannot shadow it
+// when this module is embedded alongside generated types (inline mode).
+function abortError(signal: AbortSignal): globalThis.Error {
+  const reason = (signal as { reason?: unknown }).reason;
+  if (reason instanceof Error) return reason;
+  return new DOMException('The operation was aborted.', 'AbortError');
+}
+
+/**
+ * The RESOLVED OpenAPI serialization spec for one query parameter — callers apply the
+ * OpenAPI defaults (`style: 'form'`, `explode: true`) before building one.
+ */
+type QueryStyle = {
+  style: NonNullable<ParamSpec['style']>;
+  explode: boolean;
+  allowReserved?: boolean;
+};
+
+/**
+ * Encode everything except the RFC-3986 reserved set, for `allowReserved: true` params —
+ * `filter=a/b` survives instead of `filter=a%2Fb`.
+ */
+function encodeReserved(value: string): string {
+  return encodeURIComponent(value).replace(
+    /%(3A|2F|3F|23|5B|5D|40|21|24|26|27|28|29|2A|2B|2C|3B|3D)/g,
+    (match) => decodeURIComponent(match)
+  );
+}
+
+/** Substitute `{name}` template segments with encoded values; a missing value is a caller bug. */
+function substitutePath(template: string, values: Record<string, unknown>): string {
+  return template.replace(/\{([^{}]+)\}/g, (_match, name: string) => {
+    const value = values[name];
+    if (value === undefined) throw new Error(`Missing path parameter "${name}"`);
+    return encodeURIComponent(String(value));
+  });
+}
+
+/**
+ * Build the request URL: `serverUrl` (trailing slash trimmed) + path + serialized query.
+ * Query parameters honor their OpenAPI `style`/`explode`/`allowReserved` (from `styles`);
+ * without a spec, arrays repeat the key (`form`+`explode`), objects serialize as
+ * `deepObject` brackets, and `null`/`undefined` entries are skipped.
+ */
+function buildUrl(
+  serverUrl: string,
+  path: string,
+  query?: Record<string, QueryValue>,
+  styles?: Record<string, QueryStyle>
+): string {
+  // Trim trailing slashes with a scan, not `/\/+$/` — an anchored `+` regex is
+  // quadratic on adversarial many-slash input (the server URL is caller data).
+  let end = serverUrl.length;
+  while (end > 0 && serverUrl.charCodeAt(end - 1) === 47 /* '/' */) end--;
+  const url = serverUrl.slice(0, end) + path;
+  if (!query) return url;
+  const params = new URLSearchParams();
+  const raw: string[] = [];
+  for (const [key, value] of Object.entries(query)) {
+    if (value === undefined || value === null) continue;
+    const spec = styles?.[key];
+    if (!spec) {
+      if (Array.isArray(value)) {
+        for (const v of value) {
+          if (v !== undefined && v !== null) params.append(key, String(v));
+        }
+      } else if (Object(value) === value) {
+        // Object-valued query params use `deepObject` style: key[subKey]=subValue.
+        for (const [subKey, subValue] of Object.entries(value)) {
+          if (subValue !== undefined && subValue !== null) {
+            params.append(`${key}[${subKey}]`, String(subValue));
+          }
+        }
+      } else {
+        params.append(key, String(value));
+      }
+      continue;
+    }
+    if (Array.isArray(value)) {
+      const items = value.filter((v) => v !== undefined && v !== null).map(String);
+      if (spec.style === 'form' && spec.explode) {
+        for (const v of items) {
+          if (spec.allowReserved) raw.push(`${key}=${encodeReserved(v)}`);
+          else params.append(key, v);
+        }
+      } else {
+        // Delimited styles put the LITERAL delimiter on the wire; only the
+        // values are encoded. `%20` (not `+`) is the literal space delimiter.
+        const delim =
+          spec.style === 'pipeDelimited' ? '|' : spec.style === 'spaceDelimited' ? '%20' : ',';
+        const enc = spec.allowReserved ? encodeReserved : encodeURIComponent;
+        raw.push(`${encodeURIComponent(key)}=${items.map(enc).join(delim)}`);
+      }
+    } else if (Object(value) === value) {
+      // `deepObject` (and any object spec, for now): key[subKey]=subValue.
+      for (const [subKey, subValue] of Object.entries(value)) {
+        if (subValue !== undefined && subValue !== null) {
+          if (spec.allowReserved) raw.push(`${key}[${subKey}]=${encodeReserved(String(subValue))}`);
+          else params.append(`${key}[${subKey}]`, String(subValue));
+        }
+      }
+    } else if (spec.allowReserved) {
+      raw.push(`${key}=${encodeReserved(String(value))}`);
+    } else {
+      params.append(key, String(value));
+    }
+  }
+  const qs = [params.toString(), ...raw].filter(Boolean).join('&');
+  return qs ? `${url}?${qs}` : url;
+}
+
+/**
+ * Read the response body per `kind`. `'auto'` negotiates from the content type
+ * (JSON, then `text/*`, then Blob); `'void'` and `204` responses read nothing.
+ */
+async function parse(response: Response, kind: ParseAs | 'void'): Promise<unknown> {
+  if (kind === 'void' || response.status === 204) return undefined;
+  if (kind === 'stream') return response.body;
+  if (kind === 'blob') return response.blob();
+  if (kind === 'arrayBuffer') return response.arrayBuffer();
+  if (kind === 'formData') return response.formData();
+  if (kind === 'text') return response.text();
+  if (kind === 'json') return response.json();
+  // 'auto' — negotiate from the response's content type (case-insensitively:
+  // `Text/Plain` and `application/JSON` are valid per RFC 9110).
+  const contentType = (response.headers.get('content-type') ?? '').toLowerCase();
+  if (contentType.includes('json')) return response.json();
+  if (contentType.startsWith('text/')) return response.text();
+  return response.blob();
+}
+
+/** Best-effort decode of a non-2xx body (JSON when declared, else text; undefined on failure). */
+async function readError(response: Response): Promise<unknown> {
+  const contentType = response.headers.get('content-type') ?? '';
+  if (contentType.toLowerCase().includes('json')) {
+    return response.json().catch(() => undefined);
+  }
+  return response.text().catch(() => undefined);
+}
+
+const IDEMPOTENT_METHODS = new Set(['GET', 'HEAD', 'PUT', 'DELETE', 'OPTIONS']);
+const TRANSIENT_STATUS = new Set([408, 429, 500, 502, 503, 504]);
+
+/**
+ * The default retry predicate: idempotent methods only, on a transport error or a
+ * transient status. A custom `retryOn` fully replaces this (no method check kept).
+ */
+function defaultRetryOn(ctx: RetryContext): boolean {
+  if (!IDEMPOTENT_METHODS.has(ctx.request.method.toUpperCase())) return false;
+  return ctx.response === undefined || TRANSIENT_STATUS.has(ctx.response.status);
+}
+
+/**
+ * The delay before the next attempt: a `Retry-After` header (seconds or HTTP-date)
+ * wins; otherwise fixed/exponential backoff over `retryDelay`, with full jitter
+ * unless `jitter === false`.
+ */
+function retryDelay(retry: RetryConfig, attempt: number, retryAfter: string | null): number {
+  if (retryAfter) {
+    const seconds = Number(retryAfter);
+    if (!Number.isNaN(seconds)) return seconds * 1000;
+    const when = Date.parse(retryAfter);
+    if (!Number.isNaN(when)) return Math.max(0, when - Date.now());
+  }
+  const base = retry.retryDelay ?? 1000;
+  const raw = retry.retryStrategy === 'fixed' ? base : base * Math.pow(2, attempt - 1);
+  return retry.jitter === false ? raw : Math.random() * raw;
+}
+
+/** Abort-aware sleep: resolves after `ms`, rejects with the abort reason immediately on abort. */
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(abortError(signal));
+      return;
+    }
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(abortError(signal as AbortSignal));
+    };
+    const timer = setTimeout(() => {
+      if (signal) signal.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+    if (signal) signal.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
+/** Resolve a credential: a literal passes through; a function is awaited per request. */
+async function resolveToken(provider: TokenProvider): Promise<string> {
+  return typeof provider === 'function' ? await provider() : provider;
+}
+
+/** UTF-8-safe base64: bare `btoa` throws on non-Latin-1 credentials (RFC 7617 allows UTF-8). */
+function encodeBase64(text: string): string {
+  let binary = '';
+  for (const byte of new TextEncoder().encode(text)) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+
+/** Whether a credential for this scheme is configured on the instance. */
+function isConfigured(scheme: SecuritySpec, config: ClientConfig): boolean {
+  if (scheme.kind === 'apiKey') return config.auth?.apiKey?.[scheme.scheme] !== undefined;
+  if (scheme.kind === 'bearer') return config.auth?.bearer !== undefined;
+  return config.auth?.basic !== undefined;
+}
+
+/**
+ * Build the auth headers/query for one operation's `security` OR-alternatives from the
+ * instance credentials (`config.auth`) — capability module, wired into `createClient`.
+ * The first alternative whose schemes (an AND-set) are all configured is applied, so
+ * "bearer OR apiKey" works with either credential and never sends both. When none is
+ * fully configured, the first alternative's configured schemes are still sent (the
+ * server rejects the request, mirroring the previous behavior).
+ * Cookie-borne apiKeys fold into a single `Cookie` header joined with `; `.
+ */
+async function resolveAuth(
+  security: readonly (readonly SecuritySpec[])[],
+  config: ClientConfig
+): Promise<{ headers: Record<string, string>; query: Record<string, string> }> {
+  const alternative =
+    security.find((schemes) => schemes.every((scheme) => isConfigured(scheme, config))) ??
+    security[0] ??
+    [];
+  const headers: Record<string, string> = {};
+  const query: Record<string, string> = {};
+  const cookies: string[] = [];
+  for (const scheme of alternative) {
+    if (scheme.kind === 'apiKey') {
+      const provider = config.auth?.apiKey?.[scheme.scheme];
+      if (provider === undefined) continue;
+      const value = await resolveToken(provider);
+      if (scheme.in === 'header') headers[scheme.name] = value;
+      else if (scheme.in === 'query') query[scheme.name] = value;
+      // Cookie values may contain reserved characters (`;`, `=`, space, …); percent-encode
+      // so the credential can't break the `Cookie` header syntax.
+      else cookies.push(`${scheme.name}=${encodeURIComponent(value)}`);
+    } else if (scheme.kind === 'bearer') {
+      const provider = config.auth?.bearer;
+      if (provider !== undefined) headers.Authorization = `Bearer ${await resolveToken(provider)}`;
+    } else {
+      const basic = config.auth?.basic;
+      if (basic !== undefined) {
+        headers.Authorization = `Basic ${encodeBase64(`${basic.username}:${basic.password}`)}`;
+      }
+    }
+  }
+  if (cookies.length > 0) headers.Cookie = cookies.join('; ');
+  return { headers, query };
+}
+
+/**
+ * Optional behaviors the send core can use but never statically imports — wired by
+ * `createClient` (the same seam the future inline-mode assembler relies on).
+ */
+type SendCapabilities = {
+  /** Serialize a typed multipart body (a plain object) to FormData. */
+  serializeMultipart?: (body: Record<string, unknown>) => FormData;
+};
+
+/**
+ * Normalize a caller's `HeadersInit` (plain record, `Headers` instance, or entry pairs)
+ * to a plain record — spreading a `Headers` or an array contributes no entries.
+ */
+function toHeaderRecord(headers: HeadersInit | undefined): Record<string, string> {
+  if (headers === undefined) return {};
+  if (headers instanceof Headers) {
+    const record: Record<string, string> = {};
+    headers.forEach((value, key) => {
+      record[key] = value;
+    });
+    return record;
+  }
+  if (Array.isArray(headers)) return Object.fromEntries(headers);
+  return headers;
+}
+
+/**
+ * The effective middleware chain for a request: the single `onRequest`/`onResponse`/
+ * `onError` config hooks as one implicit first middleware, then `config.middleware`.
+ */
+function middlewareChain(config: ClientConfig): Middleware[] {
+  const single =
+    config.onRequest || config.onResponse || config.onError
+      ? [{ onRequest: config.onRequest, onResponse: config.onResponse, onError: config.onError }]
+      : [];
+  return [...single, ...(config.middleware ?? [])];
+}
+
+/**
+ * The fetch core shared by every operation: default + config + per-call headers, the
+ * `onRequest` chain (BEFORE body serialization, so mutations are sent), body
+ * serialization (JSON, or FormData via the multipart capability), the retry loop
+ * (idempotent-only defaults, `Retry-After`, abandoned-body drain), and the reverse
+ * `onResponse` onion. Returns the final response plus the request context.
+ */
+async function send(
+  config: ClientConfig,
+  op: OperationContext,
+  url: string,
+  init: RequestOptions,
+  body: unknown | undefined,
+  multipart: boolean,
+  caps: SendCapabilities
+): Promise<{ response: Response; context: RequestContext }> {
+  const { retry: callRetry, ...fetchInit } = init;
+  const retry: RetryConfig = { ...config.retry, ...callRetry };
+  const extra = typeof config.headers === 'function' ? await config.headers() : config.headers;
+  const headers: Record<string, string> = {
+    Accept: 'application/json',
+    ...extra,
+    ...toHeaderRecord(fetchInit.headers),
+  };
+  const context: RequestContext = {
+    url,
+    method: fetchInit.method ?? 'GET',
+    headers,
+    body,
+    operation: op,
+  };
+  const middleware = middlewareChain(config);
+  for (const mw of middleware) if (mw.onRequest) await mw.onRequest(context);
+  // Serialize AFTER onRequest so body mutations (case conversion, enveloping, signing) take effect.
+  let payload: BodyInit | undefined;
+  if (context.body !== undefined) {
+    const value = context.body;
+    const isBinary =
+      value instanceof Blob ||
+      value instanceof ArrayBuffer ||
+      ArrayBuffer.isView(value as ArrayBufferView);
+    const isFormData = typeof FormData !== 'undefined' && value instanceof FormData;
+    const isURLSearchParams = value instanceof URLSearchParams;
+    if (isFormData || isURLSearchParams || isBinary || typeof value === 'string') {
+      payload = value as BodyInit;
+    } else if (multipart) {
+      if (!caps.serializeMultipart) {
+        throw new Error('Multipart capability not wired: cannot serialize the request body');
+      }
+      payload = caps.serializeMultipart(value as Record<string, unknown>);
+    } else {
+      payload = JSON.stringify(value);
+      if (!('Content-Type' in context.headers) && !('content-type' in context.headers)) {
+        context.headers['Content-Type'] = 'application/json';
+      }
+    }
+  }
+  const doFetch = config.fetch ?? fetch;
+  const maxAttempts = 1 + (retry.retries ?? 0);
+  const retryOn = retry.retryOn ?? defaultRetryOn;
+  const signal = fetchInit.signal ?? undefined;
+
+  let attempt = 0;
+  while (true) {
+    attempt++;
+    if (signal?.aborted) throw abortError(signal);
+    let response: Response;
+    try {
+      response = await doFetch(context.url, {
+        ...fetchInit,
+        method: context.method,
+        headers: context.headers,
+        body: payload,
+      });
+    } catch (error) {
+      if (
+        attempt < maxAttempts &&
+        !signal?.aborted &&
+        (await retryOn({ attempt, request: context, error }))
+      ) {
+        await sleep(retryDelay(retry, attempt, null), signal);
+        continue;
+      }
+      throw error;
+    }
+    // Reverse order: the last-registered middleware wraps closest to the network (onion).
+    for (let i = middleware.length - 1; i >= 0; i--) {
+      const onResponse = middleware[i].onResponse;
+      if (onResponse) {
+        const replaced = await onResponse(response, context);
+        if (replaced && replaced !== response) {
+          // Cancel the abandoned original's body — like the retry path, an unread body
+          // keeps its connection checked out under Node/undici.
+          await response.body?.cancel().catch(() => undefined);
+          response = replaced;
+        }
+      }
+    }
+    if (
+      !response.ok &&
+      attempt < maxAttempts &&
+      !signal?.aborted &&
+      (await retryOn({ attempt, request: context, response }))
+    ) {
+      const retryAfter = response.headers.get('retry-after');
+      // Drain the abandoned response body before the next attempt: an unread body
+      // keeps the connection checked out (and can stall the pool) under Node/undici
+      // and other strict HTTP clients. Ignore errors (e.g. a middleware already read it).
+      await response.body?.cancel().catch(() => undefined);
+      await sleep(retryDelay(retry, attempt, retryAfter), signal);
+      continue;
+    }
+    return { response, context };
+  }
+}
+
+/**
+ * The optional behaviors `createClientCore` can dispatch to but never statically
+ * imports. The package's public `createClient` wires the full set; the future
+ * inline-mode assembler wires only the capabilities a spec needs.
+ */
+type Capabilities = SendCapabilities & {
+  resolveAuth?: (
+    security: readonly (readonly SecuritySpec[])[],
+    config: ClientConfig
+  ) => Promise<{ headers: Record<string, string>; query: Record<string, string> }>;
+  sse?: (
+    config: ClientConfig,
+    op: OperationContext,
+    // Re-preparing per (re)connect (not a frozen url/init) lets a refresh-style
+    // TokenProvider issue a fresh credential after a dropped stream reconnects.
+    prepare: () => Promise<{ url: string; init: SseOptions }>,
+    dataKind: 'json' | 'text'
+  ) => AsyncGenerator<ServerSentEvent<unknown>>;
+  paginate?: {
+    pages: (
+      call: (args?: OperationArgs, init?: RequestOptions) => Promise<unknown>,
+      spec: PaginationSpec,
+      args?: OperationArgs,
+      init?: RequestOptions
+    ) => AsyncGenerator<unknown>;
+    items: (
+      call: (args?: OperationArgs, init?: RequestOptions) => Promise<unknown>,
+      spec: PaginationSpec,
+      args?: OperationArgs,
+      init?: RequestOptions
+    ) => AsyncGenerator<unknown>;
+  };
+};
+
+/** The grouped args wire shape: path params by name plus the `params`/`body`/`headers`/`cookies` slots. */
+type OperationArgs = {
+  params?: Record<string, QueryValue>;
+  body?: unknown;
+  headers?: Record<string, unknown>;
+  cookies?: Record<string, unknown>;
+} & Record<string, unknown>;
+
+/** The response reader implied by the descriptor (before any per-call `parseAs` override). */
+function kindFor(op: OperationDescriptor): ParseAs | 'void' {
+  if (op.responseKind === 'void' || op.responseKind === 'blob' || op.responseKind === 'text') {
+    return op.responseKind;
+  }
+  return 'auto';
+}
+
+/** Route the grouped args by the descriptor: path values, query object, body, extra headers, cookies. */
+function splitArgs(op: OperationDescriptor, args: OperationArgs) {
+  const path: Record<string, unknown> = {};
+  for (const param of op.params ?? []) {
+    if (param.in === 'path') path[param.name] = args[param.name];
+  }
+  return {
+    path,
+    query: args.params,
+    body: args.body,
+    headers: args.headers,
+    cookies: args.cookies,
+  };
+}
+
+/**
+ * The query-serialization hints for the descriptor's query params. A spec is built only
+ * when the param deviates from the OpenAPI defaults (`form` + `explode: true`, encoded),
+ * and always fully resolved — so `explode: false` or `allowReserved` alone (no `style`)
+ * are honored, and an omitted `explode` keeps the exploded default.
+ */
+function queryStyles(op: OperationDescriptor): Record<string, QueryStyle> | undefined {
+  let styles: Record<string, QueryStyle> | undefined;
+  for (const param of op.params ?? []) {
+    if (param.in !== 'query') continue;
+    const deviates =
+      (param.style !== undefined && param.style !== 'form') ||
+      param.explode === false ||
+      param.allowReserved === true;
+    if (!deviates) continue;
+    styles ??= {};
+    styles[param.name] = {
+      style: param.style ?? 'form',
+      explode: param.explode ?? true,
+      allowReserved: param.allowReserved,
+    };
+  }
+  return styles;
+}
+
+/** Stringify caller-supplied extra headers, skipping empty entries. */
+function stringHeaders(headers: Record<string, unknown> | undefined): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [key, value] of Object.entries(headers ?? {})) {
+    if (value !== undefined && value !== null) out[key] = String(value);
+  }
+  return out;
+}
+
+/** Build the request pieces an attempt needs: the final URL and the merged per-call init. */
+async function prepareRequest(
+  config: ClientConfig,
+  op: OperationDescriptor,
+  args: OperationArgs,
+  init: RequestOptions | SseOptions,
+  caps: Capabilities
+): Promise<{ url: string; init: RequestOptions; body: unknown }> {
+  const { path, query, body, headers, cookies } = splitArgs(op, args);
+  const authed: { headers: Record<string, string>; query: Record<string, string> } =
+    op.security?.length && caps.resolveAuth
+      ? await caps.resolveAuth(op.security, config)
+      : { headers: {}, query: {} };
+  // Cookie params join the auth-injected cookies in one `Cookie` header (values
+  // percent-encoded, like auth cookies). Server-side only — browsers own the header.
+  const cookiePairs = Object.entries(cookies ?? {})
+    .filter(([, value]) => value !== undefined && value !== null)
+    .map(([cookieName, value]) => `${cookieName}=${encodeURIComponent(String(value))}`);
+  if (cookiePairs.length > 0) {
+    authed.headers.Cookie = [authed.headers.Cookie, ...cookiePairs].filter(Boolean).join('; ');
+  }
+  const fullQuery: Record<string, QueryValue> = { ...query, ...authed.query };
+  const url = buildUrl(
+    config.serverUrl ?? '',
+    substitutePath(op.path, path),
+    Object.keys(fullQuery).length > 0 ? fullQuery : undefined,
+    queryStyles(op)
+  );
+  const mergedInit: RequestOptions = {
+    ...init,
+    method: op.method.toUpperCase(),
+    // Precedence, lowest → highest (later spreads win): injected auth → explicit
+    // header params → caller `init.headers` — the caller always overrides both.
+    headers: {
+      ...authed.headers,
+      ...stringHeaders(headers),
+      ...toHeaderRecord(init.headers),
+    },
+  };
+  return { url, init: mergedInit, body };
+}
+
+/** One non-SSE call: send, then branch on the configured error mode. */
+async function execute(
+  config: ClientConfig,
+  op: OperationDescriptor,
+  args: OperationArgs,
+  init: RequestOptions,
+  caps: Capabilities
+): Promise<unknown> {
+  const prepared = await prepareRequest(config, op, args, init, caps);
+  const opCtx: OperationContext = { id: op.id, path: op.path, tags: [...(op.tags ?? [])] };
+  const { parseAs, ...sendInit } = prepared.init;
+  const { response, context } = await send(
+    config,
+    opCtx,
+    prepared.url,
+    sendInit,
+    prepared.body,
+    op.body?.multipart === true,
+    caps
+  );
+  const readKind = parseAs ?? kindFor(op);
+  if (config.errorMode === 'result') {
+    if (!response.ok) {
+      return { data: undefined, error: await readError(response), response };
+    }
+    return { data: await parse(response, readKind), error: undefined, response };
+  }
+  if (!response.ok) {
+    let error: globalThis.Error = new ApiError(
+      context.url,
+      response.status,
+      response.statusText,
+      await readError(response)
+    );
+    // Thread the error through each middleware's onError in turn (each may replace it).
+    for (const mw of middlewareChain(config)) {
+      if (mw.onError) error = await mw.onError(error as ApiErrorLike, context);
+    }
+    throw error;
+  }
+  return parse(response, readKind);
+}
+
+/** The paginate capability, or a descriptive throw when a paginated op is iterated unwired. */
+function paginateCapability(caps: Capabilities, op: OperationDescriptor) {
+  if (!caps.paginate) {
+    throw new Error(`Pagination capability not wired: cannot iterate operation "${op.id}"`);
+  }
+  return caps.paginate;
+}
+
+/**
+ * The per-page call the iterators drive: the method itself in throw mode; in result
+ * mode a wrapper that unwraps the `{ data, error, response }` envelope — the page
+ * pointers are data-rooted — rethrowing a failed page as `ApiError` (iteration is
+ * error-mode-agnostic; the throw-mode-only `onError` middleware hook is not invoked).
+ */
+function pageCall(
+  method: (args?: OperationArgs, init?: RequestOptions) => Promise<unknown>,
+  config: ClientConfig
+) {
+  if (config.errorMode !== 'result') return method;
+  return async (args?: OperationArgs, init?: RequestOptions) => {
+    const envelope = (await method(args, init)) as {
+      data: unknown;
+      error: unknown;
+      response: Response;
+    };
+    // Failure is `!response.ok` — NOT `data === undefined`: a successful bodyless page
+    // (204/void) also parses to undefined data, and a failed page's `error` can be
+    // undefined too (unreadable body). The pointers then miss on the undefined data
+    // and iteration stops cleanly, which is the correct semantics for an empty page.
+    if (!envelope.response.ok) {
+      const { response } = envelope;
+      throw new ApiError(response.url, response.status, response.statusText, envelope.error);
+    }
+    return envelope.data;
+  };
+}
+
+/**
+ * Build a typed instance client over operation descriptors: one real bound method per
+ * operation (attached by a construction-time loop — no Proxy), plus the core members
+ * (`configure`/`use`/`auth`), which are assigned AFTER the loop so they win any name
+ * collision with an operation. All behavior dispatches through the capability seam.
+ */
+function createClientCore<
+  Ops extends OpsShape,
+  Id extends string = string,
+  Path extends string = string,
+  Tag extends string = string,
+>(
+  operations: Record<string, OperationDescriptor>,
+  initial: ClientConfig<OperationContext<Id, Path, Tag>> = {},
+  caps: Capabilities = {}
+): Client<Ops, OperationContext<Id, Path, Tag>> {
+  // The literal-union narrowing is a compile-time DX contract only; internally the
+  // runtime works with the base (string-typed) context. One cast at this boundary —
+  // `ClientConfig<Narrow>` is not assignable to `ClientConfig` (middleware ctx
+  // params are contravariant).
+  const given = initial as ClientConfig;
+  // Private mutable config; the middleware array is copied so `use()` never mutates the caller's.
+  const config: ClientConfig = { ...given, middleware: [...(given.middleware ?? [])] };
+  const client = {} as Record<string, unknown>;
+
+  for (const [name, op] of Object.entries(operations)) {
+    if (op.responseKind === 'sse') {
+      const method = (args: OperationArgs = {}, init: SseOptions = {}) => {
+        if (!caps.sse) {
+          throw new Error(`SSE capability not wired: cannot stream operation "${op.id}"`);
+        }
+        const stream = caps.sse;
+        return (async function* () {
+          const opCtx: OperationContext = { id: op.id, path: op.path, tags: [...(op.tags ?? [])] };
+          // A thunk the stream re-runs on every (re)connect, so auth (which `prepareRequest`
+          // resolves) is refreshed per attempt rather than frozen at the first connect.
+          const prepare = async () => {
+            const prepared = await prepareRequest(config, op, args, init, caps);
+            return { url: prepared.url, init: prepared.init as SseOptions, body: prepared.body };
+          };
+          yield* stream(config, opCtx, prepare, op.sseDataKind ?? 'text');
+        })();
+      };
+      // Consumers key off the function reference (cache keys, `OPERATIONS[fn.name]`), so
+      // each closure carries its operationId instead of an inferred binding name.
+      Object.defineProperty(method, 'name', { value: name });
+      client[name] = method;
+    } else {
+      const method = (args: OperationArgs = {}, init: RequestOptions = {}) =>
+        execute(config, op, args, init, caps);
+      Object.defineProperty(method, 'name', { value: name });
+      const spec = op.pagination;
+      // Paginated ops keep their one-shot call and gain `.pages`/`.items`, dispatching
+      // through the capability seam (like SSE: absent capability throws descriptively).
+      // Iteration is error-mode-agnostic: the iterators' pointers are data-rooted, so on
+      // a result-mode client (`errorMode` is fixed at construction — `configure()`
+      // ignores it) each page's envelope is unwrapped before it reaches the capability.
+      // A failed page aborts iteration by throwing ApiError, even on result-mode
+      // clients; the `onError` middleware hook (throw-mode-only) is not invoked.
+      client[name] = spec
+        ? Object.assign(method, {
+            pages: (args?: OperationArgs, init?: RequestOptions) =>
+              paginateCapability(caps, op).pages(pageCall(method, config), spec, args, init),
+            items: (args?: OperationArgs, init?: RequestOptions) =>
+              paginateCapability(caps, op).items(pageCall(method, config), spec, args, init),
+          })
+        : method;
+    }
+  }
+
+  // Core members are assigned AFTER the operation loop — they win over colliding op names.
+  client.configure = (next: ClientConfig): void => {
+    // `errorMode` is fixed at generate time (it shapes the static types); flipping it at
+    // runtime would silently desync return shapes from `Client<Ops>`, so it is ignored.
+    const { errorMode: _fixed, auth, ...rest } = next;
+    Object.assign(config, rest);
+    // `auth` merges into existing credentials (like the `auth.*` setters) rather than
+    // replacing wholesale — so `configure({ auth: { bearer } })` keeps a previously set
+    // basic/apiKey. `apiKey` merges per scheme.
+    if (auth) {
+      config.auth = {
+        ...config.auth,
+        ...auth,
+        ...(auth.apiKey ? { apiKey: { ...config.auth?.apiKey, ...auth.apiKey } } : {}),
+      };
+    }
+  };
+  client.use = (...middleware: Middleware[]): void => {
+    // Reassign (don't push) so a caller-provided `middleware` array isn't mutated.
+    config.middleware = [...(config.middleware ?? []), ...middleware];
+  };
+  client.auth = {
+    bearer(token: TokenProvider): void {
+      config.auth = { ...config.auth, bearer: token };
+    },
+    basic(username: string, password: string): void {
+      config.auth = { ...config.auth, basic: { username, password } };
+    },
+    apiKey(scheme: string, value: TokenProvider): void {
+      config.auth = { ...config.auth, apiKey: { ...config.auth?.apiKey, [scheme]: value } };
+    },
+  };
+
+  return client as Client<Ops, OperationContext<Id, Path, Tag>>;
+}
+
+/**
+ * The client factory: `createClientCore` wired with the capabilities this API needs.
+ * Exported so apps can build additional instances (per-tenant, per-environment) over
+ * the same `OPERATIONS`/`Ops`. The trailing string params carry the wiring's literal
+ * unions (`OperationId`/`OperationPath`/`OperationTag`) into `ctx.operation`.
+ */
+export function createClient<
+  Ops extends OpsShape,
+  Id extends string = string,
+  Path extends string = string,
+  Tag extends string = string,
+>(
+  operations: Record<string, OperationDescriptor>,
+  config?: ClientConfig<OperationContext<Id, Path, Tag>>
+): Client<Ops, OperationContext<Id, Path, Tag>> {
+  return createClientCore<Ops, Id, Path, Tag>(operations, config, { resolveAuth });
+}
+
+export const client = createClient<Ops, OperationId, OperationPath, OperationTag>(OPERATIONS, { serverUrl: "https://api.cafe.redocly.com" });
+
+export const { configure, use } = client;
+export const setBearer = client.auth.bearer;
+export const setApiKey = (value: TokenProvider) => client.auth.apiKey("ApiKey", value);
+export const listMenuItems = (params: {
+    /**
+     * Use the `endCursor` as a value for the `after` parameter to get the next page.
+     */
+    after?: string;
+    /**
+     * Use the `startCursor` as a value for the `before` parameter to get the next page.
+     */
+    before?: string;
+    /**
+     * To sort by id in descending order use `-id`.
+     * To sort by id in ascending order use `id`.
+     */
+    sort?: string;
+    /**
+     * Filters the collection items using space-separated `field:value` pairs.
+     *
+     * **Format:** `field1:value1 field2:value2`
+     *
+     * **Supported operators:**
+     * - `field:value` - Exact match
+     * - `field:value1,value2` - Match any of the comma-separated values (OR)
+     * - Time ranges: Use `30d` (30 days), `7d` (7 days), `1h` (1 hour), etc.
+     *
+     * **Examples:**
+     * - `status:placed` - Filter by single status.
+     * - `status:placed,completed` - Filter by multiple statuses.
+     * - `createdAt:30d` - Filter orders created in the last 30 days.
+     * - `orderId:ord_01h1s5z6vf2mm1mz3hevnn9va7` - Filter by specific order ID.
+     * - `status:placed createdAt:7d` - Combine multiple filters.
+     */
+    filter?: string;
+    /**
+     * Performs a case-insensitive text search across relevant fields in the collection.
+     *
+     * **Fields searched depend on the endpoint:**
+     * - **Menu items:** `name`, `photoTextDescription`
+     * - **Orders:** `customerName`, `id`
+     *
+     * Returns items where any of the searchable fields contain the search term as a substring.
+     */
+    search?: string;
+    /**
+     * Use to return a number of results per page.
+     * If there is more data, use in combination with `after` to page through the data.
+     * @minimum 1
+     * @maximum 100
+     */
+    limit?: number;
+} = {}, init: RequestOptions = {}) => client.listMenuItems({ params }, init);
+export const createMenuItem = (body: FormData, init: RequestOptions = {}) => client.createMenuItem({ body }, init);
+export const deleteMenuItem = (menuItemId: string, init: RequestOptions = {}) => client.deleteMenuItem({ menuItemId }, init);
+export const getMenuItemPhoto = (menuItemId: string, params: {
+    /**
+     * Photo size to retrieve.
+     */
+    photoSize?: "thumbnail" | "medium" | "large";
+} = {}, init: RequestOptions = {}) => client.getMenuItemPhoto({ menuItemId, params }, init);
+export const listOrders = (params: {
+    /**
+     * Filters the collection items using space-separated `field:value` pairs.
+     *
+     * **Format:** `field1:value1 field2:value2`
+     *
+     * **Supported operators:**
+     * - `field:value` - Exact match
+     * - `field:value1,value2` - Match any of the comma-separated values (OR)
+     * - Time ranges: Use `30d` (30 days), `7d` (7 days), `1h` (1 hour), etc.
+     *
+     * **Examples:**
+     * - `status:placed` - Filter by single status.
+     * - `status:placed,completed` - Filter by multiple statuses.
+     * - `createdAt:30d` - Filter orders created in the last 30 days.
+     * - `orderId:ord_01h1s5z6vf2mm1mz3hevnn9va7` - Filter by specific order ID.
+     * - `status:placed createdAt:7d` - Combine multiple filters.
+     */
+    filter?: string;
+    /**
+     * To sort by id in descending order use `-id`.
+     * To sort by id in ascending order use `id`.
+     */
+    sort?: string;
+    /**
+     * Use to return a number of results per page.
+     * If there is more data, use in combination with `after` to page through the data.
+     * @minimum 1
+     * @maximum 100
+     */
+    limit?: number;
+    /**
+     * Use the `endCursor` as a value for the `after` parameter to get the next page.
+     */
+    after?: string;
+    /**
+     * Use the `startCursor` as a value for the `before` parameter to get the next page.
+     */
+    before?: string;
+    /**
+     * Performs a case-insensitive text search across relevant fields in the collection.
+     *
+     * **Fields searched depend on the endpoint:**
+     * - **Menu items:** `name`, `photoTextDescription`
+     * - **Orders:** `customerName`, `id`
+     *
+     * Returns items where any of the searchable fields contain the search term as a substring.
+     */
+    search?: string;
+} = {}, init: RequestOptions = {}) => client.listOrders({ params }, init);
+export const createOrder = (body: Omit<Order, "id" | "object" | "status" | "totalPrice" | "createdAt" | "updatedAt">, init: RequestOptions = {}) => client.createOrder({ body }, init);
+export const getOrderById = (orderId: string, headers: {
+    /**
+     * Optional client-supplied correlation ID, echoed in logs and traces.
+     * @format uuid
+     */
+    "X-Request-Id"?: string;
+} = {}, init: RequestOptions = {}) => client.getOrderById({ orderId, headers }, init);
+export const deleteOrder = (orderId: string, init: RequestOptions = {}) => client.deleteOrder({ orderId }, init);
+export const updateOrder = (orderId: string, body?: {
+    status: OrderStatus;
+}, init: RequestOptions = {}) => client.updateOrder({ orderId, body }, init);
+export const listOrderItems = (params: {
+    /**
+     * Filters the collection items using space-separated `field:value` pairs.
+     *
+     * **Format:** `field1:value1 field2:value2`
+     *
+     * **Supported operators:**
+     * - `field:value` - Exact match
+     * - `field:value1,value2` - Match any of the comma-separated values (OR)
+     * - Time ranges: Use `30d` (30 days), `7d` (7 days), `1h` (1 hour), etc.
+     *
+     * **Examples:**
+     * - `status:placed` - Filter by single status.
+     * - `status:placed,completed` - Filter by multiple statuses.
+     * - `createdAt:30d` - Filter orders created in the last 30 days.
+     * - `orderId:ord_01h1s5z6vf2mm1mz3hevnn9va7` - Filter by specific order ID.
+     * - `status:placed createdAt:7d` - Combine multiple filters.
+     */
+    filter?: string;
+} = {}, init: RequestOptions = {}) => client.listOrderItems({ params }, init);
+export const getRevenue = (params: {
+    /**
+     * Start date for the revenue calculation period (ISO 8601 datetime format).
+     * Defaults to 30 days ago if not provided.
+     * @format date
+     */
+    startDate?: string;
+    /**
+     * End date for the revenue calculation period (ISO 8601 datetime format).
+     * Defaults to current time if not provided.
+     * @format date
+     */
+    endDate?: string;
+} = {}, init: RequestOptions = {}) => client.getRevenue({ params }, init);
+export const registerOAuth2Client = (body: RegisterClientObject, init: RequestOptions = {}) => client.registerOAuth2Client({ body }, init);
diff --git a/tests/e2e/generate-client/cafe.test.ts b/tests/e2e/generate-client/cafe.test.ts
new file mode 100644
index 0000000000..b409f5cb3f
--- /dev/null
+++ b/tests/e2e/generate-client/cafe.test.ts
@@ -0,0 +1,382 @@
+import { spawnSync, type ChildProcess } from 'node:child_process';
+import { existsSync, readFileSync, rmSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { cliEntry, killServer, repoRoot, startServer } from './helpers.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const fixture = join(__dirname, 'fixtures/cafe.yaml');
+const consumerDir = join(__dirname, 'cafe-consumer');
+const generatedFile = join(consumerDir, 'api.ts');
+const serverScript = join(consumerDir, 'server.ts');
+const indexScript = join(consumerDir, 'index.ts');
+const configureScript = join(consumerDir, 'index-configure.ts');
+
+const SERVER_PORT = 3101;
+const SERVER_BASE = `http://127.0.0.1:${SERVER_PORT}`;
+
+type LogEntry = {
+  method: string;
+  url: string;
+  contentType: string | undefined;
+  body: string;
+  headers: Record<string, string>;
+};
+type StepResult =
+  | { kind: 'ok'; name: string; data: unknown }
+  | { kind: 'err'; name: string; error: string };
+
+const snapshotFile = join(__dirname, 'cafe.snapshot.ts');
+
+describe('generate-client end-to-end (cafe.yaml)', () => {
+  let serverProcess: ChildProcess | undefined;
+  let results: StepResult[] = [];
+  let log: LogEntry[] = [];
+  /** Raw generator output — what the CLI emits from cafe.yaml without any overrides. */
+  let rawGenerated = '';
+  /** Generator output the consumer imports — same source, but serverUrl pinned at the mock via --server-url. */
+  let generated = '';
+
+  beforeAll(async () => {
+    if (existsSync(generatedFile)) {
+      rmSync(generatedFile, { force: true });
+    }
+
+    serverProcess = await startServer(
+      serverScript,
+      consumerDir,
+      { CAFE_SERVER_PORT: String(SERVER_PORT) },
+      SERVER_BASE,
+      'cafe-server'
+    );
+
+    // First pass: capture the *canonical* output (spec-derived serverUrl) for the file snapshot.
+    // We don't keep this on disk — the consumer needs the mock-targeted variant.
+    const snapshotGen = spawnSync(
+      'node',
+      [cliEntry, 'generate-client', fixture, '--output', generatedFile],
+      { encoding: 'utf-8', cwd: repoRoot }
+    );
+    if (snapshotGen.status !== 0) {
+      throw new Error(`generate-client (snapshot pass) failed:\n${snapshotGen.stderr}`);
+    }
+    rawGenerated = readFileSync(generatedFile, 'utf-8');
+
+    // Second pass: regenerate with --server-url so the consumer's import targets the mock.
+    // This is the file the consumer actually loads — and replaces the old string-replace hack.
+    const consumerGen = spawnSync(
+      'node',
+      [
+        cliEntry,
+        'generate-client',
+        fixture,
+        '--output',
+        generatedFile,
+        '--server-url',
+        SERVER_BASE,
+      ],
+      { encoding: 'utf-8', cwd: repoRoot }
+    );
+    if (consumerGen.status !== 0) {
+      throw new Error(`generate-client (consumer pass) failed:\n${consumerGen.stderr}`);
+    }
+    generated = readFileSync(generatedFile, 'utf-8');
+    if (!generated.includes(`{ serverUrl: "${SERVER_BASE}" }`)) {
+      throw new Error(
+        `--server-url was not honoured; expected \`{ serverUrl: "${SERVER_BASE}" }\``
+      );
+    }
+
+    // Type-check the consumer.
+    const tsc = spawnSync('npx', ['tsc', '--noEmit', '-p', consumerDir], {
+      encoding: 'utf-8',
+      cwd: repoRoot,
+    });
+    if (tsc.status !== 0) {
+      throw new Error(`tsc --noEmit failed:\nstdout:\n${tsc.stdout}\nstderr:\n${tsc.stderr}`);
+    }
+
+    // Run consumer.
+    const run = spawnSync('npx', ['tsx', indexScript], {
+      encoding: 'utf-8',
+      cwd: consumerDir,
+      env: { ...process.env, CAFE_BASE: SERVER_BASE },
+    });
+    if (run.status !== 0) {
+      throw new Error(`consumer failed:\nstdout:\n${run.stdout}\nstderr:\n${run.stderr}`);
+    }
+    results = JSON.parse(run.stdout.trim()) as StepResult[];
+
+    const logResponse = await fetch(`${SERVER_BASE}/__test__/log`);
+    log = (await logResponse.json()) as LogEntry[];
+  }, 120_000);
+
+  afterAll(async () => {
+    if (serverProcess) await killServer(serverProcess);
+  });
+
+  test('generated file matches the committed snapshot (cafe.snapshot.ts)', async () => {
+    // Full-file guard against accidental emitter regressions. The PR diff against this
+    // snapshot is the single most informative signal when the IR builder or emitter changes.
+    // After an intentional emitter change, regenerate with: `npm run e2e -- -u`.
+    await expect(rawGenerated).toMatchFileSnapshot(snapshotFile);
+  });
+
+  test('generated file contains expected named types', () => {
+    expect(generated).toContain('export type MenuItem = Beverage | Dessert;');
+    expect(generated).toContain('export type Beverage = {');
+    expect(generated).toContain('} & MenuBaseItem;');
+    expect(generated).toContain(
+      'export type OrderStatus = "placed" | "preparing" | "completed" | "canceled";'
+    );
+    expect(generated).toContain('export type MenuItemList = {');
+    expect(generated).toContain('export type OrderList = {');
+    expect(generated).toContain('export type RevenueStatistics = {');
+    expect(generated).toContain('export type OAuth2Client = {');
+  });
+
+  test('generated file declares one flat call-sugar function per operation', () => {
+    const expected = [
+      'listMenuItems',
+      'createMenuItem',
+      'deleteMenuItem',
+      'getMenuItemPhoto',
+      'listOrders',
+      'createOrder',
+      'getOrderById',
+      'updateOrder',
+      'deleteOrder',
+      'listOrderItems',
+      'getRevenue',
+      'registerOAuth2Client',
+    ];
+    for (const name of expected) {
+      expect(generated).toContain(`export const ${name} = (`);
+    }
+  });
+
+  test('exports an OPERATIONS descriptor map keyed by operationId (method + path template)', () => {
+    expect(generated).toContain('export const OPERATIONS = {');
+    expect(generated).toContain('} as const satisfies Record<string, OperationDescriptor>;');
+    expect(generated).toContain('export type OperationId = keyof typeof OPERATIONS;');
+    // A path-param operation keeps its `{param}` template, uppercased method, and tags.
+    expect(generated).toContain(
+      'getOrderById: { id: "getOrderById", method: "GET", path: "/orders/{orderId}", tags: ["Orders"]'
+    );
+    expect(generated).toContain(
+      'updateOrder: { id: "updateOrder", method: "PATCH", path: "/orders/{orderId}", tags: ["Orders"]'
+    );
+    expect(generated).toContain(
+      'createOrder: { id: "createOrder", method: "POST", path: "/orders", tags: ["Orders"]'
+    );
+    // The typed instance client is built over the descriptors.
+    expect(generated).toContain(
+      'export const client = createClient<Ops, OperationId, OperationPath, OperationTag>(OPERATIONS,'
+    );
+    expect(generated).toContain('export const { configure, use } = client;');
+  });
+
+  test('generated file uses ergonomic signatures (positional path params + params object + body)', () => {
+    expect(generated).toContain('export const deleteMenuItem = (menuItemId: string,');
+    expect(generated).toContain('export const getMenuItemPhoto = (menuItemId: string,');
+    expect(generated).toContain('export const updateOrder = (orderId: string,');
+    expect(generated).toContain('export const listMenuItems = (params:');
+    // readOnly fields are dropped from the create body (Bucket C).
+    expect(generated).toContain(
+      'export const createOrder = (body: Omit<Order, "id" | "object" | "status" | "totalPrice" | "createdAt" | "updatedAt">,'
+    );
+    expect(generated).toContain('export const createMenuItem = (body: FormData,');
+  });
+
+  // Named string enums get a runtime const-object companion by default, which the
+  // consumer uses (`OrderStatus.completed`) when updating an order.
+  test('emits a const-object companion for the OrderStatus string enum', () => {
+    expect(generated).toContain('export type OrderStatus =');
+    expect(generated).toContain('export const OrderStatus = {');
+    expect(generated).toContain('  completed: "completed",');
+    expect(generated).toContain('} as const;');
+  });
+
+  test('every consumer step succeeds', () => {
+    const failures = results.filter((r) => r.kind === 'err');
+    expect(failures, JSON.stringify(failures, null, 2)).toEqual([]);
+  });
+
+  test('listMenuItems serialises the query string with after/limit/sort/search', () => {
+    const entry = log.find((e) => e.method === 'GET' && e.url.startsWith('/menu?'));
+    expect(entry).toBeDefined();
+    expect(entry!.url).toContain('after=cursor1');
+    expect(entry!.url).toContain('limit=5');
+    expect(entry!.url).toContain('sort=-name');
+    expect(entry!.url).toContain('search=coffee');
+  });
+
+  test('createMenuItem POSTs multipart/form-data with the provided FormData', () => {
+    const entry = log.find((e) => e.method === 'POST' && e.url === '/menu');
+    expect(entry).toBeDefined();
+    expect(entry!.contentType).toMatch(/^multipart\/form-data; boundary=/);
+    expect(entry!.body).toContain('name="name"');
+    expect(entry!.body).toContain('Latte');
+  });
+
+  test('deleteMenuItem sends DELETE on the path-templated URL', () => {
+    const entry = log.find(
+      (e) => e.method === 'DELETE' && e.url === '/menu/prd_01h1s5z6vf2mm1mz3hevnn9va7'
+    );
+    expect(entry).toBeDefined();
+  });
+
+  test('getMenuItemPhoto reads a binary response as Blob', () => {
+    const photoStep = results.find((r) => r.name === 'getMenuItemPhoto');
+    expect(photoStep?.kind).toBe('ok');
+    if (photoStep?.kind === 'ok') {
+      // The mock server generates the body from the OpenAPI spec. The exact size
+      // and MIME depend on sampler internals (mock-server's supported-media-type
+      // allowlist may pick text/plain over image/png), so we assert only on the
+      // contract that matters here: the binary path returns a non-empty Blob.
+      const data = photoStep.data as {
+        kind: string;
+        size: number;
+        type: string;
+      };
+      expect(data.kind).toBe('blob');
+      expect(data.size).toBeGreaterThan(0);
+    }
+  });
+
+  test('createOrder POSTs JSON body with Content-Type: application/json', () => {
+    const entry = log.find((e) => e.method === 'POST' && e.url === '/orders');
+    expect(entry).toBeDefined();
+    expect(entry!.contentType).toMatch(/^application\/json/);
+    const parsed = JSON.parse(entry!.body) as { customerName: string };
+    expect(parsed.customerName).toBe('Ada Lovelace');
+  });
+
+  test('updateOrder PATCHes the URL and forwards the JSON body', () => {
+    const entry = log.find(
+      (e) => e.method === 'PATCH' && e.url === '/orders/ord_01h1s5z6vf2mm1mz3hevnn9va7'
+    );
+    expect(entry).toBeDefined();
+    const parsed = JSON.parse(entry!.body) as { status: string };
+    expect(parsed.status).toBe('completed');
+  });
+
+  // getOrderById declares an optional `X-Request-Id` header param; the consumer
+  // supplies it, and it must reach the server as a real request header.
+  test('getOrderById sends the X-Request-Id operation header parameter', () => {
+    const entry = log.find(
+      (e) => e.method === 'GET' && e.url === '/orders/ord_01h1s5z6vf2mm1mz3hevnn9va7'
+    );
+    expect(entry).toBeDefined();
+    expect(entry!.headers['x-request-id']).toBe('11111111-2222-3333-4444-555555555555');
+  });
+
+  // The consumer calls setBearer()/setApiKey() once; every OAuth2 operation must
+  // then carry the bearer header, every ApiKey operation the X-API-Key header,
+  // and `security: []` operations neither.
+  test('setBearer() injects Authorization on OAuth2 operations (getOrderById)', () => {
+    const entry = log.find(
+      (e) => e.method === 'GET' && e.url === '/orders/ord_01h1s5z6vf2mm1mz3hevnn9va7'
+    );
+    expect(entry).toBeDefined();
+    expect(entry!.headers['authorization']).toBe('Bearer test-bearer-token');
+  });
+
+  test('setApiKey() injects X-API-Key on ApiKey operations (getRevenue)', () => {
+    const entry = log.find((e) => e.method === 'GET' && e.url.startsWith('/revenue'));
+    expect(entry).toBeDefined();
+    expect(entry!.headers['x-api-key']).toBe('test-api-key');
+  });
+
+  test('operations declared security: [] send no credentials (listMenuItems)', () => {
+    const entry = log.find((e) => e.method === 'GET' && e.url.startsWith('/menu?'));
+    expect(entry).toBeDefined();
+    expect(entry!.headers['authorization']).toBeUndefined();
+    expect(entry!.headers['x-api-key']).toBeUndefined();
+  });
+
+  // The discriminated-union type guards must agree with the raw `category`
+  // discriminant and be mutually exclusive.
+  test('isBeverage/isDessert narrow a MenuItem from the server response', () => {
+    const step = results.find((r) => r.name === 'menuItemGuards');
+    expect(step?.kind).toBe('ok');
+    if (step?.kind === 'ok') {
+      const data = step.data as {
+        category: string;
+        isBeverage: boolean;
+        isDessert: boolean;
+        agree: boolean;
+        exclusive: boolean;
+      };
+      expect(data.agree).toBe(true);
+      expect(data.exclusive).toBe(true);
+    }
+  });
+
+  test('204 No Content paths return void (deleteOrder)', () => {
+    const step = results.find((r) => r.name === 'deleteOrder');
+    expect(step?.kind).toBe('ok');
+    if (step?.kind === 'ok') expect(step.data).toBeUndefined();
+  });
+
+  test('listOrderItems serialises query filter and returns an array', () => {
+    const entry = log.find((e) => e.method === 'GET' && e.url.startsWith('/order-items'));
+    expect(entry).toBeDefined();
+    expect(entry!.url).toContain('filter=orderId%3Aord_01h1s5z6vf2mm1mz3hevnn9va7');
+    const step = results.find((r) => r.name === 'listOrderItems');
+    expect(step?.kind).toBe('ok');
+    if (step?.kind === 'ok') expect(Array.isArray(step.data)).toBe(true);
+  });
+
+  test('getRevenue serialises ISO date strings as query params', () => {
+    const entry = log.find((e) => e.method === 'GET' && e.url.startsWith('/revenue?'));
+    expect(entry).toBeDefined();
+    expect(entry!.url).toContain('startDate=2026-01-01');
+    expect(entry!.url).toContain('endDate=2026-01-31');
+  });
+
+  test('registerOAuth2Client posts JSON arrays correctly', () => {
+    const entry = log.find((e) => e.method === 'POST' && e.url === '/oauth2/register');
+    expect(entry).toBeDefined();
+    const parsed = JSON.parse(entry!.body) as {
+      scopes: string[];
+      grantTypes: string[];
+      name: string;
+    };
+    expect(parsed.name).toBe('demo-client');
+    expect(parsed.scopes).toEqual(['menu:read', 'orders:read']);
+    expect(parsed.grantTypes).toEqual(['client_credentials']);
+  });
+
+  test('ApiError is thrown for non-2xx responses with parsed JSON body', () => {
+    const step = results.find((r) => r.name === 'error-path');
+    expect(step?.kind).toBe('ok');
+    if (step?.kind === 'ok') {
+      expect(step.data).toEqual({
+        apiError: true,
+        status: 500,
+        statusText: 'Internal Server Error',
+      });
+    }
+  });
+
+  // `configure({ serverUrl })` is exercised mid-flight: the first call hits the mock,
+  // the second (after flipping to an unreachable host) fails to connect, and the
+  // third (after restoring) succeeds again.
+  test('configure({ serverUrl }) switches the base URL for subsequent operations', () => {
+    const run = spawnSync('npx', ['tsx', configureScript], {
+      encoding: 'utf-8',
+      cwd: consumerDir,
+      env: { ...process.env, CAFE_BASE: SERVER_BASE },
+    });
+    expect(run.status, `configure consumer stderr:\n${run.stderr}`).toBe(0);
+    const steps = JSON.parse(run.stdout.trim()) as Array<
+      { kind: 'ok'; name: string } | { kind: 'err'; name: string; error: string }
+    >;
+    expect(steps.find((s) => s.name === 'initial-call-against-mock')?.kind).toBe('ok');
+    const flipped = steps.find((s) => s.name === 'call-after-configure-to-unreachable');
+    expect(flipped?.kind).toBe('err');
+    expect(steps.find((s) => s.name === 'call-after-configure-restored')?.kind).toBe('ok');
+  });
+});
diff --git a/tests/e2e/generate-client/error-mode.test.ts b/tests/e2e/generate-client/error-mode.test.ts
new file mode 100644
index 0000000000..e06ffb4bb5
--- /dev/null
+++ b/tests/e2e/generate-client/error-mode.test.ts
@@ -0,0 +1,93 @@
+// e2e for `--error-mode result`: the result-shape / typed-errors client.
+//
+// We assert on the generated source (string checks) and strict-tsc the output
+// (single-file and the split two-file set) — this is the same lightweight
+// harness used by spec-versions.test.ts. We deliberately do NOT spin up the
+// mock-server behavioral harness (base.test.ts / cafe.test.ts), which needs a
+// dedicated consumer dir with server.ts/index.ts: strict tsc over the
+// discriminated `Result<TData, TError>` already proves the typed `error` flows
+// through, and the behavioral retry/abort path is shared (the runtime's `send`)
+// and covered by the existing throw-mode base e2e. The split case guards that
+// the entry bakes `errorMode: "result"` into the client config too.
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { generate, strictTypecheck, tscBin } from './helpers.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/** Recursively collect every generated `.ts` file under `dir`. */
+function collectTsFiles(dir: string): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) out.push(...collectTsFiles(full));
+    else if (entry.endsWith('.ts')) out.push(full);
+  }
+  return out;
+}
+
+describe('generate-client error mode', () => {
+  it('single-file result mode: typed error alias + Result terminal, strict tsc passes', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'ots-errmode-single-'));
+    const out = join(dir, 'client.ts');
+    generate(join(__dirname, 'fixtures', 'error-mode.yaml'), out, ['--error-mode', 'result']);
+    expect(existsSync(out)).toBe(true);
+
+    const generated = readFileSync(out, 'utf-8');
+    expect(generated).toContain('export const getThing = (');
+    expect(generated).toContain('result: Result<GetThingResult, GetThingError>;');
+    expect(generated).toContain('export type GetThingError = ProblemDetails;');
+    // The mode is baked into the client instance config (configure() cannot flip it).
+    expect(generated).toContain('errorMode: "result"');
+
+    strictTypecheck(dir, ['client.ts']);
+    rmSync(dir, { recursive: true, force: true });
+  }, 60_000);
+
+  it('split result mode: the entry bakes errorMode result, strict tsc passes over both files', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'ots-errmode-split-'));
+    // Split mode takes a `.ts` entry path; the schemas file is written beside it.
+    const entry = join(dir, 'client.ts');
+    generate(join(__dirname, 'fixtures', 'error-mode.yaml'), entry, [
+      '--error-mode',
+      'result',
+      '--output-mode',
+      'split',
+    ]);
+    expect(existsSync(entry)).toBe(true);
+
+    const files = collectTsFiles(dir);
+    expect(files.map((f) => f.split('/').pop()).sort()).toEqual(['client.schemas.ts', 'client.ts']);
+
+    // The result shape is baked into the entry: typed Ops results and the instance config.
+    const entrySrc = readFileSync(entry, 'utf-8');
+    expect(entrySrc).toContain('errorMode: "result"');
+    expect(entrySrc).toContain('Result<');
+
+    // Strict tsc over the whole tree (bundler resolution handles the `.js` ESM imports).
+    const tsc = spawnSync(
+      tscBin,
+      [
+        '--noEmit',
+        '--strict',
+        '--noUnusedLocals',
+        '--target',
+        'ES2020',
+        '--module',
+        'esnext',
+        '--moduleResolution',
+        'bundler',
+        '--lib',
+        'ES2020,DOM',
+        ...files,
+      ],
+      { encoding: 'utf-8', cwd: dir }
+    );
+    expect(tsc.status, `tsc failed:\n${tsc.stdout}\n${tsc.stderr}`).toBe(0);
+    rmSync(dir, { recursive: true, force: true });
+  }, 60_000);
+});
diff --git a/tests/e2e/generate-client/examples.test.ts b/tests/e2e/generate-client/examples.test.ts
new file mode 100644
index 0000000000..62aaca272e
--- /dev/null
+++ b/tests/e2e/generate-client/examples.test.ts
@@ -0,0 +1,85 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(__dirname, '../../..');
+const cli = join(repoRoot, 'packages/cli/lib/index.js');
+const tsx = join(repoRoot, 'node_modules/.bin/tsx');
+const examplesDir = join(__dirname, 'examples');
+
+// Every directory under examples/ is an example; `_shared` holds the spec they have in common.
+const EXAMPLES = readdirSync(examplesDir, { withFileTypes: true })
+  .filter((entry) => entry.isDirectory() && entry.name !== '_shared')
+  .map((entry) => entry.name)
+  .sort();
+
+// The one example whose generated client stays committed (its README sells the single
+// self-contained file); it doubles as the drift baseline for the generator's output.
+// The other examples gitignore `src/api/` — CI regenerates and type-checks them via
+// `examples:regen` + `typecheck:examples` in @redocly/client-generator.
+const COMMITTED = 'zero-install-quickstart';
+
+/**
+ * Regenerate an example's client into `outFile`. A `redocly.yaml` example is generated by
+ * naming its `apis:` alias (which equals the example folder name) with `--output` redirecting
+ * the entry file to a temp dir; the programmatic example runs its `generate.ts` with `OUT`.
+ */
+function regenerate(
+  exampleDir: string,
+  name: string,
+  outFile: string
+): { status: number | null; stderr: string } {
+  if (existsSync(join(exampleDir, 'redocly.yaml'))) {
+    return spawnSync('node', [cli, 'generate-client', name, '--output', outFile], {
+      cwd: exampleDir,
+      encoding: 'utf-8',
+    });
+  }
+  return spawnSync(tsx, [join(exampleDir, 'generate.ts')], {
+    cwd: exampleDir,
+    encoding: 'utf-8',
+    env: { ...process.env, OUT: outFile },
+  });
+}
+
+/** All files (relative paths) under a dir, recursively. */
+function listFiles(dir: string, base = dir): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...listFiles(full, base));
+    else out.push(full.slice(base.length + 1));
+  }
+  return out;
+}
+
+describe('examples generate with the current generator', () => {
+  for (const name of EXAMPLES) {
+    it(`${name}: generation succeeds`, () => {
+      const exampleDir = join(examplesDir, name);
+      const tmp = mkdtempSync(join(tmpdir(), `ex-${name}-`));
+      try {
+        const res = regenerate(exampleDir, name, join(tmp, 'client.ts'));
+        expect(res.status, res.stderr).toBe(0);
+        expect(listFiles(tmp).length).toBeGreaterThan(0);
+
+        if (name === COMMITTED) {
+          const committed = join(exampleDir, 'src/api');
+          const committedFiles = listFiles(committed).sort();
+          expect(listFiles(tmp).sort(), `file set differs for ${name}`).toEqual(committedFiles);
+          for (const rel of committedFiles) {
+            expect(
+              readFileSync(join(tmp, rel), 'utf-8'),
+              `${name}/src/api/${rel} is stale — run \`npm run examples:regen -w @redocly/client-generator\``
+            ).toBe(readFileSync(join(committed, rel), 'utf-8'));
+          }
+        }
+      } finally {
+        rmSync(tmp, { recursive: true, force: true });
+      }
+    }, 60_000);
+  }
+});
diff --git a/tests/e2e/generate-client/examples/README.md b/tests/e2e/generate-client/examples/README.md
new file mode 100644
index 0000000000..46d75b842f
--- /dev/null
+++ b/tests/e2e/generate-client/examples/README.md
@@ -0,0 +1,41 @@
+# Examples
+
+Runnable examples of clients generated by `@redocly/client-generator`.
+Most are Vite apps that _consume_ a client generated via the `redocly generate-client` CLI (a `redocly.yaml`); `programmatic` _generates_ one with the `generateClient(...)` API.
+Eight examples share the cafe spec in [`_shared/cafe.yaml`](./_shared/cafe.yaml); the rest carry their own.
+
+The generated client under `src/api/` is gitignored — CI regenerates every client and type-checks the consumer code against it (the `examples` job), and `zero-install-quickstart` keeps its client committed as the canonical browsable copy, drift-checked in `tests/e2e/generate-client/examples.test.ts`.
+
+| Example                                                | How it's generated             | Shows                                                                                                                                     |
+| ------------------------------------------------------ | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| [fetch-functions](./fetch-functions)                   | CLI · `sdk`, functions         | free functions + `ApiError`                                                                                                               |
+| [baked-setup](./baked-setup)                           | CLI · `sdk`, functions         | publisher defaults baked into the client via `--setup` (`defineClientSetup`)                                                              |
+| [zod](./zod)                                           | CLI · `sdk`, `zod`             | validating responses with generated zod schemas                                                                                           |
+| [tanstack-query](./tanstack-query)                     | CLI · `sdk`, `tanstack-query`  | React `useQuery(<op>Options())`                                                                                                           |
+| [mock](./mock)                                         | CLI · `sdk`, `mock`            | MSW handlers from generated `handlers`                                                                                                    |
+| [programmatic](./programmatic)                         | `generateClient(...)` API      | generating the client from a Node script                                                                                                  |
+| [package-runtime](./package-runtime)                   | CLI · `sdk`, package runtime   | `runtime: package` — types + descriptors only; the versioned runtime is imported from `@redocly/client-generator`, fixes via `npm update` |
+| [zero-install-quickstart](./zero-install-quickstart)   | CLI · `sdk`                    | the first-touch loop: generate → import → call; one self-contained file, zero runtime dependencies                                        |
+| [node-native](./node-native)                           | CLI · `sdk`                    | `importExt: ts` — `.ts` import specifiers so plain `node src/main.ts` runs the client via Node's built-in type stripping                  |
+| [configure-and-middleware](./configure-and-middleware) | CLI · `sdk`                    | `configure({ serverUrl, retry, fetch })`, `use()` targeting `ctx.operation` (literal unions), body mutation, auth setter, `ApiError.body` |
+| [multi-instance](./multi-instance)                     | CLI · `sdk`, package runtime   | per-tenant instances via `createClient(OPERATIONS)` — works in both runtimes; this example uses `runtime: package`                        |
+| [sse-streaming](./sse-streaming)                       | CLI · `sdk`                    | typed `for await` over SSE, auto-reconnect via `Last-Event-ID` (`reconnectDelay`/`reconnect: false`), clean abort                         |
+| [vendored-edge](./vendored-edge)                       | CLI · `sdk`                    | the generated file copied into a no-npm edge worker (`export default { fetch }`); `typescript` is the only dev tool                       |
+| [pagination](./pagination)                             | CLI · `sdk`                    | auto-pagination from a `client.pagination` convention: `for await` over `.items()`/`.pages()` next to the unchanged one-shot call         |
+| [custom-pagination](./custom-pagination)               | CLI · `sdk`                    | hand-written paging over the typed client for shapes the built-in styles don't cover (body cursors)                                       |
+| [custom-generator](./custom-generator)                 | CLI · `sdk` + custom generator | a local `generators` plugin emitting a `<operationId>: 'METHOD /path'` route map next to the sdk                                          |
+| [nested-facade](./nested-facade)                       | CLI · `sdk` + custom generator | `api.<resource>.<operation>` facade derived from the spec's tags by a plugin — regenerates with the spec                                  |
+
+## Run one
+
+```bash
+# from the repo root: generate the gitignored clients first
+npm run examples:regen -w @redocly/client-generator
+
+cd tests/e2e/generate-client/examples/<name>
+npm install
+npm run dev        # the Vite apps; `programmatic` uses `npm run generate`,
+                   # `zero-install-quickstart`/`node-native` `npm start`, `vendored-edge` `npm run typecheck`
+```
+
+Each example can also regenerate just its own client with `npm run generate` inside its directory.
diff --git a/tests/e2e/generate-client/examples/_shared/cafe.yaml b/tests/e2e/generate-client/examples/_shared/cafe.yaml
new file mode 100644
index 0000000000..a255b72a20
--- /dev/null
+++ b/tests/e2e/generate-client/examples/_shared/cafe.yaml
@@ -0,0 +1,1163 @@
+openapi: 3.2.0
+info:
+  title: Redocly Cafe
+  description: |
+    Demo API for cafe operators (not customers) to manage menus, orders, and revenue.
+    Create API credentials and try it yourself in a realistic OpenAPI workflow.
+  version: 1.0.0
+  contact:
+    email: team@redocly.com
+    url: https://redocly.com/contact-us/
+  license:
+    name: MIT
+    url: https://opensource.org/licenses/MIT
+  termsOfService: https://redocly.com/subscription-agreement
+servers:
+  - url: https://api.cafe.redocly.com
+    description: Live server.
+tags:
+  - name: Authorization
+    description: Create a client to demo the API.
+  - name: Products
+    description: Operations related to products.
+  - name: Orders
+    description: Order management operations.
+  - name: Statistics
+    description: Statistics operations.
+paths:
+  /menu:
+    get:
+      tags:
+        - Products
+      summary: List all menu items
+      description: Retrieve a collection of menu items with optional filtering and pagination.
+      operationId: listMenuItems
+      security: []
+      parameters:
+        - $ref: '#/components/parameters/After'
+        - $ref: '#/components/parameters/Before'
+        - $ref: '#/components/parameters/Sort'
+        - $ref: '#/components/parameters/Filter'
+        - $ref: '#/components/parameters/Search'
+        - $ref: '#/components/parameters/Limit'
+      responses:
+        '200':
+          description: Successful operation.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MenuItemList'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+    post:
+      tags:
+        - Products
+      summary: Create menu item
+      description: Create a new menu item.
+      operationId: createMenuItem
+      security:
+        - OAuth2:
+            - menu:write
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              $ref: '#/components/schemas/MenuItem'
+      responses:
+        '201':
+          description: Menu item created successfully.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MenuItem'
+              examples:
+                MenuItemResponse:
+                  value:
+                    id: prd_01khr487f7qm7p44xn427m43vb
+                    object: menuItem
+                    name: coffee
+                    price: 4000
+                    category: beverage
+                    createdAt: '2026-02-18T10:20:38.228Z'
+                    updatedAt: '2026-02-18T10:20:38.228Z'
+                    volume: 600
+                    containsCaffeine: false
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '409':
+          $ref: '#/components/responses/Conflict'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+  /menu/{menuItemId}:
+    parameters:
+      - $ref: '#/components/parameters/MenuItemId'
+    delete:
+      tags:
+        - Products
+      summary: Delete a menu item
+      description: Delete an existing menu item.
+      operationId: deleteMenuItem
+      security:
+        - OAuth2:
+            - menu:write
+      responses:
+        '204':
+          description: Menu item deleted successfully.
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+  /menu-item-images/{menuItemId}:
+    parameters:
+      - $ref: '#/components/parameters/MenuItemId'
+    get:
+      operationId: getMenuItemPhoto
+      summary: Retrieve a menu item photo
+      description: Retrieve the product photo image for a specific menu item.
+      security: []
+      tags:
+        - Products
+      parameters:
+        - $ref: '#/components/parameters/PhotoSize'
+      responses:
+        '200':
+          description: Menu item photo retrieved successfully.
+          content:
+            image/png:
+              schema:
+                type: string
+                format: binary
+            text/plain:
+              schema:
+                description: Alternative image text.
+                type: string
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+  /orders:
+    get:
+      tags:
+        - Orders
+      summary: List all orders
+      description: Retrieve a collection of orders with optional filtering and pagination.
+      operationId: listOrders
+      security:
+        - OAuth2:
+            - orders:read
+      parameters:
+        - $ref: '#/components/parameters/Filter'
+        - $ref: '#/components/parameters/Sort'
+        - $ref: '#/components/parameters/Limit'
+        - $ref: '#/components/parameters/After'
+        - $ref: '#/components/parameters/Before'
+        - $ref: '#/components/parameters/Search'
+      responses:
+        '200':
+          description: Successful operation.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OrderList'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+    post:
+      tags:
+        - Orders
+      summary: Create order
+      description: |
+        Create a new order.
+        Order items cannot be changed - if they need to be updated, the order should be canceled and a new one placed.
+      operationId: createOrder
+      security:
+        - OAuth2:
+            - orders:write
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Order'
+            examples:
+              OrderRequest:
+                dataValue:
+                  customerName: Mary Ann
+                  orderItems:
+                    - menuItemId: prd_01h1s5z6vf2mm1mz3hevnn9va7
+                      quantity: 2
+                      comment: No sugar!
+                      discount: 0
+      responses:
+        '201':
+          description: Order placed successfully.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Order'
+              examples:
+                OrderResponse:
+                  dataValue:
+                    id: ord_01h1s5z6vf2mm1mz3hevnn9va7
+                    customerName: Mary Ann
+                    orderItems:
+                      - menuItemId: prd_01h1s5z6vf2mm1mz3hevnn9va7
+                        quantity: 2
+                        comment: No sugar!
+                        discount: 0
+                    object: order
+                    status: placed
+                    totalPrice: 200
+                    createdAt: '2026-08-24T14:15:22Z'
+                    updatedAt: '2026-08-24T14:15:22Z'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+  /orders/{orderId}:
+    get:
+      tags:
+        - Orders
+      summary: Retrieve an order
+      description: Retrieve a single order by its ID.
+      operationId: getOrderById
+      security:
+        - OAuth2:
+            - orders:read
+      parameters:
+        - $ref: '#/components/parameters/OrderId'
+        - name: X-Request-Id
+          in: header
+          required: false
+          description: |
+            Optional client-supplied correlation ID, echoed in logs and traces.
+          schema:
+            type: string
+            format: uuid
+      responses:
+        '200':
+          description: Successful operation.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Order'
+              examples:
+                OrderResponse:
+                  dataValue:
+                    id: ord_01h1s5z6vf2mm1mz3hevnn9va7
+                    customerName: Mary Ann
+                    orderItems:
+                      - menuItemId: prd_01h1s5z6vf2mm1mz3hevnn9va7
+                        quantity: 2
+                        comment: No sugar!
+                        discount: 0
+                    object: order
+                    status: placed
+                    totalPrice: 200
+                    createdAt: '2026-08-24T14:15:22Z'
+                    updatedAt: '2026-08-24T14:15:22Z'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+    patch:
+      tags:
+        - Orders
+      summary: Partially update an order
+      description: |
+        Update an existing order status.
+        Order items cannot be changed - if they need to be updated, the order should be canceled and a new one placed.
+      operationId: updateOrder
+      security:
+        - OAuth2:
+            - orders:write
+      parameters:
+        - $ref: '#/components/parameters/OrderId'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              description: |
+                Partial order update using JSON Merge Patch - only include fields to update.
+              properties:
+                status:
+                  $ref: '#/components/schemas/OrderStatus'
+              required:
+                - status
+      responses:
+        '200':
+          description: Order updated successfully.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Order'
+              examples:
+                OrderResponse:
+                  dataValue:
+                    id: ord_01h1s5z6vf2mm1mz3hevnn9va7
+                    customerName: Mary Ann
+                    orderItems:
+                      - menuItemId: prd_01h1s5z6vf2mm1mz3hevnn9va7
+                        quantity: 2
+                        comment: No sugar!
+                        discount: 0
+                    object: order
+                    status: completed
+                    totalPrice: 200
+                    createdAt: '2026-08-24T14:15:22Z'
+                    updatedAt: '2026-08-24T14:15:22Z'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+    delete:
+      tags:
+        - Orders
+      summary: Delete an order
+      description: |
+        Delete the order.
+        To keep the order history, the order should be canceled instead of deleted.
+      operationId: deleteOrder
+      security:
+        - OAuth2:
+            - orders:write
+      parameters:
+        - $ref: '#/components/parameters/OrderId'
+      responses:
+        '204':
+          description: Order deleted successfully.
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+  /order-items:
+    get:
+      tags:
+        - Orders
+      summary: List all order items with menu item details
+      description: |
+        Returns an array of order items for a specific order.
+        Use the `filter` parameter to filter by order ID.
+      operationId: listOrderItems
+      security:
+        - OAuth2:
+            - orders:read
+      parameters:
+        - $ref: '#/components/parameters/Filter'
+          required: true
+      responses:
+        '200':
+          description: Successful operation.
+          content:
+            application/json:
+              schema:
+                type: array
+                description: List of menu items that are part of the order.
+                items:
+                  $ref: '#/components/schemas/OrderItem'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+  /revenue:
+    get:
+      tags:
+        - Statistics
+      summary: Get revenue statistics
+      description: |
+        Retrieve revenue statistics for a configurable date range.
+        Returns revenue, order counts, average order amount, and other useful statistics.
+      operationId: getRevenue
+      security:
+        - ApiKey: []
+      parameters:
+        - name: startDate
+          in: query
+          required: false
+          description: |
+            Start date for the revenue calculation period (ISO 8601 datetime format).
+            Defaults to 30 days ago if not provided.
+          schema:
+            type: string
+            format: date
+          example: '2026-01-01'
+        - name: endDate
+          in: query
+          required: false
+          description: |
+            End date for the revenue calculation period (ISO 8601 datetime format).
+            Defaults to current time if not provided.
+          schema:
+            type: string
+            format: date
+          example: '2026-01-31'
+      responses:
+        '200':
+          description: Revenue statistics retrieved successfully.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RevenueStatistics'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+  /oauth2/register:
+    post:
+      tags:
+        - Authorization
+      summary: Create OAuth2 client
+      description: |
+        Register a new OAuth2 client for dynamic client registration.  This endpoint implements the Dynamic Client Registration Protocol (RFC 7591), using camelCase field names instead of the RFC's snake_case convention (e.g., `redirectUris` instead of `redirect_uris`, `grantTypes` instead of `grant_types`). The `name` field is required. Other fields are optional. If not provided:
+        - `redirectUris` defaults to an empty array. Note: When using the `authorization_code` grant type, 
+          `redirectUris` must be provided (per RFC 7591 Section 2).
+        - `scopes` defaults to all available scopes (menu:read, menu:write, orders:read, orders:write) - `grantTypes` defaults to both supported grant types (authorization_code, client_credentials)
+        Returns the registered client information per RFC 7591, including:
+        - `clientId` and `clientSecret` (must be stored securely) - `clientIdIssuedAt` and `clientSecretExpiresAt` timestamps - All registered client metadata (name, redirectUris, scopes, grantTypes)
+      operationId: registerOAuth2Client
+      security: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RegisterClientObject'
+      responses:
+        '201':
+          description: OAuth2 client registered successfully.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OAuth2Client'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+webhooks:
+  order-notification:
+    post:
+      tags:
+        - Orders
+      operationId: orderNotificationWebhook
+      security: []
+      summary: Order notification webhook
+      description: Webhook triggered when a new order is placed.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/OrderNotification'
+      responses:
+        '200':
+          description: Webhook received successfully.
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+components:
+  securitySchemes:
+    OAuth2:
+      type: oauth2
+      description: OAuth2 authorization for API access.
+      flows:
+        authorizationCode:
+          authorizationUrl: https://api.cafe.redocly.com/oauth2/authorize
+          tokenUrl: https://api.cafe.redocly.com/oauth2/token
+          scopes:
+            menu:read: Read access to menu items and images
+            menu:write: Write access to menu items (create, delete)
+            orders:read: Read access to orders
+            orders:write: Write access to orders (create, update, delete)
+        clientCredentials:
+          tokenUrl: https://api.cafe.redocly.com/oauth2/token
+          scopes:
+            menu:read: Read access to menu items and images
+            menu:write: Write access to menu items (create, delete)
+            orders:read: Read access to orders
+            orders:write: Write access to orders (create, update, delete)
+    ApiKey:
+      type: apiKey
+      name: X-API-Key
+      in: header
+      description: API key for internal operations.
+  parameters:
+    After:
+      name: after
+      in: query
+      required: false
+      description: Use the `endCursor` as a value for the `after` parameter to get the next page.
+      schema:
+        type: string
+      example: a25fgaksjf23la==
+    Before:
+      name: before
+      in: query
+      required: false
+      description: |
+        Use the `startCursor` as a value for the `before` parameter to get the next page.
+      schema:
+        type: string
+      example: bfg23aksjf23zb1==
+    Sort:
+      name: sort
+      description: |-
+        To sort by id in descending order use `-id`.
+        To sort by id in ascending order use `id`.
+      in: query
+      required: false
+      schema:
+        type: string
+      example: '-name'
+    Filter:
+      name: filter
+      description: |-
+        Filters the collection items using space-separated `field:value` pairs.
+
+        **Format:** `field1:value1 field2:value2`
+
+        **Supported operators:**
+        - `field:value` - Exact match
+        - `field:value1,value2` - Match any of the comma-separated values (OR)
+        - Time ranges: Use `30d` (30 days), `7d` (7 days), `1h` (1 hour), etc.
+
+        **Examples:**
+        - `status:placed` - Filter by single status.
+        - `status:placed,completed` - Filter by multiple statuses.
+        - `createdAt:30d` - Filter orders created in the last 30 days.
+        - `orderId:ord_01h1s5z6vf2mm1mz3hevnn9va7` - Filter by specific order ID.
+        - `status:placed createdAt:7d` - Combine multiple filters.
+      in: query
+      required: false
+      schema:
+        type: string
+      example: orderId:ord_01h1s5z6vf2mm1mz3hevnn9va7
+    Search:
+      name: search
+      in: query
+      description: |-
+        Performs a case-insensitive text search across relevant fields in the collection.
+
+        **Fields searched depend on the endpoint:**
+        - **Menu items:** `name`, `photoTextDescription`
+        - **Orders:** `customerName`, `id`
+
+        Returns items where any of the searchable fields contain the search term as a substring.
+      required: false
+      schema:
+        type: string
+      example: coffee
+    Limit:
+      name: limit
+      description: |
+        Use to return a number of results per page.
+        If there is more data, use in combination with `after` to page through the data.
+      in: query
+      required: false
+      schema:
+        type: integer
+        minimum: 1
+        maximum: 100
+        default: 10
+      example: 10
+    MenuItemId:
+      name: menuItemId
+      in: path
+      description: ID of the menu item to retrieve.
+      required: true
+      schema:
+        type: string
+        pattern: ^prd_[0-9abcdefghjkmnpqrstvwxyz]{26}$
+      example: prd_01h1s5z6vf2mm1mz3hevnn9va7
+    PhotoSize:
+      name: photoSize
+      in: query
+      description: Photo size to retrieve.
+      required: false
+      schema:
+        type: string
+        enum:
+          - thumbnail
+          - medium
+          - large
+        default: medium
+    OrderId:
+      name: orderId
+      in: path
+      description: ID of the order to retrieve.
+      required: true
+      schema:
+        type: string
+        pattern: ^ord_[0-9abcdefghjkmnpqrstvwxyz]{26}$
+      example: ord_01h1s5z6vf2mm1mz3hevnn9va7
+  schemas:
+    Page:
+      type: object
+      properties:
+        endCursor:
+          type:
+            - string
+            - 'null'
+          description: |-
+            Use with the `after` query parameter to load the next page of data.
+            When `null`, there is no data.
+            The cursor is opaque and internal structure is subject to change.
+        startCursor:
+          type:
+            - string
+            - 'null'
+          description: |-
+            Use with the `before` query parameter to load the previous page of data.
+            When `null`, there is no data.
+            The cursor is opaque and internal structure is subject to change.
+        hasNextPage:
+          type: boolean
+          description: Indicates if there is a next page with items.
+        hasPrevPage:
+          type: boolean
+          description: Indicates if there is a previous page with items.
+        limit:
+          type: integer
+          minimum: 1
+          maximum: 100
+          default: 10
+          description: Value showing how many items are in the page limit.
+        total:
+          type: integer
+          description: Count of items across all pages.
+          minimum: 0
+      required:
+        - endCursor
+        - startCursor
+        - hasNextPage
+        - hasPrevPage
+        - limit
+        - total
+    MenuBaseItem:
+      type: object
+      properties:
+        createdAt:
+          description: Created date.
+          type: string
+          format: date-time
+          readOnly: true
+        updatedAt:
+          description: Updated date.
+          type: string
+          format: date-time
+          readOnly: true
+        id:
+          description: Menu item ID. Unique identifier prefixed with `prd_`.
+          type: string
+          readOnly: true
+          pattern: ^prd_[0-9abcdefghjkmnpqrstvwxyz]{26}$
+          example: prd_01h1s5z6vf2mm1mz3hevnn9va7
+        object:
+          description: Entity name.
+          type: string
+          const: menuItem
+          readOnly: true
+        name:
+          description: Menu item name.
+          type: string
+          minLength: 1
+          maxLength: 50
+        price:
+          description: Price in cents.
+          type: integer
+          minimum: 0
+        photo:
+          writeOnly: true
+          type:
+            - string
+            - 'null'
+          format: binary
+          description: Photo of the menu item. Must be a PNG image and less than 1MB.
+        photoUrl:
+          readOnly: true
+          type: string
+          format: uri
+          description: Photo URL of the menu item.
+        photoTextDescription:
+          type:
+            - string
+            - 'null'
+      required:
+        - id
+        - name
+        - price
+        - createdAt
+        - updatedAt
+        - object
+    Beverage:
+      allOf:
+        - type: object
+          properties:
+            category:
+              description: Menu item category.
+              type: string
+              const: beverage
+            volume:
+              type: number
+              description: Size of the beverage in milliliters.
+              exclusiveMinimum: 0
+            containsCaffeine:
+              type: boolean
+              description: Indicates if the beverage contains caffeine.
+          required:
+            - category
+            - volume
+            - containsCaffeine
+        - $ref: '#/components/schemas/MenuBaseItem'
+    Dessert:
+      allOf:
+        - type: object
+          properties:
+            category:
+              description: Menu item category.
+              type: string
+              const: dessert
+            calories:
+              type: number
+              exclusiveMinimum: 0
+              description: Amount of calories.
+          required:
+            - category
+            - calories
+        - $ref: '#/components/schemas/MenuBaseItem'
+    MenuItem:
+      discriminator:
+        propertyName: category
+        mapping:
+          beverage: '#/components/schemas/Beverage'
+          dessert: '#/components/schemas/Dessert'
+      oneOf:
+        - $ref: '#/components/schemas/Beverage'
+        - $ref: '#/components/schemas/Dessert'
+      required:
+        - category
+    MenuItemList:
+      type: object
+      properties:
+        object:
+          type: string
+          const: list
+          description: Entity name.
+        page:
+          $ref: '#/components/schemas/Page'
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/MenuItem'
+      required:
+        - object
+        - page
+        - items
+    Error:
+      type: object
+      properties:
+        type:
+          type: string
+          format: uri-reference
+          description: URI reference that identifies the problem type.
+          default: about:blank
+        title:
+          type: string
+          description: Short summary of the problem type.
+        status:
+          type: integer
+          format: int32
+          description: |
+            HTTP status code generated by the origin server for this occurrence of the problem.
+          minimum: 100
+          exclusiveMaximum: 600
+        instance:
+          type: string
+          format: uri-reference
+          description: |
+            URI reference that identifies the specific occurrence of the problem, e.g. by adding a fragment identifier or sub-path to the problem type.
+            May be used to locate the root of this problem in the source code.
+          example: /some/uri-reference#specific-occurrence-context
+        details:
+          description: Additional error details.
+          type: object
+          additionalProperties: true
+      required:
+        - type
+        - title
+        - status
+    OrderStatus:
+      type: string
+      description: Order status.
+      enum:
+        - placed
+        - preparing
+        - completed
+        - canceled
+    Order:
+      type: object
+      title: Order
+      properties:
+        id:
+          description: Order ID. Unique identifier prefixed with `ord_`.
+          type: string
+          format: ulid
+          readOnly: true
+          pattern: ^ord_[0-9abcdefghjkmnpqrstvwxyz]{26}$
+          example: ord_01h1s5z6vf2mm1mz3hevnn9va7
+        object:
+          description: Entity name.
+          type: string
+          const: order
+          readOnly: true
+        customerName:
+          description: |
+            Name of the customer who placed the order.
+            Must start and end with a letter, and can contain letters, spaces, hyphens, and apostrophes (e.g., "John Doe", "Mary-Jane", "O'Brien").
+          type: string
+          pattern: ^[A-Za-z]+(?:[\s'-][A-Za-z]+)*$
+          minLength: 1
+          maxLength: 100
+        status:
+          allOf:
+            - $ref: '#/components/schemas/OrderStatus'
+          readOnly: true
+        totalPrice:
+          description: Total order price in cents.
+          type: integer
+          minimum: 0
+          readOnly: true
+        createdAt:
+          description: Created date.
+          type: string
+          format: date-time
+          readOnly: true
+        updatedAt:
+          description: Updated date.
+          type: string
+          format: date-time
+          readOnly: true
+        orderItems:
+          type: array
+          description: List of items to include in the order.
+          minItems: 1
+          items:
+            type: object
+            properties:
+              menuItemId:
+                type: string
+                format: ulid
+                description: ID of the menu item to add to the order.
+              quantity:
+                type: integer
+                minimum: 1
+                description: Quantity of the menu item.
+              discount:
+                type: integer
+                minimum: 0
+                description: Discount amount in cents (absolute value).
+                default: 0
+              comment:
+                type: string
+                maxLength: 500
+                description: Optional comment for the order item (e.g., "No sugar").
+            required:
+              - menuItemId
+              - quantity
+      required:
+        - customerName
+        - orderItems
+    OrderList:
+      type: object
+      properties:
+        object:
+          type: string
+          const: list
+          description: Entity name.
+        page:
+          $ref: '#/components/schemas/Page'
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/Order'
+      required:
+        - object
+        - page
+        - items
+    OrderItem:
+      type: object
+      properties:
+        menuItemId:
+          type: string
+          description: ID of the menu item to add to the order.
+          writeOnly: true
+        menuItem:
+          allOf:
+            - $ref: '#/components/schemas/MenuItem'
+          description: Menu item that is part of the order.
+          readOnly: true
+        quantity:
+          type: integer
+          minimum: 1
+          description: Quantity of the menu item.
+        discount:
+          type: integer
+          minimum: 0
+          description: Discount amount in cents (absolute value).
+          default: 0
+        comment:
+          type: string
+          maxLength: 500
+          description: Optional comment for the order item (e.g., "No sugar").
+      required:
+        - menuItemId
+        - quantity
+    RevenueStatistics:
+      type: object
+      description: Revenue statistics for a given date range.
+      properties:
+        revenue:
+          type: number
+          format: float
+          description: Total revenue in cents from completed orders.
+          minimum: 0
+        averageOrderAmount:
+          type: number
+          format: float
+          description: Average order amount in cents (calculated from completed orders only).
+          minimum: 0
+        totalOrders:
+          type: integer
+          description: Total number of orders (all statuses) in the date range.
+          minimum: 0
+        placedOrders:
+          type: integer
+          description: Number of placed orders.
+          minimum: 0
+        preparingOrders:
+          type: integer
+          description: Number of preparing orders.
+          minimum: 0
+        completedOrders:
+          type: integer
+          description: Number of completed orders.
+          minimum: 0
+        canceledOrders:
+          type: integer
+          description: Number of canceled orders.
+          minimum: 0
+        startDate:
+          type: string
+          format: date
+          description: Start date of the revenue calculation period.
+        endDate:
+          type: string
+          format: date
+          description: End date of the revenue calculation period.
+      required:
+        - revenue
+        - averageOrderAmount
+        - totalOrders
+        - placedOrders
+        - preparingOrders
+        - completedOrders
+        - canceledOrders
+        - startDate
+        - endDate
+    RegisterClientObject:
+      type: object
+      properties:
+        name:
+          type: string
+          description: Client name.
+        redirectUris:
+          type: array
+          items:
+            type: string
+            format: uri
+          description: List of redirect URIs (optional, defaults to empty array).
+        scopes:
+          type: array
+          items:
+            type: string
+            enum:
+              - menu:read
+              - menu:write
+              - orders:read
+              - orders:write
+          description: List of scopes.
+        grantTypes:
+          type: array
+          items:
+            type: string
+            enum:
+              - authorization_code
+              - client_credentials
+          description: List of grant types.
+      required:
+        - name
+    OAuth2Client:
+      type: object
+      description: OAuth2 client registration response. Per RFC 7591, includes the client identifier, secret, timestamps, and all registered client metadata.
+      properties:
+        clientId:
+          type: string
+          description: Client identifier issued by the authorization server.
+        clientSecret:
+          type: string
+          description: Client secret issued by the authorization server.
+        clientIdIssuedAt:
+          type: integer
+          format: int64
+          description: Time when the client_id is issued, represented as seconds since epoch (RFC7591).
+        clientSecretExpiresAt:
+          type: integer
+          format: int64
+          description: Time at which the client_secret expires, represented as seconds since epoch. 0 indicates the secret does not expire (RFC 7591).
+        name:
+          type: string
+          description: Client name (registered metadata).
+        redirectUris:
+          type: array
+          items:
+            type: string
+            format: uri
+          description: List of redirect URIs (registered metadata).
+        registrationClientUri:
+          type: string
+          format: uri
+          description: URL of the client configuration endpoint for managing this client registration (RFC 7592).
+        registrationAccessToken:
+          type: string
+          description: Access token to be used at the client configuration endpoint for managing this client registration (RFC 7592).
+        scopes:
+          type: array
+          items:
+            type: string
+            enum:
+              - menu:read
+              - menu:write
+              - orders:read
+              - orders:write
+          description: List of scopes (registered metadata).
+        grantTypes:
+          type: array
+          items:
+            type: string
+            enum:
+              - authorization_code
+              - client_credentials
+          description: List of grant types (registered metadata).
+      required:
+        - clientId
+        - clientSecret
+        - clientIdIssuedAt
+        - clientSecretExpiresAt
+        - registrationClientUri
+        - registrationAccessToken
+    OrderNotification:
+      type: object
+      required:
+        - orderId
+        - orderStatus
+        - timestamp
+      properties:
+        orderId:
+          type: string
+          description: Unique order identifier.
+        orderStatus:
+          $ref: '#/components/schemas/OrderStatus'
+        timestamp:
+          type: string
+          format: date-time
+          description: When the event occurred.
+  responses:
+    BadRequest:
+      description: Bad request - invalid input parameters.
+      content:
+        application/problem+json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    InternalServerError:
+      description: Internal server error.
+      content:
+        application/problem+json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    Unauthorized:
+      description: Unauthorized - authorization required.
+      content:
+        application/problem+json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    Forbidden:
+      description: Forbidden - insufficient permissions.
+      content:
+        application/problem+json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    Conflict:
+      description: Conflict - entity already exists.
+      content:
+        application/problem+json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    NotFound:
+      description: Resource not found.
+      content:
+        application/problem+json:
+          schema:
+            $ref: '#/components/schemas/Error'
diff --git a/tests/e2e/generate-client/examples/baked-setup/.gitignore b/tests/e2e/generate-client/examples/baked-setup/.gitignore
new file mode 100644
index 0000000000..6eb23affb8
--- /dev/null
+++ b/tests/e2e/generate-client/examples/baked-setup/.gitignore
@@ -0,0 +1,4 @@
+node_modules
+dist
+src/api/
+package-lock.json
diff --git a/tests/e2e/generate-client/examples/baked-setup/README.md b/tests/e2e/generate-client/examples/baked-setup/README.md
new file mode 100644
index 0000000000..e137554766
--- /dev/null
+++ b/tests/e2e/generate-client/examples/baked-setup/README.md
@@ -0,0 +1,35 @@
+# baked-setup
+
+Shows the **publisher** story: an SDK that ships request/response defaults _built into_ the generated
+client, so downstream users call operations with no setup of their own (see
+[ADR-0015](../../docs/adr/0015-publisher-setup-bake-in.md)).
+
+- `client-setup.ts` — the publisher's `defineClientSetup({ config, middleware })`, importing the
+  contract from `@redocly/client-generator` (so it resolves and is unit-testable before the client exists).
+- `redocly.yaml` — `setup: ./client-setup.ts` bakes it into `src/api/client.ts` at generation time.
+- `src/main.ts` — a consumer that just calls operations; the defaults are already active.
+
+Because the setup imports its contract from the package (not the not-yet-generated client), it is
+**unit-testable in isolation** — its middleware are plain functions on an inspectable object:
+
+```ts
+import setup from './client-setup.ts';
+
+const ctx = {
+  url: '/orders',
+  method: 'POST',
+  headers: {} as Record<string, string>,
+  operation: { id: 'createOrder', path: '/orders', tags: ['Orders'] },
+};
+setup.middleware![0].onRequest!(ctx as never);
+// ctx.headers['X-Idempotency-Key'] is now set; ctx.headers['X-Cafe-SDK'] === '1.0.0'
+```
+
+The generated client under `src/api/` is gitignored; CI regenerates it and type-checks this example.
+
+## Run
+
+```bash
+npm install
+npm run dev
+```
diff --git a/tests/e2e/generate-client/examples/baked-setup/client-setup.ts b/tests/e2e/generate-client/examples/baked-setup/client-setup.ts
new file mode 100644
index 0000000000..f53e976d94
--- /dev/null
+++ b/tests/e2e/generate-client/examples/baked-setup/client-setup.ts
@@ -0,0 +1,18 @@
+import { defineClientSetup, type RequestContext } from '@redocly/client-generator';
+
+// Defaults every downstream user of this SDK gets for free — baked into the client at publish time
+// by `setup:` in redocly.yaml. Imports the contract from the package (not the generated client),
+// so this file resolves and is unit-testable before the client even exists.
+export default defineClientSetup({
+  config: { serverUrl: 'https://api.cafe.redocly.com', retry: { retries: 2 } },
+  middleware: [
+    {
+      onRequest: (ctx: RequestContext) => {
+        ctx.headers['X-Cafe-SDK'] = '1.0.0';
+        if (ctx.operation.tags.includes('Orders')) {
+          ctx.headers['X-Idempotency-Key'] = crypto.randomUUID();
+        }
+      },
+    },
+  ],
+});
diff --git a/tests/e2e/generate-client/examples/baked-setup/index.html b/tests/e2e/generate-client/examples/baked-setup/index.html
new file mode 100644
index 0000000000..2aafd8e6e1
--- /dev/null
+++ b/tests/e2e/generate-client/examples/baked-setup/index.html
@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>Redocly client-generator — fetch-functions example</title>
+  </head>
+  <body>
+    <pre id="out">Loading…</pre>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
diff --git a/tests/e2e/generate-client/examples/baked-setup/package.json b/tests/e2e/generate-client/examples/baked-setup/package.json
new file mode 100644
index 0000000000..e8b68c2510
--- /dev/null
+++ b/tests/e2e/generate-client/examples/baked-setup/package.json
@@ -0,0 +1,16 @@
+{
+  "name": "@redocly-examples/baked-setup",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "generate": "redocly generate-client",
+    "dev": "vite",
+    "build": "vite build"
+  },
+  "devDependencies": {
+    "@redocly/cli": "latest",
+    "typescript": "^5.5.0",
+    "vite": "^5.4.0"
+  }
+}
diff --git a/tests/e2e/generate-client/examples/baked-setup/redocly.yaml b/tests/e2e/generate-client/examples/baked-setup/redocly.yaml
new file mode 100644
index 0000000000..91dd1bc792
--- /dev/null
+++ b/tests/e2e/generate-client/examples/baked-setup/redocly.yaml
@@ -0,0 +1,11 @@
+# redocly.yaml — drives `redocly generate-client` for this example.
+# The client is generated for the api that declares a `client` block
+# (run `redocly generate-client` with no args to build every such api).
+apis:
+  baked-setup:
+    root: ../_shared/cafe.yaml
+    clientOutput: ./src/api/client.ts
+    client:
+      generators:
+        - sdk
+      setup: ./client-setup.ts
diff --git a/tests/e2e/generate-client/examples/baked-setup/src/main.ts b/tests/e2e/generate-client/examples/baked-setup/src/main.ts
new file mode 100644
index 0000000000..79ff349ea8
--- /dev/null
+++ b/tests/e2e/generate-client/examples/baked-setup/src/main.ts
@@ -0,0 +1,12 @@
+import { listMenuItems } from './api/client.js';
+
+const out = document.querySelector<HTMLPreElement>('#out')!;
+
+// No configure()/use() here — the base URL, retry, and headers were baked into the client at
+// generation time (see ../client-setup.ts). A downstream consumer just calls operations.
+async function main() {
+  const menu = await listMenuItems({});
+  out.textContent = JSON.stringify(menu, null, 2);
+}
+
+void main();
diff --git a/tests/e2e/generate-client/examples/baked-setup/tsconfig.json b/tests/e2e/generate-client/examples/baked-setup/tsconfig.json
new file mode 100644
index 0000000000..72270fb4ed
--- /dev/null
+++ b/tests/e2e/generate-client/examples/baked-setup/tsconfig.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../tsconfig.base.json",
+  "include": ["src", "client-setup.ts"]
+}
diff --git a/tests/e2e/generate-client/examples/baked-setup/vite.config.ts b/tests/e2e/generate-client/examples/baked-setup/vite.config.ts
new file mode 100644
index 0000000000..c049f46e10
--- /dev/null
+++ b/tests/e2e/generate-client/examples/baked-setup/vite.config.ts
@@ -0,0 +1,3 @@
+import { defineConfig } from 'vite';
+
+export default defineConfig({});
diff --git a/tests/e2e/generate-client/examples/configure-and-middleware/.gitignore b/tests/e2e/generate-client/examples/configure-and-middleware/.gitignore
new file mode 100644
index 0000000000..6eb23affb8
--- /dev/null
+++ b/tests/e2e/generate-client/examples/configure-and-middleware/.gitignore
@@ -0,0 +1,4 @@
+node_modules
+dist
+src/api/
+package-lock.json
diff --git a/tests/e2e/generate-client/examples/configure-and-middleware/README.md b/tests/e2e/generate-client/examples/configure-and-middleware/README.md
new file mode 100644
index 0000000000..62b744d93e
--- /dev/null
+++ b/tests/e2e/generate-client/examples/configure-and-middleware/README.md
@@ -0,0 +1,26 @@
+# configure-and-middleware example
+
+Customizing the client **without editing the generated file** — every mechanism composes
+from the hand-written `src/main.ts`, so it survives regeneration
+(see [ADR-0014](../../../../packages/client-generator/docs/adr/0014-request-response-customization.md)):
+
+- `configure({ serverUrl, retry, fetch })` — an exponential, `Retry-After`-aware retry
+  policy and a custom transport (here a canned `fetch`, so the demo runs offline).
+- `use()` middleware targeting `ctx.operation.id` / `ctx.operation.tags` (typed literal
+  unions — typos fail the build), mutating the request body (`ctx.body` edits are sent),
+  and observing each attempt's raw `Response`.
+- The generated `setApiKey()` auth setter.
+- A per-call header via the trailing `RequestOptions` argument.
+- `ApiError` handling with the spec's problem document on `error.body`.
+
+## Run
+
+```bash
+npm install
+npm run generate   # generate src/api (the client is gitignored)
+npm run dev        # open the printed local URL
+```
+
+The app uses a canned `fetch` so it runs offline and the retry is deterministic: the first
+`GET /payments` attempt returns 503 and the policy resends it. The generated client under
+`src/api/` is gitignored; CI regenerates it and type-checks this example.
diff --git a/tests/e2e/generate-client/examples/configure-and-middleware/index.html b/tests/e2e/generate-client/examples/configure-and-middleware/index.html
new file mode 100644
index 0000000000..1bdd570742
--- /dev/null
+++ b/tests/e2e/generate-client/examples/configure-and-middleware/index.html
@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>Redocly client-generator — configure-and-middleware example</title>
+  </head>
+  <body>
+    <pre id="out">Loading…</pre>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
diff --git a/tests/e2e/generate-client/examples/configure-and-middleware/openapi.yaml b/tests/e2e/generate-client/examples/configure-and-middleware/openapi.yaml
new file mode 100644
index 0000000000..3b4f9e163a
--- /dev/null
+++ b/tests/e2e/generate-client/examples/configure-and-middleware/openapi.yaml
@@ -0,0 +1,169 @@
+openapi: 3.2.0
+info:
+  title: Payments API
+  description: Demo payments API for the configure-and-middleware example.
+  version: 1.0.0
+servers:
+  - url: https://api.payments.example.com
+tags:
+  - name: Payments
+    description: Payment operations.
+security:
+  - ApiKeyAuth: []
+paths:
+  /payments:
+    get:
+      tags:
+        - Payments
+      summary: List payments
+      operationId: listPayments
+      parameters:
+        - name: status
+          in: query
+          required: false
+          description: Filter by payment status.
+          schema:
+            $ref: '#/components/schemas/PaymentStatus'
+      responses:
+        '200':
+          description: Successful operation.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PaymentList'
+        '503':
+          description: Temporarily unavailable — retry later.
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/ProblemDetails'
+    post:
+      tags:
+        - Payments
+      summary: Create a payment
+      operationId: createPayment
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/PaymentRequest'
+      responses:
+        '201':
+          description: Payment created.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Payment'
+        '402':
+          description: Payment declined.
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/ProblemDetails'
+  /payments/{paymentId}:
+    get:
+      tags:
+        - Payments
+      summary: Retrieve a payment
+      operationId: getPayment
+      parameters:
+        - name: paymentId
+          in: path
+          required: true
+          description: ID of the payment.
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Successful operation.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Payment'
+        '404':
+          description: Payment not found.
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/ProblemDetails'
+components:
+  securitySchemes:
+    ApiKeyAuth:
+      type: apiKey
+      in: header
+      name: X-Api-Key
+      description: API key for server-to-server access.
+  schemas:
+    PaymentStatus:
+      type: string
+      description: Payment status.
+      enum:
+        - pending
+        - settled
+        - failed
+    Payment:
+      type: object
+      properties:
+        id:
+          description: Payment ID.
+          type: string
+        amount:
+          description: Amount in cents.
+          type: integer
+          minimum: 0
+        currency:
+          description: ISO 4217 currency code.
+          type: string
+        status:
+          $ref: '#/components/schemas/PaymentStatus'
+      required:
+        - id
+        - amount
+        - currency
+        - status
+    PaymentRequest:
+      type: object
+      properties:
+        amount:
+          description: Amount in cents.
+          type: integer
+          minimum: 1
+        currency:
+          description: ISO 4217 currency code.
+          type: string
+        reference:
+          description: Free-form merchant reference.
+          type: string
+      required:
+        - amount
+        - currency
+    PaymentList:
+      type: object
+      properties:
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/Payment'
+      required:
+        - items
+    ProblemDetails:
+      type: object
+      description: RFC 9457 problem document.
+      properties:
+        type:
+          description: URI reference that identifies the problem type.
+          type: string
+          default: about:blank
+        title:
+          description: Short summary of the problem type.
+          type: string
+        status:
+          description: HTTP status code.
+          type: integer
+        detail:
+          description: Occurrence-specific explanation.
+          type: string
+      required:
+        - title
+        - status
diff --git a/tests/e2e/generate-client/examples/configure-and-middleware/package.json b/tests/e2e/generate-client/examples/configure-and-middleware/package.json
new file mode 100644
index 0000000000..87ffbcff76
--- /dev/null
+++ b/tests/e2e/generate-client/examples/configure-and-middleware/package.json
@@ -0,0 +1,16 @@
+{
+  "name": "@redocly-examples/configure-and-middleware",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "generate": "redocly generate-client",
+    "dev": "vite",
+    "build": "vite build"
+  },
+  "devDependencies": {
+    "@redocly/cli": "latest",
+    "typescript": "^5.5.0",
+    "vite": "^5.4.0"
+  }
+}
diff --git a/tests/e2e/generate-client/examples/configure-and-middleware/redocly.yaml b/tests/e2e/generate-client/examples/configure-and-middleware/redocly.yaml
new file mode 100644
index 0000000000..e8e7e00d44
--- /dev/null
+++ b/tests/e2e/generate-client/examples/configure-and-middleware/redocly.yaml
@@ -0,0 +1,8 @@
+# redocly.yaml — drives `redocly generate-client` for this example.
+apis:
+  configure-and-middleware:
+    root: ./openapi.yaml
+    clientOutput: ./src/api/client.ts
+    client:
+      generators:
+        - sdk
diff --git a/tests/e2e/generate-client/examples/configure-and-middleware/src/main.ts b/tests/e2e/generate-client/examples/configure-and-middleware/src/main.ts
new file mode 100644
index 0000000000..b33ca4d3fa
--- /dev/null
+++ b/tests/e2e/generate-client/examples/configure-and-middleware/src/main.ts
@@ -0,0 +1,106 @@
+// configure-and-middleware — the client's DX knobs in one place.
+//
+// * `configure()`: server URL + a retry policy (idempotent methods only by default;
+//   `Retry-After` honored; per-call override via `init.retry`).
+// * `use()`: middleware that targets `ctx.operation.id` — a LITERAL UNION of this
+//   spec's operation ids, so a typo fails the build instead of silently never matching.
+// * `setApiKey()`: per-scheme auth sugar; injected only on operations whose
+//   `security` names the scheme.
+// * `ApiError`: a non-2xx response throws, carrying the decoded problem document
+//   on `error.body`.
+import {
+  ApiError,
+  configure,
+  createPayment,
+  getPayment,
+  listPayments,
+  setApiKey,
+  use,
+  type ProblemDetails,
+} from './api/client.js';
+
+const out = document.querySelector<HTMLPreElement>('#out')!;
+const log: string[] = [];
+
+// A canned transport so the example runs offline — and fails deterministically:
+// the FIRST `GET /payments` attempt returns 503 with `Retry-After: 0`, so the
+// configured retry policy resends it; an unknown payment id returns a 404 problem.
+let listAttempts = 0;
+const canned = (async (url: string, init: RequestInit) => {
+  const { pathname } = new URL(url);
+  const problem = (status: number, title: string, detail: string) =>
+    new Response(JSON.stringify({ type: 'about:blank', title, status, detail }), {
+      status,
+      headers: { 'content-type': 'application/problem+json', 'retry-after': '0' },
+    });
+  if (init.method === 'GET' && pathname === '/payments') {
+    if (++listAttempts === 1) return problem(503, 'Service Unavailable', 'Warming up — retry.');
+    return new Response(
+      JSON.stringify({
+        items: [{ id: 'pay_1', amount: 1250, currency: 'EUR', status: 'settled' }],
+      }),
+      { headers: { 'content-type': 'application/json' } }
+    );
+  }
+  if (init.method === 'POST' && pathname === '/payments') {
+    return new Response(
+      JSON.stringify({ id: 'pay_2', status: 'pending', ...JSON.parse(String(init.body)) }),
+      { status: 201, headers: { 'content-type': 'application/json' } }
+    );
+  }
+  return problem(404, 'Payment not found', `No payment at ${pathname}.`);
+}) as unknown as typeof fetch;
+
+configure({
+  serverUrl: 'https://api.payments.example.com',
+  fetch: canned,
+  // Retries apply to idempotent methods on transport errors and transient statuses
+  // (408/429/5xx); `Retry-After` wins over the backoff when the server sends it.
+  retry: { retries: 2, retryDelay: 100, retryStrategy: 'exponential' },
+});
+
+// Auth sugar generated from the spec's `ApiKeyAuth` scheme: every operation whose
+// `security` requires it gets an `X-Api-Key` header — nothing to wire by hand.
+setApiKey('demo-key-123');
+
+use({
+  onRequest: (ctx) => {
+    // `ctx.operation.id` / `ctx.operation.tags` are typed literal unions —
+    // misspell 'createPayment' or 'Payments' and the comparison fails to compile.
+    if (ctx.operation.id === 'createPayment') {
+      ctx.headers['Idempotency-Key'] = crypto.randomUUID();
+      // Request-body mutation: edits to `ctx.body` are serialized and sent —
+      // the canned POST echoes the body back, so the `web:` prefix shows below.
+      const body = ctx.body as { reference: string };
+      body.reference = `web:${body.reference}`;
+    }
+    if (ctx.operation.tags.includes('Payments')) {
+      ctx.headers['X-Trace-Id'] = 'demo-trace';
+    }
+    log.push(`→ ${ctx.operation.id} ${ctx.method} ${ctx.operation.path}`);
+  },
+  // `onResponse` runs per ATTEMPT — watch the 503 and the retried 200 both arrive.
+  // (It can also replace the Response before parsing; here it only observes.)
+  onResponse: (response, ctx) => {
+    log.push(`← ${ctx.operation.id} ${response.status}`);
+  },
+});
+
+async function main() {
+  // A header for this one call only goes in the trailing RequestOptions argument.
+  const payments = await listPayments({}, { headers: { 'X-Request-Id': '42' } }); // 503 first, then retried to 200
+  const payment = await createPayment({ amount: 4200, currency: 'EUR', reference: 'INV-17' });
+  try {
+    await getPayment('pay_missing');
+  } catch (error) {
+    if (error instanceof ApiError) {
+      // `error.body` is the decoded response body; per the spec's 4xx contract
+      // it is a problem document, so narrow it to the generated type.
+      const problem = error.body as ProblemDetails;
+      log.push(`✗ getPayment ${error.status}: ${problem.title} — ${problem.detail}`);
+    }
+  }
+  out.textContent = [...log, '', JSON.stringify({ payments, payment }, null, 2)].join('\n');
+}
+
+void main();
diff --git a/tests/e2e/generate-client/examples/configure-and-middleware/tsconfig.json b/tests/e2e/generate-client/examples/configure-and-middleware/tsconfig.json
new file mode 100644
index 0000000000..4bd6962d40
--- /dev/null
+++ b/tests/e2e/generate-client/examples/configure-and-middleware/tsconfig.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../tsconfig.base.json",
+  "include": ["src"]
+}
diff --git a/tests/e2e/generate-client/examples/configure-and-middleware/vite.config.ts b/tests/e2e/generate-client/examples/configure-and-middleware/vite.config.ts
new file mode 100644
index 0000000000..c049f46e10
--- /dev/null
+++ b/tests/e2e/generate-client/examples/configure-and-middleware/vite.config.ts
@@ -0,0 +1,3 @@
+import { defineConfig } from 'vite';
+
+export default defineConfig({});
diff --git a/tests/e2e/generate-client/examples/custom-generator/.gitignore b/tests/e2e/generate-client/examples/custom-generator/.gitignore
new file mode 100644
index 0000000000..6eb23affb8
--- /dev/null
+++ b/tests/e2e/generate-client/examples/custom-generator/.gitignore
@@ -0,0 +1,4 @@
+node_modules
+dist
+src/api/
+package-lock.json
diff --git a/tests/e2e/generate-client/examples/custom-generator/README.md b/tests/e2e/generate-client/examples/custom-generator/README.md
new file mode 100644
index 0000000000..a1dc61dcfb
--- /dev/null
+++ b/tests/e2e/generate-client/examples/custom-generator/README.md
@@ -0,0 +1,14 @@
+# Custom generator (plugin) example
+
+Shows the **experimental** custom-generator API: a `generators` entry that is a path to a local
+generator runs alongside the built-in `sdk`, reading the same OpenAPI-derived IR.
+
+- [`route-map-generator.mjs`](./route-map-generator.mjs) — the custom generator. Walks the IR's
+  operations and emits `src/api/client.routes.ts`: `<operationId>: 'METHOD /path'`.
+- [`redocly.yaml`](./redocly.yaml) — `generators: [sdk, ./route-map-generator.mjs]`.
+- [`src/main.ts`](./src/main.ts) — imports both the client and the generated `routes` map.
+
+Regenerate from the repo root with `npm run examples:regen -w @redocly/client-generator`; type-check
+with `npm run typecheck:examples -w @redocly/client-generator`. See the "Custom generators" section
+of the command reference for the
+authoring contract and the `@redocly/client-generator` toolkit.
diff --git a/tests/e2e/generate-client/examples/custom-generator/index.html b/tests/e2e/generate-client/examples/custom-generator/index.html
new file mode 100644
index 0000000000..8c0c18b5ec
--- /dev/null
+++ b/tests/e2e/generate-client/examples/custom-generator/index.html
@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>Redocly client-generator — zod example</title>
+  </head>
+  <body>
+    <pre id="out">Loading…</pre>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
diff --git a/tests/e2e/generate-client/examples/custom-generator/package.json b/tests/e2e/generate-client/examples/custom-generator/package.json
new file mode 100644
index 0000000000..6bc561044a
--- /dev/null
+++ b/tests/e2e/generate-client/examples/custom-generator/package.json
@@ -0,0 +1,16 @@
+{
+  "name": "@redocly-examples/custom-generator",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "generate": "redocly generate-client",
+    "dev": "vite",
+    "build": "vite build"
+  },
+  "devDependencies": {
+    "@redocly/cli": "latest",
+    "typescript": "^5.5.0",
+    "vite": "^5.4.0"
+  }
+}
diff --git a/tests/e2e/generate-client/examples/custom-generator/redocly.yaml b/tests/e2e/generate-client/examples/custom-generator/redocly.yaml
new file mode 100644
index 0000000000..84da4e37a8
--- /dev/null
+++ b/tests/e2e/generate-client/examples/custom-generator/redocly.yaml
@@ -0,0 +1,11 @@
+# redocly.yaml — drives `redocly generate-client` for this example.
+# The client is generated for the api that declares a `client` block
+# (run `redocly generate-client` with no args to build every such api).
+apis:
+  custom-generator:
+    root: ../_shared/cafe.yaml
+    clientOutput: ./src/api/client.ts
+    client:
+      generators:
+        - sdk
+        - ./route-map-generator.mjs
diff --git a/tests/e2e/generate-client/examples/custom-generator/route-map-generator.mjs b/tests/e2e/generate-client/examples/custom-generator/route-map-generator.mjs
new file mode 100644
index 0000000000..c6b589e6d8
--- /dev/null
+++ b/tests/e2e/generate-client/examples/custom-generator/route-map-generator.mjs
@@ -0,0 +1,28 @@
+// A custom generator (the experimental plugin API). Loaded by the `generators:` list in
+// redocly.yaml as a path specifier, it runs alongside the built-in `sdk` and emits a
+// `<output>.routes.ts` map of every operation — `<operationId>: 'METHOD /path'`.
+//
+// Plain ESM so the CLI imports it under bare `node`. Authored in TypeScript you would write:
+//
+//   import { defineGenerator } from '@redocly/client-generator';
+//   export default defineGenerator({ name: 'route-map', requires: ['sdk'], run({ model, outputPath }) { … } });
+//
+// `defineGenerator` is just an identity helper for types, so a plain object works too:
+export default {
+  name: 'route-map',
+  requires: ['sdk'],
+  run({ model, outputPath }) {
+    const routes = model.services
+      .flatMap((service) => service.operations)
+      .map((op) => `  ${op.name}: '${op.method.toUpperCase()} ${op.path}',`)
+      .join('\n');
+    return [
+      {
+        path: outputPath.replace(/\.ts$/, '.routes.ts'),
+        content:
+          '// Generated by the route-map custom generator. Do not edit by hand.\n' +
+          `export const routes = {\n${routes}\n} as const;\n`,
+      },
+    ];
+  },
+};
diff --git a/tests/e2e/generate-client/examples/custom-generator/src/main.ts b/tests/e2e/generate-client/examples/custom-generator/src/main.ts
new file mode 100644
index 0000000000..e8e1449f2e
--- /dev/null
+++ b/tests/e2e/generate-client/examples/custom-generator/src/main.ts
@@ -0,0 +1,16 @@
+// Consumes both the built-in sdk client and the custom generator's output (`routes`),
+// proving the plugin's file is generated alongside the client and type-checks.
+import { configure, listMenuItems } from './api/client.js';
+import { routes } from './api/client.routes.js';
+
+configure({ serverUrl: 'https://api.cafe.redocly.com' });
+
+const out = document.querySelector<HTMLPreElement>('#out')!;
+
+async function main() {
+  // The route map the custom generator produced from the same OpenAPI description.
+  const menu = await listMenuItems();
+  out.textContent = `${routes.listMenuItems}\n${JSON.stringify(menu, null, 2)}`;
+}
+
+void main();
diff --git a/tests/e2e/generate-client/examples/custom-generator/tsconfig.json b/tests/e2e/generate-client/examples/custom-generator/tsconfig.json
new file mode 100644
index 0000000000..4bd6962d40
--- /dev/null
+++ b/tests/e2e/generate-client/examples/custom-generator/tsconfig.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../tsconfig.base.json",
+  "include": ["src"]
+}
diff --git a/tests/e2e/generate-client/examples/custom-generator/vite.config.ts b/tests/e2e/generate-client/examples/custom-generator/vite.config.ts
new file mode 100644
index 0000000000..c049f46e10
--- /dev/null
+++ b/tests/e2e/generate-client/examples/custom-generator/vite.config.ts
@@ -0,0 +1,3 @@
+import { defineConfig } from 'vite';
+
+export default defineConfig({});
diff --git a/tests/e2e/generate-client/examples/custom-pagination/.gitignore b/tests/e2e/generate-client/examples/custom-pagination/.gitignore
new file mode 100644
index 0000000000..612acc5cae
--- /dev/null
+++ b/tests/e2e/generate-client/examples/custom-pagination/.gitignore
@@ -0,0 +1,3 @@
+node_modules
+src/api/
+package-lock.json
diff --git a/tests/e2e/generate-client/examples/custom-pagination/README.md b/tests/e2e/generate-client/examples/custom-pagination/README.md
new file mode 100644
index 0000000000..47f10b8e8a
--- /dev/null
+++ b/tests/e2e/generate-client/examples/custom-pagination/README.md
@@ -0,0 +1,18 @@
+# custom-pagination
+
+Hand-written paging over the generated client, for shapes the built-in
+[`client.pagination` styles](../../../../../docs/@v2/configuration/reference/client.md)
+don't cover — here a cursor that travels in the **request body**. There is deliberately
+no `client.pagination` block: the generated `searchOrders` call is fully typed, so a
+five-line `paginate` helper is all it takes (see `src/main.ts`).
+
+For APIs the declared styles fit, prefer the native `.pages()`/`.items()` iterators —
+see the sibling [`pagination`](../pagination) example.
+
+## Run
+
+```bash
+npm install
+npm run generate
+npm start
+```
diff --git a/tests/e2e/generate-client/examples/custom-pagination/openapi.yaml b/tests/e2e/generate-client/examples/custom-pagination/openapi.yaml
new file mode 100644
index 0000000000..dab7639f6b
--- /dev/null
+++ b/tests/e2e/generate-client/examples/custom-pagination/openapi.yaml
@@ -0,0 +1,59 @@
+openapi: 3.1.0
+info:
+  title: Cafe Orders Search API
+  description: A body-cursor search API for the hand-written pagination example.
+  version: 1.0.0
+servers:
+  - url: https://api.cafe-orders.example.com
+paths:
+  /orders/search:
+    post:
+      operationId: searchOrders
+      summary: Search orders; the page cursor travels in the request BODY
+      description: >-
+        Body-cursor pagination — a shape the built-in styles do not cover (they only
+        advance query parameters), so the example pages through it with a small
+        hand-written helper over the generated typed call.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                status:
+                  type: string
+                cursor:
+                  description: Opaque cursor of the page to fetch; omit for the first page.
+                  type: string
+                limit:
+                  type: integer
+      responses:
+        '200':
+          description: One page of matching orders.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [items]
+                properties:
+                  items:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Order'
+                  nextCursor:
+                    description: Cursor of the next page; absent on the last page.
+                    type: string
+components:
+  schemas:
+    Order:
+      type: object
+      required: [id, drink, status]
+      properties:
+        id:
+          type: string
+        drink:
+          type: string
+        status:
+          type: string
+          enum: [pending, ready, delivered]
diff --git a/tests/e2e/generate-client/examples/custom-pagination/package.json b/tests/e2e/generate-client/examples/custom-pagination/package.json
new file mode 100644
index 0000000000..8129e28db8
--- /dev/null
+++ b/tests/e2e/generate-client/examples/custom-pagination/package.json
@@ -0,0 +1,15 @@
+{
+  "name": "@redocly-examples/custom-pagination",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "generate": "redocly generate-client",
+    "start": "tsx src/main.ts"
+  },
+  "devDependencies": {
+    "@redocly/cli": "latest",
+    "tsx": "^4.0.0",
+    "typescript": "^5.5.0"
+  }
+}
diff --git a/tests/e2e/generate-client/examples/custom-pagination/redocly.yaml b/tests/e2e/generate-client/examples/custom-pagination/redocly.yaml
new file mode 100644
index 0000000000..f78904a9c5
--- /dev/null
+++ b/tests/e2e/generate-client/examples/custom-pagination/redocly.yaml
@@ -0,0 +1,13 @@
+# redocly.yaml — drives `redocly generate-client` for this example.
+#
+# Deliberately NO `client.pagination` block: this API's cursor travels in the request
+# BODY, a shape the built-in styles don't cover (they only advance query parameters).
+# The example pages through it with a small hand-written helper instead — see
+# src/main.ts. The sibling `pagination` example shows the native declared styles.
+apis:
+  custom-pagination:
+    root: ./openapi.yaml
+    clientOutput: ./src/api/client.ts
+    client:
+      generators:
+        - sdk
diff --git a/tests/e2e/generate-client/examples/custom-pagination/src/main.ts b/tests/e2e/generate-client/examples/custom-pagination/src/main.ts
new file mode 100644
index 0000000000..3917c324c6
--- /dev/null
+++ b/tests/e2e/generate-client/examples/custom-pagination/src/main.ts
@@ -0,0 +1,43 @@
+// custom-pagination — hand-written paging over the generated typed client.
+//
+// This API's cursor travels in the request BODY, which the built-in pagination styles
+// don't cover (they only advance query parameters) — so there is no `client.pagination`
+// block here and `searchOrders` has no `.pages()`/`.items()`. The escape hatch is a few
+// lines: the generated call is already fully typed, so the helper (and everything it
+// yields) is too. For APIs the declared styles DO fit, prefer the native iterators —
+// see the sibling `pagination` example.
+import { configure, searchOrders } from './api/client.js';
+
+// A canned transport so the example runs offline: two pages keyed by the BODY cursor.
+const SEARCH_PAGES: Record<string, unknown> = {
+  '': {
+    items: [{ id: 'ord-101', drink: 'espresso', status: 'ready' }],
+    nextCursor: 's2',
+  },
+  s2: {
+    items: [{ id: 'ord-104', drink: 'flat white', status: 'ready' }],
+  },
+};
+const canned = (async (_url: string, init?: RequestInit) => {
+  const { cursor } = JSON.parse(String(init?.body)) as { cursor?: string };
+  return new Response(JSON.stringify(SEARCH_PAGES[cursor ?? '']), {
+    headers: { 'content-type': 'application/json' },
+  });
+}) as unknown as typeof fetch;
+
+configure({ fetch: canned });
+
+// The whole helper: call a page, yield its items, follow the cursor until it stops.
+async function* paginate<Item>(
+  page: (cursor?: string) => Promise<{ items?: Item[]; nextCursor?: string }>
+): AsyncGenerator<Item> {
+  for (let cursor: string | undefined; ; ) {
+    const { items, nextCursor } = await page(cursor);
+    yield* items ?? [];
+    if (!(cursor = nextCursor)) return;
+  }
+}
+
+for await (const order of paginate((cursor) => searchOrders({ status: 'ready', cursor }))) {
+  console.log(`search hit ${order.id}: ${order.drink}`); // `order` is `Order` — typed end to end
+}
diff --git a/tests/e2e/generate-client/examples/custom-pagination/tsconfig.json b/tests/e2e/generate-client/examples/custom-pagination/tsconfig.json
new file mode 100644
index 0000000000..4bd6962d40
--- /dev/null
+++ b/tests/e2e/generate-client/examples/custom-pagination/tsconfig.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../tsconfig.base.json",
+  "include": ["src"]
+}
diff --git a/tests/e2e/generate-client/examples/fetch-functions/.gitignore b/tests/e2e/generate-client/examples/fetch-functions/.gitignore
new file mode 100644
index 0000000000..6eb23affb8
--- /dev/null
+++ b/tests/e2e/generate-client/examples/fetch-functions/.gitignore
@@ -0,0 +1,4 @@
+node_modules
+dist
+src/api/
+package-lock.json
diff --git a/tests/e2e/generate-client/examples/fetch-functions/README.md b/tests/e2e/generate-client/examples/fetch-functions/README.md
new file mode 100644
index 0000000000..e90c7e2b89
--- /dev/null
+++ b/tests/e2e/generate-client/examples/fetch-functions/README.md
@@ -0,0 +1,15 @@
+# fetch-functions example
+
+Generated TypeScript client (`generators: ['sdk']`), consumed as free
+functions (`configure()`, `listMenuItems()`), with `ApiError` handling.
+
+## Run
+
+```bash
+npm install
+npm run generate   # generate src/api (the client is gitignored)
+npm run dev        # open the printed local URL
+```
+
+The generated client under `src/api/` is gitignored; CI regenerates it and type-checks this example.
+Point `configure({ serverUrl })` at your own server or a mock as needed.
diff --git a/tests/e2e/generate-client/examples/fetch-functions/index.html b/tests/e2e/generate-client/examples/fetch-functions/index.html
new file mode 100644
index 0000000000..2aafd8e6e1
--- /dev/null
+++ b/tests/e2e/generate-client/examples/fetch-functions/index.html
@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>Redocly client-generator — fetch-functions example</title>
+  </head>
+  <body>
+    <pre id="out">Loading…</pre>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
diff --git a/tests/e2e/generate-client/examples/fetch-functions/package.json b/tests/e2e/generate-client/examples/fetch-functions/package.json
new file mode 100644
index 0000000000..d2088413bb
--- /dev/null
+++ b/tests/e2e/generate-client/examples/fetch-functions/package.json
@@ -0,0 +1,16 @@
+{
+  "name": "@redocly-examples/fetch-functions",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "generate": "redocly generate-client",
+    "dev": "vite",
+    "build": "vite build"
+  },
+  "devDependencies": {
+    "@redocly/cli": "latest",
+    "typescript": "^5.5.0",
+    "vite": "^5.4.0"
+  }
+}
diff --git a/tests/e2e/generate-client/examples/fetch-functions/redocly.yaml b/tests/e2e/generate-client/examples/fetch-functions/redocly.yaml
new file mode 100644
index 0000000000..0e7e6b995e
--- /dev/null
+++ b/tests/e2e/generate-client/examples/fetch-functions/redocly.yaml
@@ -0,0 +1,10 @@
+# redocly.yaml — drives `redocly generate-client` for this example.
+# The client is generated for the api that declares a `client` block
+# (run `redocly generate-client` with no args to build every such api).
+apis:
+  fetch-functions:
+    root: ../_shared/cafe.yaml
+    clientOutput: ./src/api/client.ts
+    client:
+      generators:
+        - sdk
diff --git a/tests/e2e/generate-client/examples/fetch-functions/src/main.ts b/tests/e2e/generate-client/examples/fetch-functions/src/main.ts
new file mode 100644
index 0000000000..81dde239e4
--- /dev/null
+++ b/tests/e2e/generate-client/examples/fetch-functions/src/main.ts
@@ -0,0 +1,33 @@
+import { configure, use, listMenuItems, ApiError } from './api/client.js';
+
+configure({ serverUrl: 'https://api.cafe.redocly.com' });
+
+const out = document.querySelector<HTMLPreElement>('#out')!;
+
+// Middleware composes cross-cutting concerns (tracing, auth refresh, logging, …).
+// `onRequest` runs in registration order, `onResponse` in reverse (onion); register as many as you
+// like with `use()`. Here we observe the response.
+//
+// Heads-up: adding a *custom request header* in `onRequest` (e.g. `ctx.headers['X-Request-Id'] = …`)
+// makes the browser send a CORS preflight, so the target API must list that header in its
+// `Access-Control-Allow-Headers`. The public cafe demo allows only Content-Type / Authorization /
+// X-API-Key, so injecting `X-Request-Id` there fails with "Failed to fetch".
+use({
+  onResponse: (response) => {
+    document.title = `cafe — ${response.status}`;
+  },
+});
+
+async function main() {
+  try {
+    const items = await listMenuItems();
+    out.textContent = JSON.stringify(items, null, 2);
+  } catch (error) {
+    out.textContent =
+      error instanceof ApiError
+        ? `ApiError ${error.status}: ${error.statusText}`
+        : `Unexpected error: ${String(error)}`;
+  }
+}
+
+void main();
diff --git a/tests/e2e/generate-client/examples/fetch-functions/tsconfig.json b/tests/e2e/generate-client/examples/fetch-functions/tsconfig.json
new file mode 100644
index 0000000000..4bd6962d40
--- /dev/null
+++ b/tests/e2e/generate-client/examples/fetch-functions/tsconfig.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../tsconfig.base.json",
+  "include": ["src"]
+}
diff --git a/tests/e2e/generate-client/examples/fetch-functions/vite.config.ts b/tests/e2e/generate-client/examples/fetch-functions/vite.config.ts
new file mode 100644
index 0000000000..c049f46e10
--- /dev/null
+++ b/tests/e2e/generate-client/examples/fetch-functions/vite.config.ts
@@ -0,0 +1,3 @@
+import { defineConfig } from 'vite';
+
+export default defineConfig({});
diff --git a/tests/e2e/generate-client/examples/mock/.gitignore b/tests/e2e/generate-client/examples/mock/.gitignore
new file mode 100644
index 0000000000..6eb23affb8
--- /dev/null
+++ b/tests/e2e/generate-client/examples/mock/.gitignore
@@ -0,0 +1,4 @@
+node_modules
+dist
+src/api/
+package-lock.json
diff --git a/tests/e2e/generate-client/examples/mock/README.md b/tests/e2e/generate-client/examples/mock/README.md
new file mode 100644
index 0000000000..5cd9201929
--- /dev/null
+++ b/tests/e2e/generate-client/examples/mock/README.md
@@ -0,0 +1,22 @@
+# mock example
+
+Generated TypeScript client plus **MSW** mocks (`generators: ['sdk', 'mock']`), shown two ways from the
+same generated `src/api/` and the same `handlers`:
+
+- **Browser** (`src/main.ts`) — starts an MSW browser worker with `setupWorker` and renders the result.
+- **Node** (`src/node.ts`) — starts a server with `msw/node`'s `setupServer` and exports `loadMockedMenu()`.
+  Node has no Service Worker, so msw patches global `fetch` directly (no `public/mockServiceWorker.js`).
+
+Either way, requests are served by the mocks — no real backend required.
+
+## Run
+
+```bash
+npm install
+npm run generate   # generate src/api (the client is gitignored)
+npm run dev        # browser: open the printed local URL
+```
+
+For the Node variant, import and call `loadMockedMenu()` from `src/node.ts` in your own entrypoint or test.
+
+The generated client + MSW mocks under `src/api/` are gitignored; CI regenerates them and type-checks this example.
diff --git a/tests/e2e/generate-client/examples/mock/index.html b/tests/e2e/generate-client/examples/mock/index.html
new file mode 100644
index 0000000000..8c0c18b5ec
--- /dev/null
+++ b/tests/e2e/generate-client/examples/mock/index.html
@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>Redocly client-generator — zod example</title>
+  </head>
+  <body>
+    <pre id="out">Loading…</pre>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
diff --git a/tests/e2e/generate-client/examples/mock/package.json b/tests/e2e/generate-client/examples/mock/package.json
new file mode 100644
index 0000000000..2f4d39860e
--- /dev/null
+++ b/tests/e2e/generate-client/examples/mock/package.json
@@ -0,0 +1,22 @@
+{
+  "name": "@redocly-examples/mock",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "generate": "redocly generate-client",
+    "dev": "vite",
+    "build": "vite build"
+  },
+  "devDependencies": {
+    "@redocly/cli": "latest",
+    "msw": "^2.0.0",
+    "typescript": "^5.5.0",
+    "vite": "^5.4.0"
+  },
+  "msw": {
+    "workerDirectory": [
+      "public"
+    ]
+  }
+}
diff --git a/tests/e2e/generate-client/examples/mock/public/mockServiceWorker.js b/tests/e2e/generate-client/examples/mock/public/mockServiceWorker.js
new file mode 100644
index 0000000000..06fe839147
--- /dev/null
+++ b/tests/e2e/generate-client/examples/mock/public/mockServiceWorker.js
@@ -0,0 +1,336 @@
+/* eslint-disable */
+/* tslint:disable */
+
+/**
+ * Mock Service Worker.
+ * @see https://github.com/mswjs/msw
+ * - Please do NOT modify this file.
+ */
+
+const PACKAGE_VERSION = '2.14.6';
+const INTEGRITY_CHECKSUM = '4db4a41e972cec1b64cc569c66952d82';
+const IS_MOCKED_RESPONSE = Symbol('isMockedResponse');
+const activeClientIds = new Set();
+
+addEventListener('install', function () {
+  self.skipWaiting();
+});
+
+addEventListener('activate', function (event) {
+  event.waitUntil(self.clients.claim());
+});
+
+addEventListener('message', async function (event) {
+  const clientId = Reflect.get(event.source || {}, 'id');
+
+  if (!clientId || !self.clients) {
+    return;
+  }
+
+  const client = await self.clients.get(clientId);
+
+  if (!client) {
+    return;
+  }
+
+  const allClients = await self.clients.matchAll({
+    type: 'window',
+  });
+
+  switch (event.data) {
+    case 'KEEPALIVE_REQUEST': {
+      sendToClient(client, {
+        type: 'KEEPALIVE_RESPONSE',
+      });
+      break;
+    }
+
+    case 'INTEGRITY_CHECK_REQUEST': {
+      sendToClient(client, {
+        type: 'INTEGRITY_CHECK_RESPONSE',
+        payload: {
+          packageVersion: PACKAGE_VERSION,
+          checksum: INTEGRITY_CHECKSUM,
+        },
+      });
+      break;
+    }
+
+    case 'MOCK_ACTIVATE': {
+      activeClientIds.add(clientId);
+
+      sendToClient(client, {
+        type: 'MOCKING_ENABLED',
+        payload: {
+          client: {
+            id: client.id,
+            frameType: client.frameType,
+          },
+        },
+      });
+      break;
+    }
+
+    case 'CLIENT_CLOSED': {
+      activeClientIds.delete(clientId);
+
+      const remainingClients = allClients.filter((client) => {
+        return client.id !== clientId;
+      });
+
+      // Unregister itself when there are no more clients
+      if (remainingClients.length === 0) {
+        self.registration.unregister();
+      }
+
+      break;
+    }
+  }
+});
+
+addEventListener('fetch', function (event) {
+  const requestInterceptedAt = Date.now();
+
+  // Bypass navigation requests.
+  if (event.request.mode === 'navigate') {
+    return;
+  }
+
+  // Opening the DevTools triggers the "only-if-cached" request
+  // that cannot be handled by the worker. Bypass such requests.
+  if (event.request.cache === 'only-if-cached' && event.request.mode !== 'same-origin') {
+    return;
+  }
+
+  // Bypass all requests when there are no active clients.
+  // Prevents the self-unregistered worked from handling requests
+  // after it's been terminated (still remains active until the next reload).
+  if (activeClientIds.size === 0) {
+    return;
+  }
+
+  const requestId = crypto.randomUUID();
+  event.respondWith(handleRequest(event, requestId, requestInterceptedAt));
+});
+
+/**
+ * @param {FetchEvent} event
+ * @param {string} requestId
+ * @param {number} requestInterceptedAt
+ */
+async function handleRequest(event, requestId, requestInterceptedAt) {
+  const client = await resolveMainClient(event);
+  const requestCloneForEvents = event.request.clone();
+  const response = await getResponse(event, client, requestId, requestInterceptedAt);
+
+  // Send back the response clone for the "response:*" life-cycle events.
+  // Ensure MSW is active and ready to handle the message, otherwise
+  // this message will pend indefinitely.
+  if (client && activeClientIds.has(client.id)) {
+    const serializedRequest = await serializeRequest(requestCloneForEvents);
+
+    // Clone the response so both the client and the library could consume it.
+    const responseClone = response.clone();
+
+    sendToClient(
+      client,
+      {
+        type: 'RESPONSE',
+        payload: {
+          isMockedResponse: IS_MOCKED_RESPONSE in response,
+          request: {
+            id: requestId,
+            ...serializedRequest,
+          },
+          response: {
+            type: responseClone.type,
+            status: responseClone.status,
+            statusText: responseClone.statusText,
+            headers: Object.fromEntries(responseClone.headers.entries()),
+            body: responseClone.body,
+          },
+        },
+      },
+      responseClone.body ? [serializedRequest.body, responseClone.body] : []
+    );
+  }
+
+  return response;
+}
+
+/**
+ * Resolve the main client for the given event.
+ * Client that issues a request doesn't necessarily equal the client
+ * that registered the worker. It's with the latter the worker should
+ * communicate with during the response resolving phase.
+ * @param {FetchEvent} event
+ * @returns {Promise<Client | undefined>}
+ */
+async function resolveMainClient(event) {
+  const client = await self.clients.get(event.clientId);
+
+  if (activeClientIds.has(event.clientId)) {
+    return client;
+  }
+
+  if (client?.frameType === 'top-level') {
+    return client;
+  }
+
+  const allClients = await self.clients.matchAll({
+    type: 'window',
+  });
+
+  return allClients
+    .filter((client) => {
+      // Get only those clients that are currently visible.
+      return client.visibilityState === 'visible';
+    })
+    .find((client) => {
+      // Find the client ID that's recorded in the
+      // set of clients that have registered the worker.
+      return activeClientIds.has(client.id);
+    });
+}
+
+/**
+ * @param {FetchEvent} event
+ * @param {Client | undefined} client
+ * @param {string} requestId
+ * @param {number} requestInterceptedAt
+ * @returns {Promise<Response>}
+ */
+async function getResponse(event, client, requestId, requestInterceptedAt) {
+  // Clone the request because it might've been already used
+  // (i.e. its body has been read and sent to the client).
+  const requestClone = event.request.clone();
+
+  function passthrough() {
+    // Cast the request headers to a new Headers instance
+    // so the headers can be manipulated with.
+    const headers = new Headers(requestClone.headers);
+
+    // Remove the "accept" header value that marked this request as passthrough.
+    // This prevents request alteration and also keeps it compliant with the
+    // user-defined CORS policies.
+    const acceptHeader = headers.get('accept');
+    if (acceptHeader) {
+      const values = acceptHeader.split(',').map((value) => value.trim());
+      const filteredValues = values.filter((value) => value !== 'msw/passthrough');
+
+      if (filteredValues.length > 0) {
+        headers.set('accept', filteredValues.join(', '));
+      } else {
+        headers.delete('accept');
+      }
+    }
+
+    return fetch(requestClone, { headers });
+  }
+
+  // Bypass mocking when the client is not active.
+  if (!client) {
+    return passthrough();
+  }
+
+  // Bypass initial page load requests (i.e. static assets).
+  // The absence of the immediate/parent client in the map of the active clients
+  // means that MSW hasn't dispatched the "MOCK_ACTIVATE" event yet
+  // and is not ready to handle requests.
+  if (!activeClientIds.has(client.id)) {
+    return passthrough();
+  }
+
+  // Notify the client that a request has been intercepted.
+  const serializedRequest = await serializeRequest(event.request);
+  const clientMessage = await sendToClient(
+    client,
+    {
+      type: 'REQUEST',
+      payload: {
+        id: requestId,
+        interceptedAt: requestInterceptedAt,
+        ...serializedRequest,
+      },
+    },
+    [serializedRequest.body]
+  );
+
+  switch (clientMessage.type) {
+    case 'MOCK_RESPONSE': {
+      return respondWithMock(clientMessage.data);
+    }
+
+    case 'PASSTHROUGH': {
+      return passthrough();
+    }
+  }
+
+  return passthrough();
+}
+
+/**
+ * @param {Client} client
+ * @param {any} message
+ * @param {Array<Transferable>} transferrables
+ * @returns {Promise<any>}
+ */
+function sendToClient(client, message, transferrables = []) {
+  return new Promise((resolve, reject) => {
+    const channel = new MessageChannel();
+
+    channel.port1.onmessage = (event) => {
+      if (event.data && event.data.error) {
+        return reject(event.data.error);
+      }
+
+      resolve(event.data);
+    };
+
+    client.postMessage(message, [channel.port2, ...transferrables.filter(Boolean)]);
+  });
+}
+
+/**
+ * @param {Response} response
+ * @returns {Response}
+ */
+function respondWithMock(response) {
+  // Setting response status code to 0 is a no-op.
+  // However, when responding with a "Response.error()", the produced Response
+  // instance will have status code set to 0. Since it's not possible to create
+  // a Response instance with status code 0, handle that use-case separately.
+  if (response.status === 0) {
+    return Response.error();
+  }
+
+  const mockedResponse = new Response(response.body, response);
+
+  Reflect.defineProperty(mockedResponse, IS_MOCKED_RESPONSE, {
+    value: true,
+    enumerable: true,
+  });
+
+  return mockedResponse;
+}
+
+/**
+ * @param {Request} request
+ */
+async function serializeRequest(request) {
+  return {
+    url: request.url,
+    mode: request.mode,
+    method: request.method,
+    headers: Object.fromEntries(request.headers.entries()),
+    cache: request.cache,
+    credentials: request.credentials,
+    destination: request.destination,
+    integrity: request.integrity,
+    redirect: request.redirect,
+    referrer: request.referrer,
+    referrerPolicy: request.referrerPolicy,
+    body: await request.arrayBuffer(),
+    keepalive: request.keepalive,
+  };
+}
diff --git a/tests/e2e/generate-client/examples/mock/redocly.yaml b/tests/e2e/generate-client/examples/mock/redocly.yaml
new file mode 100644
index 0000000000..8a37c931fa
--- /dev/null
+++ b/tests/e2e/generate-client/examples/mock/redocly.yaml
@@ -0,0 +1,11 @@
+# redocly.yaml — drives `redocly generate-client` for this example.
+# The client is generated for the api that declares a `client` block
+# (run `redocly generate-client` with no args to build every such api).
+apis:
+  mock:
+    root: ../_shared/cafe.yaml
+    clientOutput: ./src/api/client.ts
+    client:
+      generators:
+        - sdk
+        - mock
diff --git a/tests/e2e/generate-client/examples/mock/src/main.ts b/tests/e2e/generate-client/examples/mock/src/main.ts
new file mode 100644
index 0000000000..9928640947
--- /dev/null
+++ b/tests/e2e/generate-client/examples/mock/src/main.ts
@@ -0,0 +1,24 @@
+import { setupWorker } from 'msw/browser';
+
+import { configure, listMenuItems, ApiError } from './api/client.js';
+import { handlers } from './api/client.mocks.js';
+
+const out = document.querySelector<HTMLPreElement>('#out')!;
+
+async function main() {
+  try {
+    await setupWorker(...handlers).start();
+    configure({ serverUrl: 'https://api.cafe.redocly.com' });
+    const response = await listMenuItems();
+    out.textContent = `Mocked ${response.items.length} items:\n${JSON.stringify(
+      response,
+      null,
+      2
+    )}`;
+  } catch (error) {
+    out.textContent =
+      error instanceof ApiError ? `ApiError ${error.status}` : `Error: ${String(error)}`;
+  }
+}
+
+void main();
diff --git a/tests/e2e/generate-client/examples/mock/src/node.ts b/tests/e2e/generate-client/examples/mock/src/node.ts
new file mode 100644
index 0000000000..8567681783
--- /dev/null
+++ b/tests/e2e/generate-client/examples/mock/src/node.ts
@@ -0,0 +1,20 @@
+// Node counterpart to `main.ts`: the same generated `sdk` + `mock` client and the same
+// `handlers`, but driven by msw/node's `setupServer`. Node has no Service Worker, so msw
+// patches global `fetch` directly instead of registering `public/mockServiceWorker.js`.
+import { setupServer } from 'msw/node';
+
+import { configure, listMenuItems } from './api/client.js';
+import { handlers } from './api/client.mocks.js';
+
+const server = setupServer(...handlers);
+
+export async function loadMockedMenu() {
+  server.listen();
+  configure({ serverUrl: 'https://api.cafe.redocly.com' });
+  try {
+    // Served by the generated mocks — no real backend required.
+    return await listMenuItems();
+  } finally {
+    server.close();
+  }
+}
diff --git a/tests/e2e/generate-client/examples/mock/tsconfig.json b/tests/e2e/generate-client/examples/mock/tsconfig.json
new file mode 100644
index 0000000000..4bd6962d40
--- /dev/null
+++ b/tests/e2e/generate-client/examples/mock/tsconfig.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../tsconfig.base.json",
+  "include": ["src"]
+}
diff --git a/tests/e2e/generate-client/examples/mock/vite.config.ts b/tests/e2e/generate-client/examples/mock/vite.config.ts
new file mode 100644
index 0000000000..c049f46e10
--- /dev/null
+++ b/tests/e2e/generate-client/examples/mock/vite.config.ts
@@ -0,0 +1,3 @@
+import { defineConfig } from 'vite';
+
+export default defineConfig({});
diff --git a/tests/e2e/generate-client/examples/multi-instance/.gitignore b/tests/e2e/generate-client/examples/multi-instance/.gitignore
new file mode 100644
index 0000000000..6eb23affb8
--- /dev/null
+++ b/tests/e2e/generate-client/examples/multi-instance/.gitignore
@@ -0,0 +1,4 @@
+node_modules
+dist
+src/api/
+package-lock.json
diff --git a/tests/e2e/generate-client/examples/multi-instance/README.md b/tests/e2e/generate-client/examples/multi-instance/README.md
new file mode 100644
index 0000000000..0bf0d8b2ff
--- /dev/null
+++ b/tests/e2e/generate-client/examples/multi-instance/README.md
@@ -0,0 +1,21 @@
+# multi-instance example
+
+Per-tenant client instances from one generated module: `createClient` (from
+`@redocly/client-generator`) plus the generated `OPERATIONS` descriptors and
+`Ops`/`OperationId`/… types build one isolated instance per tenant — each with its own
+`serverUrl`, bearer token, and middleware.
+
+The generated module exports `createClient` in **both runtimes**, so the same pattern
+works with the default `inline` mode (import it from the generated file instead). This
+example uses `runtime: package` to also show the factory coming from the installed package.
+
+## Run
+
+```bash
+npm install
+npm run generate   # generate src/api (the client is gitignored)
+npm run dev        # open the printed local URL
+```
+
+The app uses a canned `fetch` that echoes the tenant host and `Authorization` header, so the
+per-instance isolation is visible offline. The generated client under `src/api/` is gitignored; CI regenerates it and type-checks this example.
diff --git a/tests/e2e/generate-client/examples/multi-instance/index.html b/tests/e2e/generate-client/examples/multi-instance/index.html
new file mode 100644
index 0000000000..a2b31a21d0
--- /dev/null
+++ b/tests/e2e/generate-client/examples/multi-instance/index.html
@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>Redocly client-generator — multi-instance example</title>
+  </head>
+  <body>
+    <pre id="out">Loading…</pre>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
diff --git a/tests/e2e/generate-client/examples/multi-instance/openapi.yaml b/tests/e2e/generate-client/examples/multi-instance/openapi.yaml
new file mode 100644
index 0000000000..2d4d468ce3
--- /dev/null
+++ b/tests/e2e/generate-client/examples/multi-instance/openapi.yaml
@@ -0,0 +1,81 @@
+openapi: 3.2.0
+info:
+  title: Projects API
+  description: Demo per-tenant projects API for the multi-instance example.
+  version: 1.0.0
+servers:
+  - url: https://acme.api.example.com
+    description: Default tenant — each client instance overrides `serverUrl`.
+tags:
+  - name: Projects
+    description: Project operations.
+security:
+  - BearerAuth: []
+paths:
+  /projects:
+    get:
+      tags:
+        - Projects
+      summary: List projects
+      operationId: listProjects
+      responses:
+        '200':
+          description: Successful operation.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ProjectList'
+    post:
+      tags:
+        - Projects
+      summary: Create a project
+      operationId: createProject
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ProjectRequest'
+      responses:
+        '201':
+          description: Project created.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Project'
+components:
+  securitySchemes:
+    BearerAuth:
+      type: http
+      scheme: bearer
+      description: Per-tenant access token.
+  schemas:
+    Project:
+      type: object
+      properties:
+        id:
+          description: Project ID.
+          type: string
+        name:
+          description: Project name.
+          type: string
+      required:
+        - id
+        - name
+    ProjectRequest:
+      type: object
+      properties:
+        name:
+          description: Project name.
+          type: string
+      required:
+        - name
+    ProjectList:
+      type: object
+      properties:
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/Project'
+      required:
+        - items
diff --git a/tests/e2e/generate-client/examples/multi-instance/package.json b/tests/e2e/generate-client/examples/multi-instance/package.json
new file mode 100644
index 0000000000..06c0325f6b
--- /dev/null
+++ b/tests/e2e/generate-client/examples/multi-instance/package.json
@@ -0,0 +1,19 @@
+{
+  "name": "@redocly-examples/multi-instance",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "generate": "redocly generate-client",
+    "dev": "vite",
+    "build": "vite build"
+  },
+  "dependencies": {
+    "@redocly/client-generator": "latest"
+  },
+  "devDependencies": {
+    "@redocly/cli": "latest",
+    "typescript": "^5.5.0",
+    "vite": "^5.4.0"
+  }
+}
diff --git a/tests/e2e/generate-client/examples/multi-instance/redocly.yaml b/tests/e2e/generate-client/examples/multi-instance/redocly.yaml
new file mode 100644
index 0000000000..eb1a5e90e7
--- /dev/null
+++ b/tests/e2e/generate-client/examples/multi-instance/redocly.yaml
@@ -0,0 +1,11 @@
+# redocly.yaml — drives `redocly generate-client` for this example.
+# `runtime: package` because multi-instance needs `createClient`, which the
+# package exports; the default `inline` mode keeps it module-local.
+apis:
+  multi-instance:
+    root: ./openapi.yaml
+    clientOutput: ./src/api/client.ts
+    client:
+      generators:
+        - sdk
+      runtime: package
diff --git a/tests/e2e/generate-client/examples/multi-instance/src/main.ts b/tests/e2e/generate-client/examples/multi-instance/src/main.ts
new file mode 100644
index 0000000000..e8f35e2fdf
--- /dev/null
+++ b/tests/e2e/generate-client/examples/multi-instance/src/main.ts
@@ -0,0 +1,77 @@
+// multi-instance — one generated module, many isolated client instances.
+//
+// The generated file exports the raw wiring — the `OPERATIONS` descriptors and the
+// `Ops`/`OperationId`/`OperationPath`/`OperationTag` types — alongside its default
+// `client`. With `runtime: package`, `createClient` is imported from
+// `@redocly/client-generator`, so an app can build one instance per tenant, each
+// with its own `serverUrl`, credentials, and middleware — nothing is module-global.
+//
+// (The generated module exports `createClient` in BOTH runtimes, so the same
+// pattern works with the default `inline` mode too — this example uses
+// `runtime: package` to also demonstrate importing the factory from the package.)
+import { createClient } from '@redocly/client-generator';
+
+import {
+  OPERATIONS,
+  type OperationId,
+  type OperationPath,
+  type OperationTag,
+  type Ops,
+} from './api/client.js';
+
+const out = document.querySelector<HTMLPreElement>('#out')!;
+const log: string[] = [];
+
+// A canned transport that echoes WHICH tenant was addressed and AS WHOM, so the
+// per-instance isolation is visible in the output (and the example runs offline).
+const canned = (async (url: string, init: RequestInit) => {
+  const { host, pathname } = new URL(url);
+  const headers = init.headers as Record<string, string>;
+  const tenant = host.split('.')[0];
+  log.push(`${init.method} ${host}${pathname} — ${headers['Authorization'] ?? 'anonymous'}`);
+  const project = { id: `prj_${tenant}_1`, name: `${tenant} website` };
+  return init.method === 'POST'
+    ? new Response(JSON.stringify({ ...project, ...JSON.parse(String(init.body)) }), {
+        status: 201,
+        headers: { 'content-type': 'application/json' },
+      })
+    : new Response(JSON.stringify({ items: [project] }), {
+        headers: { 'content-type': 'application/json' },
+      });
+}) as unknown as typeof fetch;
+
+// The per-tenant factory: same descriptors, isolated config. The type parameters
+// carry the generated literal unions into `ctx.operation` for middleware targeting.
+function tenantClient(tenant: string, token: string) {
+  const instance = createClient<Ops, OperationId, OperationPath, OperationTag>(OPERATIONS, {
+    serverUrl: `https://${tenant}.api.example.com`,
+    fetch: canned,
+  });
+  instance.auth.bearer(token); // per-instance credentials — no shared auth state
+  return instance;
+}
+
+const acme = tenantClient('acme', 'acme-token');
+const globex = tenantClient('globex', 'globex-token');
+
+// Middleware is per-instance too: only globex requests carry the tier header.
+globex.use({
+  onRequest: (ctx) => {
+    ctx.headers['X-Tenant-Tier'] = 'enterprise';
+  },
+});
+
+async function main() {
+  const [acmeProjects, globexProjects] = await Promise.all([
+    acme.listProjects(),
+    globex.listProjects(),
+  ]);
+  const created = await acme.createProject({ body: { name: 'Launch site' } });
+  out.textContent = [
+    ...log,
+    '',
+    JSON.stringify({ acmeProjects, globexProjects, created }, null, 2),
+  ].join('\n');
+}
+
+void main();
diff --git a/tests/e2e/generate-client/examples/multi-instance/tsconfig.json b/tests/e2e/generate-client/examples/multi-instance/tsconfig.json
new file mode 100644
index 0000000000..4bd6962d40
--- /dev/null
+++ b/tests/e2e/generate-client/examples/multi-instance/tsconfig.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../tsconfig.base.json",
+  "include": ["src"]
+}
diff --git a/tests/e2e/generate-client/examples/multi-instance/vite.config.ts b/tests/e2e/generate-client/examples/multi-instance/vite.config.ts
new file mode 100644
index 0000000000..c049f46e10
--- /dev/null
+++ b/tests/e2e/generate-client/examples/multi-instance/vite.config.ts
@@ -0,0 +1,3 @@
+import { defineConfig } from 'vite';
+
+export default defineConfig({});
diff --git a/tests/e2e/generate-client/examples/nested-facade/.gitignore b/tests/e2e/generate-client/examples/nested-facade/.gitignore
new file mode 100644
index 0000000000..33d6b355f6
--- /dev/null
+++ b/tests/e2e/generate-client/examples/nested-facade/.gitignore
@@ -0,0 +1,2 @@
+src/api/
+package-lock.json
diff --git a/tests/e2e/generate-client/examples/nested-facade/README.md b/tests/e2e/generate-client/examples/nested-facade/README.md
new file mode 100644
index 0000000000..4ea7dbb045
--- /dev/null
+++ b/tests/e2e/generate-client/examples/nested-facade/README.md
@@ -0,0 +1,15 @@
+# nested-facade
+
+A resource-grouped call shape — `api.orders.listOrders(…)` — derived from the
+spec's **tags** by a small [custom generator](./nested-facade-generator.mjs)
+(the experimental plugin API), so the nesting regenerates with the spec instead
+of living in a hand-maintained facade file. Everything stays fully typed: the
+facade just re-exports the sdk's generated functions in nested objects.
+
+## Run
+
+```bash
+npm install
+npm run generate
+npm start
+```
diff --git a/tests/e2e/generate-client/examples/nested-facade/nested-facade-generator.mjs b/tests/e2e/generate-client/examples/nested-facade/nested-facade-generator.mjs
new file mode 100644
index 0000000000..ebee143162
--- /dev/null
+++ b/tests/e2e/generate-client/examples/nested-facade/nested-facade-generator.mjs
@@ -0,0 +1,38 @@
+// A custom generator (the experimental plugin API): groups the sdk's generated
+// free functions by their first tag and emits a nested facade —
+// `api.orders.listOrders(…)` — derived from the spec, regenerated with it.
+//
+// Authored in TypeScript you would write:
+//   import { defineGenerator } from '@redocly/client-generator';
+//   export default defineGenerator({ name: 'nested-facade', requires: ['sdk'], run({ model, outputPath }) { … } });
+const groupIdent = (tag) => {
+  const ident = tag.replace(/[^A-Za-z0-9_$]/g, '_');
+  return /^[A-Za-z_$]/.test(ident) ? ident[0].toLowerCase() + ident.slice(1) : `_${ident}`;
+};
+
+export default {
+  name: 'nested-facade',
+  requires: ['sdk'],
+  run({ model, outputPath }) {
+    const groups = new Map();
+    for (const op of model.services.flatMap((service) => service.operations)) {
+      const group = groupIdent(op.tags[0] ?? 'other');
+      (groups.get(group) ?? groups.set(group, []).get(group)).push(op.name);
+    }
+    const names = [...groups.values()].flat().sort();
+    const stem = outputPath.split(/[\\/]/).pop().replace(/\.ts$/, '');
+    const body = [...groups]
+      .map(([group, ops]) => `export const ${group} = { ${ops.join(', ')} } as const;`)
+      .join('\n');
+    return [
+      {
+        path: outputPath.replace(/\.ts$/, '.facade.ts'),
+        content:
+          '// Generated by the nested-facade custom generator. Do not edit by hand.\n' +
+          `import { ${names.join(', ')} } from './${stem}.js';\n\n` +
+          body +
+          `\n\nexport const api = { ${[...groups.keys()].join(', ')} } as const;\n`,
+      },
+    ];
+  },
+};
diff --git a/tests/e2e/generate-client/examples/nested-facade/openapi.yaml b/tests/e2e/generate-client/examples/nested-facade/openapi.yaml
new file mode 100644
index 0000000000..d345ddbc7d
--- /dev/null
+++ b/tests/e2e/generate-client/examples/nested-facade/openapi.yaml
@@ -0,0 +1,72 @@
+openapi: 3.1.0
+info:
+  title: Cafe API
+  description: A small tagged API for the nested-facade example.
+  version: 1.0.0
+servers:
+  - url: https://api.cafe-orders.example.com
+tags:
+  - name: Orders
+  - name: Menu
+paths:
+  /orders:
+    get:
+      operationId: listOrders
+      tags: [Orders]
+      responses:
+        '200':
+          description: All orders.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Order'
+  /orders/{orderId}:
+    get:
+      operationId: getOrder
+      tags: [Orders]
+      parameters:
+        - name: orderId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: The order.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Order'
+  /menu:
+    get:
+      operationId: listMenuItems
+      tags: [Menu]
+      responses:
+        '200':
+          description: The menu.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/MenuItem'
+components:
+  schemas:
+    Order:
+      type: object
+      required: [id, drink]
+      properties:
+        id:
+          type: string
+        drink:
+          type: string
+    MenuItem:
+      type: object
+      required: [name, price]
+      properties:
+        name:
+          type: string
+        price:
+          type: integer
diff --git a/tests/e2e/generate-client/examples/nested-facade/package.json b/tests/e2e/generate-client/examples/nested-facade/package.json
new file mode 100644
index 0000000000..5fbb88558e
--- /dev/null
+++ b/tests/e2e/generate-client/examples/nested-facade/package.json
@@ -0,0 +1,15 @@
+{
+  "name": "@redocly-examples/nested-facade",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "generate": "redocly generate-client",
+    "start": "tsx src/main.ts"
+  },
+  "devDependencies": {
+    "@redocly/cli": "latest",
+    "tsx": "^4.0.0",
+    "typescript": "^5.5.0"
+  }
+}
diff --git a/tests/e2e/generate-client/examples/nested-facade/redocly.yaml b/tests/e2e/generate-client/examples/nested-facade/redocly.yaml
new file mode 100644
index 0000000000..daf72c0a5b
--- /dev/null
+++ b/tests/e2e/generate-client/examples/nested-facade/redocly.yaml
@@ -0,0 +1,13 @@
+# redocly.yaml — drives `redocly generate-client` for this example.
+#
+# The custom generator below derives a nested, resource-grouped facade
+# (`api.orders.listOrders(…)`) from the spec's tags — so the nesting regenerates
+# with the spec instead of living in a hand-maintained file.
+apis:
+  nested-facade:
+    root: ./openapi.yaml
+    clientOutput: ./src/api/client.ts
+    client:
+      generators:
+        - sdk
+        - ./nested-facade-generator.mjs
diff --git a/tests/e2e/generate-client/examples/nested-facade/src/main.ts b/tests/e2e/generate-client/examples/nested-facade/src/main.ts
new file mode 100644
index 0000000000..db810ba43d
--- /dev/null
+++ b/tests/e2e/generate-client/examples/nested-facade/src/main.ts
@@ -0,0 +1,28 @@
+import { api } from './api/client.facade.js';
+// nested-facade — a resource-grouped client shape, generated from the spec's tags.
+//
+// The generated sdk exposes flat functions and the `client` instance; some teams
+// prefer `api.<resource>.<operation>(…)`. Instead of hand-maintaining that facade,
+// the custom generator in ./nested-facade-generator.mjs derives it from the spec's
+// tags — every regeneration keeps it in sync, and everything stays fully typed.
+import { configure } from './api/client.js';
+
+// A canned transport so the example runs offline.
+const CANNED: Record<string, unknown> = {
+  '/orders': [{ id: 'ord-101', drink: 'espresso' }],
+  '/menu': [{ name: 'latte', price: 450 }],
+};
+const canned = (async (url: string) =>
+  new Response(JSON.stringify(CANNED[new URL(url).pathname]), {
+    headers: { 'content-type': 'application/json' },
+  })) as unknown as typeof fetch;
+
+configure({ fetch: canned });
+
+// Nested, resource-first call shape — same typed functions underneath.
+for (const order of await api.orders.listOrders()) {
+  console.log(`order ${order.id}: ${order.drink}`);
+}
+for (const item of await api.menu.listMenuItems()) {
+  console.log(`menu: ${item.name} — $${(item.price / 100).toFixed(2)}`);
+}
diff --git a/tests/e2e/generate-client/examples/nested-facade/tsconfig.json b/tests/e2e/generate-client/examples/nested-facade/tsconfig.json
new file mode 100644
index 0000000000..4bd6962d40
--- /dev/null
+++ b/tests/e2e/generate-client/examples/nested-facade/tsconfig.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../tsconfig.base.json",
+  "include": ["src"]
+}
diff --git a/tests/e2e/generate-client/examples/node-native/.gitignore b/tests/e2e/generate-client/examples/node-native/.gitignore
new file mode 100644
index 0000000000..612acc5cae
--- /dev/null
+++ b/tests/e2e/generate-client/examples/node-native/.gitignore
@@ -0,0 +1,3 @@
+node_modules
+src/api/
+package-lock.json
diff --git a/tests/e2e/generate-client/examples/node-native/README.md b/tests/e2e/generate-client/examples/node-native/README.md
new file mode 100644
index 0000000000..825d7dfc5e
--- /dev/null
+++ b/tests/e2e/generate-client/examples/node-native/README.md
@@ -0,0 +1,16 @@
+# node-native
+
+Run the generated client with plain `node` — no tsx, no loader, no build step.
+
+Node 22.7+ strips TypeScript types natively but resolves import specifiers literally:
+there is no `.js` → `.ts` remap, so the default generated imports (`./client.schemas.js`) don't resolve.
+Setting `importExt: ts` (or passing `--import-ext ts`) makes the generator emit real on-disk `.ts` specifiers instead,
+and your own code imports the client the same way (`./api/client.ts`).
+
+Keep the default `js` extension when the client goes through `tsc` or a bundler — this option targets literal-resolution runtimes only.
+
+```bash
+npm install
+npm run generate
+npm start
+```
diff --git a/tests/e2e/generate-client/examples/node-native/openapi.yaml b/tests/e2e/generate-client/examples/node-native/openapi.yaml
new file mode 100644
index 0000000000..0d3078b028
--- /dev/null
+++ b/tests/e2e/generate-client/examples/node-native/openapi.yaml
@@ -0,0 +1,58 @@
+openapi: 3.2.0
+info:
+  title: Cafe Menu (Node native)
+  description: A tiny slice of the Redocly Cafe demo API — just enough for a first call.
+  version: 1.0.0
+servers:
+  - url: https://api.cafe.redocly.com
+    description: Live demo server.
+paths:
+  /menu:
+    get:
+      summary: List all menu items
+      operationId: listMenuItems
+      security: []
+      parameters:
+        - name: limit
+          in: query
+          required: false
+          description: Number of results per page.
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 10
+      responses:
+        '200':
+          description: Successful operation.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MenuItemList'
+components:
+  schemas:
+    MenuItem:
+      type: object
+      properties:
+        id:
+          description: Menu item ID.
+          type: string
+        name:
+          description: Menu item name.
+          type: string
+        price:
+          description: Price in cents.
+          type: integer
+      required:
+        - id
+        - name
+        - price
+    MenuItemList:
+      type: object
+      properties:
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/MenuItem'
+      required:
+        - items
diff --git a/tests/e2e/generate-client/examples/node-native/package.json b/tests/e2e/generate-client/examples/node-native/package.json
new file mode 100644
index 0000000000..f49846de62
--- /dev/null
+++ b/tests/e2e/generate-client/examples/node-native/package.json
@@ -0,0 +1,14 @@
+{
+  "name": "@redocly-examples/node-native",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "generate": "redocly generate-client",
+    "start": "node src/main.ts"
+  },
+  "devDependencies": {
+    "@redocly/cli": "latest",
+    "typescript": "^5.5.0"
+  }
+}
diff --git a/tests/e2e/generate-client/examples/node-native/redocly.yaml b/tests/e2e/generate-client/examples/node-native/redocly.yaml
new file mode 100644
index 0000000000..cab21aa9df
--- /dev/null
+++ b/tests/e2e/generate-client/examples/node-native/redocly.yaml
@@ -0,0 +1,10 @@
+# redocly.yaml — drives `redocly generate-client` for this example.
+apis:
+  node-native:
+    root: ./openapi.yaml
+    clientOutput: ./src/api/client.ts
+    client:
+      generators:
+        - sdk
+      outputMode: split
+      importExt: ts
diff --git a/tests/e2e/generate-client/examples/node-native/src/main.ts b/tests/e2e/generate-client/examples/node-native/src/main.ts
new file mode 100644
index 0000000000..de372bc361
--- /dev/null
+++ b/tests/e2e/generate-client/examples/node-native/src/main.ts
@@ -0,0 +1,11 @@
+// node-native — run the TypeScript client directly with `node`, no loader, no build step.
+//
+// The client was generated with `importExt: ts`, so its internal imports use real
+// on-disk `.ts` specifiers — what Node's built-in type stripping resolves (Node 22.7+).
+// The import below uses a `.ts` extension for the same reason.
+import { listMenuItems } from './api/client.ts';
+
+const menu = await listMenuItems({ limit: 3 });
+for (const item of menu.items) {
+  console.log(`${item.name} — $${(item.price / 100).toFixed(2)}`);
+}
diff --git a/tests/e2e/generate-client/examples/node-native/tsconfig.json b/tests/e2e/generate-client/examples/node-native/tsconfig.json
new file mode 100644
index 0000000000..0e7c07dacb
--- /dev/null
+++ b/tests/e2e/generate-client/examples/node-native/tsconfig.json
@@ -0,0 +1,7 @@
+{
+  "extends": "../tsconfig.base.json",
+  "compilerOptions": {
+    "allowImportingTsExtensions": true
+  },
+  "include": ["src"]
+}
diff --git a/tests/e2e/generate-client/examples/package-runtime/.gitignore b/tests/e2e/generate-client/examples/package-runtime/.gitignore
new file mode 100644
index 0000000000..6eb23affb8
--- /dev/null
+++ b/tests/e2e/generate-client/examples/package-runtime/.gitignore
@@ -0,0 +1,4 @@
+node_modules
+dist
+src/api/
+package-lock.json
diff --git a/tests/e2e/generate-client/examples/package-runtime/README.md b/tests/e2e/generate-client/examples/package-runtime/README.md
new file mode 100644
index 0000000000..25c941bf3d
--- /dev/null
+++ b/tests/e2e/generate-client/examples/package-runtime/README.md
@@ -0,0 +1,19 @@
+# package-runtime example
+
+Generated TypeScript client using **`runtime: package`**: the generated `src/api/client.ts`
+contains only this API's types and operation descriptors and imports the engine
+(`createClient`, `ApiError`, middleware, auth) from `@redocly/client-generator` — the example's
+one real dependency. Engine fixes arrive via `npm update @redocly/client-generator` with no
+regeneration; regenerate only when the API contract changes.
+
+## Run
+
+```bash
+npm install
+npm run generate   # generate src/api (the client is gitignored)
+npm run dev        # open the printed local URL
+```
+
+The generated client under `src/api/` is gitignored; CI regenerates it and type-checks this example.
+The app code is the same as the inline examples — `configure()`, `use()` middleware, free
+functions, the `client` instance, `ApiError` — only the runtime's distribution differs.
diff --git a/tests/e2e/generate-client/examples/package-runtime/index.html b/tests/e2e/generate-client/examples/package-runtime/index.html
new file mode 100644
index 0000000000..2cc6be9a3b
--- /dev/null
+++ b/tests/e2e/generate-client/examples/package-runtime/index.html
@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>Redocly client-generator — package-runtime example</title>
+  </head>
+  <body>
+    <pre id="out">Loading…</pre>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
diff --git a/tests/e2e/generate-client/examples/package-runtime/package.json b/tests/e2e/generate-client/examples/package-runtime/package.json
new file mode 100644
index 0000000000..0007c9d199
--- /dev/null
+++ b/tests/e2e/generate-client/examples/package-runtime/package.json
@@ -0,0 +1,19 @@
+{
+  "name": "@redocly-examples/package-runtime",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "generate": "redocly generate-client",
+    "dev": "vite",
+    "build": "vite build"
+  },
+  "dependencies": {
+    "@redocly/client-generator": "latest"
+  },
+  "devDependencies": {
+    "@redocly/cli": "latest",
+    "typescript": "^5.5.0",
+    "vite": "^5.4.0"
+  }
+}
diff --git a/tests/e2e/generate-client/examples/package-runtime/redocly.yaml b/tests/e2e/generate-client/examples/package-runtime/redocly.yaml
new file mode 100644
index 0000000000..5aa5ec8bbd
--- /dev/null
+++ b/tests/e2e/generate-client/examples/package-runtime/redocly.yaml
@@ -0,0 +1,12 @@
+# redocly.yaml — drives `redocly generate-client` for this example.
+# `runtime: package` makes the generated client import the engine from
+# `@redocly/client-generator` instead of inlining it — runtime fixes arrive
+# via `npm update @redocly/client-generator`, no regeneration needed.
+apis:
+  package-runtime:
+    root: ../_shared/cafe.yaml
+    clientOutput: ./src/api/client.ts
+    client:
+      generators:
+        - sdk
+      runtime: package
diff --git a/tests/e2e/generate-client/examples/package-runtime/src/main.ts b/tests/e2e/generate-client/examples/package-runtime/src/main.ts
new file mode 100644
index 0000000000..0d074681f0
--- /dev/null
+++ b/tests/e2e/generate-client/examples/package-runtime/src/main.ts
@@ -0,0 +1,48 @@
+// package-runtime example — same app code as the inline examples, different distribution.
+//
+// This client was generated with `runtime: package`: instead of embedding the engine
+// (fetch, retries, middleware, auth) in `src/api/client.ts`, the generated file contains
+// only THIS API's types and operation descriptors and imports the engine from
+// `@redocly/client-generator`. Engine fixes and improvements arrive with
+// `npm update @redocly/client-generator` — regenerate only when the API contract changes.
+import { ApiError, client, configure, listMenuItems, use } from './api/client.js';
+
+configure({ serverUrl: 'https://api.cafe.redocly.com' });
+
+const out = document.querySelector<HTMLPreElement>('#out')!;
+
+// Middleware runs inside the packaged engine but sees the generated OPERATIONS metadata:
+// `ctx.operation.id` is the spec operationId, stable across engine updates.
+const trace: string[] = [];
+use({
+  onRequest: (ctx) => {
+    trace.push(`→ ${ctx.operation.id} — ${ctx.method} ${ctx.url}`);
+  },
+  onResponse: (response, ctx) => {
+    document.title = `cafe — ${ctx.operation.id} ${response.status}`;
+  },
+});
+
+async function main() {
+  try {
+    // A typed call through a generated free function…
+    const menu = await listMenuItems({ limit: 3 });
+    // …and one through the generated `client` instance (the same runtime underneath).
+    const [first] = menu.items;
+    const photo = first
+      ? await client.getMenuItemPhoto({ menuItemId: first.id, params: { photoSize: 'thumbnail' } })
+      : undefined;
+    const photoLine =
+      photo instanceof Blob
+        ? `${first?.name} thumbnail: ${photo.type}, ${photo.size} bytes`
+        : photo;
+    out.textContent = [...trace, '', photoLine, '', JSON.stringify(menu.items, null, 2)].join('\n');
+  } catch (error) {
+    out.textContent =
+      error instanceof ApiError
+        ? `ApiError ${error.status}: ${error.statusText}`
+        : `Unexpected error: ${String(error)}`;
+  }
+}
+
+void main();
diff --git a/tests/e2e/generate-client/examples/package-runtime/tsconfig.json b/tests/e2e/generate-client/examples/package-runtime/tsconfig.json
new file mode 100644
index 0000000000..4bd6962d40
--- /dev/null
+++ b/tests/e2e/generate-client/examples/package-runtime/tsconfig.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../tsconfig.base.json",
+  "include": ["src"]
+}
diff --git a/tests/e2e/generate-client/examples/package-runtime/vite.config.ts b/tests/e2e/generate-client/examples/package-runtime/vite.config.ts
new file mode 100644
index 0000000000..c049f46e10
--- /dev/null
+++ b/tests/e2e/generate-client/examples/package-runtime/vite.config.ts
@@ -0,0 +1,3 @@
+import { defineConfig } from 'vite';
+
+export default defineConfig({});
diff --git a/tests/e2e/generate-client/examples/pagination/.gitignore b/tests/e2e/generate-client/examples/pagination/.gitignore
new file mode 100644
index 0000000000..612acc5cae
--- /dev/null
+++ b/tests/e2e/generate-client/examples/pagination/.gitignore
@@ -0,0 +1,3 @@
+node_modules
+src/api/
+package-lock.json
diff --git a/tests/e2e/generate-client/examples/pagination/README.md b/tests/e2e/generate-client/examples/pagination/README.md
new file mode 100644
index 0000000000..9935ec5aff
--- /dev/null
+++ b/tests/e2e/generate-client/examples/pagination/README.md
@@ -0,0 +1,16 @@
+# pagination example
+
+Auto-pagination from a `redocly.yaml` convention: the `client.pagination` block declares
+one cursor rule, the generator applies it to every operation it structurally fits, and
+the paginated operation gains `.pages()` / `.items()` async iterators next to its
+unchanged one-shot call. Item types are computed statically from the response schema.
+
+## Run
+
+```bash
+npm install        # dev tooling only (the CLI + tsx); the client itself needs nothing
+npm run generate   # generate src/api (the client is gitignored)
+npm start          # iterates two canned pages of orders and prints them
+```
+
+The generated client under `src/api/` is gitignored; CI regenerates it and type-checks this example.
diff --git a/tests/e2e/generate-client/examples/pagination/openapi.yaml b/tests/e2e/generate-client/examples/pagination/openapi.yaml
new file mode 100644
index 0000000000..5a4c9058cc
--- /dev/null
+++ b/tests/e2e/generate-client/examples/pagination/openapi.yaml
@@ -0,0 +1,69 @@
+openapi: 3.1.0
+info:
+  title: Cafe Orders API
+  description: A tiny cursor-paginated orders API for the auto-pagination example.
+  version: 1.0.0
+servers:
+  - url: https://api.cafe-orders.example.com
+paths:
+  /orders:
+    get:
+      operationId: listOrders
+      summary: List orders, one cursor page at a time
+      parameters:
+        - name: cursor
+          in: query
+          description: Opaque cursor of the page to fetch; omit for the first page.
+          schema:
+            type: string
+        - name: limit
+          in: query
+          description: Page size.
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: One page of orders.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [orders]
+                properties:
+                  orders:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Order'
+                  nextCursor:
+                    description: Cursor of the next page; absent on the last page.
+                    type: string
+  /orders/{orderId}:
+    get:
+      operationId: getOrder
+      summary: Retrieve one order
+      parameters:
+        - name: orderId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: The order.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Order'
+components:
+  schemas:
+    Order:
+      type: object
+      required: [id, drink, status]
+      properties:
+        id:
+          type: string
+        drink:
+          type: string
+        status:
+          type: string
+          enum: [pending, ready, delivered]
diff --git a/tests/e2e/generate-client/examples/pagination/package.json b/tests/e2e/generate-client/examples/pagination/package.json
new file mode 100644
index 0000000000..017b007a80
--- /dev/null
+++ b/tests/e2e/generate-client/examples/pagination/package.json
@@ -0,0 +1,15 @@
+{
+  "name": "@redocly-examples/pagination",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "generate": "redocly generate-client",
+    "start": "tsx src/main.ts"
+  },
+  "devDependencies": {
+    "@redocly/cli": "latest",
+    "tsx": "^4.0.0",
+    "typescript": "^5.5.0"
+  }
+}
diff --git a/tests/e2e/generate-client/examples/pagination/redocly.yaml b/tests/e2e/generate-client/examples/pagination/redocly.yaml
new file mode 100644
index 0000000000..9d6b34bc23
--- /dev/null
+++ b/tests/e2e/generate-client/examples/pagination/redocly.yaml
@@ -0,0 +1,19 @@
+# redocly.yaml — drives `redocly generate-client` for this example.
+#
+# The `pagination` block declares ONE cursor convention for the whole API. It is
+# declared + VERIFIED: the generator applies it only to operations it structurally
+# fits (the `cursor` query param exists, the pointers resolve in the response) —
+# here `listOrders` gains `.pages()`/`.items()` and `getOrder` stays a plain call.
+apis:
+  pagination:
+    root: ./openapi.yaml
+    clientOutput: ./src/api/client.ts
+    client:
+      generators:
+        - sdk
+      pagination:
+        style: cursor
+        cursorParam: cursor
+        nextCursor: /nextCursor
+        limitParam: limit
+        items: /orders
diff --git a/tests/e2e/generate-client/examples/pagination/src/main.ts b/tests/e2e/generate-client/examples/pagination/src/main.ts
new file mode 100644
index 0000000000..bb6e6c5d17
--- /dev/null
+++ b/tests/e2e/generate-client/examples/pagination/src/main.ts
@@ -0,0 +1,45 @@
+// pagination — a declared convention, verified per operation.
+//
+// The redocly.yaml `client.pagination` block declares ONE cursor convention for the
+// whole API: advance the `cursor` query param, follow `/nextCursor` in each response,
+// yield the array under `/orders`. The generator applies it only where it
+// STRUCTURALLY FITS — `listOrders` has the param and the pointers resolve, so it keeps
+// its one-shot call and gains `.pages()` / `.items()`; `getOrder` has no `cursor`
+// param, so it stays a plain call. (Explicit declarations — `x-pagination` in the spec
+// or per-operation config — that don't fit fail generation instead of being skipped.)
+import { configure, listOrders } from './api/client.js';
+
+// A canned transport so the example runs offline: two pages of orders. The first page
+// carries `nextCursor`; the last page doesn't — that absence is the stop signal.
+const PAGES: Record<string, unknown> = {
+  '': {
+    orders: [
+      { id: 'ord-101', drink: 'espresso', status: 'ready' },
+      { id: 'ord-102', drink: 'latte', status: 'pending' },
+    ],
+    nextCursor: 'p2',
+  },
+  p2: {
+    orders: [{ id: 'ord-103', drink: 'cortado', status: 'delivered' }],
+  },
+};
+const canned = (async (url: string) => {
+  const cursor = new URL(url).searchParams.get('cursor') ?? '';
+  return new Response(JSON.stringify(PAGES[cursor]), {
+    headers: { 'content-type': 'application/json' },
+  });
+}) as unknown as typeof fetch;
+
+configure({ fetch: canned });
+
+// `.items()` walks every order across every page — the cursor plumbing is invisible,
+// and each `order` is the statically computed element type (`Order`).
+for await (const order of listOrders.items({ params: { limit: 20 } })) {
+  console.log(`${order.id}: ${order.drink} (${order.status})`);
+}
+
+// `.pages()` when you need page-level access (progress reporting, batch writes).
+let pageNumber = 0;
+for await (const page of listOrders.pages({ params: { limit: 20 } })) {
+  console.log(`page ${++pageNumber}: ${page.orders.length} orders`);
+}
diff --git a/tests/e2e/generate-client/examples/pagination/tsconfig.json b/tests/e2e/generate-client/examples/pagination/tsconfig.json
new file mode 100644
index 0000000000..4bd6962d40
--- /dev/null
+++ b/tests/e2e/generate-client/examples/pagination/tsconfig.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../tsconfig.base.json",
+  "include": ["src"]
+}
diff --git a/tests/e2e/generate-client/examples/programmatic/.gitignore b/tests/e2e/generate-client/examples/programmatic/.gitignore
new file mode 100644
index 0000000000..6eb23affb8
--- /dev/null
+++ b/tests/e2e/generate-client/examples/programmatic/.gitignore
@@ -0,0 +1,4 @@
+node_modules
+dist
+src/api/
+package-lock.json
diff --git a/tests/e2e/generate-client/examples/programmatic/README.md b/tests/e2e/generate-client/examples/programmatic/README.md
new file mode 100644
index 0000000000..eb877c5307
--- /dev/null
+++ b/tests/e2e/generate-client/examples/programmatic/README.md
@@ -0,0 +1,16 @@
+# programmatic example
+
+Generates the client **programmatically** with `generateClient(...)` from
+`@redocly/client-generator` — the same API the `redocly generate-client` CLI uses — instead of a
+`redocly.yaml`. See [`generate.ts`](./generate.ts). Useful when generation is part of a build script,
+codegen pipeline, or test setup.
+
+## Run
+
+```bash
+npm install
+npm run generate   # runs generate.ts → writes src/api/client.ts
+```
+
+The generated client under `src/api/` is gitignored; CI regenerates it and type-checks this example.
+`generateClient(...)` returns `{ outputPath, bytes, files }`.
diff --git a/tests/e2e/generate-client/examples/programmatic/generate.ts b/tests/e2e/generate-client/examples/programmatic/generate.ts
new file mode 100644
index 0000000000..2984185f0f
--- /dev/null
+++ b/tests/e2e/generate-client/examples/programmatic/generate.ts
@@ -0,0 +1,19 @@
+// Generate the client *programmatically* with `generateClient(...)` — the API behind the
+// `redocly generate-client` CLI — instead of a `redocly.yaml`. Run: `npm run generate`.
+// (The CI drift-check sets `OUT` to redirect the output to a temp dir.)
+import { generateClient } from '@redocly/client-generator';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+const result = await generateClient({
+  api: join(here, '../_shared/cafe.yaml'),
+  output: process.env.OUT ?? join(here, 'src/api/client.ts'),
+  outputMode: 'single', // 'single' | 'split'
+  argsStyle: 'flat', // 'flat' | 'grouped'
+  errorMode: 'throw', // 'throw' | 'result'
+  generators: ['sdk'], // add 'zod' | 'tanstack-query' | 'transformers'
+});
+
+console.log(`Wrote ${result.files.length} file(s), ${result.bytes} bytes to ${result.outputPath}`);
diff --git a/tests/e2e/generate-client/examples/programmatic/package.json b/tests/e2e/generate-client/examples/programmatic/package.json
new file mode 100644
index 0000000000..6d7561ef41
--- /dev/null
+++ b/tests/e2e/generate-client/examples/programmatic/package.json
@@ -0,0 +1,14 @@
+{
+  "name": "@redocly-examples/programmatic",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "generate": "tsx generate.ts"
+  },
+  "devDependencies": {
+    "@redocly/client-generator": "latest",
+    "tsx": "^4.0.0",
+    "typescript": "^5.5.0"
+  }
+}
diff --git a/tests/e2e/generate-client/examples/programmatic/src/main.ts b/tests/e2e/generate-client/examples/programmatic/src/main.ts
new file mode 100644
index 0000000000..1d54f67be6
--- /dev/null
+++ b/tests/e2e/generate-client/examples/programmatic/src/main.ts
@@ -0,0 +1,9 @@
+// Consume the programmatically-generated client. The output is identical to the CLI's —
+// programmatic generation only changes *how* you invoke the generator, not what it emits.
+import { configure, listMenuItems } from './api/client.js';
+
+configure({ serverUrl: 'https://api.cafe.redocly.com' });
+
+export async function loadMenu() {
+  return listMenuItems();
+}
diff --git a/tests/e2e/generate-client/examples/programmatic/tsconfig.json b/tests/e2e/generate-client/examples/programmatic/tsconfig.json
new file mode 100644
index 0000000000..4bd6962d40
--- /dev/null
+++ b/tests/e2e/generate-client/examples/programmatic/tsconfig.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../tsconfig.base.json",
+  "include": ["src"]
+}
diff --git a/tests/e2e/generate-client/examples/sse-streaming/.gitignore b/tests/e2e/generate-client/examples/sse-streaming/.gitignore
new file mode 100644
index 0000000000..6eb23affb8
--- /dev/null
+++ b/tests/e2e/generate-client/examples/sse-streaming/.gitignore
@@ -0,0 +1,4 @@
+node_modules
+dist
+src/api/
+package-lock.json
diff --git a/tests/e2e/generate-client/examples/sse-streaming/README.md b/tests/e2e/generate-client/examples/sse-streaming/README.md
new file mode 100644
index 0000000000..7809a3e5ae
--- /dev/null
+++ b/tests/e2e/generate-client/examples/sse-streaming/README.md
@@ -0,0 +1,18 @@
+# sse-streaming example
+
+A `text/event-stream` operation consumed as a typed async generator: `for await` over
+`streamOrderEvents()` yields `ServerSentEvent<OrderEvent>` with `ev.data` typed from the
+spec's `itemSchema`. Shows auto-reconnect resuming via `Last-Event-ID` (tuned with
+`reconnectDelay`; opt out with `reconnect: false`) and a clean abort via `AbortController`.
+
+## Run
+
+```bash
+npm install
+npm run generate   # generate src/api (the client is gitignored)
+npm run dev        # open the printed local URL
+```
+
+The app uses a canned SSE `fetch` so it runs offline and the reconnect is deterministic:
+connection 1 drops mid-stream, connection 2 resumes from the last event id. The generated
+client under `src/api/` is gitignored; CI regenerates it and type-checks this example.
diff --git a/tests/e2e/generate-client/examples/sse-streaming/index.html b/tests/e2e/generate-client/examples/sse-streaming/index.html
new file mode 100644
index 0000000000..008f3c9cc0
--- /dev/null
+++ b/tests/e2e/generate-client/examples/sse-streaming/index.html
@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>Redocly client-generator — sse-streaming example</title>
+  </head>
+  <body>
+    <pre id="out">Loading…</pre>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
diff --git a/tests/e2e/generate-client/examples/sse-streaming/openapi.yaml b/tests/e2e/generate-client/examples/sse-streaming/openapi.yaml
new file mode 100644
index 0000000000..2a9a604e2a
--- /dev/null
+++ b/tests/e2e/generate-client/examples/sse-streaming/openapi.yaml
@@ -0,0 +1,58 @@
+openapi: 3.2.0
+info:
+  title: Cafe Order Events
+  description: Demo event-stream API for the sse-streaming example.
+  version: 1.0.0
+servers:
+  - url: https://events.cafe.example.com
+tags:
+  - name: Events
+    description: Live event streams.
+paths:
+  /order-events:
+    get:
+      tags:
+        - Events
+      summary: Stream order status changes
+      operationId: streamOrderEvents
+      responses:
+        '200':
+          description: A stream of order status changes.
+          content:
+            text/event-stream:
+              itemSchema:
+                $ref: '#/components/schemas/OrderEvent'
+  /kitchen-ticker:
+    get:
+      tags:
+        - Events
+      summary: Stream the kitchen ticker
+      operationId: streamKitchenTicker
+      responses:
+        '200':
+          description: A long-lived stream of raw ticker lines.
+          content:
+            text/event-stream: {}
+components:
+  schemas:
+    OrderEvent:
+      type: object
+      properties:
+        orderId:
+          description: Order ID.
+          type: string
+        status:
+          description: New order status.
+          type: string
+          enum:
+            - placed
+            - preparing
+            - ready
+            - completed
+        seq:
+          description: Monotonic event sequence number.
+          type: integer
+      required:
+        - orderId
+        - status
+        - seq
diff --git a/tests/e2e/generate-client/examples/sse-streaming/package.json b/tests/e2e/generate-client/examples/sse-streaming/package.json
new file mode 100644
index 0000000000..dd122ec5e0
--- /dev/null
+++ b/tests/e2e/generate-client/examples/sse-streaming/package.json
@@ -0,0 +1,16 @@
+{
+  "name": "@redocly-examples/sse-streaming",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "generate": "redocly generate-client",
+    "dev": "vite",
+    "build": "vite build"
+  },
+  "devDependencies": {
+    "@redocly/cli": "latest",
+    "typescript": "^5.5.0",
+    "vite": "^5.4.0"
+  }
+}
diff --git a/tests/e2e/generate-client/examples/sse-streaming/redocly.yaml b/tests/e2e/generate-client/examples/sse-streaming/redocly.yaml
new file mode 100644
index 0000000000..29ff096d03
--- /dev/null
+++ b/tests/e2e/generate-client/examples/sse-streaming/redocly.yaml
@@ -0,0 +1,8 @@
+# redocly.yaml — drives `redocly generate-client` for this example.
+apis:
+  sse-streaming:
+    root: ./openapi.yaml
+    clientOutput: ./src/api/client.ts
+    client:
+      generators:
+        - sdk
diff --git a/tests/e2e/generate-client/examples/sse-streaming/src/main.ts b/tests/e2e/generate-client/examples/sse-streaming/src/main.ts
new file mode 100644
index 0000000000..721b54d317
--- /dev/null
+++ b/tests/e2e/generate-client/examples/sse-streaming/src/main.ts
@@ -0,0 +1,76 @@
+// sse-streaming — a `text/event-stream` operation is a typed async generator.
+//
+// `for await (const ev of streamOrderEvents())` yields `ServerSentEvent<OrderEvent>`:
+// `ev.data` is the spec's item schema (`ev.id`/`ev.event`/`ev.retry` are the SSE fields).
+// A DROPPED connection auto-reconnects, resuming via `Last-Event-ID` (backoff: the
+// server's `retry:` value, then `reconnectDelay`, then 1s); a CLEAN stream end finishes
+// the loop. Pass `reconnect: false` to surface drops as errors instead, and an
+// AbortSignal (or `break`) to end the iterator cleanly — no AbortError escapes.
+import {
+  streamKitchenTicker,
+  streamOrderEvents,
+  configure,
+  type OrderEvent,
+} from './api/client.js';
+
+const out = document.querySelector<HTMLPreElement>('#out')!;
+const log: string[] = [];
+
+// A canned SSE transport so the example runs offline and the reconnect is
+// deterministic: connection 1 drops after two events; connection 2 resumes
+// from `Last-Event-ID` and then ends cleanly.
+const encoder = new TextEncoder();
+const frame = (seq: number, status: OrderEvent['status']) =>
+  `id: ${seq}\ndata: ${JSON.stringify({ orderId: `ord_${seq}`, status, seq })}\n\n`;
+const sseBody = (frames: string[], end: 'close' | 'drop' | AbortSignal | null | undefined) =>
+  new ReadableStream<Uint8Array>({
+    start(controller) {
+      for (const f of frames) controller.enqueue(encoder.encode(f));
+      if (end === 'close') controller.close();
+      else if (end === 'drop') controller.error(new Error('connection reset'));
+      // Otherwise hold the stream open until the caller aborts.
+      else end?.addEventListener('abort', () => controller.error(end.reason), { once: true });
+    },
+  });
+
+let connections = 0;
+const canned = (async (url: string, init: RequestInit) => {
+  const { pathname } = new URL(url);
+  const headers = init.headers as Record<string, string>;
+  let body: ReadableStream<Uint8Array>;
+  if (pathname === '/order-events') {
+    connections++;
+    log.push(`connection ${connections} (Last-Event-ID: ${headers['Last-Event-ID'] ?? 'none'})`);
+    body =
+      connections === 1
+        ? sseBody([frame(1, 'placed'), frame(2, 'preparing')], 'drop')
+        : sseBody([frame(3, 'ready'), frame(4, 'completed')], 'close');
+  } else {
+    body = sseBody(['data: espresso up\n\n', 'data: two flat whites\n\n'], init.signal);
+  }
+  return new Response(body, { headers: { 'content-type': 'text/event-stream' } });
+}) as unknown as typeof fetch;
+
+configure({ serverUrl: 'https://events.cafe.example.com', fetch: canned });
+
+async function main() {
+  // 1. Typed events across an auto-reconnect. `reconnectDelay` keeps the demo snappy
+  //    (the real default backs off from 1s, honoring a server `retry:` hint).
+  for await (const ev of streamOrderEvents({ reconnectDelay: 50 })) {
+    log.push(`  #${ev.id} order ${ev.data.orderId} → ${ev.data.status}`);
+  }
+  log.push('order stream ended cleanly (a clean end never reconnects)');
+
+  // 2. Abort a held-open stream: the `for await` loop just ends — no AbortError.
+  //    `reconnect: false` would instead surface a drop as a thrown error.
+  const controller = new AbortController();
+  for await (const ev of streamKitchenTicker({ signal: controller.signal })) {
+    log.push(`  ticker: ${ev.data}`);
+    if (ev.data === 'two flat whites') controller.abort();
+  }
+  log.push('ticker aborted — the iterator completed cleanly');
+
+  out.textContent = log.join('\n');
+}
+
+void main();
diff --git a/tests/e2e/generate-client/examples/sse-streaming/tsconfig.json b/tests/e2e/generate-client/examples/sse-streaming/tsconfig.json
new file mode 100644
index 0000000000..4bd6962d40
--- /dev/null
+++ b/tests/e2e/generate-client/examples/sse-streaming/tsconfig.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../tsconfig.base.json",
+  "include": ["src"]
+}
diff --git a/tests/e2e/generate-client/examples/sse-streaming/vite.config.ts b/tests/e2e/generate-client/examples/sse-streaming/vite.config.ts
new file mode 100644
index 0000000000..c049f46e10
--- /dev/null
+++ b/tests/e2e/generate-client/examples/sse-streaming/vite.config.ts
@@ -0,0 +1,3 @@
+import { defineConfig } from 'vite';
+
+export default defineConfig({});
diff --git a/tests/e2e/generate-client/examples/tanstack-query/.gitignore b/tests/e2e/generate-client/examples/tanstack-query/.gitignore
new file mode 100644
index 0000000000..6eb23affb8
--- /dev/null
+++ b/tests/e2e/generate-client/examples/tanstack-query/.gitignore
@@ -0,0 +1,4 @@
+node_modules
+dist
+src/api/
+package-lock.json
diff --git a/tests/e2e/generate-client/examples/tanstack-query/README.md b/tests/e2e/generate-client/examples/tanstack-query/README.md
new file mode 100644
index 0000000000..19fbc36c6b
--- /dev/null
+++ b/tests/e2e/generate-client/examples/tanstack-query/README.md
@@ -0,0 +1,15 @@
+# tanstack-query example
+
+Generated TypeScript client plus **TanStack Query** (React) factories
+(`generators: ['sdk', 'tanstack-query']`). The app uses `useQuery(<op>Options())` under a
+`QueryClientProvider`.
+
+## Run
+
+```bash
+npm install
+npm run generate   # generate src/api (the client is gitignored)
+npm run dev        # open the printed local URL
+```
+
+The generated client + TanStack factories under `src/api/` are gitignored; CI regenerates them and type-checks this example.
diff --git a/tests/e2e/generate-client/examples/tanstack-query/index.html b/tests/e2e/generate-client/examples/tanstack-query/index.html
new file mode 100644
index 0000000000..3e8b0cc40b
--- /dev/null
+++ b/tests/e2e/generate-client/examples/tanstack-query/index.html
@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>Redocly client-generator — tanstack-query example</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
diff --git a/tests/e2e/generate-client/examples/tanstack-query/package.json b/tests/e2e/generate-client/examples/tanstack-query/package.json
new file mode 100644
index 0000000000..49d2822510
--- /dev/null
+++ b/tests/e2e/generate-client/examples/tanstack-query/package.json
@@ -0,0 +1,24 @@
+{
+  "name": "@redocly-examples/tanstack-query",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "generate": "redocly generate-client",
+    "dev": "vite",
+    "build": "vite build"
+  },
+  "dependencies": {
+    "@tanstack/react-query": "^5.0.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@redocly/cli": "latest",
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "@vitejs/plugin-react": "^4.3.0",
+    "typescript": "^5.5.0",
+    "vite": "^5.4.0"
+  }
+}
diff --git a/tests/e2e/generate-client/examples/tanstack-query/redocly.yaml b/tests/e2e/generate-client/examples/tanstack-query/redocly.yaml
new file mode 100644
index 0000000000..7572c29f9d
--- /dev/null
+++ b/tests/e2e/generate-client/examples/tanstack-query/redocly.yaml
@@ -0,0 +1,11 @@
+# redocly.yaml — drives `redocly generate-client` for this example.
+# The client is generated for the api that declares a `client` block
+# (run `redocly generate-client` with no args to build every such api).
+apis:
+  tanstack-query:
+    root: ../_shared/cafe.yaml
+    clientOutput: ./src/api/client.ts
+    client:
+      generators:
+        - sdk
+        - tanstack-query
diff --git a/tests/e2e/generate-client/examples/tanstack-query/src/App.tsx b/tests/e2e/generate-client/examples/tanstack-query/src/App.tsx
new file mode 100644
index 0000000000..f8aa426f4a
--- /dev/null
+++ b/tests/e2e/generate-client/examples/tanstack-query/src/App.tsx
@@ -0,0 +1,13 @@
+import { useQuery } from '@tanstack/react-query';
+
+import { configure } from './api/client.js';
+import { listMenuItemsOptions } from './api/client.tanstack.js';
+
+configure({ serverUrl: 'https://api.cafe.redocly.com' });
+
+export function App() {
+  const { data, error, isLoading } = useQuery(listMenuItemsOptions({}));
+  if (isLoading) return <p>Loading…</p>;
+  if (error) return <p>Error: {String(error)}</p>;
+  return <pre>{JSON.stringify(data, null, 2)}</pre>;
+}
diff --git a/tests/e2e/generate-client/examples/tanstack-query/src/main.tsx b/tests/e2e/generate-client/examples/tanstack-query/src/main.tsx
new file mode 100644
index 0000000000..0184b35f37
--- /dev/null
+++ b/tests/e2e/generate-client/examples/tanstack-query/src/main.tsx
@@ -0,0 +1,15 @@
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import React from 'react';
+import { createRoot } from 'react-dom/client';
+
+import { App } from './App.js';
+
+const queryClient = new QueryClient();
+
+createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <QueryClientProvider client={queryClient}>
+      <App />
+    </QueryClientProvider>
+  </React.StrictMode>
+);
diff --git a/tests/e2e/generate-client/examples/tanstack-query/tsconfig.json b/tests/e2e/generate-client/examples/tanstack-query/tsconfig.json
new file mode 100644
index 0000000000..5e95adc139
--- /dev/null
+++ b/tests/e2e/generate-client/examples/tanstack-query/tsconfig.json
@@ -0,0 +1,7 @@
+{
+  "extends": "../tsconfig.base.json",
+  "compilerOptions": {
+    "jsx": "react-jsx"
+  },
+  "include": ["src"]
+}
diff --git a/tests/e2e/generate-client/examples/tanstack-query/vite.config.ts b/tests/e2e/generate-client/examples/tanstack-query/vite.config.ts
new file mode 100644
index 0000000000..f1134976b7
--- /dev/null
+++ b/tests/e2e/generate-client/examples/tanstack-query/vite.config.ts
@@ -0,0 +1,4 @@
+import react from '@vitejs/plugin-react';
+import { defineConfig } from 'vite';
+
+export default defineConfig({ plugins: [react()] });
diff --git a/tests/e2e/generate-client/examples/tsconfig.base.json b/tests/e2e/generate-client/examples/tsconfig.base.json
new file mode 100644
index 0000000000..59c1ef1ffb
--- /dev/null
+++ b/tests/e2e/generate-client/examples/tsconfig.base.json
@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "noEmit": true,
+    "skipLibCheck": true,
+    "verbatimModuleSyntax": true
+  }
+}
diff --git a/tests/e2e/generate-client/examples/vendored-edge/.gitignore b/tests/e2e/generate-client/examples/vendored-edge/.gitignore
new file mode 100644
index 0000000000..612acc5cae
--- /dev/null
+++ b/tests/e2e/generate-client/examples/vendored-edge/.gitignore
@@ -0,0 +1,3 @@
+node_modules
+src/api/
+package-lock.json
diff --git a/tests/e2e/generate-client/examples/vendored-edge/README.md b/tests/e2e/generate-client/examples/vendored-edge/README.md
new file mode 100644
index 0000000000..76e2de6fe2
--- /dev/null
+++ b/tests/e2e/generate-client/examples/vendored-edge/README.md
@@ -0,0 +1,19 @@
+# vendored-edge example
+
+The self-contained story taken to its end: the client was generated **once** and the single
+output file copied into this directory. `src/api/client.ts` imports nothing, so the same file
+runs on Cloudflare Workers, Deno Deploy, Bun, or any runtime with web-standard `fetch` —
+no npm install, no node_modules at runtime. `worker.ts` is an edge-style handler
+(`export default { fetch }`) that proxies the cafe API through the vendored client.
+
+## Use
+
+```bash
+npm install         # typescript only — and only to type-check
+npm run generate    # generate src/api (the client is gitignored)
+npm run typecheck
+```
+
+To re-vendor after a spec change, run `redocly generate-client` wherever the CLI is available
+and copy the new `client.ts` over. The `redocly.yaml` here records how the file was produced;
+the repo's CI uses it to drift-check the vendored copy against the generator.
diff --git a/tests/e2e/generate-client/examples/vendored-edge/openapi.yaml b/tests/e2e/generate-client/examples/vendored-edge/openapi.yaml
new file mode 100644
index 0000000000..66d1b5d8f4
--- /dev/null
+++ b/tests/e2e/generate-client/examples/vendored-edge/openapi.yaml
@@ -0,0 +1,97 @@
+openapi: 3.2.0
+info:
+  title: Cafe Menu Upstream
+  description: The upstream API the vendored-edge worker proxies.
+  version: 1.0.0
+servers:
+  - url: https://api.cafe.redocly.com
+    description: Live demo server.
+tags:
+  - name: Products
+    description: Menu operations.
+paths:
+  /menu:
+    get:
+      tags:
+        - Products
+      summary: List all menu items
+      operationId: listMenuItems
+      security: []
+      parameters:
+        - name: search
+          in: query
+          required: false
+          description: Case-insensitive substring match on item names.
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Successful operation.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MenuItemList'
+  /menu-item-images/{menuItemId}:
+    get:
+      tags:
+        - Products
+      summary: Retrieve a menu item photo
+      operationId: getMenuItemPhoto
+      security: []
+      parameters:
+        - name: menuItemId
+          in: path
+          required: true
+          description: ID of the menu item.
+          schema:
+            type: string
+        - name: photoSize
+          in: query
+          required: false
+          description: Photo size to retrieve.
+          schema:
+            type: string
+            enum:
+              - thumbnail
+              - medium
+              - large
+            default: medium
+      responses:
+        '200':
+          description: Menu item photo.
+          content:
+            image/png:
+              schema:
+                type: string
+                format: binary
+            text/plain:
+              schema:
+                description: Alternative image text.
+                type: string
+components:
+  schemas:
+    MenuItem:
+      type: object
+      properties:
+        id:
+          description: Menu item ID.
+          type: string
+        name:
+          description: Menu item name.
+          type: string
+        price:
+          description: Price in cents.
+          type: integer
+      required:
+        - id
+        - name
+        - price
+    MenuItemList:
+      type: object
+      properties:
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/MenuItem'
+      required:
+        - items
diff --git a/tests/e2e/generate-client/examples/vendored-edge/package.json b/tests/e2e/generate-client/examples/vendored-edge/package.json
new file mode 100644
index 0000000000..cac5795aa5
--- /dev/null
+++ b/tests/e2e/generate-client/examples/vendored-edge/package.json
@@ -0,0 +1,12 @@
+{
+  "name": "@redocly-examples/vendored-edge",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0"
+  }
+}
diff --git a/tests/e2e/generate-client/examples/vendored-edge/redocly.yaml b/tests/e2e/generate-client/examples/vendored-edge/redocly.yaml
new file mode 100644
index 0000000000..7bf35132be
--- /dev/null
+++ b/tests/e2e/generate-client/examples/vendored-edge/redocly.yaml
@@ -0,0 +1,10 @@
+# redocly.yaml — how the vendored src/api/client.ts was produced (and how the
+# repo's CI drift-checks it). The deployed worker does NOT need this file or the
+# CLI: the client is generated once, then the single output file is copied in.
+apis:
+  vendored-edge:
+    root: ./openapi.yaml
+    clientOutput: ./src/api/client.ts
+    client:
+      generators:
+        - sdk
diff --git a/tests/e2e/generate-client/examples/vendored-edge/tsconfig.json b/tests/e2e/generate-client/examples/vendored-edge/tsconfig.json
new file mode 100644
index 0000000000..c517a7d7eb
--- /dev/null
+++ b/tests/e2e/generate-client/examples/vendored-edge/tsconfig.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../tsconfig.base.json",
+  "include": ["worker.ts", "src"]
+}
diff --git a/tests/e2e/generate-client/examples/vendored-edge/worker.ts b/tests/e2e/generate-client/examples/vendored-edge/worker.ts
new file mode 100644
index 0000000000..d395a7868a
--- /dev/null
+++ b/tests/e2e/generate-client/examples/vendored-edge/worker.ts
@@ -0,0 +1,38 @@
+// vendored-edge — the generated client as a VENDORED artifact.
+//
+// `src/api/client.ts` was generated once and copied in. It imports nothing, so
+// the same file runs anywhere web-standard `fetch` exists — Cloudflare Workers,
+// Deno Deploy, Bun, a browser — with no package.json dependencies and no
+// node_modules at runtime. This is an edge-style handler (the
+// `export default { fetch }` shape) proxying the upstream cafe API through the
+// vendored client; `typescript` is the only dev tool here, and only to type-check.
+import { ApiError, client } from './src/api/client.js';
+
+export default {
+  async fetch(request: Request): Promise<Response> {
+    const url = new URL(request.url);
+    try {
+      if (url.pathname === '/menu') {
+        const menu = await client.listMenuItems({
+          params: { search: url.searchParams.get('search') ?? undefined },
+        });
+        return Response.json(menu.items);
+      }
+      const photo = url.pathname.match(/^\/photo\/(?<menuItemId>[^/]+)$/);
+      if (photo?.groups) {
+        const image = await client.getMenuItemPhoto({
+          menuItemId: photo.groups.menuItemId,
+          params: { photoSize: 'thumbnail' },
+        });
+        return image instanceof Blob
+          ? new Response(image, { headers: { 'content-type': image.type } })
+          : new Response(image);
+      }
+      return new Response('Not found', { status: 404 });
+    } catch (error) {
+      // The upstream's error body passes through with its status; anything else is a 502.
+      if (error instanceof ApiError) return Response.json(error.body, { status: error.status });
+      return new Response('Upstream unavailable', { status: 502 });
+    }
+  },
+};
diff --git a/tests/e2e/generate-client/examples/zero-install-quickstart/.gitignore b/tests/e2e/generate-client/examples/zero-install-quickstart/.gitignore
new file mode 100644
index 0000000000..d5f19d89b3
--- /dev/null
+++ b/tests/e2e/generate-client/examples/zero-install-quickstart/.gitignore
@@ -0,0 +1,2 @@
+node_modules
+package-lock.json
diff --git a/tests/e2e/generate-client/examples/zero-install-quickstart/README.md b/tests/e2e/generate-client/examples/zero-install-quickstart/README.md
new file mode 100644
index 0000000000..1ce46cf84c
--- /dev/null
+++ b/tests/e2e/generate-client/examples/zero-install-quickstart/README.md
@@ -0,0 +1,15 @@
+# zero-install-quickstart example
+
+The first-touch loop: `redocly generate-client` → import → call. The generated
+`src/api/client.ts` is one self-contained file with **zero runtime dependencies** —
+nothing to install, nothing to keep in sync with a client library.
+
+## Run
+
+```bash
+npm install        # dev tooling only (the CLI + tsx); the client itself needs nothing
+npm run generate   # regenerate src/api from openapi.yaml (optional; client is checked in)
+npm start          # calls the live cafe demo API and prints the menu
+```
+
+The generated client under `src/api/` is committed and drift-checked against the generator in CI.
diff --git a/tests/e2e/generate-client/examples/zero-install-quickstart/openapi.yaml b/tests/e2e/generate-client/examples/zero-install-quickstart/openapi.yaml
new file mode 100644
index 0000000000..671443f1d8
--- /dev/null
+++ b/tests/e2e/generate-client/examples/zero-install-quickstart/openapi.yaml
@@ -0,0 +1,148 @@
+openapi: 3.2.0
+info:
+  title: Cafe Menu Quickstart
+  description: A tiny slice of the Redocly Cafe demo API — just enough for a first call.
+  version: 1.0.0
+servers:
+  - url: https://api.cafe.redocly.com
+    description: Live demo server.
+tags:
+  - name: Products
+    description: Menu operations.
+  - name: Authorization
+    description: Demo credentials.
+paths:
+  /menu:
+    get:
+      tags:
+        - Products
+      summary: List all menu items
+      operationId: listMenuItems
+      security: []
+      parameters:
+        - name: search
+          in: query
+          required: false
+          description: Case-insensitive substring match on item names.
+          schema:
+            type: string
+        - name: limit
+          in: query
+          required: false
+          description: Number of results per page.
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 10
+      responses:
+        '200':
+          description: Successful operation.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MenuItemList'
+  /menu-item-images/{menuItemId}:
+    get:
+      tags:
+        - Products
+      summary: Retrieve a menu item photo
+      operationId: getMenuItemPhoto
+      security: []
+      parameters:
+        - name: menuItemId
+          in: path
+          required: true
+          description: ID of the menu item.
+          schema:
+            type: string
+        - name: photoSize
+          in: query
+          required: false
+          description: Photo size to retrieve.
+          schema:
+            type: string
+            enum:
+              - thumbnail
+              - medium
+              - large
+            default: medium
+      responses:
+        '200':
+          description: Menu item photo.
+          content:
+            image/png:
+              schema:
+                type: string
+                format: binary
+            text/plain:
+              schema:
+                description: Alternative image text.
+                type: string
+  /oauth2/register:
+    post:
+      tags:
+        - Authorization
+      summary: Create OAuth2 client
+      operationId: registerOAuth2Client
+      security: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RegisterClientRequest'
+      responses:
+        '201':
+          description: OAuth2 client registered.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OAuth2Client'
+components:
+  schemas:
+    MenuItem:
+      type: object
+      properties:
+        id:
+          description: Menu item ID.
+          type: string
+        name:
+          description: Menu item name.
+          type: string
+        price:
+          description: Price in cents.
+          type: integer
+      required:
+        - id
+        - name
+        - price
+    MenuItemList:
+      type: object
+      properties:
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/MenuItem'
+      required:
+        - items
+    RegisterClientRequest:
+      type: object
+      properties:
+        name:
+          description: Client name.
+          type: string
+      required:
+        - name
+    OAuth2Client:
+      type: object
+      properties:
+        clientId:
+          description: Client identifier issued by the authorization server.
+          type: string
+        clientSecret:
+          description: Client secret issued by the authorization server.
+          type: string
+      required:
+        - clientId
+        - clientSecret
diff --git a/tests/e2e/generate-client/examples/zero-install-quickstart/package.json b/tests/e2e/generate-client/examples/zero-install-quickstart/package.json
new file mode 100644
index 0000000000..53c7930021
--- /dev/null
+++ b/tests/e2e/generate-client/examples/zero-install-quickstart/package.json
@@ -0,0 +1,15 @@
+{
+  "name": "@redocly-examples/zero-install-quickstart",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "generate": "redocly generate-client",
+    "start": "tsx src/main.ts"
+  },
+  "devDependencies": {
+    "@redocly/cli": "latest",
+    "tsx": "^4.0.0",
+    "typescript": "^5.5.0"
+  }
+}
diff --git a/tests/e2e/generate-client/examples/zero-install-quickstart/redocly.yaml b/tests/e2e/generate-client/examples/zero-install-quickstart/redocly.yaml
new file mode 100644
index 0000000000..be28cd8da3
--- /dev/null
+++ b/tests/e2e/generate-client/examples/zero-install-quickstart/redocly.yaml
@@ -0,0 +1,8 @@
+# redocly.yaml — drives `redocly generate-client` for this example.
+apis:
+  zero-install-quickstart:
+    root: ./openapi.yaml
+    clientOutput: ./src/api/client.ts
+    client:
+      generators:
+        - sdk
diff --git a/tests/e2e/generate-client/examples/zero-install-quickstart/src/api/client.ts b/tests/e2e/generate-client/examples/zero-install-quickstart/src/api/client.ts
new file mode 100644
index 0000000000..96bf3a116d
--- /dev/null
+++ b/tests/e2e/generate-client/examples/zero-install-quickstart/src/api/client.ts
@@ -0,0 +1,1124 @@
+// Generated by @redocly/client-generator — do not edit by hand.
+// Source: OpenAPI document. Re-run `redocly generate-client` to update.
+
+/**
+ * Cafe Menu Quickstart (v1.0.0)
+ * A tiny slice of the Redocly Cafe demo API — just enough for a first call.
+ */
+
+export type MenuItem = {
+    /**
+     * Menu item ID.
+     */
+    id: string;
+    /**
+     * Menu item name.
+     */
+    name: string;
+    /**
+     * Price in cents.
+     */
+    price: number;
+};
+
+export type MenuItemList = {
+    items: MenuItem[];
+};
+
+export type RegisterClientRequest = {
+    /**
+     * Client name.
+     */
+    name: string;
+};
+
+export type OAuth2Client = {
+    /**
+     * Client identifier issued by the authorization server.
+     */
+    clientId: string;
+    /**
+     * Client secret issued by the authorization server.
+     */
+    clientSecret: string;
+};
+
+export type ListMenuItemsResult = MenuItemList;
+
+export type ListMenuItemsParams = {
+    /**
+     * Case-insensitive substring match on item names.
+     */
+    search?: string;
+    /**
+     * Number of results per page.
+     * @minimum 1
+     * @maximum 100
+     */
+    limit?: number;
+};
+
+export type ListMenuItemsVariables = {
+    params?: ListMenuItemsParams;
+};
+
+export type GetMenuItemPhotoResult = Blob | string;
+
+export type GetMenuItemPhotoParams = {
+    /**
+     * Photo size to retrieve.
+     */
+    photoSize?: "thumbnail" | "medium" | "large";
+};
+
+export type GetMenuItemPhotoVariables = {
+    /**
+     * ID of the menu item.
+     */
+    menuItemId: string;
+    params?: GetMenuItemPhotoParams;
+};
+
+export type RegisterOAuth2ClientResult = OAuth2Client;
+
+export type RegisterOAuth2ClientBody = RegisterClientRequest;
+
+export type RegisterOAuth2ClientVariables = {
+    body: RegisterOAuth2ClientBody;
+};
+
+/**
+ * Per-operation `args`/`result` shapes (plus `kind: 'sse'` for event streams) — the
+ * type-level companion of `OPERATIONS` that gives `createClient<Ops>` its typed methods.
+ */
+export type Ops = {
+    listMenuItems: {
+        args: {
+            params?: ListMenuItemsParams;
+        };
+        result: ListMenuItemsResult;
+    };
+    getMenuItemPhoto: {
+        args: {
+            /**
+             * ID of the menu item.
+             */
+            menuItemId: string;
+            params?: GetMenuItemPhotoParams;
+        };
+        result: GetMenuItemPhotoResult;
+    };
+    registerOAuth2Client: {
+        args: {
+            body: RegisterOAuth2ClientBody;
+        };
+        result: RegisterOAuth2ClientResult;
+    };
+};
+
+/**
+ * The wire-shape descriptor for every operation, keyed by operationId — the data the
+ * runtime routes requests by. Also minification-safe static metadata (method, path,
+ * tags) for cache keys, tracing span names, and request logging.
+ */
+export const OPERATIONS = {
+    listMenuItems: { id: "listMenuItems", method: "GET", path: "/menu", tags: ["Products"], params: [{ name: "search", in: "query" }, { name: "limit", in: "query" }] },
+    getMenuItemPhoto: { id: "getMenuItemPhoto", method: "GET", path: "/menu-item-images/{menuItemId}", tags: ["Products"], params: [{ name: "menuItemId", in: "path" }, { name: "photoSize", in: "query" }], responseKind: "blob" },
+    registerOAuth2Client: { id: "registerOAuth2Client", method: "POST", path: "/oauth2/register", tags: ["Authorization"], body: { contentType: "application/json" } }
+} as const satisfies Record<string, OperationDescriptor>;
+
+export type OperationId = keyof typeof OPERATIONS;
+
+export type OperationPath = (typeof OPERATIONS)[OperationId]["path"];
+
+export type OperationTag = Extract<(typeof OPERATIONS)[OperationId], {
+    tags: readonly string[];
+}>["tags"][number];
+
+// ─── Embedded runtime (@redocly/client-generator, assembled per this API's needs) ───
+
+/**
+ * The public type surface of the client runtime — `@redocly/client-generator`'s
+ * app-facing runtime module. Pure types, no runtime code (excluded from coverage).
+ * The generator emits `OPERATIONS` literals typed
+ * `satisfies Record<string, OperationDescriptor>` against this module, so an
+ * incompatible runtime/generated pair fails the consumer's build (the semver skew guard).
+ */
+
+/** How one operation parameter is sent: its location plus OpenAPI query-serialization hints. */
+export type ParamSpec = {
+  name: string;
+  in: 'path' | 'query' | 'header' | 'cookie';
+  style?: 'form' | 'spaceDelimited' | 'pipeDelimited' | 'deepObject';
+  explode?: boolean;
+  allowReserved?: boolean;
+};
+
+/** One security scheme, denormalized onto the operation (`scheme` names the spec's scheme). */
+export type SecuritySpec =
+  | { scheme: string; kind: 'bearer' | 'basic' }
+  | { scheme: string; kind: 'apiKey'; name: string; in: 'header' | 'query' | 'cookie' };
+
+/**
+ * How to auto-iterate a paginated operation (drives its `.pages()`/`.items()` members).
+ * `nextCursor` and `items` are RFC 6901 JSON pointers into the page (response) value.
+ */
+export type PaginationSpec = {
+  style: 'cursor' | 'offset' | 'page';
+  /** The query param the iterator advances: the cursor (`cursor`) or number (`offset`/`page`). */
+  param: string;
+  /** Optional page-size query param (recorded for tooling; never set by the runtime). */
+  limitParam?: string;
+  /** Cursor style only: pointer to the next cursor in the page. */
+  nextCursor?: string;
+  /** Cursor style only: optional pointer to a boolean "more pages" flag — `false` stops iteration. */
+  hasMore?: string;
+  /** Pointer to the page's item array. */
+  items: string;
+};
+
+/** The frozen data contract between generated code and the runtime: one operation's wire shape. */
+export type OperationDescriptor = {
+  id: string;
+  method: string;
+  path: string;
+  tags?: readonly string[];
+  params?: readonly ParamSpec[];
+  /** `multipart: true` marks a typed object body serialized to FormData by the runtime. */
+  body?: { contentType: string; multipart?: boolean };
+  /** Defaults to `'json'` (content-type negotiation on parse). */
+  responseKind?: 'json' | 'text' | 'blob' | 'void' | 'sse';
+  sseDataKind?: 'json' | 'text';
+  /** OR-alternatives, each an AND-set: the runtime applies the first fully-configured one. */
+  security?: readonly (readonly SecuritySpec[])[];
+  pagination?: PaginationSpec;
+};
+
+/** A query value: scalars, arrays of scalars, or objects (serialized as deepObject brackets). */
+export type QueryValue =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | Array<string | number | boolean | null | undefined>
+  | Record<string, unknown>;
+
+/** A credential: a literal, or a (possibly async) function resolved per request (refresh flows). */
+export type TokenProvider = string | (() => string | Promise<string>);
+
+/** Per-instance credentials, keyed by the scheme kinds the runtime can inject. */
+export type AuthCredentials = {
+  bearer?: TokenProvider;
+  basic?: { username: string; password: string };
+  apiKey?: Record<string, TokenProvider>;
+};
+
+/** Backoff shape: 'fixed' = constant delay; 'exponential' = doubling per attempt. */
+export type RetryStrategy = 'fixed' | 'exponential';
+
+/**
+ * The operation's identity, exposed to middleware for targeting (`ctx.operation`).
+ * Generated clients instantiate the type parameters with the spec's literal unions
+ * (`OperationId`/`OperationPath`/`OperationTag`) so a misspelled operation id in a
+ * middleware comparison fails to compile; the string defaults keep every
+ * spec-independent consumer (`runtime-contract.ts`, the runtime internals) working
+ * with the base shape. `tags` stays mutable (`Tag[]`) so setup-contract types
+ * (byte-locked to generated output) remain assignable through middleware callbacks.
+ */
+export type OperationContext<
+  Id extends string = string,
+  Path extends string = string,
+  Tag extends string = string,
+> = { id: Id; path: Path; tags: Tag[] };
+
+/** The mutable request context threaded through the middleware chain. */
+export type RequestContext<Op extends OperationContext = OperationContext> = {
+  url: string;
+  method: string;
+  headers: Record<string, string>;
+  body?: unknown;
+  operation: Op;
+};
+
+/** The failed attempt handed to a custom `retryOn`: exactly one of `response`/`error` is set. */
+export type RetryContext<Op extends OperationContext = OperationContext> = {
+  attempt: number;
+  request: RequestContext<Op>;
+  response?: Response;
+  error?: unknown;
+};
+
+/** Opt-in retry policy; a per-call override merges field-by-field over the config policy. */
+export type RetryConfig<Op extends OperationContext = OperationContext> = {
+  retries?: number;
+  retryDelay?: number;
+  retryStrategy?: RetryStrategy;
+  jitter?: boolean;
+  retryOn?: (ctx: RetryContext<Op>) => boolean | Promise<boolean>;
+};
+
+/**
+ * Structural stand-in for the runtime's ApiError so this module stays import-free
+ * (pure types); the real `ApiError` class is assignable to it.
+ */
+export type ApiErrorLike = globalThis.Error & {
+  url: string;
+  status: number;
+  statusText: string;
+  body: unknown;
+};
+
+/** One interceptor: any subset of the three hooks. */
+export type Middleware<Op extends OperationContext = OperationContext> = {
+  onRequest?: (ctx: RequestContext<Op>) => void | Promise<void>;
+  onResponse?: (
+    response: Response,
+    ctx: RequestContext<Op>
+  ) => Response | void | Promise<Response | void>;
+  /** Throw mode only: may map/replace the error. */
+  // `globalThis.Error` so a spec schema named `Error` cannot shadow it in inline mode.
+  onError?: (
+    error: ApiErrorLike,
+    ctx: RequestContext<Op>
+  ) => globalThis.Error | Promise<globalThis.Error>;
+};
+
+/** Client configuration: transport, defaults, retry policy, middleware, and credentials. */
+export type ClientConfig<Op extends OperationContext = OperationContext> = {
+  serverUrl?: string;
+  fetch?: typeof fetch;
+  headers?:
+    | Record<string, string>
+    | (() => Record<string, string> | Promise<Record<string, string>>);
+  retry?: RetryConfig<Op>;
+  middleware?: Middleware<Op>[];
+  auth?: AuthCredentials;
+  /** Fixed at generate time by the generator (`'throw'` when omitted); `configure()` ignores it. */
+  errorMode?: 'throw' | 'result';
+  onRequest?: Middleware<Op>['onRequest'];
+  onResponse?: Middleware<Op>['onResponse'];
+  onError?: Middleware<Op>['onError'];
+};
+
+/** Response readers for the per-call `parseAs` override. */
+export type ParseAs = 'auto' | 'json' | 'text' | 'blob' | 'arrayBuffer' | 'formData' | 'stream';
+
+/** Per-call options: standard `RequestInit` plus a retry override and a forced reader. */
+export type RequestOptions = RequestInit & { retry?: RetryConfig; parseAs?: ParseAs };
+
+/** Per-call options for an SSE stream; reconnect defaults to true. */
+export type SseOptions = RequestInit & { reconnect?: boolean; reconnectDelay?: number };
+
+/** A single decoded Server-Sent Event with its payload typed from the spec. */
+export type ServerSentEvent<T> = { event?: string; data: T; id?: string; retry?: number };
+
+/** Result-mode return shape: exactly one of `data`/`error` is set. */
+export type Result<TData, TError> =
+  | { data: TData; error: undefined; response: Response }
+  | { data: undefined; error: TError; response: Response };
+
+/**
+ * The generated `Ops` type's shape: per-operation args/result, plus `kind: 'sse'` for
+ * streams and, for paginated operations, `item` (the page's element type) and — on
+ * result-mode clients only — `page` (the RAW page type `.pages()` yields, since
+ * iteration unwraps the `Result` envelope the one-shot `result` carries).
+ */
+export type OpsShape = Record<
+  string,
+  { args: object; result: unknown; kind?: 'sse'; item?: unknown; page?: unknown }
+>;
+
+/** The always-present client members (assigned after the operation loop — they win collisions). */
+export type ClientCore<Op extends OperationContext = OperationContext> = {
+  /** Merge into the config; note `middleware` REPLACES the chain (use `use()` to compose). */
+  configure(config: ClientConfig<Op>): void;
+  /** Append interceptors (composes with baked/publisher middleware). */
+  use(...middleware: Middleware<Op>[]): void;
+  auth: {
+    bearer(token: TokenProvider): void;
+    basic(username: string, password: string): void;
+    apiKey(scheme: string, value: TokenProvider): void;
+  };
+};
+
+/**
+ * The standard TypeScript optionality probe: `{}` has no required members, so
+ * `{} extends A` is true exactly when every member of `A` is optional.
+ */
+// oxlint-disable-next-line typescript/no-empty-object-type
+type NoRequiredKeys<A> = {} extends A ? true : false;
+
+/**
+ * The page type `.pages()` yields: the RAW page declared by `page` (the generator
+ * writes it only on result-mode paginated entries, whose `result` is the envelope),
+ * or the method's own `result` (throw mode — already the raw page).
+ */
+type PageOf<Entry extends OpsShape[string]> = Entry extends { page: unknown }
+  ? Entry['page']
+  : Entry['result'];
+
+/**
+ * The auto-pagination members intersected onto a paginated method — present exactly when
+ * the Ops entry declares `item` (the generator writes it only for paginated operations).
+ * Args optionality mirrors the method's own; `unknown` otherwise (identity under `&`).
+ * Iteration is error-mode-agnostic: `.pages()`/`.items()` yield raw pages/items, and a
+ * failed page aborts iteration by throwing `ApiError`, even on result-mode clients; the
+ * `onError` middleware hook (throw-mode-only) is not invoked.
+ */
+type Paginated<Entry extends OpsShape[string]> = 'item' extends keyof Entry
+  ? NoRequiredKeys<Entry['args']> extends true
+    ? {
+        pages(args?: Entry['args'], init?: RequestOptions): AsyncGenerator<PageOf<Entry>>;
+        items(args?: Entry['args'], init?: RequestOptions): AsyncGenerator<Entry['item']>;
+      }
+    : {
+        pages(args: Entry['args'], init?: RequestOptions): AsyncGenerator<PageOf<Entry>>;
+        items(args: Entry['args'], init?: RequestOptions): AsyncGenerator<Entry['item']>;
+      }
+  : unknown;
+
+/** The typed instance client: one bound method per operation plus the core members. */
+export type Client<Ops extends OpsShape, Op extends OperationContext = OperationContext> = {
+  [K in keyof Ops]: Ops[K] extends { kind: 'sse' }
+    ? NoRequiredKeys<Ops[K]['args']> extends true
+      ? (
+          args?: Ops[K]['args'],
+          init?: SseOptions
+        ) => AsyncGenerator<ServerSentEvent<Ops[K]['result']>>
+      : (
+          args: Ops[K]['args'],
+          init?: SseOptions
+        ) => AsyncGenerator<ServerSentEvent<Ops[K]['result']>>
+    : (NoRequiredKeys<Ops[K]['args']> extends true
+        ? (args?: Ops[K]['args'], init?: RequestOptions) => Promise<Ops[K]['result']>
+        : (args: Ops[K]['args'], init?: RequestOptions) => Promise<Ops[K]['result']>) &
+        Paginated<Ops[K]>;
+} & ClientCore<Op>;
+
+/** The error thrown (throw mode) for a non-2xx response, carrying the decoded error body. */
+export class ApiError extends Error {
+  public readonly url: string;
+  public readonly status: number;
+  public readonly statusText: string;
+  public readonly body: unknown;
+  constructor(url: string, status: number, statusText: string, body: unknown) {
+    super(`Request failed with status ${status}`);
+    this.name = 'ApiError';
+    this.url = url;
+    this.status = status;
+    this.statusText = statusText;
+    this.body = body;
+  }
+}
+
+/** The error to throw for an aborted request: the caller's abort reason when it is an Error. */
+// `globalThis.Error` (not bare `Error`) so a spec schema named `Error` cannot shadow it
+// when this module is embedded alongside generated types (inline mode).
+function abortError(signal: AbortSignal): globalThis.Error {
+  const reason = (signal as { reason?: unknown }).reason;
+  if (reason instanceof Error) return reason;
+  return new DOMException('The operation was aborted.', 'AbortError');
+}
+
+/**
+ * The RESOLVED OpenAPI serialization spec for one query parameter — callers apply the
+ * OpenAPI defaults (`style: 'form'`, `explode: true`) before building one.
+ */
+type QueryStyle = {
+  style: NonNullable<ParamSpec['style']>;
+  explode: boolean;
+  allowReserved?: boolean;
+};
+
+/**
+ * Encode everything except the RFC-3986 reserved set, for `allowReserved: true` params —
+ * `filter=a/b` survives instead of `filter=a%2Fb`.
+ */
+function encodeReserved(value: string): string {
+  return encodeURIComponent(value).replace(
+    /%(3A|2F|3F|23|5B|5D|40|21|24|26|27|28|29|2A|2B|2C|3B|3D)/g,
+    (match) => decodeURIComponent(match)
+  );
+}
+
+/** Substitute `{name}` template segments with encoded values; a missing value is a caller bug. */
+function substitutePath(template: string, values: Record<string, unknown>): string {
+  return template.replace(/\{([^{}]+)\}/g, (_match, name: string) => {
+    const value = values[name];
+    if (value === undefined) throw new Error(`Missing path parameter "${name}"`);
+    return encodeURIComponent(String(value));
+  });
+}
+
+/**
+ * Build the request URL: `serverUrl` (trailing slash trimmed) + path + serialized query.
+ * Query parameters honor their OpenAPI `style`/`explode`/`allowReserved` (from `styles`);
+ * without a spec, arrays repeat the key (`form`+`explode`), objects serialize as
+ * `deepObject` brackets, and `null`/`undefined` entries are skipped.
+ */
+function buildUrl(
+  serverUrl: string,
+  path: string,
+  query?: Record<string, QueryValue>,
+  styles?: Record<string, QueryStyle>
+): string {
+  // Trim trailing slashes with a scan, not `/\/+$/` — an anchored `+` regex is
+  // quadratic on adversarial many-slash input (the server URL is caller data).
+  let end = serverUrl.length;
+  while (end > 0 && serverUrl.charCodeAt(end - 1) === 47 /* '/' */) end--;
+  const url = serverUrl.slice(0, end) + path;
+  if (!query) return url;
+  const params = new URLSearchParams();
+  const raw: string[] = [];
+  for (const [key, value] of Object.entries(query)) {
+    if (value === undefined || value === null) continue;
+    const spec = styles?.[key];
+    if (!spec) {
+      if (Array.isArray(value)) {
+        for (const v of value) {
+          if (v !== undefined && v !== null) params.append(key, String(v));
+        }
+      } else if (Object(value) === value) {
+        // Object-valued query params use `deepObject` style: key[subKey]=subValue.
+        for (const [subKey, subValue] of Object.entries(value)) {
+          if (subValue !== undefined && subValue !== null) {
+            params.append(`${key}[${subKey}]`, String(subValue));
+          }
+        }
+      } else {
+        params.append(key, String(value));
+      }
+      continue;
+    }
+    if (Array.isArray(value)) {
+      const items = value.filter((v) => v !== undefined && v !== null).map(String);
+      if (spec.style === 'form' && spec.explode) {
+        for (const v of items) {
+          if (spec.allowReserved) raw.push(`${key}=${encodeReserved(v)}`);
+          else params.append(key, v);
+        }
+      } else {
+        // Delimited styles put the LITERAL delimiter on the wire; only the
+        // values are encoded. `%20` (not `+`) is the literal space delimiter.
+        const delim =
+          spec.style === 'pipeDelimited' ? '|' : spec.style === 'spaceDelimited' ? '%20' : ',';
+        const enc = spec.allowReserved ? encodeReserved : encodeURIComponent;
+        raw.push(`${encodeURIComponent(key)}=${items.map(enc).join(delim)}`);
+      }
+    } else if (Object(value) === value) {
+      // `deepObject` (and any object spec, for now): key[subKey]=subValue.
+      for (const [subKey, subValue] of Object.entries(value)) {
+        if (subValue !== undefined && subValue !== null) {
+          if (spec.allowReserved) raw.push(`${key}[${subKey}]=${encodeReserved(String(subValue))}`);
+          else params.append(`${key}[${subKey}]`, String(subValue));
+        }
+      }
+    } else if (spec.allowReserved) {
+      raw.push(`${key}=${encodeReserved(String(value))}`);
+    } else {
+      params.append(key, String(value));
+    }
+  }
+  const qs = [params.toString(), ...raw].filter(Boolean).join('&');
+  return qs ? `${url}?${qs}` : url;
+}
+
+/**
+ * Read the response body per `kind`. `'auto'` negotiates from the content type
+ * (JSON, then `text/*`, then Blob); `'void'` and `204` responses read nothing.
+ */
+async function parse(response: Response, kind: ParseAs | 'void'): Promise<unknown> {
+  if (kind === 'void' || response.status === 204) return undefined;
+  if (kind === 'stream') return response.body;
+  if (kind === 'blob') return response.blob();
+  if (kind === 'arrayBuffer') return response.arrayBuffer();
+  if (kind === 'formData') return response.formData();
+  if (kind === 'text') return response.text();
+  if (kind === 'json') return response.json();
+  // 'auto' — negotiate from the response's content type (case-insensitively:
+  // `Text/Plain` and `application/JSON` are valid per RFC 9110).
+  const contentType = (response.headers.get('content-type') ?? '').toLowerCase();
+  if (contentType.includes('json')) return response.json();
+  if (contentType.startsWith('text/')) return response.text();
+  return response.blob();
+}
+
+/** Best-effort decode of a non-2xx body (JSON when declared, else text; undefined on failure). */
+async function readError(response: Response): Promise<unknown> {
+  const contentType = response.headers.get('content-type') ?? '';
+  if (contentType.toLowerCase().includes('json')) {
+    return response.json().catch(() => undefined);
+  }
+  return response.text().catch(() => undefined);
+}
+
+const IDEMPOTENT_METHODS = new Set(['GET', 'HEAD', 'PUT', 'DELETE', 'OPTIONS']);
+const TRANSIENT_STATUS = new Set([408, 429, 500, 502, 503, 504]);
+
+/**
+ * The default retry predicate: idempotent methods only, on a transport error or a
+ * transient status. A custom `retryOn` fully replaces this (no method check kept).
+ */
+function defaultRetryOn(ctx: RetryContext): boolean {
+  if (!IDEMPOTENT_METHODS.has(ctx.request.method.toUpperCase())) return false;
+  return ctx.response === undefined || TRANSIENT_STATUS.has(ctx.response.status);
+}
+
+/**
+ * The delay before the next attempt: a `Retry-After` header (seconds or HTTP-date)
+ * wins; otherwise fixed/exponential backoff over `retryDelay`, with full jitter
+ * unless `jitter === false`.
+ */
+function retryDelay(retry: RetryConfig, attempt: number, retryAfter: string | null): number {
+  if (retryAfter) {
+    const seconds = Number(retryAfter);
+    if (!Number.isNaN(seconds)) return seconds * 1000;
+    const when = Date.parse(retryAfter);
+    if (!Number.isNaN(when)) return Math.max(0, when - Date.now());
+  }
+  const base = retry.retryDelay ?? 1000;
+  const raw = retry.retryStrategy === 'fixed' ? base : base * Math.pow(2, attempt - 1);
+  return retry.jitter === false ? raw : Math.random() * raw;
+}
+
+/** Abort-aware sleep: resolves after `ms`, rejects with the abort reason immediately on abort. */
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(abortError(signal));
+      return;
+    }
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(abortError(signal as AbortSignal));
+    };
+    const timer = setTimeout(() => {
+      if (signal) signal.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+    if (signal) signal.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
+/**
+ * Optional behaviors the send core can use but never statically imports — wired by
+ * `createClient` (the same seam the future inline-mode assembler relies on).
+ */
+type SendCapabilities = {
+  /** Serialize a typed multipart body (a plain object) to FormData. */
+  serializeMultipart?: (body: Record<string, unknown>) => FormData;
+};
+
+/**
+ * Normalize a caller's `HeadersInit` (plain record, `Headers` instance, or entry pairs)
+ * to a plain record — spreading a `Headers` or an array contributes no entries.
+ */
+function toHeaderRecord(headers: HeadersInit | undefined): Record<string, string> {
+  if (headers === undefined) return {};
+  if (headers instanceof Headers) {
+    const record: Record<string, string> = {};
+    headers.forEach((value, key) => {
+      record[key] = value;
+    });
+    return record;
+  }
+  if (Array.isArray(headers)) return Object.fromEntries(headers);
+  return headers;
+}
+
+/**
+ * The effective middleware chain for a request: the single `onRequest`/`onResponse`/
+ * `onError` config hooks as one implicit first middleware, then `config.middleware`.
+ */
+function middlewareChain(config: ClientConfig): Middleware[] {
+  const single =
+    config.onRequest || config.onResponse || config.onError
+      ? [{ onRequest: config.onRequest, onResponse: config.onResponse, onError: config.onError }]
+      : [];
+  return [...single, ...(config.middleware ?? [])];
+}
+
+/**
+ * The fetch core shared by every operation: default + config + per-call headers, the
+ * `onRequest` chain (BEFORE body serialization, so mutations are sent), body
+ * serialization (JSON, or FormData via the multipart capability), the retry loop
+ * (idempotent-only defaults, `Retry-After`, abandoned-body drain), and the reverse
+ * `onResponse` onion. Returns the final response plus the request context.
+ */
+async function send(
+  config: ClientConfig,
+  op: OperationContext,
+  url: string,
+  init: RequestOptions,
+  body: unknown | undefined,
+  multipart: boolean,
+  caps: SendCapabilities
+): Promise<{ response: Response; context: RequestContext }> {
+  const { retry: callRetry, ...fetchInit } = init;
+  const retry: RetryConfig = { ...config.retry, ...callRetry };
+  const extra = typeof config.headers === 'function' ? await config.headers() : config.headers;
+  const headers: Record<string, string> = {
+    Accept: 'application/json',
+    ...extra,
+    ...toHeaderRecord(fetchInit.headers),
+  };
+  const context: RequestContext = {
+    url,
+    method: fetchInit.method ?? 'GET',
+    headers,
+    body,
+    operation: op,
+  };
+  const middleware = middlewareChain(config);
+  for (const mw of middleware) if (mw.onRequest) await mw.onRequest(context);
+  // Serialize AFTER onRequest so body mutations (case conversion, enveloping, signing) take effect.
+  let payload: BodyInit | undefined;
+  if (context.body !== undefined) {
+    const value = context.body;
+    const isBinary =
+      value instanceof Blob ||
+      value instanceof ArrayBuffer ||
+      ArrayBuffer.isView(value as ArrayBufferView);
+    const isFormData = typeof FormData !== 'undefined' && value instanceof FormData;
+    const isURLSearchParams = value instanceof URLSearchParams;
+    if (isFormData || isURLSearchParams || isBinary || typeof value === 'string') {
+      payload = value as BodyInit;
+    } else if (multipart) {
+      if (!caps.serializeMultipart) {
+        throw new Error('Multipart capability not wired: cannot serialize the request body');
+      }
+      payload = caps.serializeMultipart(value as Record<string, unknown>);
+    } else {
+      payload = JSON.stringify(value);
+      if (!('Content-Type' in context.headers) && !('content-type' in context.headers)) {
+        context.headers['Content-Type'] = 'application/json';
+      }
+    }
+  }
+  const doFetch = config.fetch ?? fetch;
+  const maxAttempts = 1 + (retry.retries ?? 0);
+  const retryOn = retry.retryOn ?? defaultRetryOn;
+  const signal = fetchInit.signal ?? undefined;
+
+  let attempt = 0;
+  while (true) {
+    attempt++;
+    if (signal?.aborted) throw abortError(signal);
+    let response: Response;
+    try {
+      response = await doFetch(context.url, {
+        ...fetchInit,
+        method: context.method,
+        headers: context.headers,
+        body: payload,
+      });
+    } catch (error) {
+      if (
+        attempt < maxAttempts &&
+        !signal?.aborted &&
+        (await retryOn({ attempt, request: context, error }))
+      ) {
+        await sleep(retryDelay(retry, attempt, null), signal);
+        continue;
+      }
+      throw error;
+    }
+    // Reverse order: the last-registered middleware wraps closest to the network (onion).
+    for (let i = middleware.length - 1; i >= 0; i--) {
+      const onResponse = middleware[i].onResponse;
+      if (onResponse) {
+        const replaced = await onResponse(response, context);
+        if (replaced && replaced !== response) {
+          // Cancel the abandoned original's body — like the retry path, an unread body
+          // keeps its connection checked out under Node/undici.
+          await response.body?.cancel().catch(() => undefined);
+          response = replaced;
+        }
+      }
+    }
+    if (
+      !response.ok &&
+      attempt < maxAttempts &&
+      !signal?.aborted &&
+      (await retryOn({ attempt, request: context, response }))
+    ) {
+      const retryAfter = response.headers.get('retry-after');
+      // Drain the abandoned response body before the next attempt: an unread body
+      // keeps the connection checked out (and can stall the pool) under Node/undici
+      // and other strict HTTP clients. Ignore errors (e.g. a middleware already read it).
+      await response.body?.cancel().catch(() => undefined);
+      await sleep(retryDelay(retry, attempt, retryAfter), signal);
+      continue;
+    }
+    return { response, context };
+  }
+}
+
+/**
+ * The optional behaviors `createClientCore` can dispatch to but never statically
+ * imports. The package's public `createClient` wires the full set; the future
+ * inline-mode assembler wires only the capabilities a spec needs.
+ */
+type Capabilities = SendCapabilities & {
+  resolveAuth?: (
+    security: readonly (readonly SecuritySpec[])[],
+    config: ClientConfig
+  ) => Promise<{ headers: Record<string, string>; query: Record<string, string> }>;
+  sse?: (
+    config: ClientConfig,
+    op: OperationContext,
+    // Re-preparing per (re)connect (not a frozen url/init) lets a refresh-style
+    // TokenProvider issue a fresh credential after a dropped stream reconnects.
+    prepare: () => Promise<{ url: string; init: SseOptions }>,
+    dataKind: 'json' | 'text'
+  ) => AsyncGenerator<ServerSentEvent<unknown>>;
+  paginate?: {
+    pages: (
+      call: (args?: OperationArgs, init?: RequestOptions) => Promise<unknown>,
+      spec: PaginationSpec,
+      args?: OperationArgs,
+      init?: RequestOptions
+    ) => AsyncGenerator<unknown>;
+    items: (
+      call: (args?: OperationArgs, init?: RequestOptions) => Promise<unknown>,
+      spec: PaginationSpec,
+      args?: OperationArgs,
+      init?: RequestOptions
+    ) => AsyncGenerator<unknown>;
+  };
+};
+
+/** The grouped args wire shape: path params by name plus the `params`/`body`/`headers`/`cookies` slots. */
+type OperationArgs = {
+  params?: Record<string, QueryValue>;
+  body?: unknown;
+  headers?: Record<string, unknown>;
+  cookies?: Record<string, unknown>;
+} & Record<string, unknown>;
+
+/** The response reader implied by the descriptor (before any per-call `parseAs` override). */
+function kindFor(op: OperationDescriptor): ParseAs | 'void' {
+  if (op.responseKind === 'void' || op.responseKind === 'blob' || op.responseKind === 'text') {
+    return op.responseKind;
+  }
+  return 'auto';
+}
+
+/** Route the grouped args by the descriptor: path values, query object, body, extra headers, cookies. */
+function splitArgs(op: OperationDescriptor, args: OperationArgs) {
+  const path: Record<string, unknown> = {};
+  for (const param of op.params ?? []) {
+    if (param.in === 'path') path[param.name] = args[param.name];
+  }
+  return {
+    path,
+    query: args.params,
+    body: args.body,
+    headers: args.headers,
+    cookies: args.cookies,
+  };
+}
+
+/**
+ * The query-serialization hints for the descriptor's query params. A spec is built only
+ * when the param deviates from the OpenAPI defaults (`form` + `explode: true`, encoded),
+ * and always fully resolved — so `explode: false` or `allowReserved` alone (no `style`)
+ * are honored, and an omitted `explode` keeps the exploded default.
+ */
+function queryStyles(op: OperationDescriptor): Record<string, QueryStyle> | undefined {
+  let styles: Record<string, QueryStyle> | undefined;
+  for (const param of op.params ?? []) {
+    if (param.in !== 'query') continue;
+    const deviates =
+      (param.style !== undefined && param.style !== 'form') ||
+      param.explode === false ||
+      param.allowReserved === true;
+    if (!deviates) continue;
+    styles ??= {};
+    styles[param.name] = {
+      style: param.style ?? 'form',
+      explode: param.explode ?? true,
+      allowReserved: param.allowReserved,
+    };
+  }
+  return styles;
+}
+
+/** Stringify caller-supplied extra headers, skipping empty entries. */
+function stringHeaders(headers: Record<string, unknown> | undefined): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [key, value] of Object.entries(headers ?? {})) {
+    if (value !== undefined && value !== null) out[key] = String(value);
+  }
+  return out;
+}
+
+/** Build the request pieces an attempt needs: the final URL and the merged per-call init. */
+async function prepareRequest(
+  config: ClientConfig,
+  op: OperationDescriptor,
+  args: OperationArgs,
+  init: RequestOptions | SseOptions,
+  caps: Capabilities
+): Promise<{ url: string; init: RequestOptions; body: unknown }> {
+  const { path, query, body, headers, cookies } = splitArgs(op, args);
+  const authed: { headers: Record<string, string>; query: Record<string, string> } =
+    op.security?.length && caps.resolveAuth
+      ? await caps.resolveAuth(op.security, config)
+      : { headers: {}, query: {} };
+  // Cookie params join the auth-injected cookies in one `Cookie` header (values
+  // percent-encoded, like auth cookies). Server-side only — browsers own the header.
+  const cookiePairs = Object.entries(cookies ?? {})
+    .filter(([, value]) => value !== undefined && value !== null)
+    .map(([cookieName, value]) => `${cookieName}=${encodeURIComponent(String(value))}`);
+  if (cookiePairs.length > 0) {
+    authed.headers.Cookie = [authed.headers.Cookie, ...cookiePairs].filter(Boolean).join('; ');
+  }
+  const fullQuery: Record<string, QueryValue> = { ...query, ...authed.query };
+  const url = buildUrl(
+    config.serverUrl ?? '',
+    substitutePath(op.path, path),
+    Object.keys(fullQuery).length > 0 ? fullQuery : undefined,
+    queryStyles(op)
+  );
+  const mergedInit: RequestOptions = {
+    ...init,
+    method: op.method.toUpperCase(),
+    // Precedence, lowest → highest (later spreads win): injected auth → explicit
+    // header params → caller `init.headers` — the caller always overrides both.
+    headers: {
+      ...authed.headers,
+      ...stringHeaders(headers),
+      ...toHeaderRecord(init.headers),
+    },
+  };
+  return { url, init: mergedInit, body };
+}
+
+/** One non-SSE call: send, then branch on the configured error mode. */
+async function execute(
+  config: ClientConfig,
+  op: OperationDescriptor,
+  args: OperationArgs,
+  init: RequestOptions,
+  caps: Capabilities
+): Promise<unknown> {
+  const prepared = await prepareRequest(config, op, args, init, caps);
+  const opCtx: OperationContext = { id: op.id, path: op.path, tags: [...(op.tags ?? [])] };
+  const { parseAs, ...sendInit } = prepared.init;
+  const { response, context } = await send(
+    config,
+    opCtx,
+    prepared.url,
+    sendInit,
+    prepared.body,
+    op.body?.multipart === true,
+    caps
+  );
+  const readKind = parseAs ?? kindFor(op);
+  if (config.errorMode === 'result') {
+    if (!response.ok) {
+      return { data: undefined, error: await readError(response), response };
+    }
+    return { data: await parse(response, readKind), error: undefined, response };
+  }
+  if (!response.ok) {
+    let error: globalThis.Error = new ApiError(
+      context.url,
+      response.status,
+      response.statusText,
+      await readError(response)
+    );
+    // Thread the error through each middleware's onError in turn (each may replace it).
+    for (const mw of middlewareChain(config)) {
+      if (mw.onError) error = await mw.onError(error as ApiErrorLike, context);
+    }
+    throw error;
+  }
+  return parse(response, readKind);
+}
+
+/** The paginate capability, or a descriptive throw when a paginated op is iterated unwired. */
+function paginateCapability(caps: Capabilities, op: OperationDescriptor) {
+  if (!caps.paginate) {
+    throw new Error(`Pagination capability not wired: cannot iterate operation "${op.id}"`);
+  }
+  return caps.paginate;
+}
+
+/**
+ * The per-page call the iterators drive: the method itself in throw mode; in result
+ * mode a wrapper that unwraps the `{ data, error, response }` envelope — the page
+ * pointers are data-rooted — rethrowing a failed page as `ApiError` (iteration is
+ * error-mode-agnostic; the throw-mode-only `onError` middleware hook is not invoked).
+ */
+function pageCall(
+  method: (args?: OperationArgs, init?: RequestOptions) => Promise<unknown>,
+  config: ClientConfig
+) {
+  if (config.errorMode !== 'result') return method;
+  return async (args?: OperationArgs, init?: RequestOptions) => {
+    const envelope = (await method(args, init)) as {
+      data: unknown;
+      error: unknown;
+      response: Response;
+    };
+    // Failure is `!response.ok` — NOT `data === undefined`: a successful bodyless page
+    // (204/void) also parses to undefined data, and a failed page's `error` can be
+    // undefined too (unreadable body). The pointers then miss on the undefined data
+    // and iteration stops cleanly, which is the correct semantics for an empty page.
+    if (!envelope.response.ok) {
+      const { response } = envelope;
+      throw new ApiError(response.url, response.status, response.statusText, envelope.error);
+    }
+    return envelope.data;
+  };
+}
+
+/**
+ * Build a typed instance client over operation descriptors: one real bound method per
+ * operation (attached by a construction-time loop — no Proxy), plus the core members
+ * (`configure`/`use`/`auth`), which are assigned AFTER the loop so they win any name
+ * collision with an operation. All behavior dispatches through the capability seam.
+ */
+function createClientCore<
+  Ops extends OpsShape,
+  Id extends string = string,
+  Path extends string = string,
+  Tag extends string = string,
+>(
+  operations: Record<string, OperationDescriptor>,
+  initial: ClientConfig<OperationContext<Id, Path, Tag>> = {},
+  caps: Capabilities = {}
+): Client<Ops, OperationContext<Id, Path, Tag>> {
+  // The literal-union narrowing is a compile-time DX contract only; internally the
+  // runtime works with the base (string-typed) context. One cast at this boundary —
+  // `ClientConfig<Narrow>` is not assignable to `ClientConfig` (middleware ctx
+  // params are contravariant).
+  const given = initial as ClientConfig;
+  // Private mutable config; the middleware array is copied so `use()` never mutates the caller's.
+  const config: ClientConfig = { ...given, middleware: [...(given.middleware ?? [])] };
+  const client = {} as Record<string, unknown>;
+
+  for (const [name, op] of Object.entries(operations)) {
+    if (op.responseKind === 'sse') {
+      const method = (args: OperationArgs = {}, init: SseOptions = {}) => {
+        if (!caps.sse) {
+          throw new Error(`SSE capability not wired: cannot stream operation "${op.id}"`);
+        }
+        const stream = caps.sse;
+        return (async function* () {
+          const opCtx: OperationContext = { id: op.id, path: op.path, tags: [...(op.tags ?? [])] };
+          // A thunk the stream re-runs on every (re)connect, so auth (which `prepareRequest`
+          // resolves) is refreshed per attempt rather than frozen at the first connect.
+          const prepare = async () => {
+            const prepared = await prepareRequest(config, op, args, init, caps);
+            return { url: prepared.url, init: prepared.init as SseOptions, body: prepared.body };
+          };
+          yield* stream(config, opCtx, prepare, op.sseDataKind ?? 'text');
+        })();
+      };
+      // Consumers key off the function reference (cache keys, `OPERATIONS[fn.name]`), so
+      // each closure carries its operationId instead of an inferred binding name.
+      Object.defineProperty(method, 'name', { value: name });
+      client[name] = method;
+    } else {
+      const method = (args: OperationArgs = {}, init: RequestOptions = {}) =>
+        execute(config, op, args, init, caps);
+      Object.defineProperty(method, 'name', { value: name });
+      const spec = op.pagination;
+      // Paginated ops keep their one-shot call and gain `.pages`/`.items`, dispatching
+      // through the capability seam (like SSE: absent capability throws descriptively).
+      // Iteration is error-mode-agnostic: the iterators' pointers are data-rooted, so on
+      // a result-mode client (`errorMode` is fixed at construction — `configure()`
+      // ignores it) each page's envelope is unwrapped before it reaches the capability.
+      // A failed page aborts iteration by throwing ApiError, even on result-mode
+      // clients; the `onError` middleware hook (throw-mode-only) is not invoked.
+      client[name] = spec
+        ? Object.assign(method, {
+            pages: (args?: OperationArgs, init?: RequestOptions) =>
+              paginateCapability(caps, op).pages(pageCall(method, config), spec, args, init),
+            items: (args?: OperationArgs, init?: RequestOptions) =>
+              paginateCapability(caps, op).items(pageCall(method, config), spec, args, init),
+          })
+        : method;
+    }
+  }
+
+  // Core members are assigned AFTER the operation loop — they win over colliding op names.
+  client.configure = (next: ClientConfig): void => {
+    // `errorMode` is fixed at generate time (it shapes the static types); flipping it at
+    // runtime would silently desync return shapes from `Client<Ops>`, so it is ignored.
+    const { errorMode: _fixed, auth, ...rest } = next;
+    Object.assign(config, rest);
+    // `auth` merges into existing credentials (like the `auth.*` setters) rather than
+    // replacing wholesale — so `configure({ auth: { bearer } })` keeps a previously set
+    // basic/apiKey. `apiKey` merges per scheme.
+    if (auth) {
+      config.auth = {
+        ...config.auth,
+        ...auth,
+        ...(auth.apiKey ? { apiKey: { ...config.auth?.apiKey, ...auth.apiKey } } : {}),
+      };
+    }
+  };
+  client.use = (...middleware: Middleware[]): void => {
+    // Reassign (don't push) so a caller-provided `middleware` array isn't mutated.
+    config.middleware = [...(config.middleware ?? []), ...middleware];
+  };
+  client.auth = {
+    bearer(token: TokenProvider): void {
+      config.auth = { ...config.auth, bearer: token };
+    },
+    basic(username: string, password: string): void {
+      config.auth = { ...config.auth, basic: { username, password } };
+    },
+    apiKey(scheme: string, value: TokenProvider): void {
+      config.auth = { ...config.auth, apiKey: { ...config.auth?.apiKey, [scheme]: value } };
+    },
+  };
+
+  return client as Client<Ops, OperationContext<Id, Path, Tag>>;
+}
+
+/**
+ * The client factory: `createClientCore` wired with the capabilities this API needs.
+ * Exported so apps can build additional instances (per-tenant, per-environment) over
+ * the same `OPERATIONS`/`Ops`. The trailing string params carry the wiring's literal
+ * unions (`OperationId`/`OperationPath`/`OperationTag`) into `ctx.operation`.
+ */
+export function createClient<
+  Ops extends OpsShape,
+  Id extends string = string,
+  Path extends string = string,
+  Tag extends string = string,
+>(
+  operations: Record<string, OperationDescriptor>,
+  config?: ClientConfig<OperationContext<Id, Path, Tag>>
+): Client<Ops, OperationContext<Id, Path, Tag>> {
+  return createClientCore<Ops, Id, Path, Tag>(operations, config, {});
+}
+
+export const client = createClient<Ops, OperationId, OperationPath, OperationTag>(OPERATIONS, { serverUrl: "https://api.cafe.redocly.com" });
+
+export const { configure, use } = client;
+export const listMenuItems = (params: {
+    /**
+     * Case-insensitive substring match on item names.
+     */
+    search?: string;
+    /**
+     * Number of results per page.
+     * @minimum 1
+     * @maximum 100
+     */
+    limit?: number;
+} = {}, init: RequestOptions = {}) => client.listMenuItems({ params }, init);
+export const getMenuItemPhoto = (menuItemId: string, params: {
+    /**
+     * Photo size to retrieve.
+     */
+    photoSize?: "thumbnail" | "medium" | "large";
+} = {}, init: RequestOptions = {}) => client.getMenuItemPhoto({ menuItemId, params }, init);
+export const registerOAuth2Client = (body: RegisterClientRequest, init: RequestOptions = {}) => client.registerOAuth2Client({ body }, init);
diff --git a/tests/e2e/generate-client/examples/zero-install-quickstart/src/main.ts b/tests/e2e/generate-client/examples/zero-install-quickstart/src/main.ts
new file mode 100644
index 0000000000..54eb670ea4
--- /dev/null
+++ b/tests/e2e/generate-client/examples/zero-install-quickstart/src/main.ts
@@ -0,0 +1,19 @@
+// zero-install-quickstart — the whole loop: generate → import → call.
+//
+// `redocly generate-client` turned openapi.yaml into ONE self-contained file
+// (src/api/client.ts) with zero runtime dependencies — there is no client
+// library to install or keep in sync. Import the generated functions and call.
+import { getMenuItemPhoto, listMenuItems } from './api/client.js';
+
+const menu = await listMenuItems({ limit: 3 });
+for (const item of menu.items) {
+  console.log(`${item.name} — $${(item.price / 100).toFixed(2)}`);
+}
+
+const [first] = menu.items;
+if (first) {
+  const photo = await getMenuItemPhoto(first.id, { photoSize: 'thumbnail' });
+  console.log(
+    photo instanceof Blob ? `${first.name} photo: ${photo.type}, ${photo.size} bytes` : photo
+  );
+}
diff --git a/tests/e2e/generate-client/examples/zero-install-quickstart/tsconfig.json b/tests/e2e/generate-client/examples/zero-install-quickstart/tsconfig.json
new file mode 100644
index 0000000000..4bd6962d40
--- /dev/null
+++ b/tests/e2e/generate-client/examples/zero-install-quickstart/tsconfig.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../tsconfig.base.json",
+  "include": ["src"]
+}
diff --git a/tests/e2e/generate-client/examples/zod/.gitignore b/tests/e2e/generate-client/examples/zod/.gitignore
new file mode 100644
index 0000000000..6eb23affb8
--- /dev/null
+++ b/tests/e2e/generate-client/examples/zod/.gitignore
@@ -0,0 +1,4 @@
+node_modules
+dist
+src/api/
+package-lock.json
diff --git a/tests/e2e/generate-client/examples/zod/README.md b/tests/e2e/generate-client/examples/zod/README.md
new file mode 100644
index 0000000000..bbac00272b
--- /dev/null
+++ b/tests/e2e/generate-client/examples/zod/README.md
@@ -0,0 +1,15 @@
+# zod example
+
+Generated TypeScript client plus **zod** schemas (`generators: ['sdk', 'zod']`).
+The app turns on `zodValidation()` — request bodies and JSON responses are validated
+against the generated schemas on every call — and also uses a schema directly.
+
+## Run
+
+```bash
+npm install
+npm run generate   # generate src/api (the client is gitignored)
+npm run dev        # open the printed local URL
+```
+
+The generated client + zod schemas under `src/api/` are gitignored; CI regenerates them and type-checks this example.
diff --git a/tests/e2e/generate-client/examples/zod/index.html b/tests/e2e/generate-client/examples/zod/index.html
new file mode 100644
index 0000000000..8c0c18b5ec
--- /dev/null
+++ b/tests/e2e/generate-client/examples/zod/index.html
@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>Redocly client-generator — zod example</title>
+  </head>
+  <body>
+    <pre id="out">Loading…</pre>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
diff --git a/tests/e2e/generate-client/examples/zod/package.json b/tests/e2e/generate-client/examples/zod/package.json
new file mode 100644
index 0000000000..9910b341de
--- /dev/null
+++ b/tests/e2e/generate-client/examples/zod/package.json
@@ -0,0 +1,17 @@
+{
+  "name": "@redocly-examples/zod",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "generate": "redocly generate-client",
+    "dev": "vite",
+    "build": "vite build"
+  },
+  "devDependencies": {
+    "@redocly/cli": "latest",
+    "typescript": "^5.5.0",
+    "vite": "^5.4.0",
+    "zod": "^4.0.0"
+  }
+}
diff --git a/tests/e2e/generate-client/examples/zod/redocly.yaml b/tests/e2e/generate-client/examples/zod/redocly.yaml
new file mode 100644
index 0000000000..fe808914ae
--- /dev/null
+++ b/tests/e2e/generate-client/examples/zod/redocly.yaml
@@ -0,0 +1,11 @@
+# redocly.yaml — drives `redocly generate-client` for this example.
+# The client is generated for the api that declares a `client` block
+# (run `redocly generate-client` with no args to build every such api).
+apis:
+  zod:
+    root: ../_shared/cafe.yaml
+    clientOutput: ./src/api/client.ts
+    client:
+      generators:
+        - sdk
+        - zod
diff --git a/tests/e2e/generate-client/examples/zod/src/main.ts b/tests/e2e/generate-client/examples/zod/src/main.ts
new file mode 100644
index 0000000000..844b4c4d58
--- /dev/null
+++ b/tests/e2e/generate-client/examples/zod/src/main.ts
@@ -0,0 +1,27 @@
+import { configure, listMenuItems, use, ApiError } from './api/client.js';
+import { zodValidation, ZodValidationError, MenuItemListSchema } from './api/client.zod.js';
+
+configure({ serverUrl: 'https://api.cafe.redocly.com' });
+// Every request body and JSON response is now validated against the generated schemas.
+use(zodValidation());
+
+const out = document.querySelector<HTMLPreElement>('#out')!;
+
+async function main() {
+  try {
+    const items = await listMenuItems(); // already validated by the middleware
+    out.textContent = `Validated ${items.items.length} items:\n${JSON.stringify(items, null, 2)}`;
+
+    // Schemas are also importable directly for one-off checks (e.g. form input, cached data).
+    MenuItemListSchema.parse(items);
+  } catch (error) {
+    if (error instanceof ZodValidationError) {
+      out.textContent = `The server broke the contract on ${error.operationId}:\n${error.message}`;
+    } else {
+      out.textContent =
+        error instanceof ApiError ? `ApiError ${error.status}` : `Error: ${String(error)}`;
+    }
+  }
+}
+
+void main();
diff --git a/tests/e2e/generate-client/examples/zod/tsconfig.json b/tests/e2e/generate-client/examples/zod/tsconfig.json
new file mode 100644
index 0000000000..4bd6962d40
--- /dev/null
+++ b/tests/e2e/generate-client/examples/zod/tsconfig.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../tsconfig.base.json",
+  "include": ["src"]
+}
diff --git a/tests/e2e/generate-client/examples/zod/vite.config.ts b/tests/e2e/generate-client/examples/zod/vite.config.ts
new file mode 100644
index 0000000000..c049f46e10
--- /dev/null
+++ b/tests/e2e/generate-client/examples/zod/vite.config.ts
@@ -0,0 +1,3 @@
+import { defineConfig } from 'vite';
+
+export default defineConfig({});
diff --git a/tests/e2e/generate-client/extension.test.ts b/tests/e2e/generate-client/extension.test.ts
new file mode 100644
index 0000000000..7a32f992b1
--- /dev/null
+++ b/tests/e2e/generate-client/extension.test.ts
@@ -0,0 +1,148 @@
+/**
+ * Behavioral e2e for the extension contract (D3). Rather than a live server, we
+ * inject a fake `fetch` via `configure()` / `createClient(…, config)` and capture what
+ * the generated runtime actually produced — proving that `serverUrl`, `config.headers`,
+ * `onRequest`, transport-swap, and per-instance config observably take effect.
+ */
+import { existsSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { outdent } from 'outdent';
+
+import { generateInto, runConsumer } from './helpers.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const fixture = join(__dirname, 'fixtures/base.yaml');
+
+describe('extension contract — flat surface (configure)', () => {
+  let dir = '';
+  beforeAll(() => {
+    dir = mkdtempSync(join(tmpdir(), 'ext-fn-'));
+    generateInto(dir, fixture);
+  }, 60_000);
+  afterAll(() => {
+    if (dir && existsSync(dir)) rmSync(dir, { recursive: true, force: true });
+  });
+
+  test('configure() applies serverUrl, config.headers, onRequest, and the fetch transport-swap', () => {
+    const captured = runConsumer(
+      dir,
+      outdent`
+        import { configure, listPets } from './client.ts';
+
+        const seen: { url?: string; headers?: Record<string, string> } = {};
+        configure({
+          serverUrl: 'https://configured.example',
+          headers: { 'X-Tenant': 'acme' },
+          onRequest: (ctx) => { ctx.headers['X-Trace'] = 'trace-123'; },
+          fetch: (async (url: string, init: RequestInit) => {
+            seen.url = String(url);
+            seen.headers = init.headers as Record<string, string>;
+            return new Response('[]', { status: 200, headers: { 'content-type': 'application/json' } });
+          }) as unknown as typeof fetch,
+        });
+
+        await listPets();
+        console.log(JSON.stringify(seen));
+      `
+    ) as { url: string; headers: Record<string, string> };
+
+    // serverUrl override was honored (not the spec's localhost:3102).
+    expect(captured.url).toBe('https://configured.example/pets');
+    // The fake fetch was actually used, and both config.headers + onRequest applied.
+    expect(captured.headers['X-Tenant']).toBe('acme');
+    expect(captured.headers['X-Trace']).toBe('trace-123');
+  }, 60_000);
+
+  test('onError maps a failed request to a custom error', () => {
+    const result = runConsumer(
+      dir,
+      outdent`
+        import { configure, getPetById, ApiError } from './client.ts';
+
+        class NotFound extends Error {}
+        configure({
+          fetch: (async () =>
+            new Response('{"detail":"nope"}', { status: 404, headers: { 'content-type': 'application/json' } })) as unknown as typeof fetch,
+          onError: (error: ApiError) => new NotFound('mapped:' + error.status),
+        });
+
+        try {
+          await getPetById(1);
+          console.log(JSON.stringify({ threw: false }));
+        } catch (e) {
+          console.log(JSON.stringify({ threw: true, name: (e as Error).constructor.name, message: (e as Error).message }));
+        }
+      `
+    ) as { threw: boolean; name: string; message: string };
+
+    expect(result.threw).toBe(true);
+    expect(result.name).toBe('NotFound');
+    expect(result.message).toBe('mapped:404');
+  }, 60_000);
+});
+
+describe('extension contract — per-instance config (createClient)', () => {
+  let dir = '';
+  beforeAll(() => {
+    // The temp dir lives INSIDE the repo so the consumer's import of
+    // `@redocly/client-generator` resolves through the workspace node_modules symlink.
+    dir = mkdtempSync(join(__dirname, '.tmp-ext-instance-'));
+    generateInto(dir, fixture, ['--runtime', 'package']);
+  }, 60_000);
+  afterAll(() => {
+    if (dir && existsSync(dir)) rmSync(dir, { recursive: true, force: true });
+  });
+
+  test('two instances carry independent serverUrl + headers (multi-tenant isolation)', () => {
+    const calls = runConsumer(
+      dir,
+      outdent`
+        import { createClient } from '@redocly/client-generator';
+        import { OPERATIONS, type Ops } from './client.ts';
+
+        const calls: Array<{ tag: string; url: string; tenant: string }> = [];
+        const make = (tag: string) =>
+          (async (url: string, init: RequestInit) => {
+            const headers = init.headers as Record<string, string>;
+            calls.push({ tag, url: String(url), tenant: headers['X-Tenant'] });
+            return new Response('[]', { status: 200, headers: { 'content-type': 'application/json' } });
+          }) as unknown as typeof fetch;
+
+        const a = createClient<Ops>(OPERATIONS, { serverUrl: 'https://a.example', headers: { 'X-Tenant': 'A' }, fetch: make('a') });
+        const b = createClient<Ops>(OPERATIONS, { serverUrl: 'https://b.example', headers: { 'X-Tenant': 'B' }, fetch: make('b') });
+
+        await a.listPets();
+        await b.listPets();
+        console.log(JSON.stringify(calls));
+      `
+    ) as Array<{ tag: string; url: string; tenant: string }>;
+
+    expect(calls).toHaveLength(2);
+    expect(calls[0]).toEqual({ tag: 'a', url: 'https://a.example/pets', tenant: 'A' });
+    expect(calls[1]).toEqual({ tag: 'b', url: 'https://b.example/pets', tenant: 'B' });
+  }, 60_000);
+
+  test('the generated module instance keeps the spec-derived serverUrl unless overridden', () => {
+    const seen = runConsumer(
+      dir,
+      outdent`
+        import { client } from './client.ts';
+
+        let captured = '';
+        client.configure({
+          fetch: (async (url: string) => {
+            captured = String(url);
+            return new Response('[]', { status: 200, headers: { 'content-type': 'application/json' } });
+          }) as unknown as typeof fetch,
+        });
+        await client.listPets();
+        console.log(JSON.stringify({ captured }));
+      `
+    ) as { captured: string };
+
+    // configure() only swapped the transport → the baked serverUrl from base.yaml stays.
+    expect(seen.captured).toBe('http://localhost:3102/pets');
+  }, 60_000);
+});
diff --git a/tests/e2e/generate-client/fixtures/auth.yaml b/tests/e2e/generate-client/fixtures/auth.yaml
new file mode 100644
index 0000000000..c1f2c73d60
--- /dev/null
+++ b/tests/e2e/generate-client/fixtures/auth.yaml
@@ -0,0 +1,75 @@
+openapi: 3.0.3
+info: { title: Auth Breadth API, version: 1.0.0 }
+servers:
+  - { url: https://api.example.com }
+paths:
+  /bearer:
+    get:
+      operationId: getBearer
+      security:
+        - Bearer: []
+      responses:
+        '200':
+          description: ok
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Thing' }
+  /basic:
+    get:
+      operationId: getBasic
+      security:
+        - Basic: []
+      responses:
+        '200':
+          description: ok
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Thing' }
+  /query:
+    get:
+      operationId: getQuery
+      parameters:
+        - { name: limit, in: query, schema: { type: integer } }
+      security:
+        - QueryKey: []
+      responses:
+        '200':
+          description: ok
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Thing' }
+  /cookie:
+    get:
+      operationId: getCookie
+      security:
+        - CookieKey: []
+      responses:
+        '200':
+          description: ok
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Thing' }
+  /header:
+    get:
+      operationId: getHeader
+      security:
+        - HeaderKey: []
+      responses:
+        '200':
+          description: ok
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Thing' }
+components:
+  securitySchemes:
+    Bearer: { type: http, scheme: bearer }
+    Basic: { type: http, scheme: basic }
+    QueryKey: { type: apiKey, in: query, name: api_key }
+    CookieKey: { type: apiKey, in: cookie, name: sid }
+    HeaderKey: { type: apiKey, in: header, name: X-Key }
+  schemas:
+    Thing:
+      type: object
+      required: [id]
+      properties:
+        id: { type: string }
diff --git a/tests/e2e/generate-client/fixtures/base.yaml b/tests/e2e/generate-client/fixtures/base.yaml
new file mode 100644
index 0000000000..5d4d8ab2c6
--- /dev/null
+++ b/tests/e2e/generate-client/fixtures/base.yaml
@@ -0,0 +1,234 @@
+openapi: 3.1.0
+info:
+  title: Base Consumer
+  version: 1.0.0
+  description: |
+    Minimal spec that exercises core runtime behavior (real call, cancellation)
+    plus edge cases discovered against the real Redocly API (reunite.yaml):
+    OAS 3.1 `enum` containing `null`, and `style: deepObject` object query params.
+servers:
+  - url: http://localhost:3102
+paths:
+  /pets/{id}:
+    get:
+      operationId: getPetById
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: A single pet.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Pet'
+  /pets:
+    get:
+      operationId: listPets
+      parameters:
+        - name: filter
+          in: query
+          required: false
+          style: deepObject
+          explode: true
+          description: Object-valued filter serialized as deepObject.
+          schema:
+            $ref: '#/components/schemas/PetFilter'
+      responses:
+        '200':
+          description: A list of pets.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Pet'
+    post:
+      operationId: createPet
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Pet'
+      responses:
+        '201':
+          description: The created pet.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Pet'
+  /pets/{id}/cancel-test:
+    get:
+      operationId: getSlowPet
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: A slow response (used to exercise cancellation).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Pet'
+  /search:
+    post:
+      operationId: search
+      description: |
+        Name-collision regression: `operationId: search` makes the result alias name
+        match the SearchResult schema it returns. The generator must not emit a circular
+        self-referential alias (TS2440/TS2308 in multi-file output).
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/PetFilter'
+      responses:
+        '200':
+          description: Search results.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SearchResult'
+  /pets/bulk:
+    post:
+      operationId: bulkUpsertPets
+      description: |
+        The 200 body is an array whose items are an *inline* discriminated union
+        (`status`). The generator must emit `is<Member>` guards for that nested
+        union, narrowing the items to the named member types.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: array
+              items:
+                $ref: '#/components/schemas/Pet'
+      responses:
+        '200':
+          description: Per-item results.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PetBulkResult'
+  /status:
+    get:
+      operationId: getStatus
+      description: |
+        Name-collision regression (non-self-referential): operationId `getStatus` derives a
+        result alias whose name also exists as an unrelated schema below. The generator must
+        suppress the operation result alias so the two don't both declare the same type name
+        (a duplicate-identifier error).
+      responses:
+        '200':
+          description: ok
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Pet'
+components:
+  schemas:
+    Pet:
+      type: object
+      required: [name]
+      properties:
+        id:
+          description: Server-assigned id; readOnly, so it is dropped from request bodies.
+          type: integer
+          readOnly: true
+        name:
+          type: string
+        status:
+          description: Lifecycle status; OAS 3.1 enum that includes null.
+          type:
+            - string
+            - 'null'
+          enum:
+            - available
+            - pending
+            - sold
+            - null
+        metadata:
+          description: Free-form object (no declared properties) — a record of unknown, not `{}`.
+          type: object
+        owner:
+          description: oneOf with an empty branch — must stay `string`, not collapse to `unknown`.
+          oneOf:
+            - type: string
+            - {}
+        deletedAt:
+          description: OAS 3.1 single null type — must render as `null`, not `unknown`.
+          type: 'null'
+    PetBulkSuccessItem:
+      description: Discriminated-union member (status=ok) — a nested-union guard target.
+      type: object
+      required: [status, resource]
+      properties:
+        status:
+          type: string
+          const: ok
+        resource:
+          $ref: '#/components/schemas/Pet'
+    PetBulkErrorItem:
+      description: Discriminated-union member (status=error).
+      type: object
+      required: [status, error]
+      properties:
+        status:
+          type: string
+          const: error
+        error:
+          type: string
+    PetBulkResult:
+      description: Array of an inline discriminated union — guards must narrow the items.
+      type: array
+      items:
+        oneOf:
+          - $ref: '#/components/schemas/PetBulkSuccessItem'
+          - $ref: '#/components/schemas/PetBulkErrorItem'
+        discriminator:
+          propertyName: status
+          mapping:
+            ok: '#/components/schemas/PetBulkSuccessItem'
+            error: '#/components/schemas/PetBulkErrorItem'
+    GetStatusResult:
+      description: Unrelated schema whose name collides with the `getStatus` op result alias.
+      type: object
+      properties:
+        ready:
+          type: boolean
+    PetFilter:
+      type: object
+      properties:
+        name:
+          type: string
+        status:
+          type: string
+    SearchResult:
+      description: Result alias for `search` collides with this schema name (regression guard).
+      type: object
+      properties:
+        total:
+          type: integer
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/Pet'
+    ExtendedPet:
+      description: Own discriminant property AND allOf — the own property must survive the intersection.
+      type: object
+      required: [kind]
+      properties:
+        kind:
+          type: string
+          const: extended
+      allOf:
+        - $ref: '#/components/schemas/Pet'
diff --git a/tests/e2e/generate-client/fixtures/cafe.yaml b/tests/e2e/generate-client/fixtures/cafe.yaml
new file mode 100644
index 0000000000..a255b72a20
--- /dev/null
+++ b/tests/e2e/generate-client/fixtures/cafe.yaml
@@ -0,0 +1,1163 @@
+openapi: 3.2.0
+info:
+  title: Redocly Cafe
+  description: |
+    Demo API for cafe operators (not customers) to manage menus, orders, and revenue.
+    Create API credentials and try it yourself in a realistic OpenAPI workflow.
+  version: 1.0.0
+  contact:
+    email: team@redocly.com
+    url: https://redocly.com/contact-us/
+  license:
+    name: MIT
+    url: https://opensource.org/licenses/MIT
+  termsOfService: https://redocly.com/subscription-agreement
+servers:
+  - url: https://api.cafe.redocly.com
+    description: Live server.
+tags:
+  - name: Authorization
+    description: Create a client to demo the API.
+  - name: Products
+    description: Operations related to products.
+  - name: Orders
+    description: Order management operations.
+  - name: Statistics
+    description: Statistics operations.
+paths:
+  /menu:
+    get:
+      tags:
+        - Products
+      summary: List all menu items
+      description: Retrieve a collection of menu items with optional filtering and pagination.
+      operationId: listMenuItems
+      security: []
+      parameters:
+        - $ref: '#/components/parameters/After'
+        - $ref: '#/components/parameters/Before'
+        - $ref: '#/components/parameters/Sort'
+        - $ref: '#/components/parameters/Filter'
+        - $ref: '#/components/parameters/Search'
+        - $ref: '#/components/parameters/Limit'
+      responses:
+        '200':
+          description: Successful operation.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MenuItemList'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+    post:
+      tags:
+        - Products
+      summary: Create menu item
+      description: Create a new menu item.
+      operationId: createMenuItem
+      security:
+        - OAuth2:
+            - menu:write
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              $ref: '#/components/schemas/MenuItem'
+      responses:
+        '201':
+          description: Menu item created successfully.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MenuItem'
+              examples:
+                MenuItemResponse:
+                  value:
+                    id: prd_01khr487f7qm7p44xn427m43vb
+                    object: menuItem
+                    name: coffee
+                    price: 4000
+                    category: beverage
+                    createdAt: '2026-02-18T10:20:38.228Z'
+                    updatedAt: '2026-02-18T10:20:38.228Z'
+                    volume: 600
+                    containsCaffeine: false
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '409':
+          $ref: '#/components/responses/Conflict'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+  /menu/{menuItemId}:
+    parameters:
+      - $ref: '#/components/parameters/MenuItemId'
+    delete:
+      tags:
+        - Products
+      summary: Delete a menu item
+      description: Delete an existing menu item.
+      operationId: deleteMenuItem
+      security:
+        - OAuth2:
+            - menu:write
+      responses:
+        '204':
+          description: Menu item deleted successfully.
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+  /menu-item-images/{menuItemId}:
+    parameters:
+      - $ref: '#/components/parameters/MenuItemId'
+    get:
+      operationId: getMenuItemPhoto
+      summary: Retrieve a menu item photo
+      description: Retrieve the product photo image for a specific menu item.
+      security: []
+      tags:
+        - Products
+      parameters:
+        - $ref: '#/components/parameters/PhotoSize'
+      responses:
+        '200':
+          description: Menu item photo retrieved successfully.
+          content:
+            image/png:
+              schema:
+                type: string
+                format: binary
+            text/plain:
+              schema:
+                description: Alternative image text.
+                type: string
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+  /orders:
+    get:
+      tags:
+        - Orders
+      summary: List all orders
+      description: Retrieve a collection of orders with optional filtering and pagination.
+      operationId: listOrders
+      security:
+        - OAuth2:
+            - orders:read
+      parameters:
+        - $ref: '#/components/parameters/Filter'
+        - $ref: '#/components/parameters/Sort'
+        - $ref: '#/components/parameters/Limit'
+        - $ref: '#/components/parameters/After'
+        - $ref: '#/components/parameters/Before'
+        - $ref: '#/components/parameters/Search'
+      responses:
+        '200':
+          description: Successful operation.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OrderList'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+    post:
+      tags:
+        - Orders
+      summary: Create order
+      description: |
+        Create a new order.
+        Order items cannot be changed - if they need to be updated, the order should be canceled and a new one placed.
+      operationId: createOrder
+      security:
+        - OAuth2:
+            - orders:write
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Order'
+            examples:
+              OrderRequest:
+                dataValue:
+                  customerName: Mary Ann
+                  orderItems:
+                    - menuItemId: prd_01h1s5z6vf2mm1mz3hevnn9va7
+                      quantity: 2
+                      comment: No sugar!
+                      discount: 0
+      responses:
+        '201':
+          description: Order placed successfully.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Order'
+              examples:
+                OrderResponse:
+                  dataValue:
+                    id: ord_01h1s5z6vf2mm1mz3hevnn9va7
+                    customerName: Mary Ann
+                    orderItems:
+                      - menuItemId: prd_01h1s5z6vf2mm1mz3hevnn9va7
+                        quantity: 2
+                        comment: No sugar!
+                        discount: 0
+                    object: order
+                    status: placed
+                    totalPrice: 200
+                    createdAt: '2026-08-24T14:15:22Z'
+                    updatedAt: '2026-08-24T14:15:22Z'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+  /orders/{orderId}:
+    get:
+      tags:
+        - Orders
+      summary: Retrieve an order
+      description: Retrieve a single order by its ID.
+      operationId: getOrderById
+      security:
+        - OAuth2:
+            - orders:read
+      parameters:
+        - $ref: '#/components/parameters/OrderId'
+        - name: X-Request-Id
+          in: header
+          required: false
+          description: |
+            Optional client-supplied correlation ID, echoed in logs and traces.
+          schema:
+            type: string
+            format: uuid
+      responses:
+        '200':
+          description: Successful operation.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Order'
+              examples:
+                OrderResponse:
+                  dataValue:
+                    id: ord_01h1s5z6vf2mm1mz3hevnn9va7
+                    customerName: Mary Ann
+                    orderItems:
+                      - menuItemId: prd_01h1s5z6vf2mm1mz3hevnn9va7
+                        quantity: 2
+                        comment: No sugar!
+                        discount: 0
+                    object: order
+                    status: placed
+                    totalPrice: 200
+                    createdAt: '2026-08-24T14:15:22Z'
+                    updatedAt: '2026-08-24T14:15:22Z'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+    patch:
+      tags:
+        - Orders
+      summary: Partially update an order
+      description: |
+        Update an existing order status.
+        Order items cannot be changed - if they need to be updated, the order should be canceled and a new one placed.
+      operationId: updateOrder
+      security:
+        - OAuth2:
+            - orders:write
+      parameters:
+        - $ref: '#/components/parameters/OrderId'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              description: |
+                Partial order update using JSON Merge Patch - only include fields to update.
+              properties:
+                status:
+                  $ref: '#/components/schemas/OrderStatus'
+              required:
+                - status
+      responses:
+        '200':
+          description: Order updated successfully.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Order'
+              examples:
+                OrderResponse:
+                  dataValue:
+                    id: ord_01h1s5z6vf2mm1mz3hevnn9va7
+                    customerName: Mary Ann
+                    orderItems:
+                      - menuItemId: prd_01h1s5z6vf2mm1mz3hevnn9va7
+                        quantity: 2
+                        comment: No sugar!
+                        discount: 0
+                    object: order
+                    status: completed
+                    totalPrice: 200
+                    createdAt: '2026-08-24T14:15:22Z'
+                    updatedAt: '2026-08-24T14:15:22Z'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+    delete:
+      tags:
+        - Orders
+      summary: Delete an order
+      description: |
+        Delete the order.
+        To keep the order history, the order should be canceled instead of deleted.
+      operationId: deleteOrder
+      security:
+        - OAuth2:
+            - orders:write
+      parameters:
+        - $ref: '#/components/parameters/OrderId'
+      responses:
+        '204':
+          description: Order deleted successfully.
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+  /order-items:
+    get:
+      tags:
+        - Orders
+      summary: List all order items with menu item details
+      description: |
+        Returns an array of order items for a specific order.
+        Use the `filter` parameter to filter by order ID.
+      operationId: listOrderItems
+      security:
+        - OAuth2:
+            - orders:read
+      parameters:
+        - $ref: '#/components/parameters/Filter'
+          required: true
+      responses:
+        '200':
+          description: Successful operation.
+          content:
+            application/json:
+              schema:
+                type: array
+                description: List of menu items that are part of the order.
+                items:
+                  $ref: '#/components/schemas/OrderItem'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+  /revenue:
+    get:
+      tags:
+        - Statistics
+      summary: Get revenue statistics
+      description: |
+        Retrieve revenue statistics for a configurable date range.
+        Returns revenue, order counts, average order amount, and other useful statistics.
+      operationId: getRevenue
+      security:
+        - ApiKey: []
+      parameters:
+        - name: startDate
+          in: query
+          required: false
+          description: |
+            Start date for the revenue calculation period (ISO 8601 datetime format).
+            Defaults to 30 days ago if not provided.
+          schema:
+            type: string
+            format: date
+          example: '2026-01-01'
+        - name: endDate
+          in: query
+          required: false
+          description: |
+            End date for the revenue calculation period (ISO 8601 datetime format).
+            Defaults to current time if not provided.
+          schema:
+            type: string
+            format: date
+          example: '2026-01-31'
+      responses:
+        '200':
+          description: Revenue statistics retrieved successfully.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RevenueStatistics'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+  /oauth2/register:
+    post:
+      tags:
+        - Authorization
+      summary: Create OAuth2 client
+      description: |
+        Register a new OAuth2 client for dynamic client registration.  This endpoint implements the Dynamic Client Registration Protocol (RFC 7591), using camelCase field names instead of the RFC's snake_case convention (e.g., `redirectUris` instead of `redirect_uris`, `grantTypes` instead of `grant_types`). The `name` field is required. Other fields are optional. If not provided:
+        - `redirectUris` defaults to an empty array. Note: When using the `authorization_code` grant type, 
+          `redirectUris` must be provided (per RFC 7591 Section 2).
+        - `scopes` defaults to all available scopes (menu:read, menu:write, orders:read, orders:write) - `grantTypes` defaults to both supported grant types (authorization_code, client_credentials)
+        Returns the registered client information per RFC 7591, including:
+        - `clientId` and `clientSecret` (must be stored securely) - `clientIdIssuedAt` and `clientSecretExpiresAt` timestamps - All registered client metadata (name, redirectUris, scopes, grantTypes)
+      operationId: registerOAuth2Client
+      security: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RegisterClientObject'
+      responses:
+        '201':
+          description: OAuth2 client registered successfully.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OAuth2Client'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+webhooks:
+  order-notification:
+    post:
+      tags:
+        - Orders
+      operationId: orderNotificationWebhook
+      security: []
+      summary: Order notification webhook
+      description: Webhook triggered when a new order is placed.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/OrderNotification'
+      responses:
+        '200':
+          description: Webhook received successfully.
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+components:
+  securitySchemes:
+    OAuth2:
+      type: oauth2
+      description: OAuth2 authorization for API access.
+      flows:
+        authorizationCode:
+          authorizationUrl: https://api.cafe.redocly.com/oauth2/authorize
+          tokenUrl: https://api.cafe.redocly.com/oauth2/token
+          scopes:
+            menu:read: Read access to menu items and images
+            menu:write: Write access to menu items (create, delete)
+            orders:read: Read access to orders
+            orders:write: Write access to orders (create, update, delete)
+        clientCredentials:
+          tokenUrl: https://api.cafe.redocly.com/oauth2/token
+          scopes:
+            menu:read: Read access to menu items and images
+            menu:write: Write access to menu items (create, delete)
+            orders:read: Read access to orders
+            orders:write: Write access to orders (create, update, delete)
+    ApiKey:
+      type: apiKey
+      name: X-API-Key
+      in: header
+      description: API key for internal operations.
+  parameters:
+    After:
+      name: after
+      in: query
+      required: false
+      description: Use the `endCursor` as a value for the `after` parameter to get the next page.
+      schema:
+        type: string
+      example: a25fgaksjf23la==
+    Before:
+      name: before
+      in: query
+      required: false
+      description: |
+        Use the `startCursor` as a value for the `before` parameter to get the next page.
+      schema:
+        type: string
+      example: bfg23aksjf23zb1==
+    Sort:
+      name: sort
+      description: |-
+        To sort by id in descending order use `-id`.
+        To sort by id in ascending order use `id`.
+      in: query
+      required: false
+      schema:
+        type: string
+      example: '-name'
+    Filter:
+      name: filter
+      description: |-
+        Filters the collection items using space-separated `field:value` pairs.
+
+        **Format:** `field1:value1 field2:value2`
+
+        **Supported operators:**
+        - `field:value` - Exact match
+        - `field:value1,value2` - Match any of the comma-separated values (OR)
+        - Time ranges: Use `30d` (30 days), `7d` (7 days), `1h` (1 hour), etc.
+
+        **Examples:**
+        - `status:placed` - Filter by single status.
+        - `status:placed,completed` - Filter by multiple statuses.
+        - `createdAt:30d` - Filter orders created in the last 30 days.
+        - `orderId:ord_01h1s5z6vf2mm1mz3hevnn9va7` - Filter by specific order ID.
+        - `status:placed createdAt:7d` - Combine multiple filters.
+      in: query
+      required: false
+      schema:
+        type: string
+      example: orderId:ord_01h1s5z6vf2mm1mz3hevnn9va7
+    Search:
+      name: search
+      in: query
+      description: |-
+        Performs a case-insensitive text search across relevant fields in the collection.
+
+        **Fields searched depend on the endpoint:**
+        - **Menu items:** `name`, `photoTextDescription`
+        - **Orders:** `customerName`, `id`
+
+        Returns items where any of the searchable fields contain the search term as a substring.
+      required: false
+      schema:
+        type: string
+      example: coffee
+    Limit:
+      name: limit
+      description: |
+        Use to return a number of results per page.
+        If there is more data, use in combination with `after` to page through the data.
+      in: query
+      required: false
+      schema:
+        type: integer
+        minimum: 1
+        maximum: 100
+        default: 10
+      example: 10
+    MenuItemId:
+      name: menuItemId
+      in: path
+      description: ID of the menu item to retrieve.
+      required: true
+      schema:
+        type: string
+        pattern: ^prd_[0-9abcdefghjkmnpqrstvwxyz]{26}$
+      example: prd_01h1s5z6vf2mm1mz3hevnn9va7
+    PhotoSize:
+      name: photoSize
+      in: query
+      description: Photo size to retrieve.
+      required: false
+      schema:
+        type: string
+        enum:
+          - thumbnail
+          - medium
+          - large
+        default: medium
+    OrderId:
+      name: orderId
+      in: path
+      description: ID of the order to retrieve.
+      required: true
+      schema:
+        type: string
+        pattern: ^ord_[0-9abcdefghjkmnpqrstvwxyz]{26}$
+      example: ord_01h1s5z6vf2mm1mz3hevnn9va7
+  schemas:
+    Page:
+      type: object
+      properties:
+        endCursor:
+          type:
+            - string
+            - 'null'
+          description: |-
+            Use with the `after` query parameter to load the next page of data.
+            When `null`, there is no data.
+            The cursor is opaque and internal structure is subject to change.
+        startCursor:
+          type:
+            - string
+            - 'null'
+          description: |-
+            Use with the `before` query parameter to load the previous page of data.
+            When `null`, there is no data.
+            The cursor is opaque and internal structure is subject to change.
+        hasNextPage:
+          type: boolean
+          description: Indicates if there is a next page with items.
+        hasPrevPage:
+          type: boolean
+          description: Indicates if there is a previous page with items.
+        limit:
+          type: integer
+          minimum: 1
+          maximum: 100
+          default: 10
+          description: Value showing how many items are in the page limit.
+        total:
+          type: integer
+          description: Count of items across all pages.
+          minimum: 0
+      required:
+        - endCursor
+        - startCursor
+        - hasNextPage
+        - hasPrevPage
+        - limit
+        - total
+    MenuBaseItem:
+      type: object
+      properties:
+        createdAt:
+          description: Created date.
+          type: string
+          format: date-time
+          readOnly: true
+        updatedAt:
+          description: Updated date.
+          type: string
+          format: date-time
+          readOnly: true
+        id:
+          description: Menu item ID. Unique identifier prefixed with `prd_`.
+          type: string
+          readOnly: true
+          pattern: ^prd_[0-9abcdefghjkmnpqrstvwxyz]{26}$
+          example: prd_01h1s5z6vf2mm1mz3hevnn9va7
+        object:
+          description: Entity name.
+          type: string
+          const: menuItem
+          readOnly: true
+        name:
+          description: Menu item name.
+          type: string
+          minLength: 1
+          maxLength: 50
+        price:
+          description: Price in cents.
+          type: integer
+          minimum: 0
+        photo:
+          writeOnly: true
+          type:
+            - string
+            - 'null'
+          format: binary
+          description: Photo of the menu item. Must be a PNG image and less than 1MB.
+        photoUrl:
+          readOnly: true
+          type: string
+          format: uri
+          description: Photo URL of the menu item.
+        photoTextDescription:
+          type:
+            - string
+            - 'null'
+      required:
+        - id
+        - name
+        - price
+        - createdAt
+        - updatedAt
+        - object
+    Beverage:
+      allOf:
+        - type: object
+          properties:
+            category:
+              description: Menu item category.
+              type: string
+              const: beverage
+            volume:
+              type: number
+              description: Size of the beverage in milliliters.
+              exclusiveMinimum: 0
+            containsCaffeine:
+              type: boolean
+              description: Indicates if the beverage contains caffeine.
+          required:
+            - category
+            - volume
+            - containsCaffeine
+        - $ref: '#/components/schemas/MenuBaseItem'
+    Dessert:
+      allOf:
+        - type: object
+          properties:
+            category:
+              description: Menu item category.
+              type: string
+              const: dessert
+            calories:
+              type: number
+              exclusiveMinimum: 0
+              description: Amount of calories.
+          required:
+            - category
+            - calories
+        - $ref: '#/components/schemas/MenuBaseItem'
+    MenuItem:
+      discriminator:
+        propertyName: category
+        mapping:
+          beverage: '#/components/schemas/Beverage'
+          dessert: '#/components/schemas/Dessert'
+      oneOf:
+        - $ref: '#/components/schemas/Beverage'
+        - $ref: '#/components/schemas/Dessert'
+      required:
+        - category
+    MenuItemList:
+      type: object
+      properties:
+        object:
+          type: string
+          const: list
+          description: Entity name.
+        page:
+          $ref: '#/components/schemas/Page'
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/MenuItem'
+      required:
+        - object
+        - page
+        - items
+    Error:
+      type: object
+      properties:
+        type:
+          type: string
+          format: uri-reference
+          description: URI reference that identifies the problem type.
+          default: about:blank
+        title:
+          type: string
+          description: Short summary of the problem type.
+        status:
+          type: integer
+          format: int32
+          description: |
+            HTTP status code generated by the origin server for this occurrence of the problem.
+          minimum: 100
+          exclusiveMaximum: 600
+        instance:
+          type: string
+          format: uri-reference
+          description: |
+            URI reference that identifies the specific occurrence of the problem, e.g. by adding a fragment identifier or sub-path to the problem type.
+            May be used to locate the root of this problem in the source code.
+          example: /some/uri-reference#specific-occurrence-context
+        details:
+          description: Additional error details.
+          type: object
+          additionalProperties: true
+      required:
+        - type
+        - title
+        - status
+    OrderStatus:
+      type: string
+      description: Order status.
+      enum:
+        - placed
+        - preparing
+        - completed
+        - canceled
+    Order:
+      type: object
+      title: Order
+      properties:
+        id:
+          description: Order ID. Unique identifier prefixed with `ord_`.
+          type: string
+          format: ulid
+          readOnly: true
+          pattern: ^ord_[0-9abcdefghjkmnpqrstvwxyz]{26}$
+          example: ord_01h1s5z6vf2mm1mz3hevnn9va7
+        object:
+          description: Entity name.
+          type: string
+          const: order
+          readOnly: true
+        customerName:
+          description: |
+            Name of the customer who placed the order.
+            Must start and end with a letter, and can contain letters, spaces, hyphens, and apostrophes (e.g., "John Doe", "Mary-Jane", "O'Brien").
+          type: string
+          pattern: ^[A-Za-z]+(?:[\s'-][A-Za-z]+)*$
+          minLength: 1
+          maxLength: 100
+        status:
+          allOf:
+            - $ref: '#/components/schemas/OrderStatus'
+          readOnly: true
+        totalPrice:
+          description: Total order price in cents.
+          type: integer
+          minimum: 0
+          readOnly: true
+        createdAt:
+          description: Created date.
+          type: string
+          format: date-time
+          readOnly: true
+        updatedAt:
+          description: Updated date.
+          type: string
+          format: date-time
+          readOnly: true
+        orderItems:
+          type: array
+          description: List of items to include in the order.
+          minItems: 1
+          items:
+            type: object
+            properties:
+              menuItemId:
+                type: string
+                format: ulid
+                description: ID of the menu item to add to the order.
+              quantity:
+                type: integer
+                minimum: 1
+                description: Quantity of the menu item.
+              discount:
+                type: integer
+                minimum: 0
+                description: Discount amount in cents (absolute value).
+                default: 0
+              comment:
+                type: string
+                maxLength: 500
+                description: Optional comment for the order item (e.g., "No sugar").
+            required:
+              - menuItemId
+              - quantity
+      required:
+        - customerName
+        - orderItems
+    OrderList:
+      type: object
+      properties:
+        object:
+          type: string
+          const: list
+          description: Entity name.
+        page:
+          $ref: '#/components/schemas/Page'
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/Order'
+      required:
+        - object
+        - page
+        - items
+    OrderItem:
+      type: object
+      properties:
+        menuItemId:
+          type: string
+          description: ID of the menu item to add to the order.
+          writeOnly: true
+        menuItem:
+          allOf:
+            - $ref: '#/components/schemas/MenuItem'
+          description: Menu item that is part of the order.
+          readOnly: true
+        quantity:
+          type: integer
+          minimum: 1
+          description: Quantity of the menu item.
+        discount:
+          type: integer
+          minimum: 0
+          description: Discount amount in cents (absolute value).
+          default: 0
+        comment:
+          type: string
+          maxLength: 500
+          description: Optional comment for the order item (e.g., "No sugar").
+      required:
+        - menuItemId
+        - quantity
+    RevenueStatistics:
+      type: object
+      description: Revenue statistics for a given date range.
+      properties:
+        revenue:
+          type: number
+          format: float
+          description: Total revenue in cents from completed orders.
+          minimum: 0
+        averageOrderAmount:
+          type: number
+          format: float
+          description: Average order amount in cents (calculated from completed orders only).
+          minimum: 0
+        totalOrders:
+          type: integer
+          description: Total number of orders (all statuses) in the date range.
+          minimum: 0
+        placedOrders:
+          type: integer
+          description: Number of placed orders.
+          minimum: 0
+        preparingOrders:
+          type: integer
+          description: Number of preparing orders.
+          minimum: 0
+        completedOrders:
+          type: integer
+          description: Number of completed orders.
+          minimum: 0
+        canceledOrders:
+          type: integer
+          description: Number of canceled orders.
+          minimum: 0
+        startDate:
+          type: string
+          format: date
+          description: Start date of the revenue calculation period.
+        endDate:
+          type: string
+          format: date
+          description: End date of the revenue calculation period.
+      required:
+        - revenue
+        - averageOrderAmount
+        - totalOrders
+        - placedOrders
+        - preparingOrders
+        - completedOrders
+        - canceledOrders
+        - startDate
+        - endDate
+    RegisterClientObject:
+      type: object
+      properties:
+        name:
+          type: string
+          description: Client name.
+        redirectUris:
+          type: array
+          items:
+            type: string
+            format: uri
+          description: List of redirect URIs (optional, defaults to empty array).
+        scopes:
+          type: array
+          items:
+            type: string
+            enum:
+              - menu:read
+              - menu:write
+              - orders:read
+              - orders:write
+          description: List of scopes.
+        grantTypes:
+          type: array
+          items:
+            type: string
+            enum:
+              - authorization_code
+              - client_credentials
+          description: List of grant types.
+      required:
+        - name
+    OAuth2Client:
+      type: object
+      description: OAuth2 client registration response. Per RFC 7591, includes the client identifier, secret, timestamps, and all registered client metadata.
+      properties:
+        clientId:
+          type: string
+          description: Client identifier issued by the authorization server.
+        clientSecret:
+          type: string
+          description: Client secret issued by the authorization server.
+        clientIdIssuedAt:
+          type: integer
+          format: int64
+          description: Time when the client_id is issued, represented as seconds since epoch (RFC7591).
+        clientSecretExpiresAt:
+          type: integer
+          format: int64
+          description: Time at which the client_secret expires, represented as seconds since epoch. 0 indicates the secret does not expire (RFC 7591).
+        name:
+          type: string
+          description: Client name (registered metadata).
+        redirectUris:
+          type: array
+          items:
+            type: string
+            format: uri
+          description: List of redirect URIs (registered metadata).
+        registrationClientUri:
+          type: string
+          format: uri
+          description: URL of the client configuration endpoint for managing this client registration (RFC 7592).
+        registrationAccessToken:
+          type: string
+          description: Access token to be used at the client configuration endpoint for managing this client registration (RFC 7592).
+        scopes:
+          type: array
+          items:
+            type: string
+            enum:
+              - menu:read
+              - menu:write
+              - orders:read
+              - orders:write
+          description: List of scopes (registered metadata).
+        grantTypes:
+          type: array
+          items:
+            type: string
+            enum:
+              - authorization_code
+              - client_credentials
+          description: List of grant types (registered metadata).
+      required:
+        - clientId
+        - clientSecret
+        - clientIdIssuedAt
+        - clientSecretExpiresAt
+        - registrationClientUri
+        - registrationAccessToken
+    OrderNotification:
+      type: object
+      required:
+        - orderId
+        - orderStatus
+        - timestamp
+      properties:
+        orderId:
+          type: string
+          description: Unique order identifier.
+        orderStatus:
+          $ref: '#/components/schemas/OrderStatus'
+        timestamp:
+          type: string
+          format: date-time
+          description: When the event occurred.
+  responses:
+    BadRequest:
+      description: Bad request - invalid input parameters.
+      content:
+        application/problem+json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    InternalServerError:
+      description: Internal server error.
+      content:
+        application/problem+json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    Unauthorized:
+      description: Unauthorized - authorization required.
+      content:
+        application/problem+json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    Forbidden:
+      description: Forbidden - insufficient permissions.
+      content:
+        application/problem+json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    Conflict:
+      description: Conflict - entity already exists.
+      content:
+        application/problem+json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    NotFound:
+      description: Resource not found.
+      content:
+        application/problem+json:
+          schema:
+            $ref: '#/components/schemas/Error'
diff --git a/tests/e2e/generate-client/fixtures/error-mode.yaml b/tests/e2e/generate-client/fixtures/error-mode.yaml
new file mode 100644
index 0000000000..e6ffff38b1
--- /dev/null
+++ b/tests/e2e/generate-client/fixtures/error-mode.yaml
@@ -0,0 +1,36 @@
+openapi: 3.0.3
+info: { title: Error Mode API, version: 1.0.0 }
+servers:
+  - { url: https://api.example.com }
+paths:
+  /things/{id}:
+    get:
+      operationId: getThing
+      tags: [things]
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string } }
+      responses:
+        '200':
+          description: ok
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Thing' }
+        '404':
+          description: not found
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ProblemDetails' }
+components:
+  schemas:
+    Thing:
+      type: object
+      required: [id]
+      properties:
+        id: { type: string }
+        name: { type: string }
+    ProblemDetails:
+      type: object
+      required: [title]
+      properties:
+        title: { type: string }
+        status: { type: integer }
diff --git a/tests/e2e/generate-client/fixtures/no-operationid.yaml b/tests/e2e/generate-client/fixtures/no-operationid.yaml
new file mode 100644
index 0000000000..cee32bb4c3
--- /dev/null
+++ b/tests/e2e/generate-client/fixtures/no-operationid.yaml
@@ -0,0 +1,20 @@
+openapi: 3.0.3
+info: { title: No OperationId API, version: 1.0.0 }
+servers:
+  - { url: https://api.example.com }
+paths:
+  /giftcards/{cardId}:
+    get:
+      responses:
+        '200':
+          description: ok
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Giftcard' }
+components:
+  schemas:
+    Giftcard:
+      type: object
+      required: [cardId]
+      properties:
+        cardId: { type: string }
diff --git a/tests/e2e/generate-client/fixtures/oas3.2.yaml b/tests/e2e/generate-client/fixtures/oas3.2.yaml
new file mode 100644
index 0000000000..1447ecf8b9
--- /dev/null
+++ b/tests/e2e/generate-client/fixtures/oas3.2.yaml
@@ -0,0 +1,27 @@
+openapi: 3.2.0
+$self: https://example.com/openapi
+info: { title: OAS 3.2 API, version: 1.0.0 }
+servers:
+  - { url: https://api.example.com, name: production }
+paths:
+  /things/{id}:
+    get:
+      operationId: getThing
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string } }
+      responses:
+        '200':
+          description: ok
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Thing' }
+components:
+  schemas:
+    Thing:
+      type: object
+      required: [id]
+      properties:
+        id: { type: string }
+        status:
+          type: [string, 'null']
+          enum: [active, archived, null]
diff --git a/tests/e2e/generate-client/fixtures/package-runtime.yaml b/tests/e2e/generate-client/fixtures/package-runtime.yaml
new file mode 100644
index 0000000000..a5e5605b19
--- /dev/null
+++ b/tests/e2e/generate-client/fixtures/package-runtime.yaml
@@ -0,0 +1,82 @@
+openapi: 3.1.0
+info:
+  title: Package Runtime API
+  version: 1.0.0
+servers:
+  - url: http://localhost:3123
+paths:
+  /orders/{order-id}:
+    get:
+      operationId: getOrder
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: order-id
+          in: path
+          required: true
+          schema: { type: string }
+        - name: expand
+          in: query
+          schema: { type: string }
+      responses:
+        '200':
+          description: The order.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Order' }
+  /orders:
+    post:
+      operationId: createOrder
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/NewOrder' }
+      responses:
+        '201':
+          description: Created.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Order' }
+  /configure-op:
+    get:
+      # Collides with the client's reserved `configure` member — the operation is renamed.
+      operationId: configure
+      responses:
+        '200':
+          description: Status.
+          content:
+            application/json:
+              schema: { type: string }
+  /events:
+    get:
+      operationId: streamEvents
+      responses:
+        '200':
+          description: Order events.
+          content:
+            text/event-stream:
+              schema: { $ref: '#/components/schemas/OrderEvent' }
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+  schemas:
+    Order:
+      type: object
+      required: [id, status]
+      properties:
+        id: { type: string }
+        status: { type: string }
+    NewOrder:
+      type: object
+      required: [status]
+      properties:
+        status: { type: string }
+    OrderEvent:
+      type: object
+      required: [seq]
+      properties:
+        seq: { type: integer }
+        text: { type: string }
diff --git a/tests/e2e/generate-client/fixtures/pagination.yaml b/tests/e2e/generate-client/fixtures/pagination.yaml
new file mode 100644
index 0000000000..6d016c79e5
--- /dev/null
+++ b/tests/e2e/generate-client/fixtures/pagination.yaml
@@ -0,0 +1,98 @@
+openapi: 3.1.0
+info:
+  title: Cafe Orders Pagination API
+  version: 1.0.0
+servers:
+  - url: http://localhost:3131
+paths:
+  /orders:
+    get:
+      operationId: listOrders
+      summary: List orders, one cursor page at a time.
+      # The extension arm: the pagination rule travels with the spec — no config needed.
+      x-pagination:
+        style: cursor
+        cursorParam: cursor
+        nextCursor: /nextCursor
+        limitParam: limit
+        items: /orders
+      parameters:
+        - name: cursor
+          in: query
+          description: Opaque cursor of the page to fetch; omit for the first page.
+          schema: { type: string }
+        - name: limit
+          in: query
+          description: Page size.
+          schema: { type: integer }
+      responses:
+        '200':
+          description: One page of orders.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [orders]
+                properties:
+                  orders:
+                    type: array
+                    items: { $ref: '#/components/schemas/Order' }
+                  nextCursor:
+                    description: Cursor of the next page; absent on the last page.
+                    type: string
+  /menu:
+    get:
+      operationId: listMenuItems
+      summary: List menu items, one offset page at a time.
+      # No extension here — pagination arrives via the config convention rule.
+      parameters:
+        - name: offset
+          in: query
+          description: Index of the first item to return.
+          schema: { type: integer }
+        - name: limit
+          in: query
+          description: Page size.
+          schema: { type: integer }
+      responses:
+        '200':
+          description: One page of menu items.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [items, total]
+                properties:
+                  items:
+                    type: array
+                    items: { $ref: '#/components/schemas/MenuItem' }
+                  total: { type: integer }
+  /orders/{orderId}:
+    get:
+      operationId: getOrder
+      summary: Retrieve one order.
+      parameters:
+        - name: orderId
+          in: path
+          required: true
+          schema: { type: string }
+      responses:
+        '200':
+          description: The order.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Order' }
+components:
+  schemas:
+    Order:
+      type: object
+      required: [id, status]
+      properties:
+        id: { type: string }
+        status: { type: string }
+    MenuItem:
+      type: object
+      required: [id, name]
+      properties:
+        id: { type: string }
+        name: { type: string }
diff --git a/tests/e2e/generate-client/fixtures/query-styles.yaml b/tests/e2e/generate-client/fixtures/query-styles.yaml
new file mode 100644
index 0000000000..9d140cb7c3
--- /dev/null
+++ b/tests/e2e/generate-client/fixtures/query-styles.yaml
@@ -0,0 +1,56 @@
+openapi: 3.0.3
+info:
+  title: Query Styles
+  version: 1.0.0
+servers:
+  - url: http://localhost:3199
+paths:
+  /search:
+    get:
+      operationId: search
+      parameters:
+        - name: tags
+          in: query
+          style: pipeDelimited
+          explode: false
+          schema:
+            type: array
+            items:
+              type: string
+        - name: q
+          in: query
+          style: spaceDelimited
+          explode: false
+          schema:
+            type: array
+            items:
+              type: string
+        - name: ids
+          in: query
+          style: form
+          explode: false
+          schema:
+            type: array
+            items:
+              type: string
+        - name: filter
+          in: query
+          allowReserved: true
+          schema:
+            type: string
+        - name: limit
+          in: query
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: Results.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  results:
+                    type: array
+                    items:
+                      type: string
diff --git a/tests/e2e/generate-client/fixtures/route-map-plugin.mjs b/tests/e2e/generate-client/fixtures/route-map-plugin.mjs
new file mode 100644
index 0000000000..937da80d82
--- /dev/null
+++ b/tests/e2e/generate-client/fixtures/route-map-plugin.mjs
@@ -0,0 +1,18 @@
+// A custom generator loaded by path specifier in the plugin e2e. Plain ESM (no imports) so the
+// compiled CLI can import it under bare `node`. Emits a `<output>.routes.ts` map of every operation.
+export default {
+  name: 'route-map',
+  requires: ['sdk'],
+  run({ model, outputPath }) {
+    const routes = model.services
+      .flatMap((s) => s.operations)
+      .map((op) => `  ${op.name}: '${op.method.toUpperCase()} ${op.path}',`)
+      .join('\n');
+    return [
+      {
+        path: outputPath.replace(/\.ts$/, '.routes.ts'),
+        content: `export const routes = {\n${routes}\n} as const;\n`,
+      },
+    ];
+  },
+};
diff --git a/tests/e2e/generate-client/fixtures/sse.yaml b/tests/e2e/generate-client/fixtures/sse.yaml
new file mode 100644
index 0000000000..47fffcc4a4
--- /dev/null
+++ b/tests/e2e/generate-client/fixtures/sse.yaml
@@ -0,0 +1,58 @@
+openapi: 3.2.0
+$self: https://example.com/openapi
+info: { title: SSE API, version: 1.0.0 }
+servers:
+  - { url: http://localhost:3104, name: production }
+paths:
+  /health:
+    get:
+      operationId: getHealth
+      tags: [Health]
+      responses:
+        '200':
+          description: ok
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Health' }
+  /messages:
+    get:
+      operationId: streamMessages
+      tags: [Messages]
+      responses:
+        '200':
+          description: a stream of messages
+          content:
+            text/event-stream:
+              itemSchema: { $ref: '#/components/schemas/Message' }
+  /abort-messages:
+    get:
+      operationId: streamAbort
+      tags: [Messages]
+      responses:
+        '200':
+          description: a long-lived stream of messages (for the abort scenario)
+          content:
+            text/event-stream:
+              itemSchema: { $ref: '#/components/schemas/Message' }
+  /ticks:
+    get:
+      operationId: streamTicks
+      tags: [Ticks]
+      responses:
+        '200':
+          description: a stream of raw ticks
+          content:
+            text/event-stream: {}
+components:
+  schemas:
+    Health:
+      type: object
+      required: [status]
+      properties:
+        status: { type: string }
+    Message:
+      type: object
+      required: [text, seq]
+      properties:
+        text: { type: string }
+        seq: { type: integer }
diff --git a/tests/e2e/generate-client/fixtures/swagger2.yaml b/tests/e2e/generate-client/fixtures/swagger2.yaml
new file mode 100644
index 0000000000..1c09b6611f
--- /dev/null
+++ b/tests/e2e/generate-client/fixtures/swagger2.yaml
@@ -0,0 +1,37 @@
+swagger: '2.0'
+info: { title: Swagger2 API, version: 1.0.0 }
+host: api.example.com
+basePath: /v2
+schemes: [https]
+consumes: [application/json]
+produces: [application/json]
+securityDefinitions:
+  ApiKey: { type: apiKey, name: X-API-Key, in: header }
+paths:
+  /pets/{id}:
+    get:
+      operationId: getPet
+      parameters:
+        - { name: id, in: path, required: true, type: integer }
+        - { name: verbose, in: query, required: false, type: boolean }
+      responses:
+        '200': { description: ok, schema: { $ref: '#/definitions/Pet' } }
+  /pets:
+    post:
+      operationId: createPet
+      parameters:
+        - { name: body, in: body, required: true, schema: { $ref: '#/definitions/Pet' } }
+      responses:
+        '201': { description: created, schema: { $ref: '#/definitions/Pet' } }
+definitions:
+  Pet:
+    type: object
+    required: [id, name]
+    properties:
+      id: { type: integer }
+      name: { type: string }
+      owner: { $ref: '#/definitions/Owner' }
+  Owner:
+    type: object
+    properties:
+      name: { type: string }
diff --git a/tests/e2e/generate-client/fixtures/transformers.yaml b/tests/e2e/generate-client/fixtures/transformers.yaml
new file mode 100644
index 0000000000..2bd80b6deb
--- /dev/null
+++ b/tests/e2e/generate-client/fixtures/transformers.yaml
@@ -0,0 +1,61 @@
+openapi: 3.1.0
+info:
+  title: Transformers Fixture
+  version: 1.0.0
+  description: |
+    Exercises the `--date-type Date` sdk knob + the `transformers` generator
+    across the date-bearing shapes: a top-level `date-time` scalar, an array of
+    `date` scalars, and a `$ref` to another schema that also carries a date (to
+    drive transformer composition `transformPet -> transformOwner`).
+servers:
+  - url: http://localhost:3199
+paths:
+  /pets/{id}:
+    get:
+      operationId: getPet
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: A single pet.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Pet'
+components:
+  schemas:
+    Pet:
+      type: object
+      required: [id, name]
+      properties:
+        id:
+          type: integer
+        name:
+          type: string
+        createdAt:
+          description: Top-level date-time scalar — converted to Date.
+          type: string
+          format: date-time
+        dates:
+          description: Array of date scalars — each element converted to Date.
+          type: array
+          items:
+            type: string
+            format: date
+        owner:
+          description: Ref to a date-bearing schema — drives transformer composition.
+          $ref: '#/components/schemas/Owner'
+    Owner:
+      type: object
+      required: [name]
+      properties:
+        name:
+          type: string
+        since:
+          description: Nested/ref'd date — converted via transformOwner.
+          type: string
+          format: date
diff --git a/tests/e2e/generate-client/generator-contract.test.ts b/tests/e2e/generate-client/generator-contract.test.ts
new file mode 100644
index 0000000000..1c7b982bcb
--- /dev/null
+++ b/tests/e2e/generate-client/generator-contract.test.ts
@@ -0,0 +1,174 @@
+// The generator compatibility contract: an incompatible `--generator` selection must
+// fail fast with an actionable message (never emit a client that won't compile), and
+// `tanstack-query` must gracefully skip SSE operations (which the sdk doesn't export).
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { outdent } from 'outdent';
+
+import { cliEntry, repoRoot, tscBin } from './helpers.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const cafe = join(__dirname, 'fixtures', 'cafe.yaml');
+const sse = join(__dirname, 'fixtures', 'sse.yaml');
+
+function run(args: string[]): { status: number | null; out: string } {
+  const res = spawnSync('node', [cliEntry, 'generate-client', ...args], {
+    encoding: 'utf-8',
+    cwd: repoRoot,
+  });
+  return { status: res.status, out: `${res.stdout}\n${res.stderr}` };
+}
+
+describe('generate-client generator compatibility contract', () => {
+  it('rejects tanstack-query without sdk, naming the fix', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'ots-contract-'));
+    const { status, out } = run([
+      cafe,
+      '--output',
+      join(dir, 'c.ts'),
+      '--generator',
+      'tanstack-query',
+    ]);
+    expect(status).not.toBe(0);
+    expect(out).toMatch(/requires the "sdk" generator/);
+    expect(out).toMatch(/--generator sdk --generator tanstack-query/);
+    rmSync(dir, { recursive: true, force: true });
+  }, 60_000);
+
+  it('rejects tanstack-query with result error mode', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'ots-contract-'));
+    const { status, out } = run([
+      cafe,
+      '--output',
+      join(dir, 'c.ts'),
+      '--generator',
+      'sdk',
+      '--generator',
+      'tanstack-query',
+      '--error-mode',
+      'result',
+    ]);
+    expect(status).not.toBe(0);
+    expect(out).toMatch(/does not support --error-mode "result"/);
+    rmSync(dir, { recursive: true, force: true });
+  }, 60_000);
+
+  it('rejects transformers without --date-type Date', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'ots-contract-'));
+    const { status, out } = run([
+      cafe,
+      '--output',
+      join(dir, 'c.ts'),
+      '--generator',
+      'sdk',
+      '--generator',
+      'transformers',
+    ]);
+    expect(status).not.toBe(0);
+    expect(out).toMatch(/requires --date-type Date/);
+    rmSync(dir, { recursive: true, force: true });
+  }, 60_000);
+
+  it('defaults to the sdk client when no --generator is passed', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'ots-contract-'));
+    const outFile = join(dir, 'c.ts');
+    // With no `--generator` flag the selection is unset, so it falls back to the default
+    // sdk generator and emits a client rather than silently producing nothing.
+    const { status, out } = run([cafe, '--output', outFile]);
+    expect(status, out).toBe(0);
+    expect(existsSync(outFile)).toBe(true);
+    expect(readFileSync(outFile, 'utf-8')).toContain('export const client = createClient<Ops,');
+    rmSync(dir, { recursive: true, force: true });
+  }, 60_000);
+
+  it('skips SSE operations in tanstack-query (reporting them) and still emits the rest', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'ots-contract-'));
+    const { status, out } = run([
+      sse,
+      '--output',
+      join(dir, 'c.ts'),
+      '--generator',
+      'sdk',
+      '--generator',
+      'tanstack-query',
+    ]);
+    expect(status, out).toBe(0);
+    expect(out).toMatch(/tanstack-query skipped \d+ server-sent-events operation/);
+    const tanstack = readFileSync(join(dir, 'c.tanstack.ts'), 'utf-8');
+    // The non-SSE op is wrapped; the SSE ops are neither imported nor wrapped.
+    expect(tanstack).toContain('getHealthOptions');
+    expect(tanstack).not.toContain('streamMessages');
+    expect(existsSync(join(dir, 'c.ts'))).toBe(true);
+    rmSync(dir, { recursive: true, force: true });
+  }, 60_000);
+
+  it('skips a tanstack op whose <Op>Variables collides with a schema; the tree still compiles', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'ots-contract-'));
+    // Schema `GetUserVariables` collides with the `getUser` op's derived variables alias.
+    writeFileSync(
+      join(dir, 'api.yaml'),
+      outdent`
+        openapi: 3.1.0
+        info: { title: C, version: '1.0.0' }
+        paths:
+          /users/{id}:
+            get:
+              operationId: getUser
+              parameters: [{ name: id, in: path, required: true, schema: { type: string } }]
+              responses: { '200': { description: ok } }
+          /users:
+            get:
+              operationId: listUsers
+              responses: { '200': { description: ok } }
+        components:
+          schemas:
+            GetUserVariables: { type: object, properties: { ready: { type: boolean } } }
+      `,
+      'utf-8'
+    );
+    const { status, out } = run([
+      join(dir, 'api.yaml'),
+      '--output',
+      join(dir, 'c.ts'),
+      '--generator',
+      'sdk',
+      '--generator',
+      'tanstack-query',
+    ]);
+    expect(status, out).toBe(0);
+    expect(out).toMatch(
+      /tanstack-query skipped \d+ operation\(s\) whose variables type name collides/
+    );
+    const tanstack = readFileSync(join(dir, 'c.tanstack.ts'), 'utf-8');
+    expect(tanstack).not.toContain('getUserOptions'); // colliding op skipped
+    expect(tanstack).toContain('listUsersOptions'); // the rest still wrapped
+    // The whole tree compiles (no import of the suppressed alias).
+    const files = [join(dir, 'c.ts'), join(dir, 'c.tanstack.ts')];
+    const tsc = spawnSync(
+      tscBin,
+      [
+        '--noEmit',
+        '--strict',
+        '--target',
+        'ES2020',
+        '--module',
+        'esnext',
+        '--moduleResolution',
+        'bundler',
+        '--lib',
+        'ES2020,DOM',
+        ...files,
+      ],
+      { encoding: 'utf-8', cwd: dir }
+    );
+    // `@tanstack/react-query` isn't installed in the temp dir; ignore only that missing-module error.
+    const real = tsc.stdout
+      .split('\n')
+      .filter((l) => l.includes('error TS') && !l.includes('@tanstack/react-query'));
+    expect(real, tsc.stdout).toEqual([]);
+    rmSync(dir, { recursive: true, force: true });
+  }, 60_000);
+});
diff --git a/tests/e2e/generate-client/helpers.ts b/tests/e2e/generate-client/helpers.ts
new file mode 100644
index 0000000000..00ac8fd48b
--- /dev/null
+++ b/tests/e2e/generate-client/helpers.ts
@@ -0,0 +1,134 @@
+import { spawn, spawnSync, type ChildProcess } from 'node:child_process';
+import { writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+export const repoRoot = resolve(__dirname, '../../..');
+export const cliEntry = join(repoRoot, 'packages/cli/lib/index.js');
+export const tsxBin = join(repoRoot, 'node_modules/.bin/tsx');
+export const tscBin = join(repoRoot, 'node_modules/.bin/tsc');
+
+export const STRICT_TSCONFIG = {
+  compilerOptions: {
+    module: 'nodenext',
+    moduleResolution: 'nodenext',
+    target: 'es2022',
+    lib: ['ES2022', 'DOM'],
+    strict: true,
+    noEmit: true,
+    skipLibCheck: true,
+    types: [],
+  },
+};
+
+/** Run `generate-client` on a fixture; throws with the CLI's stderr on failure. */
+export function generate(fixture: string, outFile: string, extraArgs: string[] = []): void {
+  const result = spawnSync(
+    'node',
+    [cliEntry, 'generate-client', fixture, '--output', outFile, ...extraArgs],
+    { encoding: 'utf-8', cwd: repoRoot }
+  );
+  if (result.status !== 0) throw new Error(`generate-client failed:\n${result.stderr}`);
+}
+
+/**
+ * Generate `dir/client.ts` from a fixture and mark the dir as an ES module so `tsx`
+ * can run consumer scripts written next to it. Returns the generated entry path.
+ */
+export function generateInto(dir: string, fixture: string, extraArgs: string[] = []): string {
+  writeFileSync(join(dir, 'package.json'), JSON.stringify({ type: 'module' }), 'utf-8');
+  const outFile = join(dir, 'client.ts');
+  generate(fixture, outFile, extraArgs);
+  return outFile;
+}
+
+/** Write a strict tsconfig into `dir` and type-check it; throws with the tsc output on failure. */
+export function strictTypecheck(dir: string, include: string[] = ['**/*.ts']): void {
+  writeFileSync(
+    join(dir, 'tsconfig.json'),
+    JSON.stringify({ ...STRICT_TSCONFIG, include }),
+    'utf-8'
+  );
+  const tsc = spawnSync(tscBin, ['--noEmit', '-p', dir], { encoding: 'utf-8', cwd: repoRoot });
+  if (tsc.status !== 0) throw new Error(`tsc failed:\n${tsc.stdout}\n${tsc.stderr}`);
+}
+
+/** Write `dir/consumer.ts` and run it with tsx; returns its parsed JSON stdout. */
+export function runConsumer(dir: string, script: string): unknown {
+  writeFileSync(join(dir, 'consumer.ts'), script, 'utf-8');
+  const result = spawnSync(tsxBin, [join(dir, 'consumer.ts')], {
+    encoding: 'utf-8',
+    cwd: repoRoot,
+  });
+  if (result.status !== 0) {
+    throw new Error(`consumer failed:\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`);
+  }
+  return JSON.parse(result.stdout.trim());
+}
+
+/**
+ * Spawn a consumer mock server (a tsx script exposing `GET /__test__/ready`) and wait
+ * until it answers. The caller owns the returned process — stop it with `killServer`.
+ */
+export async function startServer(
+  serverScript: string,
+  cwd: string,
+  env: Record<string, string>,
+  baseUrl: string,
+  label: string
+): Promise<ChildProcess> {
+  const server = spawn('npx', ['tsx', serverScript], {
+    cwd,
+    env: { ...process.env, ...env },
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  server.stderr?.on('data', (chunk: Buffer) => {
+    process.stderr.write(`[${label} stderr] ${chunk.toString()}`);
+  });
+  await waitForServerReady(baseUrl, 15_000, label);
+  return server;
+}
+
+export async function waitForServerReady(
+  baseUrl: string,
+  timeoutMs: number,
+  label: string
+): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  let lastError: unknown;
+  while (Date.now() < deadline) {
+    try {
+      const response = await fetch(`${baseUrl}/__test__/ready`);
+      if (response.ok) return;
+      lastError = `readiness probe returned HTTP ${response.status}`;
+    } catch (error) {
+      lastError = error;
+    }
+    await new Promise((resolveFn) => setTimeout(resolveFn, 100));
+  }
+  throw new Error(
+    `${label} did not become ready within ${timeoutMs}ms: ${
+      lastError instanceof Error ? lastError.message : String(lastError)
+    }`
+  );
+}
+
+export function killServer(server: ChildProcess): Promise<void> {
+  return new Promise((resolveFn) => {
+    if (!server.pid || server.exitCode !== null) {
+      resolveFn();
+      return;
+    }
+    const onExit = (): void => resolveFn();
+    server.once('exit', onExit);
+    server.kill('SIGTERM');
+    setTimeout(() => {
+      server.removeListener('exit', onExit);
+      if (server.exitCode === null) {
+        server.kill('SIGKILL');
+      }
+      resolveFn();
+    }, 2_000);
+  });
+}
diff --git a/tests/e2e/generate-client/identifier-injection.test.ts b/tests/e2e/generate-client/identifier-injection.test.ts
new file mode 100644
index 0000000000..af9abed7e4
--- /dev/null
+++ b/tests/e2e/generate-client/identifier-injection.test.ts
@@ -0,0 +1,99 @@
+// Security regression: a hostile OpenAPI document must never inject executable code
+// into the generated client. `ts.factory.createIdentifier` prints names verbatim and
+// JSDoc text is emitted as comments, so operationIds / schema names / descriptions
+// carrying `(){};`, `export`, or `*/` are the attack surface. The generator must
+// sanitize names and escape comments such that the output is inert and strict-`tsc`
+// clean — every payload trapped inside an identifier or a comment, never a statement.
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { outdent } from 'outdent';
+
+import { cliEntry, repoRoot, tscBin } from './helpers.js';
+
+const HOSTILE_SPEC = outdent`
+  openapi: 3.1.0
+  info:
+    title: "Evil */ ;globalThis.PWNED_TITLE=1; /*"
+    version: "1.0.0"
+    description: "desc */ ;globalThis.PWNED_DESC=1; /*"
+  servers: [{ url: https://api.example.com }]
+  paths:
+    /x:
+      get:
+        operationId: "foo(a){}; globalThis.PWNED_OPID=1; export async function bar"
+        security:
+          - "k(){}; globalThis.PWNED_KEY=1; export const z": []
+        responses:
+          '200':
+            description: "ok */ ;globalThis.PWNED_RESP=1; /*"
+            content:
+              application/json:
+                schema: { $ref: '#/components/schemas/Thing' }
+  components:
+    securitySchemes:
+      "k(){}; globalThis.PWNED_KEY=1; export const z":
+        type: apiKey
+        in: header
+        name: X-Api-Key
+      other:
+        type: apiKey
+        in: header
+        name: X-Other
+    schemas:
+      Thing:
+        description: "schema */ ;globalThis.PWNED_SCHEMA=1; /*"
+        type: object
+        properties:
+          n: { type: integer }
+`;
+
+describe('generate-client identifier / comment injection', () => {
+  it('sanitizes hostile names and escapes comments; output is strict-tsc clean', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'ots-injection-'));
+    writeFileSync(join(dir, 'openapi.yaml'), HOSTILE_SPEC, 'utf-8');
+    const entry = join(dir, 'client.ts');
+    const res = spawnSync(
+      'node',
+      [cliEntry, 'generate-client', join(dir, 'openapi.yaml'), '--output', entry],
+      {
+        encoding: 'utf-8',
+        cwd: repoRoot,
+      }
+    );
+    expect(res.status, res.stderr).toBe(0);
+    // The unsafe operationId is reported and rewritten, not silently accepted.
+    expect(res.stderr).toMatch(/is not a valid TypeScript identifier/);
+
+    const src = readFileSync(entry, 'utf-8');
+    // No live comment-breakout: the payload's `*/` is neutralized to `*\/`.
+    expect(src).not.toMatch(/\*\/\s*;globalThis/);
+    // No payload survives as a top-level statement (only inside identifiers/comments).
+    expect(src).not.toMatch(/^\s*globalThis\.PWNED/m);
+    // The operation name became a single valid identifier (no parens/spaces/semicolons)
+    // in the flat call sugar.
+    expect(src).toMatch(/export const [A-Za-z_$][A-Za-z0-9_$]* = \([^)]*\) => client\./);
+
+    // Strongest proof: the whole file type-checks. Injected statements would not.
+    const tsc = spawnSync(
+      tscBin,
+      [
+        '--noEmit',
+        '--strict',
+        '--target',
+        'ES2020',
+        '--module',
+        'esnext',
+        '--moduleResolution',
+        'bundler',
+        '--lib',
+        'ES2020,DOM',
+        entry,
+      ],
+      { encoding: 'utf-8', cwd: dir }
+    );
+    expect(tsc.status, `tsc failed:\n${tsc.stdout}\n${tsc.stderr}`).toBe(0);
+    rmSync(dir, { recursive: true, force: true });
+  }, 60_000);
+});
diff --git a/tests/e2e/generate-client/middleware.test.ts b/tests/e2e/generate-client/middleware.test.ts
new file mode 100644
index 0000000000..efcf88d897
--- /dev/null
+++ b/tests/e2e/generate-client/middleware.test.ts
@@ -0,0 +1,254 @@
+/**
+ * Behavioral e2e for composable middleware/interceptors. Like `extension.test.ts`, we
+ * inject a fake `fetch` and exercise the generated runtime in a real consumer, proving
+ * that `use()` registers middleware, `onRequest` runs in order, `onResponse` runs in
+ * reverse (onion), `onError` chains, and configured middleware precedes `use()`.
+ */
+import { existsSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { outdent } from 'outdent';
+
+import { generateInto, runConsumer } from './helpers.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const fixture = join(__dirname, 'fixtures/base.yaml');
+
+const OK = `new Response('[]', { status: 200, headers: { 'content-type': 'application/json' } })`;
+
+describe('middleware — flat surface (use)', () => {
+  let dir = '';
+  beforeAll(() => {
+    dir = mkdtempSync(join(tmpdir(), 'mw-fn-'));
+    generateInto(dir, fixture);
+  }, 60_000);
+  afterAll(() => {
+    if (dir && existsSync(dir)) rmSync(dir, { recursive: true, force: true });
+  });
+
+  test('use() registers middleware: onRequest runs in order, onResponse in reverse (onion)', () => {
+    const captured = runConsumer(
+      dir,
+      outdent`
+        import { configure, use, listPets } from './client.ts';
+
+        const order: string[] = [];
+        let headers: Record<string, string> = {};
+        configure({
+          fetch: (async (_url: string, init: RequestInit) => {
+            headers = init.headers as Record<string, string>;
+            return ${OK};
+          }) as unknown as typeof fetch,
+        });
+        use(
+          { onRequest: (ctx) => { order.push('req-A'); ctx.headers['X-A'] = '1'; }, onResponse: () => { order.push('res-A'); } },
+          { onRequest: (ctx) => { order.push('req-B'); ctx.headers['X-B'] = '1'; }, onResponse: () => { order.push('res-B'); } },
+        );
+        await listPets();
+        console.log(JSON.stringify({ order, hasA: 'X-A' in headers, hasB: 'X-B' in headers }));
+      `
+    ) as { order: string[]; hasA: boolean; hasB: boolean };
+
+    expect(captured.order).toEqual(['req-A', 'req-B', 'res-B', 'res-A']);
+    expect(captured.hasA).toBe(true);
+    expect(captured.hasB).toBe(true);
+  }, 60_000);
+
+  test('onError threads through each middleware in turn', () => {
+    const result = runConsumer(
+      dir,
+      outdent`
+        import { configure, use, getPetById, type ApiError } from './client.ts';
+
+        configure({
+          fetch: (async () => new Response('{}', { status: 500, headers: { 'content-type': 'application/json' } })) as unknown as typeof fetch,
+        });
+        use(
+          { onError: (e: ApiError) => new Error('first:' + e.status) },
+          { onError: (e) => new Error('second:' + e.message) },
+        );
+        try {
+          await getPetById(1);
+          console.log(JSON.stringify({ threw: false }));
+        } catch (e) {
+          console.log(JSON.stringify({ threw: true, message: (e as Error).message }));
+        }
+      `
+    ) as { threw: boolean; message: string };
+
+    expect(result.threw).toBe(true);
+    expect(result.message).toBe('second:first:500');
+  }, 60_000);
+
+  test('use() does not mutate a caller-provided middleware array (no cross-client leak)', () => {
+    const result = runConsumer(
+      dir,
+      outdent`
+        import { configure, use, listPets, type Middleware } from './client.ts';
+
+        const mine: Middleware[] = [];
+        configure({ middleware: mine, fetch: (async () => ${OK}) as unknown as typeof fetch });
+        use({ onRequest: () => {} });
+        await listPets();
+        console.log(JSON.stringify({ mineLength: mine.length }));
+      `
+    ) as { mineLength: number };
+
+    // use() must append to a fresh array, not push into the array the caller passed.
+    expect(result.mineLength).toBe(0);
+  }, 60_000);
+
+  test('the single config.onRequest hook still runs (as an implicit first middleware)', () => {
+    const captured = runConsumer(
+      dir,
+      outdent`
+        import { configure, use, listPets } from './client.ts';
+
+        const order: string[] = [];
+        configure({
+          onRequest: () => { order.push('config'); },
+          fetch: (async () => ${OK}) as unknown as typeof fetch,
+        });
+        use({ onRequest: () => { order.push('mw'); } });
+        await listPets();
+        console.log(JSON.stringify({ order }));
+      `
+    ) as { order: string[] };
+
+    expect(captured.order).toEqual(['config', 'mw']);
+  }, 60_000);
+
+  test('onRequest sees ctx.operation { id, path, tags }', () => {
+    const captured = runConsumer(
+      dir,
+      outdent`
+        import { configure, use, createPet } from './client.ts';
+
+        let op: unknown;
+        configure({ fetch: (async () => ${OK}) as unknown as typeof fetch });
+        use({ onRequest: (ctx) => { op = ctx.operation; } });
+        await createPet({ name: 'Rex' });
+        console.log(JSON.stringify({ op }));
+      `
+    ) as { op: { id: string; path: string; tags: string[] } };
+
+    expect(captured.op.id).toBe('createPet');
+    expect(captured.op.path).toBe('/pets');
+    expect(Array.isArray(captured.op.tags)).toBe(true);
+  }, 60_000);
+
+  test('onRequest can mutate ctx.body and the change is sent', () => {
+    const captured = runConsumer(
+      dir,
+      outdent`
+        import { configure, use, createPet } from './client.ts';
+
+        let sent = '';
+        configure({
+          fetch: (async (_url: string, init: RequestInit) => { sent = init.body as string; return ${OK}; }) as unknown as typeof fetch,
+        });
+        use({ onRequest: (ctx) => { (ctx.body as { name: string }).name = 'Mutated'; } });
+        await createPet({ name: 'Rex' });
+        console.log(JSON.stringify({ sent }));
+      `
+    ) as { sent: string };
+
+    expect(JSON.parse(captured.sent)).toEqual({ name: 'Mutated' });
+  }, 60_000);
+});
+
+describe('middleware — multi-file output (split)', () => {
+  let dir = '';
+  beforeAll(() => {
+    dir = mkdtempSync(join(tmpdir(), 'mw-split-'));
+    generateInto(dir, fixture, ['--output-mode', 'split']);
+  }, 60_000);
+  afterAll(() => {
+    if (dir && existsSync(dir)) rmSync(dir, { recursive: true, force: true });
+  });
+
+  test('configure() and use() are re-exported by the entry barrel and affect operations', () => {
+    const captured = runConsumer(
+      dir,
+      outdent`
+        import { configure, use, listPets } from './client.ts';
+        let url = '', header = '';
+        configure({ serverUrl: 'https://multi.example.com', fetch: (async (u: string, init: RequestInit) => { url = u; header = (init.headers as Record<string,string>)['X-MW']; return new Response('[]', { status: 200, headers: { 'content-type': 'application/json' } }); }) as unknown as typeof fetch });
+        use({ onRequest: (ctx) => { ctx.headers['X-MW'] = 'yes'; } });
+        await listPets();
+        console.log(JSON.stringify({ url, header }));
+      `
+    ) as { url: string; header: string };
+    expect(new URL(captured.url).origin).toBe('https://multi.example.com');
+    expect(captured.header).toBe('yes');
+  }, 60_000);
+});
+
+describe('middleware — result error mode', () => {
+  let dir = '';
+  beforeAll(() => {
+    dir = mkdtempSync(join(tmpdir(), 'mw-result-'));
+    generateInto(dir, fixture, ['--error-mode', 'result']);
+  }, 60_000);
+  afterAll(() => {
+    if (dir && existsSync(dir)) rmSync(dir, { recursive: true, force: true });
+  });
+
+  test('onRequest/onResponse run; onError does not fire (the error is returned, not thrown)', () => {
+    const result = runConsumer(
+      dir,
+      outdent`
+        import { configure, use, getPetById } from './client.ts';
+
+        const ran: string[] = [];
+        configure({
+          fetch: (async () => new Response('{"bad":true}', { status: 500, headers: { 'content-type': 'application/json' } })) as unknown as typeof fetch,
+        });
+        use({
+          onRequest: () => { ran.push('req'); },
+          onResponse: () => { ran.push('res'); },
+          onError: () => { ran.push('err'); return new Error('should-not-run'); },
+        });
+        const r = await getPetById(1) as { error: unknown; data: unknown };
+        console.log(JSON.stringify({ ran, hasError: r.error !== undefined, hasData: r.data !== undefined }));
+      `
+    ) as { ran: string[]; hasError: boolean; hasData: boolean };
+
+    // onRequest + onResponse ran; onError did NOT (result mode returns the error).
+    expect(result.ran).toEqual(['req', 'res']);
+    expect(result.hasError).toBe(true);
+    expect(result.hasData).toBe(false);
+  }, 60_000);
+});
+
+describe('middleware — configured chain precedes use()', () => {
+  let dir = '';
+  beforeAll(() => {
+    dir = mkdtempSync(join(tmpdir(), 'mw-cfg-'));
+    generateInto(dir, fixture);
+  }, 60_000);
+  afterAll(() => {
+    if (dir && existsSync(dir)) rmSync(dir, { recursive: true, force: true });
+  });
+
+  test('configure({ middleware }) runs before later use() middleware', () => {
+    const captured = runConsumer(
+      dir,
+      outdent`
+        import { client } from './client.ts';
+
+        const order: string[] = [];
+        client.configure({
+          fetch: (async () => ${OK}) as unknown as typeof fetch,
+          middleware: [{ onRequest: () => { order.push('configured'); } }],
+        });
+        client.use({ onRequest: () => { order.push('use'); } });
+        await client.listPets();
+        console.log(JSON.stringify({ order }));
+      `
+    ) as { order: string[] };
+
+    expect(captured.order).toEqual(['configured', 'use']);
+  }, 60_000);
+});
diff --git a/tests/e2e/generate-client/mock.test.ts b/tests/e2e/generate-client/mock.test.ts
new file mode 100644
index 0000000000..986e7487ed
--- /dev/null
+++ b/tests/e2e/generate-client/mock.test.ts
@@ -0,0 +1,201 @@
+/**
+ * Behavioral e2e for the `mock` generator. We generate `sdk,mock` into a temp dir,
+ * then run a real consumer (via tsx) that installs the emitted MSW handlers into
+ * `setupServer` and calls a generated client operation whose native `fetch` MSW
+ * intercepts. With `onUnhandledRequest: 'error'`, a resolved call proves interception
+ * (an unmocked call would throw). The baked response is deterministic (from the
+ * sampler), so we assert exact field values.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { outdent } from 'outdent';
+
+import { generateInto, repoRoot, runConsumer, tscBin } from './helpers.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const fixture = join(__dirname, 'fixtures/base.yaml');
+// `@faker-js/faker` is hoisted to the repo root node_modules (a repo devDependency);
+// map it explicitly so tsc resolves the faker-mode module's `import { faker }` from the temp dir.
+const fakerPath = join(repoRoot, 'node_modules/@faker-js/faker');
+// A date-bearing fixture for the `--date-type Date` regression (mock + transformers).
+const dateFixture = join(__dirname, 'fixtures/transformers.yaml');
+
+describe('mock generator — generated client through MSW', () => {
+  let dir = '';
+  beforeAll(() => {
+    // The consumer imports `msw` (a hoisted repo dep). Node ESM resolves modules
+    // relative to the importing file, so the temp dir must live inside the repo
+    // tree to walk up to the root node_modules — `os.tmpdir()` would not resolve it.
+    dir = mkdtempSync(join(__dirname, 'mock-consumer-'));
+    generateInto(dir, fixture, ['--generator', 'sdk', '--generator', 'mock']);
+  }, 60_000);
+  afterAll(() => {
+    if (dir && existsSync(dir)) rmSync(dir, { recursive: true, force: true });
+  });
+
+  test('emits a sibling client.mocks.ts', () => {
+    expect(existsSync(join(dir, 'client.mocks.ts'))).toBe(true);
+  });
+
+  test('handlers installed in setupServer intercept the generated fetch and return baked data', () => {
+    const result = runConsumer(
+      dir,
+      outdent`
+        import { setupServer } from 'msw/node';
+        import { handlers } from './client.mocks.ts';
+        import { configure, getPetById } from './client.ts';
+
+        const server = setupServer(...handlers);
+        server.listen({ onUnhandledRequest: 'error' });
+        configure({ serverUrl: 'https://api.example.com' });
+        try {
+          const pet = await getPetById(1);
+          process.stdout.write(JSON.stringify({ ok: pet !== undefined, id: pet.id, name: pet.name }));
+        } finally {
+          server.close();
+        }
+      `
+    ) as { ok: boolean; id: number; name: string };
+
+    // Deterministic sampler output for the Pet schema in base.yaml.
+    expect(result.ok).toBe(true);
+    expect(result.id).toBe(0);
+    expect(result.name).toBe('string');
+  }, 60_000);
+
+  test('the generated client + mocks type-check together under strict mode', () => {
+    expect(existsSync(join(dir, 'client.mocks.ts')), 'generation must run first').toBe(true);
+
+    const tsc = spawnSync(
+      tscBin,
+      [
+        '--noEmit',
+        '--strict',
+        // The temp dir lives inside the repo tree (so `msw` resolves), which puts the
+        // repo's own tsconfig.json on the upward search path; ignore it and type-check
+        // purely from these flags.
+        '--ignoreConfig',
+        '--target',
+        'ES2020',
+        '--module',
+        'esnext',
+        '--moduleResolution',
+        'bundler',
+        '--lib',
+        'ES2020,DOM',
+        join(dir, 'client.ts'),
+        join(dir, 'client.mocks.ts'),
+      ],
+      { encoding: 'utf-8', cwd: dir }
+    );
+    expect(tsc.status, `tsc errors:\n${tsc.stdout}\n${tsc.stderr}`).toBe(0);
+  }, 90_000);
+});
+
+describe('mock generator — mock + transformers + --date-type Date compile together', () => {
+  let dir = '';
+  beforeAll(() => {
+    dir = mkdtempSync(join(__dirname, 'mock-date-'));
+    // transformers REQUIRES --date-type Date; the sdk then types date fields `Date`,
+    // so the mock sampler must bake `new Date(...)` to type-check (BUG 1 regression).
+    generateInto(dir, dateFixture, [
+      '--generator',
+      'sdk',
+      '--generator',
+      'mock',
+      '--generator',
+      'transformers',
+      '--date-type',
+      'Date',
+    ]);
+  }, 60_000);
+  afterAll(() => {
+    if (dir && existsSync(dir)) rmSync(dir, { recursive: true, force: true });
+  });
+
+  test('strict-tsc-checks client + mocks + transformers together with 0 errors', () => {
+    expect(existsSync(join(dir, 'client.mocks.ts')), 'generation must run first').toBe(true);
+
+    const tsc = spawnSync(
+      tscBin,
+      [
+        '--noEmit',
+        '--strict',
+        '--ignoreConfig',
+        '--target',
+        'ES2020',
+        '--module',
+        'esnext',
+        '--moduleResolution',
+        'bundler',
+        '--lib',
+        'ES2020,DOM',
+        join(dir, 'client.ts'),
+        join(dir, 'client.mocks.ts'),
+        join(dir, 'client.transformers.ts'),
+      ],
+      { encoding: 'utf-8', cwd: dir }
+    );
+    expect(tsc.status, `tsc errors:\n${tsc.stdout}\n${tsc.stderr}`).toBe(0);
+  }, 90_000);
+});
+
+describe('mock generator — faker mode strict-tsc-checks against real @faker-js/faker', () => {
+  let dir = '';
+  beforeAll(() => {
+    dir = mkdtempSync(join(__dirname, 'mock-faker-'));
+    generateInto(dir, fixture, [
+      '--generator',
+      'sdk',
+      '--generator',
+      'mock',
+      '--mock-data',
+      'faker',
+      '--mock-seed',
+      '42',
+    ]);
+  }, 60_000);
+  afterAll(() => {
+    if (dir && existsSync(dir)) rmSync(dir, { recursive: true, force: true });
+  });
+
+  test('emits the faker import, faker calls, and a seed pin', () => {
+    const source = readFileSync(join(dir, 'client.mocks.ts'), 'utf-8');
+    expect(source).toContain("import { faker } from '@faker-js/faker';");
+    expect(source).toMatch(/faker\.(number|lorem|datatype|string|internet|helpers)\./);
+    expect(source).toContain('faker.seed(42);');
+  });
+
+  test('the faker-mode client + mocks strict-tsc-check against real faker with 0 errors', () => {
+    expect(existsSync(join(dir, 'client.mocks.ts')), 'generation must run first').toBe(true);
+
+    // A real-tsconfig run (not `--ignoreConfig`) so `paths` maps `@faker-js/faker` to the
+    // hoisted package — type-checking the emitted faker calls against faker's real v9 API.
+    writeFileSync(
+      join(dir, 'tsconfig.json'),
+      JSON.stringify({
+        compilerOptions: {
+          module: 'esnext',
+          moduleResolution: 'bundler',
+          target: 'ES2020',
+          lib: ['ES2020', 'DOM'],
+          strict: true,
+          noEmit: true,
+          skipLibCheck: true,
+          types: [],
+          paths: {
+            '@faker-js/faker': [fakerPath],
+            '@faker-js/faker/*': [join(fakerPath, '*')],
+          },
+        },
+        include: ['client.ts', 'client.mocks.ts'],
+      }),
+      'utf-8'
+    );
+
+    const tsc = spawnSync(tscBin, ['--noEmit', '-p', dir], { encoding: 'utf-8', cwd: dir });
+    expect(tsc.status, `tsc errors:\n${tsc.stdout}\n${tsc.stderr}`).toBe(0);
+  }, 90_000);
+});
diff --git a/tests/e2e/generate-client/multipart.test.ts b/tests/e2e/generate-client/multipart.test.ts
new file mode 100644
index 0000000000..1dd24bbcee
--- /dev/null
+++ b/tests/e2e/generate-client/multipart.test.ts
@@ -0,0 +1,154 @@
+/**
+ * Behavioral e2e for typed multipart bodies (#5): the generated client takes a typed object
+ * and serializes it to `FormData` via the runtime's multipart capability — binary→Blob,
+ * arrays→repeated fields, objects→JSON parts. We inject a fake `fetch` and inspect the
+ * FormData it actually sent.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { outdent } from 'outdent';
+
+import { generate, generateInto, repoRoot, tscBin, tsxBin } from './helpers.js';
+
+function collectTsFiles(d: string): string[] {
+  return readdirSync(d).flatMap((e) => {
+    const full = join(d, e);
+    return statSync(full).isDirectory() ? collectTsFiles(full) : full.endsWith('.ts') ? [full] : [];
+  });
+}
+
+const SPEC = outdent`
+  openapi: 3.1.0
+  info: { title: M, version: 1.0.0 }
+  paths:
+    /upload:
+      post:
+        operationId: upload
+        requestBody:
+          required: true
+          content:
+            multipart/form-data:
+              schema:
+                type: object
+                required: [file, orgId]
+                properties:
+                  file: { type: string, format: binary }
+                  orgId: { type: string }
+                  tags: { type: array, items: { type: string } }
+                  meta: { type: object }
+        responses: { '200': { description: ok } }
+`;
+
+describe('generate-client typed multipart body (#5)', () => {
+  let dir = '';
+  afterEach(() => {
+    if (dir && existsSync(dir)) rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('types the fields (binary→Blob) and serializes the object to FormData', () => {
+    dir = mkdtempSync(join(tmpdir(), 'ots-multipart-'));
+    writeFileSync(join(dir, 'api.yaml'), SPEC, 'utf-8');
+    generateInto(dir, join(dir, 'api.yaml'));
+
+    writeFileSync(
+      join(dir, 'consumer.ts'),
+      outdent`
+        import { configure, upload } from './client.ts';
+
+        let body: unknown;
+        configure({
+          fetch: (async (_url: string, init: RequestInit) => {
+            body = init.body;
+            return new Response('', { status: 200 });
+          }) as unknown as typeof fetch,
+        });
+
+        const file = new Blob(['hello'], { type: 'text/plain' });
+        await upload({ file, orgId: 'org_1', tags: ['a', 'b'], meta: { k: 'v' } });
+
+        const fd = body as FormData;
+        console.log(JSON.stringify({
+          isFormData: fd instanceof FormData,
+          orgId: fd.get('orgId'),
+          fileIsBlob: fd.get('file') instanceof Blob,
+          tags: fd.getAll('tags'),
+          meta: fd.get('meta'),
+        }));
+      `,
+      'utf-8'
+    );
+    const run = spawnSync(tsxBin, [join(dir, 'consumer.ts')], { encoding: 'utf-8', cwd: repoRoot });
+    expect(run.status, `${run.stdout}\n${run.stderr}`).toBe(0);
+    const result = JSON.parse(run.stdout.trim()) as Record<string, unknown>;
+
+    expect(result.isFormData).toBe(true);
+    expect(result.orgId).toBe('org_1');
+    expect(result.fileIsBlob).toBe(true);
+    expect(result.tags).toEqual(['a', 'b']); // array → one field per item
+    expect(result.meta).toBe('{"k":"v"}'); // nested object → JSON part
+  }, 60_000);
+
+  it('serializes the multipart body AFTER onRequest, so middleware can mutate it', () => {
+    dir = mkdtempSync(join(tmpdir(), 'ots-multipart-mw-'));
+    writeFileSync(join(dir, 'api.yaml'), SPEC, 'utf-8');
+    generateInto(dir, join(dir, 'api.yaml'));
+
+    writeFileSync(
+      join(dir, 'consumer.ts'),
+      outdent`
+        import { configure, use, upload } from './client.ts';
+
+        let body: unknown;
+        configure({
+          fetch: (async (_url: string, init: RequestInit) => {
+            body = init.body;
+            return new Response('', { status: 200 });
+          }) as unknown as typeof fetch,
+        });
+        // A multipart op must expose the plain body object to onRequest (not pre-built FormData);
+        // mutating it has to be reflected in the FormData the runtime serializes afterwards.
+        use({ onRequest: (ctx) => { (ctx.body as { orgId: string }).orgId = 'mutated'; } });
+
+        const file = new Blob(['hi'], { type: 'text/plain' });
+        await upload({ file, orgId: 'org_1' });
+
+        const fd = body as FormData;
+        console.log(JSON.stringify({ isFormData: fd instanceof FormData, orgId: fd.get('orgId') }));
+      `,
+      'utf-8'
+    );
+    const run = spawnSync(tsxBin, [join(dir, 'consumer.ts')], { encoding: 'utf-8', cwd: repoRoot });
+    expect(run.status, `${run.stdout}\n${run.stderr}`).toBe(0);
+    const result = JSON.parse(run.stdout.trim()) as Record<string, unknown>;
+
+    expect(result.isFormData).toBe(true);
+    expect(result.orgId).toBe('mutated');
+  }, 60_000);
+
+  it('compiles in split output (multipart serialization lives in the embedded runtime)', () => {
+    dir = mkdtempSync(join(tmpdir(), 'ots-multipart-split-'));
+    writeFileSync(join(dir, 'api.yaml'), SPEC, 'utf-8');
+    generate(join(dir, 'api.yaml'), join(dir, 'client.ts'), ['--output-mode', 'split']);
+    const files = collectTsFiles(dir);
+    const tsc = spawnSync(
+      tscBin,
+      [
+        '--noEmit',
+        '--strict',
+        '--target',
+        'ES2020',
+        '--module',
+        'esnext',
+        '--moduleResolution',
+        'bundler',
+        '--lib',
+        'ES2020,DOM',
+        ...files,
+      ],
+      { encoding: 'utf-8', cwd: dir }
+    );
+    expect(tsc.status, `tsc failed:\n${tsc.stdout}\n${tsc.stderr}`).toBe(0);
+  }, 60_000);
+});
diff --git a/tests/e2e/generate-client/name-collision.test.ts b/tests/e2e/generate-client/name-collision.test.ts
new file mode 100644
index 0000000000..66e484413f
--- /dev/null
+++ b/tests/e2e/generate-client/name-collision.test.ts
@@ -0,0 +1,71 @@
+// Regression: an operation whose `<Op>Result` alias name collides with an existing schema
+// name (operation `search` → the `SearchResult` schema it returns) must NOT emit the
+// self-referential `export type SearchResult = SearchResult;`. That alias is circular and, in
+// split output, conflicts with the schema imported from the schemas module (TS2440) and
+// duplicates the `export *` re-export (TS2308). `base.yaml` carries this shape
+// (`operationId: search` → `$ref SearchResult`, plus a `SearchResult` component). We generate
+// the split two-file layout and strict-`tsc` it.
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, readdirSync, readFileSync, rmSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { generate, tscBin } from './helpers.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const fixture = join(__dirname, 'fixtures', 'base.yaml');
+
+/** Recursively collect every generated `.ts` file under `dir`. */
+function collectTsFiles(dir: string): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) out.push(...collectTsFiles(full));
+    else if (entry.endsWith('.ts')) out.push(full);
+  }
+  return out;
+}
+
+describe('generate-client operation/schema name collision', () => {
+  it('does not emit a self-referential *Result alias; strict tsc passes over the split set', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'ots-collision-'));
+    const entry = join(dir, 'client.ts');
+    generate(fixture, entry, ['--output-mode', 'split']);
+
+    const files = collectTsFiles(dir);
+    const allSource = files.map((f) => readFileSync(f, 'utf-8'));
+    // No file may contain the circular self-alias (self-referential variant).
+    for (let i = 0; i < files.length; i++) {
+      expect(allSource[i], `self-referential alias in ${files[i]}`).not.toMatch(
+        /export type (\w+) = \1;/
+      );
+    }
+    // Non-self-referential variant: `GetStatusResult` exists as a schema, so the op's
+    // `<Op>Result` alias must be suppressed — exactly one declaration across the set.
+    const declarations = allSource.join('\n').match(/export type GetStatusResult\b/g) ?? [];
+    expect(declarations).toHaveLength(1);
+
+    // Strict tsc over the whole set (bundler resolution handles the `.js` ESM imports).
+    const tsc = spawnSync(
+      tscBin,
+      [
+        '--noEmit',
+        '--strict',
+        '--noUnusedLocals',
+        '--target',
+        'ES2020',
+        '--module',
+        'esnext',
+        '--moduleResolution',
+        'bundler',
+        '--lib',
+        'ES2020,DOM',
+        ...files,
+      ],
+      { encoding: 'utf-8', cwd: dir }
+    );
+    expect(tsc.status, `tsc failed:\n${tsc.stdout}\n${tsc.stderr}`).toBe(0);
+    rmSync(dir, { recursive: true, force: true });
+  }, 60_000);
+});
diff --git a/tests/e2e/generate-client/operation-types.test.ts b/tests/e2e/generate-client/operation-types.test.ts
new file mode 100644
index 0000000000..02d6a4c39a
--- /dev/null
+++ b/tests/e2e/generate-client/operation-types.test.ts
@@ -0,0 +1,84 @@
+/**
+ * Proves the generated client types `ctx.operation.{id,path,tags}` as literal unions: a valid
+ * comparison compiles, a misspelled operationId/tag does NOT. The whole point of the feature is
+ * compile-time typo-catching, so it gets a dedicated strict-`tsc` check.
+ *
+ * Mechanism: the wiring instantiates `createClient<Ops, OperationId, OperationPath, …>`, so a
+ * `use()` callback's ctx is contextually narrowed. The exported `RequestContext` TYPE keeps its
+ * string defaults (spec-independent middleware stays assignable — asserted below).
+ */
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { outdent } from 'outdent';
+
+import { generate, tscBin } from './helpers.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const fixture = join(__dirname, 'fixtures/base.yaml');
+
+function gen(dir: string): void {
+  generate(fixture, join(dir, 'client.ts'));
+  writeFileSync(
+    join(dir, 'tsconfig.json'),
+    JSON.stringify({
+      compilerOptions: {
+        strict: true,
+        target: 'ES2022',
+        module: 'NodeNext',
+        moduleResolution: 'NodeNext',
+        noEmit: true,
+        allowImportingTsExtensions: true,
+        lib: ['ES2022', 'DOM'],
+        skipLibCheck: true,
+      },
+      include: ['*.ts'],
+    }),
+    'utf-8'
+  );
+}
+function typechecks(dir: string, consumer: string): boolean {
+  writeFileSync(join(dir, 'consumer.ts'), consumer, 'utf-8');
+  return (
+    spawnSync(tscBin, ['-p', join(dir, 'tsconfig.json')], { cwd: dir, encoding: 'utf-8' })
+      .status === 0
+  );
+}
+
+describe('typed ctx.operation rejects typos at compile time', () => {
+  let dir = '';
+  beforeAll(() => {
+    dir = mkdtempSync(join(tmpdir(), 'optypes-'));
+    gen(dir);
+  }, 60_000);
+  afterAll(() => {
+    if (dir) rmSync(dir, { recursive: true, force: true });
+  });
+
+  test('a valid operationId/path comparison compiles; base-typed middleware stays accepted', () => {
+    expect(
+      typechecks(
+        dir,
+        outdent`
+          import { use, type RequestContext } from './client.ts';
+          use({ onRequest: (ctx) => { if (ctx.operation.id === 'listPets' || ctx.operation.path === '/pets') {} } });
+          use({ onRequest: (ctx: RequestContext) => { ctx.headers['X-Op'] = ctx.operation.id; } });
+        `
+      )
+    ).toBe(true);
+  }, 60_000);
+
+  test('a misspelled operationId fails to compile', () => {
+    expect(
+      typechecks(
+        dir,
+        outdent`
+          import { use } from './client.ts';
+          use({ onRequest: (ctx) => { if (ctx.operation.id === 'listPetss') {} } });
+        `
+      )
+    ).toBe(false);
+  }, 60_000);
+});
diff --git a/tests/e2e/generate-client/package-mode.test.ts b/tests/e2e/generate-client/package-mode.test.ts
new file mode 100644
index 0000000000..551fe77180
--- /dev/null
+++ b/tests/e2e/generate-client/package-mode.test.ts
@@ -0,0 +1,226 @@
+import { spawnSync, type ChildProcess } from 'node:child_process';
+import { cpSync, existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { cliEntry, generate, killServer, repoRoot, startServer } from './helpers.js';
+
+// The `runtime: package` output: instead of inlining the runtime, the generated
+// client imports `createClient` from `@redocly/client-generator` (resolved through
+// the workspace's own node_modules symlink — the spec's symlinked-consumer setup).
+// The programmatic tests below exercise the API of the BUILT package; the CLI test
+// exercises the `--runtime` flag wired in stage ③a.
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const generatorLib = join(repoRoot, 'packages/client-generator/lib/index.js');
+const fixture = join(__dirname, 'fixtures/package-runtime.yaml');
+const consumerDir = join(__dirname, 'package-runtime-consumer');
+const generatedFile = join(consumerDir, 'api.ts');
+const serverScript = join(consumerDir, 'server.ts');
+const indexScript = join(consumerDir, 'index.ts');
+
+const SERVER_PORT = 3123;
+const SERVER_BASE = `http://127.0.0.1:${SERVER_PORT}`;
+
+type GenerateClient = (options: Record<string, unknown>) => Promise<unknown>;
+
+async function loadGenerateClient(): Promise<GenerateClient> {
+  const mod = (await import(pathToFileURL(generatorLib).href)) as {
+    generateClient: GenerateClient;
+  };
+  return mod.generateClient;
+}
+
+describe('generate-client package-runtime consumer', () => {
+  let serverProcess: ChildProcess | undefined;
+
+  beforeAll(async () => {
+    if (existsSync(generatedFile)) {
+      rmSync(generatedFile, { force: true });
+    }
+
+    serverProcess = await startServer(
+      serverScript,
+      consumerDir,
+      { PKG_SERVER_PORT: String(SERVER_PORT) },
+      SERVER_BASE,
+      'package-runtime-server'
+    );
+  }, 30_000);
+
+  afterAll(async () => {
+    if (serverProcess) {
+      await killServer(serverProcess);
+    }
+  });
+
+  test('end-to-end: generate package-mode client, type-check, run, assert wire behavior', async () => {
+    const generateClient = await loadGenerateClient();
+    await generateClient({ api: fixture, output: generatedFile, runtime: 'package' });
+
+    expect(existsSync(generatedFile)).toBe(true);
+    const generated = readFileSync(generatedFile, 'utf-8');
+    // Imports the runtime instead of inlining it.
+    expect(generated).toContain("from '@redocly/client-generator'");
+    expect(generated).not.toContain('__send');
+    expect(generated).not.toContain('let BASE');
+    // The skew guard and the wire-name descriptor for the non-identifier path param.
+    expect(generated).toContain('as const satisfies Record<string, OperationDescriptor>;');
+    expect(generated).toContain('{ name: "order-id", in: "path" }');
+    // The colliding operationId is renamed; its descriptor id stays the spec id.
+    expect(generated).toContain('configure_2: { id: "configure"');
+
+    // Type gate: the consumer (incl. the generated file) compiles strict against the
+    // BUILT package types — this is the `satisfies` version-skew guard in action.
+    const typecheckResult = spawnSync('npx', ['tsc', '--noEmit', '-p', consumerDir], {
+      encoding: 'utf-8',
+      cwd: repoRoot,
+    });
+    expect(
+      typecheckResult.status,
+      `tsc --noEmit failed:\nstdout:\n${typecheckResult.stdout}\nstderr:\n${typecheckResult.stderr}`
+    ).toBe(0);
+
+    const runResult = spawnSync('npx', ['tsx', indexScript], {
+      encoding: 'utf-8',
+      cwd: consumerDir,
+    });
+    expect(
+      runResult.status,
+      `consumer stdout:\n${runResult.stdout}\nstderr:\n${runResult.stderr}`
+    ).toBe(0);
+    const parsed = JSON.parse(runResult.stdout.trim()) as {
+      order: { id: string; status: string };
+      grouped: { id: string };
+      created: { id: string; status: string };
+      collided: string;
+      events: Array<{ seq: number; text?: string }>;
+      middlewareIds: string[];
+    };
+    expect(parsed.order).toEqual({ id: 'o-1', status: 'open' });
+    expect(parsed.grouped.id).toBe('o-2');
+    expect(parsed.created).toEqual({ id: 'created-1', status: 'open' });
+    expect(parsed.collided).toBe('ok');
+    expect(parsed.events).toEqual([
+      { seq: 1, text: 'a' },
+      { seq: 2, text: 'b' },
+    ]);
+    // Middleware targets the SPEC operationId — including the renamed `configure` op.
+    expect(parsed.middlewareIds).toEqual([
+      'getOrder',
+      'getOrder',
+      'createOrder',
+      'configure',
+      'streamEvents',
+    ]);
+
+    const logResponse = await fetch(`${SERVER_BASE}/__test__/log`);
+    const log = (await logResponse.json()) as Array<{
+      method: string;
+      url: string;
+      auth: string | null;
+    }>;
+    // Wire-name path substitution + query serialization + injected bearer.
+    expect(log).toContainEqual({
+      method: 'GET',
+      url: '/orders/o-1?expand=items',
+      auth: 'Bearer test-token',
+    });
+    expect(log).toContainEqual({ method: 'GET', url: '/orders/o-2', auth: 'Bearer test-token' });
+    // Unsecured operations carry no credential.
+    expect(log).toContainEqual({ method: 'POST', url: '/orders', auth: null });
+    expect(log).toContainEqual({ method: 'GET', url: '/configure-op', auth: null });
+    expect(log).toContainEqual({ method: 'GET', url: '/events', auth: null });
+  }, 60_000);
+
+  test('package mode composes with split output and the tanstack-query generator', async () => {
+    const generateClient = await loadGenerateClient();
+    const tmpDir = mkdtempSync(join(tmpdir(), 'ots-package-combos-'));
+    try {
+      // split: the entry re-exports a sibling schemas module, both in package mode.
+      const splitEntry = join(tmpDir, 'api.ts');
+      await generateClient({
+        api: fixture,
+        output: splitEntry,
+        runtime: 'package',
+        outputMode: 'split',
+      });
+      expect(existsSync(splitEntry)).toBe(true);
+      expect(readFileSync(splitEntry, 'utf-8')).toContain("from '@redocly/client-generator'");
+      const splitSchemas = join(tmpDir, 'api.schemas.ts');
+      expect(existsSync(splitSchemas)).toBe(true);
+      expect(readFileSync(splitSchemas, 'utf-8')).toContain('export type Order =');
+
+      // tanstack-query + package: the client plus the tanstack wrapper module.
+      const tanstackDir = join(tmpDir, 'tanstack');
+      const tanstackEntry = join(tanstackDir, 'api.ts');
+      await generateClient({
+        api: fixture,
+        output: tanstackEntry,
+        runtime: 'package',
+        generators: ['sdk', 'tanstack-query'],
+        queryFramework: 'react',
+      });
+      expect(existsSync(tanstackEntry)).toBe(true);
+      expect(readFileSync(tanstackEntry, 'utf-8')).toContain("from '@redocly/client-generator'");
+      const tanstackWrapper = join(tanstackDir, 'api.tanstack.ts');
+      expect(existsSync(tanstackWrapper)).toBe(true);
+      expect(readFileSync(tanstackWrapper, 'utf-8')).toContain('queryOptions');
+    } finally {
+      rmSync(tmpDir, { recursive: true, force: true });
+    }
+  }, 30_000);
+
+  test('CLI --runtime package emits a runtime import', () => {
+    const tmpDir = mkdtempSync(join(tmpdir(), 'ots-cli-runtime-'));
+    const output = join(tmpDir, 'cli.ts');
+    generate(fixture, output, ['--runtime', 'package']);
+    const generated = readFileSync(output, 'utf-8');
+    expect(generated).toContain("from '@redocly/client-generator'");
+    expect(generated).not.toContain('__send');
+    rmSync(tmpDir, { recursive: true, force: true });
+  }, 30_000);
+
+  test('the package root imports without the codegen stack installed (production install)', () => {
+    // A production app with a package-runtime client installs @redocly/client-generator
+    // but not the `typescript` peer. Copy (not symlink) package.json + lib into an empty
+    // node_modules so nothing outside the package can resolve — the root entry must
+    // still import and expose the runtime.
+    const dir = mkdtempSync(join(tmpdir(), 'pkg-root-weight-'));
+    const staged = join(dir, 'node_modules/@redocly/client-generator');
+    cpSync(join(repoRoot, 'packages/client-generator/package.json'), join(staged, 'package.json'));
+    cpSync(join(repoRoot, 'packages/client-generator/lib'), join(staged, 'lib'), {
+      recursive: true,
+    });
+    const probe = spawnSync(
+      'node',
+      [
+        '-e',
+        `import('@redocly/client-generator').then((m) => {
+           if (typeof m.createClient !== 'function') throw new Error('createClient missing');
+           if (typeof m.generateClient !== 'function') throw new Error('generateClient missing');
+           console.log('root-ok');
+         })`,
+      ],
+      { cwd: dir, encoding: 'utf-8' }
+    );
+    expect(probe.status, probe.stderr).toBe(0);
+    expect(probe.stdout).toContain('root-ok');
+    rmSync(dir, { recursive: true, force: true });
+  }, 60_000);
+
+  test('CLI --runtime rejects an unknown value', () => {
+    const tmpDir = mkdtempSync(join(tmpdir(), 'ots-cli-runtime-bogus-'));
+    const output = join(tmpDir, 'cli.ts');
+    const result = spawnSync(
+      'node',
+      [cliEntry, 'generate-client', fixture, '--output', output, '--runtime', 'bogus'],
+      { encoding: 'utf-8', cwd: repoRoot }
+    );
+    expect(result.status).not.toBe(0);
+    expect(result.stderr).toContain('Invalid values');
+    expect(existsSync(output)).toBe(false);
+    rmSync(tmpDir, { recursive: true, force: true });
+  }, 30_000);
+});
diff --git a/tests/e2e/generate-client/package-runtime-cjs.test.ts b/tests/e2e/generate-client/package-runtime-cjs.test.ts
new file mode 100644
index 0000000000..853b75969e
--- /dev/null
+++ b/tests/e2e/generate-client/package-runtime-cjs.test.ts
@@ -0,0 +1,86 @@
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { outdent } from 'outdent';
+
+import { cliEntry, repoRoot, tscBin } from './helpers.js';
+
+// A CommonJS project (e.g. a NestJS backend) consuming a `runtime: package` client emits
+// `require('@redocly/client-generator')`. That resolves through the `default` export
+// condition and loads the ESM entry via Node's require(esm) — supported by every Node
+// version the package's `engines` allow.
+
+describe('generate-client package runtime in a CommonJS project', () => {
+  it('require()s the generated client and completes a call', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'ots-cjs-'));
+    writeFileSync(join(dir, 'package.json'), '{"name":"cjs-consumer","private":true}\n');
+    mkdirSync(join(dir, 'node_modules/@redocly'), { recursive: true });
+    symlinkSync(
+      join(repoRoot, 'packages/client-generator'),
+      join(dir, 'node_modules/@redocly/client-generator')
+    );
+    writeFileSync(
+      join(dir, 'openapi.yaml'),
+      outdent`
+        openapi: 3.0.3
+        info: { title: test, version: 1.0.0 }
+        paths:
+          /foo:
+            get:
+              operationId: getFoo
+              responses:
+                '200':
+                  description: ok
+                  content:
+                    application/json:
+                      schema:
+                        type: object
+                        properties:
+                          ok: { type: boolean }
+      `
+    );
+    const generated = spawnSync(
+      'node',
+      [cliEntry, 'generate-client', 'openapi.yaml', '--output', 'api.ts', '--runtime', 'package'],
+      { cwd: dir, encoding: 'utf-8' }
+    );
+    expect(generated.status, generated.stderr).toBe(0);
+
+    const tsc = spawnSync(
+      tscBin,
+      [
+        'api.ts',
+        '--module',
+        'nodenext',
+        '--moduleResolution',
+        'nodenext',
+        '--target',
+        'es2022',
+        '--skipLibCheck',
+      ],
+      { cwd: dir, encoding: 'utf-8' }
+    );
+    expect(tsc.status, `tsc failed:\n${tsc.stdout}`).toBe(0);
+
+    writeFileSync(
+      join(dir, 'driver.cjs'),
+      outdent`
+        const { configure, getFoo } = require('./api.js');
+        configure({
+          serverUrl: 'https://api.example.com',
+          fetch: async () =>
+            new Response(JSON.stringify({ ok: true }), {
+              status: 200,
+              headers: { 'content-type': 'application/json' },
+            }),
+        });
+        getFoo().then((data) => console.log('CJS-OK', JSON.stringify(data)));
+      `
+    );
+    const run = spawnSync('node', ['driver.cjs'], { cwd: dir, encoding: 'utf-8' });
+    expect(run.status, run.stderr).toBe(0);
+    expect(run.stdout).toContain('CJS-OK {"ok":true}');
+    rmSync(dir, { recursive: true, force: true });
+  }, 60_000);
+});
diff --git a/tests/e2e/generate-client/package-runtime-consumer/.gitignore b/tests/e2e/generate-client/package-runtime-consumer/.gitignore
new file mode 100644
index 0000000000..35d9162694
--- /dev/null
+++ b/tests/e2e/generate-client/package-runtime-consumer/.gitignore
@@ -0,0 +1,2 @@
+# Generated fresh by the owning suite in beforeAll; excluded from the root typecheck.
+api.ts
diff --git a/tests/e2e/generate-client/package-runtime-consumer/index.ts b/tests/e2e/generate-client/package-runtime-consumer/index.ts
new file mode 100644
index 0000000000..68ec914434
--- /dev/null
+++ b/tests/e2e/generate-client/package-runtime-consumer/index.ts
@@ -0,0 +1,42 @@
+import { client, configure_2, createOrder, getOrder, setBearer, streamEvents, use } from './api.js';
+
+async function main(): Promise<void> {
+  const middlewareIds: string[] = [];
+  use({
+    onRequest: (ctx) => {
+      middlewareIds.push(ctx.operation.id);
+    },
+  });
+  setBearer('test-token');
+
+  // Flat sugar: positional path value forwarded under the wire name `order-id`.
+  const order = await getOrder('o-1', { expand: 'items' });
+  // Grouped instance call: the caller uses the wire-name key directly.
+  const grouped = await client.getOrder({ 'order-id': 'o-2' });
+  const created = await createOrder({ status: 'open' });
+  // The op whose id collides with the reserved `configure` member — renamed sugar,
+  // while middleware still sees the SPEC operationId.
+  const collided = await configure_2();
+
+  const events: Array<{ seq: number; text?: string }> = [];
+  for await (const event of streamEvents()) {
+    events.push({ seq: event.data.seq, text: event.data.text });
+  }
+
+  // Compile-time checks: the generated types flow through the package runtime.
+  const _orderId: string = order.id;
+  const _createdStatus: string = created.status;
+  const _collided: string = collided;
+  void _orderId;
+  void _createdStatus;
+  void _collided;
+
+  process.stdout.write(
+    JSON.stringify({ order, grouped, created, collided, events, middlewareIds }) + '\n'
+  );
+}
+
+main().catch((error) => {
+  process.stderr.write(`UNHANDLED: ${error instanceof Error ? error.message : String(error)}\n`);
+  process.exit(1);
+});
diff --git a/tests/e2e/generate-client/package-runtime-consumer/package.json b/tests/e2e/generate-client/package-runtime-consumer/package.json
new file mode 100644
index 0000000000..378af31b08
--- /dev/null
+++ b/tests/e2e/generate-client/package-runtime-consumer/package.json
@@ -0,0 +1,6 @@
+{
+  "name": "package-runtime-consumer",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module"
+}
diff --git a/tests/e2e/generate-client/package-runtime-consumer/server.ts b/tests/e2e/generate-client/package-runtime-consumer/server.ts
new file mode 100644
index 0000000000..b78d59442e
--- /dev/null
+++ b/tests/e2e/generate-client/package-runtime-consumer/server.ts
@@ -0,0 +1,78 @@
+import * as http from 'node:http';
+
+// A hand-written server for the package-runtime consumer: echoes enough request
+// detail (auth header, URL) for the test to assert the runtime's routing, and
+// serves a short SSE stream that ends cleanly.
+
+type LogEntry = { method: string; url: string; auth: string | null };
+
+const PORT = Number.parseInt(process.env.PKG_SERVER_PORT ?? '3123', 10);
+
+const requestLog: LogEntry[] = [];
+
+async function readBody(req: http.IncomingMessage): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of req) chunks.push(chunk as Buffer);
+  return Buffer.concat(chunks).toString('utf-8');
+}
+
+const server = http.createServer(async (req, res) => {
+  const method = req.method ?? 'GET';
+  const url = req.url ?? '';
+  const { pathname } = new URL(url, 'http://localhost');
+
+  if (pathname === '/__test__/ready') {
+    res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' });
+    res.end('ready');
+    return;
+  }
+  if (pathname === '/__test__/log') {
+    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+    res.end(JSON.stringify(requestLog));
+    return;
+  }
+
+  const auth = typeof req.headers.authorization === 'string' ? req.headers.authorization : null;
+  requestLog.push({ method, url, auth });
+
+  if (method === 'GET' && pathname.startsWith('/orders/')) {
+    const id = decodeURIComponent(pathname.slice('/orders/'.length));
+    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+    res.end(JSON.stringify({ id, status: 'open' }));
+    return;
+  }
+  if (method === 'POST' && pathname === '/orders') {
+    const body = JSON.parse(await readBody(req)) as { status: string };
+    res.writeHead(201, { 'Content-Type': 'application/json; charset=utf-8' });
+    res.end(JSON.stringify({ id: 'created-1', status: body.status }));
+    return;
+  }
+  if (method === 'GET' && pathname === '/configure-op') {
+    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+    res.end(JSON.stringify('ok'));
+    return;
+  }
+  if (method === 'GET' && pathname === '/events') {
+    res.writeHead(200, {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      Connection: 'keep-alive',
+    });
+    res.write('id: 1\ndata: {"seq":1,"text":"a"}\n\n');
+    res.write('id: 2\ndata: {"seq":2,"text":"b"}\n\n');
+    res.end(); // clean close — the client finishes without reconnecting
+    return;
+  }
+
+  res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+  res.end(JSON.stringify({ title: 'not found' }));
+});
+
+// The test process keeps a pooled connection from its readiness probe and fetches
+// the log only after generate + tsc + the consumer run (~10s). Outlive that gap so
+// the pooled socket is not reset mid-reuse.
+server.keepAliveTimeout = 60_000;
+
+server.listen(PORT, () => {
+  process.stdout.write(`package-runtime server listening on ${PORT}\n`);
+});
diff --git a/tests/e2e/generate-client/package-runtime-consumer/tsconfig.json b/tests/e2e/generate-client/package-runtime-consumer/tsconfig.json
new file mode 100644
index 0000000000..9e758c589a
--- /dev/null
+++ b/tests/e2e/generate-client/package-runtime-consumer/tsconfig.json
@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "target": "es2022",
+    "lib": ["ES2022", "DOM", "DOM.AsyncIterable"],
+    "strict": true,
+    "noUnusedLocals": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "types": ["node"]
+  },
+  "include": ["./**/*.ts"]
+}
diff --git a/tests/e2e/generate-client/pagination-consumer/.gitignore b/tests/e2e/generate-client/pagination-consumer/.gitignore
new file mode 100644
index 0000000000..14356b8214
--- /dev/null
+++ b/tests/e2e/generate-client/pagination-consumer/.gitignore
@@ -0,0 +1,4 @@
+# Generated fresh by pagination.test.ts in beforeAll; excluded from the root typecheck.
+api.ts
+api-offset.ts
+api-package.ts
diff --git a/tests/e2e/generate-client/pagination-consumer/index-abort.ts b/tests/e2e/generate-client/pagination-consumer/index-abort.ts
new file mode 100644
index 0000000000..36ecc4314c
--- /dev/null
+++ b/tests/e2e/generate-client/pagination-consumer/index-abort.ts
@@ -0,0 +1,32 @@
+import { listOrders } from './api.js';
+
+// Aborting mid-iteration: `init` (the AbortSignal) is forwarded to every page request,
+// so aborting after the first yielded item lets the current page drain from memory and
+// makes the NEXT page fetch reject — the iteration terminates with an AbortError.
+async function main(): Promise<void> {
+  const controller = new AbortController();
+  let received = 0;
+  let error: string | null = null;
+
+  try {
+    for await (const order of listOrders.items(
+      { params: { limit: 2 } },
+      { signal: controller.signal }
+    )) {
+      void order;
+      received++;
+      if (received === 1) {
+        controller.abort();
+      }
+    }
+  } catch (e) {
+    error = e instanceof Error ? e.name : String(e);
+  }
+
+  process.stdout.write(JSON.stringify({ received, error }) + '\n');
+}
+
+main().catch((e) => {
+  process.stderr.write(`UNHANDLED: ${e instanceof Error ? e.message : String(e)}\n`);
+  process.exit(1);
+});
diff --git a/tests/e2e/generate-client/pagination-consumer/index-offset.ts b/tests/e2e/generate-client/pagination-consumer/index-offset.ts
new file mode 100644
index 0000000000..58428c05db
--- /dev/null
+++ b/tests/e2e/generate-client/pagination-consumer/index-offset.ts
@@ -0,0 +1,28 @@
+import { listMenuItems, OPERATIONS } from './api-offset.js';
+
+// The config-convention arm: `pagination: { style: offset, … }` was passed at generate
+// time, so `listMenuItems` (which structurally fits) iterates by advancing `offset` by
+// each page's item count until an empty page arrives.
+async function main(): Promise<void> {
+  const names: string[] = [];
+  for await (const item of listMenuItems.items({ params: { limit: 2 } })) {
+    names.push(item.name); // compile-time: `item` is `MenuItem`
+  }
+
+  // The trailing empty page IS yielded (every page arrives before the stop check).
+  const pageSizes: number[] = [];
+  for await (const page of listMenuItems.pages({ params: { limit: 2 } })) {
+    pageSizes.push(page.items.length);
+  }
+
+  // Precedence, pinned at compile time: the spec's `x-pagination` (cursor) beats the
+  // offset convention on `listOrders` — its descriptor keeps the extension's rule.
+  const listOrdersStyle: 'cursor' = OPERATIONS.listOrders.pagination.style;
+
+  process.stdout.write(JSON.stringify({ names, pageSizes, listOrdersStyle }) + '\n');
+}
+
+main().catch((error) => {
+  process.stderr.write(`UNHANDLED: ${error instanceof Error ? error.message : String(error)}\n`);
+  process.exit(1);
+});
diff --git a/tests/e2e/generate-client/pagination-consumer/index-package.ts b/tests/e2e/generate-client/pagination-consumer/index-package.ts
new file mode 100644
index 0000000000..a73e8650f8
--- /dev/null
+++ b/tests/e2e/generate-client/pagination-consumer/index-package.ts
@@ -0,0 +1,18 @@
+import { listOrders } from './api-package.js';
+
+// The package-mode arm: the generated file imports the runtime from
+// `@redocly/client-generator`, so `.pages()`/`.items()` ship from the INSTALLED
+// package — one full `.items()` walk proves the capability is wired there too.
+async function main(): Promise<void> {
+  const ids: string[] = [];
+  for await (const order of listOrders.items({ params: { limit: 2 } })) {
+    ids.push(order.id);
+  }
+
+  process.stdout.write(JSON.stringify({ ids }) + '\n');
+}
+
+main().catch((error) => {
+  process.stderr.write(`UNHANDLED: ${error instanceof Error ? error.message : String(error)}\n`);
+  process.exit(1);
+});
diff --git a/tests/e2e/generate-client/pagination-consumer/index.ts b/tests/e2e/generate-client/pagination-consumer/index.ts
new file mode 100644
index 0000000000..a019257fcb
--- /dev/null
+++ b/tests/e2e/generate-client/pagination-consumer/index.ts
@@ -0,0 +1,39 @@
+import { listOrders } from './api.js';
+
+// The extension arm: `x-pagination` in the spec (no config) drives `listOrders`.
+// Exercises `.items()` across three cursor pages, `.pages()` page-level access, and
+// resume from a caller-provided cursor — while the caller's args are never mutated.
+async function main(): Promise<void> {
+  // `.items()`: the flat sugar preserves the method-attached iterators; every request
+  // forwards the caller's `limit` alongside the advancing cursor.
+  const firstArgs = { params: { limit: 2 } };
+  const ids: string[] = [];
+  for await (const order of listOrders.items(firstArgs)) {
+    ids.push(order.id); // compile-time: `order` is `Order`
+  }
+  // The iterator clones params per request — the cursor never leaks into caller args.
+  const firstCursorLeaked = 'cursor' in firstArgs.params;
+
+  // `.pages()`: whole pages, typed as the raw response — sizes pin the 2+2+1 layout.
+  const pageSizes: number[] = [];
+  for await (const page of listOrders.pages({ params: { limit: 2 } })) {
+    pageSizes.push(page.orders.length);
+  }
+
+  // Resume: a caller-provided initial cursor starts iteration at that page.
+  const resumeArgs = { params: { cursor: 'c2', limit: 2 } };
+  const resumedIds: string[] = [];
+  for await (const order of listOrders.items(resumeArgs)) {
+    resumedIds.push(order.id);
+  }
+  const resumeCursorAfter = resumeArgs.params.cursor;
+
+  process.stdout.write(
+    JSON.stringify({ ids, firstCursorLeaked, pageSizes, resumedIds, resumeCursorAfter }) + '\n'
+  );
+}
+
+main().catch((error) => {
+  process.stderr.write(`UNHANDLED: ${error instanceof Error ? error.message : String(error)}\n`);
+  process.exit(1);
+});
diff --git a/tests/e2e/generate-client/pagination-consumer/package.json b/tests/e2e/generate-client/pagination-consumer/package.json
new file mode 100644
index 0000000000..06753790e0
--- /dev/null
+++ b/tests/e2e/generate-client/pagination-consumer/package.json
@@ -0,0 +1,6 @@
+{
+  "name": "pagination-consumer",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module"
+}
diff --git a/tests/e2e/generate-client/pagination-consumer/server.ts b/tests/e2e/generate-client/pagination-consumer/server.ts
new file mode 100644
index 0000000000..816de147f7
--- /dev/null
+++ b/tests/e2e/generate-client/pagination-consumer/server.ts
@@ -0,0 +1,96 @@
+import * as http from 'node:http';
+
+// A hand-written pagination server: three cursor pages of orders keyed by an opaque
+// cursor (the last page carries no nextCursor — the stop signal), and an offset-sliced
+// menu that returns an empty page past the end. Every API request lands in a log the
+// test reads back, with a reset hook so each consumer run asserts over its own slice.
+
+type LogEntry = { method: string; url: string };
+type Order = { id: string; status: string };
+
+const PORT = Number.parseInt(process.env.PAGINATION_SERVER_PORT ?? '3131', 10);
+
+let requestLog: LogEntry[] = [];
+
+const ORDERS: Order[] = ['o-1', 'o-2', 'o-3', 'o-4', 'o-5'].map((id) => ({
+  id,
+  status: 'open',
+}));
+
+// Cursor pages (2 + 2 + 1), keyed by the cursor that requests them ('' = first page).
+const ORDER_PAGES: Record<string, { orders: Order[]; nextCursor?: string }> = {
+  '': { orders: ORDERS.slice(0, 2), nextCursor: 'c2' },
+  c2: { orders: ORDERS.slice(2, 4), nextCursor: 'c3' },
+  c3: { orders: ORDERS.slice(4) },
+};
+
+const MENU = ['espresso', 'latte', 'mocha', 'flat white', 'cortado'].map((name, index) => ({
+  id: `m-${index + 1}`,
+  name,
+}));
+
+const server = http.createServer((req, res) => {
+  const method = req.method ?? 'GET';
+  const url = req.url ?? '';
+  const { pathname, searchParams } = new URL(url, 'http://localhost');
+
+  if (pathname === '/__test__/ready') {
+    res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' });
+    res.end('ready');
+    return;
+  }
+  if (pathname === '/__test__/log') {
+    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+    res.end(JSON.stringify(requestLog));
+    return;
+  }
+  if (pathname === '/__test__/reset') {
+    requestLog = [];
+    res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' });
+    res.end('reset');
+    return;
+  }
+
+  requestLog.push({ method, url });
+
+  if (method === 'GET' && pathname === '/orders') {
+    const page = ORDER_PAGES[searchParams.get('cursor') ?? ''];
+    if (page) {
+      res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+      res.end(JSON.stringify(page));
+      return;
+    }
+    res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+    res.end(JSON.stringify({ title: 'unknown cursor' }));
+    return;
+  }
+
+  if (method === 'GET' && pathname === '/menu') {
+    const offset = Number.parseInt(searchParams.get('offset') ?? '0', 10);
+    const limit = Number.parseInt(searchParams.get('limit') ?? '2', 10);
+    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+    res.end(JSON.stringify({ items: MENU.slice(offset, offset + limit), total: MENU.length }));
+    return;
+  }
+
+  res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+  res.end(JSON.stringify({ title: 'not found' }));
+});
+
+// The test process keeps a pooled connection from its readiness probe and fetches the
+// log after generate + tsc + the consumer runs (~10s). Outlive that gap so the pooled
+// socket is not reset mid-reuse.
+server.keepAliveTimeout = 60_000;
+
+server.listen(PORT, () => {
+  process.stdout.write(`READY ${PORT}\n`);
+});
+
+const shutdown = (): void => {
+  server.close(() => {
+    process.exit(0);
+  });
+};
+
+process.on('SIGTERM', shutdown);
+process.on('SIGINT', shutdown);
diff --git a/tests/e2e/generate-client/pagination-consumer/tsconfig.json b/tests/e2e/generate-client/pagination-consumer/tsconfig.json
new file mode 100644
index 0000000000..9e758c589a
--- /dev/null
+++ b/tests/e2e/generate-client/pagination-consumer/tsconfig.json
@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "target": "es2022",
+    "lib": ["ES2022", "DOM", "DOM.AsyncIterable"],
+    "strict": true,
+    "noUnusedLocals": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "types": ["node"]
+  },
+  "include": ["./**/*.ts"]
+}
diff --git a/tests/e2e/generate-client/pagination.test.ts b/tests/e2e/generate-client/pagination.test.ts
new file mode 100644
index 0000000000..430fac40f8
--- /dev/null
+++ b/tests/e2e/generate-client/pagination.test.ts
@@ -0,0 +1,246 @@
+import { spawnSync, type ChildProcess } from 'node:child_process';
+import { existsSync, readFileSync, rmSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { killServer, repoRoot, startServer } from './helpers.js';
+
+// Auto-pagination end to end, over a live server: the `x-pagination` extension arm
+// (cursor style — three pages, resume, abort) generated with NO config, the
+// config-convention arm (offset style, applied only where it structurally fits), and a
+// package-mode arm proving `.pages()`/`.items()` ship from the installed runtime.
+// Pagination has no CLI flag, so config-carrying runs use the BUILT package's
+// programmatic `generateClient`.
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const generatorLib = join(repoRoot, 'packages/client-generator/lib/index.js');
+const fixture = join(__dirname, 'fixtures/pagination.yaml');
+const consumerDir = join(__dirname, 'pagination-consumer');
+const apiFile = join(consumerDir, 'api.ts');
+const apiOffsetFile = join(consumerDir, 'api-offset.ts');
+const apiPackageFile = join(consumerDir, 'api-package.ts');
+const serverScript = join(consumerDir, 'server.ts');
+
+const SERVER_PORT = 3131;
+const SERVER_BASE = `http://127.0.0.1:${SERVER_PORT}`;
+
+type GenerateClient = (options: Record<string, unknown>) => Promise<unknown>;
+
+async function loadGenerateClient(): Promise<GenerateClient> {
+  const mod = (await import(pathToFileURL(generatorLib).href)) as {
+    generateClient: GenerateClient;
+  };
+  return mod.generateClient;
+}
+
+/** Clear the server's request log, then return a fetcher for the run's own slice. */
+async function resetLog(): Promise<void> {
+  const response = await fetch(`${SERVER_BASE}/__test__/reset`, { method: 'POST' });
+  expect(response.ok).toBe(true);
+}
+
+async function fetchLog(): Promise<Array<{ method: string; url: string }>> {
+  const response = await fetch(`${SERVER_BASE}/__test__/log`);
+  return (await response.json()) as Array<{ method: string; url: string }>;
+}
+
+function runConsumer(script: string): { stdout: string } {
+  const result = spawnSync('npx', ['tsx', join(consumerDir, script)], {
+    encoding: 'utf-8',
+    cwd: consumerDir,
+    timeout: 30_000,
+  });
+  expect(result.status, `${script} stdout:\n${result.stdout}\nstderr:\n${result.stderr}`).toBe(0);
+  return { stdout: result.stdout };
+}
+
+describe('generate-client pagination consumer', () => {
+  let serverProcess: ChildProcess | undefined;
+
+  beforeAll(async () => {
+    for (const file of [apiFile, apiOffsetFile, apiPackageFile]) {
+      if (existsSync(file)) rmSync(file, { force: true });
+    }
+
+    serverProcess = await startServer(
+      serverScript,
+      consumerDir,
+      { PAGINATION_SERVER_PORT: String(SERVER_PORT) },
+      SERVER_BASE,
+      'pagination-server'
+    );
+  }, 30_000);
+
+  afterAll(async () => {
+    if (serverProcess) {
+      await killServer(serverProcess);
+    }
+  });
+
+  test('generate all three arms and assert the emitted pagination surface', async () => {
+    const generateClient = await loadGenerateClient();
+    // Extension arm: NO pagination config — `x-pagination` alone drives `listOrders`.
+    await generateClient({ api: fixture, output: apiFile });
+    // Convention arm: an offset rule applied to every operation it structurally fits.
+    await generateClient({
+      api: fixture,
+      output: apiOffsetFile,
+      pagination: { style: 'offset', offsetParam: 'offset', limitParam: 'limit', items: '/items' },
+    });
+    // Package arm: same extension-driven spec, runtime imported from the package.
+    await generateClient({ api: fixture, output: apiPackageFile, runtime: 'package' });
+
+    const api = readFileSync(apiFile, 'utf-8');
+    // The extension is normalized into the descriptor (param unified, stable key order).
+    expect(api).toContain(
+      'listOrders: { id: "listOrders", method: "GET", path: "/orders", params: [{ name: "cursor", in: "query" }, { name: "limit", in: "query" }], pagination: { style: "cursor", param: "cursor", limitParam: "limit", nextCursor: "/nextCursor", items: "/orders" } }'
+    );
+    // Ops declares the statically computed element type for the paginated op only.
+    expect(api).toContain('item: Order;');
+    expect(api).not.toContain('item: MenuItem;');
+    // The other operations carry NO pagination block…
+    expect(api).toContain(
+      'listMenuItems: { id: "listMenuItems", method: "GET", path: "/menu", params: [{ name: "offset", in: "query" }, { name: "limit", in: "query" }] }'
+    );
+    expect(api).toContain(
+      'getOrder: { id: "getOrder", method: "GET", path: "/orders/{orderId}", params: [{ name: "orderId", in: "path" }] }'
+    );
+    // …and the flat sugar preserves `.pages`/`.items` via Object.assign.
+    expect(api).toContain('export const listOrders = Object.assign((params: {');
+    expect(api).toContain('{ pages: client.listOrders.pages, items: client.listOrders.items });');
+    expect(api).not.toContain('client.listMenuItems.pages');
+    // Inline mode embeds paginate.ts (the infinite-loop guard is its fingerprint).
+    expect(api).toContain('// ─── Embedded runtime');
+    expect(api).toContain('Pagination did not advance');
+
+    const offset = readFileSync(apiOffsetFile, 'utf-8');
+    // The convention lands on listMenuItems (it fits)…
+    expect(offset).toContain(
+      'listMenuItems: { id: "listMenuItems", method: "GET", path: "/menu", params: [{ name: "offset", in: "query" }, { name: "limit", in: "query" }], pagination: { style: "offset", param: "offset", limitParam: "limit", items: "/items" } }'
+    );
+    expect(offset).toContain('item: MenuItem;');
+    expect(offset).toContain(
+      '{ pages: client.listMenuItems.pages, items: client.listMenuItems.items });'
+    );
+    // …precedence keeps the extension's cursor rule on listOrders (not the convention)…
+    expect(offset).toContain(
+      'pagination: { style: "cursor", param: "cursor", limitParam: "limit", nextCursor: "/nextCursor", items: "/orders" }'
+    );
+    // …and getOrder (no `offset` query param) is silently skipped, not an error.
+    expect(offset).toContain(
+      'getOrder: { id: "getOrder", method: "GET", path: "/orders/{orderId}", params: [{ name: "orderId", in: "path" }] }'
+    );
+
+    const pkg = readFileSync(apiPackageFile, 'utf-8');
+    // Package mode: no embedded runtime — pagination arrives via the import.
+    expect(pkg).toContain("from '@redocly/client-generator'");
+    expect(pkg).not.toContain('// ─── Embedded runtime');
+    expect(pkg).toContain(
+      'pagination: { style: "cursor", param: "cursor", limitParam: "limit", nextCursor: "/nextCursor", items: "/orders" }'
+    );
+    expect(pkg).toContain('{ pages: client.listOrders.pages, items: client.listOrders.items });');
+  }, 60_000);
+
+  test('typecheck gate: all three generated clients + consumer scripts, strict', () => {
+    const typecheckResult = spawnSync('npx', ['tsc', '--noEmit', '-p', consumerDir], {
+      encoding: 'utf-8',
+      cwd: repoRoot,
+    });
+    expect(
+      typecheckResult.status,
+      `tsc --noEmit failed:\nstdout:\n${typecheckResult.stdout}\nstderr:\n${typecheckResult.stderr}`
+    ).toBe(0);
+  }, 60_000);
+
+  test('cursor (extension arm): .items across 3 pages, .pages sizes, resume, no arg mutation', async () => {
+    await resetLog();
+    const { stdout } = runConsumer('index.ts');
+    const parsed = JSON.parse(stdout.trim()) as {
+      ids: string[];
+      firstCursorLeaked: boolean;
+      pageSizes: number[];
+      resumedIds: string[];
+      resumeCursorAfter: string;
+    };
+    // All five items, in order, across the 2+2+1 pages.
+    expect(parsed.ids).toEqual(['o-1', 'o-2', 'o-3', 'o-4', 'o-5']);
+    expect(parsed.pageSizes).toEqual([2, 2, 1]);
+    // Resume from `cursor: 'c2'` starts at page 2; caller args stay untouched.
+    expect(parsed.resumedIds).toEqual(['o-3', 'o-4', 'o-5']);
+    expect(parsed.firstCursorLeaked).toBe(false);
+    expect(parsed.resumeCursorAfter).toBe('c2');
+
+    // The wire: cursor progression (none, c2, c3) with `limit` forwarded every time.
+    const log = await fetchLog();
+    expect(log.map((e) => e.url)).toEqual([
+      // .items(): three pages.
+      '/orders?limit=2',
+      '/orders?limit=2&cursor=c2',
+      '/orders?limit=2&cursor=c3',
+      // .pages(): the same progression.
+      '/orders?limit=2',
+      '/orders?limit=2&cursor=c2',
+      '/orders?limit=2&cursor=c3',
+      // Resume: starts at the caller's cursor — page 1 is never requested.
+      '/orders?cursor=c2&limit=2',
+      '/orders?cursor=c3&limit=2',
+    ]);
+    expect(log.every((e) => e.method === 'GET' && e.url.includes('limit=2'))).toBe(true);
+  }, 60_000);
+
+  test('offset (convention arm): advances by page item count, stops on the empty page', async () => {
+    await resetLog();
+    const { stdout } = runConsumer('index-offset.ts');
+    const parsed = JSON.parse(stdout.trim()) as {
+      names: string[];
+      pageSizes: number[];
+      listOrdersStyle: string;
+    };
+    expect(parsed.names).toEqual(['espresso', 'latte', 'mocha', 'flat white', 'cortado']);
+    // The trailing empty page is yielded (pages arrive before the stop check).
+    expect(parsed.pageSizes).toEqual([2, 2, 1, 0]);
+    // Runtime echo of the compile-time precedence pin.
+    expect(parsed.listOrdersStyle).toBe('cursor');
+
+    // offset=0,2,4 then the empty probe at 5 — for the .items() and .pages() walks.
+    const log = await fetchLog();
+    expect(log.map((e) => e.url)).toEqual([
+      '/menu?limit=2&offset=0',
+      '/menu?limit=2&offset=2',
+      '/menu?limit=2&offset=4',
+      '/menu?limit=2&offset=5',
+      '/menu?limit=2&offset=0',
+      '/menu?limit=2&offset=2',
+      '/menu?limit=2&offset=4',
+      '/menu?limit=2&offset=5',
+    ]);
+  }, 60_000);
+
+  test('abort mid-iteration: the forwarded signal rejects the next page fetch', async () => {
+    await resetLog();
+    const { stdout } = runConsumer('index-abort.ts');
+    const parsed = JSON.parse(stdout.trim()) as { received: number; error: string | null };
+    // The first page (2 items) drains from memory, then the page-2 fetch aborts.
+    expect(parsed.received).toBe(2);
+    expect(parsed.error).toBe('AbortError');
+
+    const log = await fetchLog();
+    const pageRequests = log.filter((e) => e.url.startsWith('/orders'));
+    expect(pageRequests.length).toBeGreaterThanOrEqual(1);
+    expect(pageRequests.length).toBeLessThanOrEqual(2);
+  }, 60_000);
+
+  test('package-mode arm: .items() runs on the runtime imported from the package', async () => {
+    await resetLog();
+    const { stdout } = runConsumer('index-package.ts');
+    const parsed = JSON.parse(stdout.trim()) as { ids: string[] };
+    expect(parsed.ids).toEqual(['o-1', 'o-2', 'o-3', 'o-4', 'o-5']);
+
+    const log = await fetchLog();
+    expect(log.map((e) => e.url)).toEqual([
+      '/orders?limit=2',
+      '/orders?limit=2&cursor=c2',
+      '/orders?limit=2&cursor=c3',
+    ]);
+  }, 60_000);
+});
diff --git a/tests/e2e/generate-client/parse-as.test.ts b/tests/e2e/generate-client/parse-as.test.ts
new file mode 100644
index 0000000000..dddaa793bd
--- /dev/null
+++ b/tests/e2e/generate-client/parse-as.test.ts
@@ -0,0 +1,64 @@
+// Verifies the `parseAs` runtime escape hatch on the per-call `RequestOptions`:
+// the generated client emits the `ParseAs` type, threads `parseAs?` through
+// `RequestOptions`, and `__parse` decodes every kind (json/text/blob/arrayBuffer/
+// formData/stream/auto). We assert on the emitted source, prove the whole client
+// type-checks under strict `tsc`, and append a consumer snippet that calls an
+// operation with `{ parseAs: 'stream' }` / `{ parseAs: 'text' }` — type-checking
+// that proves the option is accepted by the generated operation signatures.
+//
+// No mock-server behavioral assertion here: `parseAs` is a pure runtime branch in
+// the runtime's `parse` (covered by the client-generator unit suite) and the
+// cafe-consumer harness already exercises the default decoding path. Strict-tsc +
+// string + type-usage assertions are sufficient and keep this test process-light.
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { generate, strictTypecheck } from './helpers.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+describe('generate-client parseAs', () => {
+  it('emits ParseAs + parseAs option, decodes every kind, and accepts parseAs per call', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'ots-parseas-'));
+    const out = join(dir, 'client.ts');
+    generate(join(__dirname, 'fixtures', 'no-operationid.yaml'), out);
+    expect(existsSync(out)).toBe(true);
+    const generated = readFileSync(out, 'utf-8');
+
+    // The public `ParseAs` type and the option on `RequestOptions`.
+    expect(generated).toContain(
+      "export type ParseAs = 'auto' | 'json' | 'text' | 'blob' | 'arrayBuffer' | 'formData' | 'stream';"
+    );
+    expect(generated).toMatch(/parseAs\?: ParseAs/);
+
+    // The runtime's `parse` covers the streaming / arrayBuffer / formData branches.
+    expect(generated).toContain('return response.body;');
+    expect(generated).toContain('return response.arrayBuffer();');
+    expect(generated).toContain('return response.formData();');
+
+    // A type-level consumer: calling the operation with `parseAs` must compile.
+    writeFileSync(
+      join(dir, 'usage.ts'),
+      [
+        "import { getGiftcardsCardId } from './client.js';",
+        '',
+        'export async function streamUsage() {',
+        "  return getGiftcardsCardId({ parseAs: 'stream' });",
+        '}',
+        '',
+        'export async function textUsage() {',
+        "  return getGiftcardsCardId({ parseAs: 'text' });",
+        '}',
+        '',
+        '// @ts-expect-error — parseAs is a closed union; bogus kinds are rejected.',
+        "export const bogus = getGiftcardsCardId({ parseAs: 'xml' });",
+        '',
+      ].join('\n'),
+      'utf-8'
+    );
+    strictTypecheck(dir, ['client.ts', 'usage.ts']);
+    rmSync(dir, { recursive: true, force: true });
+  }, 60_000);
+});
diff --git a/tests/e2e/generate-client/path-param-idents.test.ts b/tests/e2e/generate-client/path-param-idents.test.ts
new file mode 100644
index 0000000000..3b0f84df81
--- /dev/null
+++ b/tests/e2e/generate-client/path-param-idents.test.ts
@@ -0,0 +1,139 @@
+/**
+ * Behavioral e2e for non-identifier path parameters. OpenAPI allows parameter
+ * names that are not valid JS identifiers (`widget-id`), start with a digit
+ * (`2fa`), or collide with reserved words (`new`). The generator must sanitize
+ * each into a safe sugar argument name while routing the value back under the
+ * WIRE name (the descriptor's `ParamSpec.name`) — otherwise the emitted client
+ * either fails to compile or substitutes nothing into the URL template.
+ *
+ * This generates a client from such a spec, type-checks it under strict mode
+ * (proving it compiles), then runs it through a fake `fetch` (proving the URL is
+ * built from the argument value).
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { outdent } from 'outdent';
+
+import { generateInto, repoRoot, runConsumer, tscBin } from './helpers.js';
+
+const SPEC = outdent`
+  openapi: 3.0.3
+  info:
+    title: Odd Names API
+    version: 1.0.0
+  servers:
+    - url: https://api.example.com
+  paths:
+    /widgets/{widget-id}:
+      get:
+        operationId: getWidget
+        parameters:
+          - name: widget-id
+            in: path
+            required: true
+            schema:
+              type: string
+        responses:
+          '200':
+            description: ok
+            content:
+              application/json:
+                schema:
+                  type: object
+                  properties:
+                    id:
+                      type: string
+    /items/{new}:
+      get:
+        operationId: getItem
+        parameters:
+          - name: new
+            in: path
+            required: true
+            schema:
+              type: string
+        responses:
+          '200':
+            description: ok
+            content:
+              application/json:
+                schema:
+                  type: object
+                  properties:
+                    id:
+                      type: string
+`;
+
+const TSCONFIG = JSON.stringify({
+  compilerOptions: {
+    module: 'nodenext',
+    moduleResolution: 'nodenext',
+    target: 'es2022',
+    lib: ['ES2022', 'DOM'],
+    strict: true,
+    noEmit: true,
+    noUnusedLocals: true,
+    noUnusedParameters: true,
+    skipLibCheck: true,
+    types: [],
+  },
+  include: ['client.ts'],
+});
+
+describe('non-identifier path parameters', () => {
+  let dir = '';
+  beforeAll(() => {
+    dir = mkdtempSync(join(tmpdir(), 'oddnames-'));
+    writeFileSync(join(dir, 'openapi.yaml'), SPEC, 'utf-8');
+    generateInto(dir, join(dir, 'openapi.yaml'));
+  }, 60_000);
+  afterAll(() => {
+    if (dir && existsSync(dir)) rmSync(dir, { recursive: true, force: true });
+  });
+
+  test('emits safe argument names routed back under the wire name', () => {
+    const client = readFileSync(join(dir, 'client.ts'), 'utf-8');
+    // `widget-id` → safe `widget_id` argument, routed under the quoted wire key.
+    expect(client).toContain(
+      'export const getWidget = (widget_id: string, init: RequestOptions = {}) => client.getWidget({ "widget-id": widget_id }, init);'
+    );
+    // The descriptor keeps the WIRE name for URL substitution.
+    expect(client).toContain('params: [{ name: "widget-id", in: "path" }]');
+    // reserved word `new` → `_new` argument, routed under the `new` key.
+    expect(client).toContain(
+      'export const getItem = (_new: string, init: RequestOptions = {}) => client.getItem({ new: _new }, init);'
+    );
+  });
+
+  test('the generated client type-checks under strict mode', () => {
+    writeFileSync(join(dir, 'tsconfig.json'), TSCONFIG, 'utf-8');
+    const result = spawnSync(tscBin, ['--noEmit', '-p', join(dir, 'tsconfig.json')], {
+      encoding: 'utf-8',
+      cwd: repoRoot,
+    });
+    expect(result.status, `tsc failed:\n${result.stdout}\n${result.stderr}`).toBe(0);
+  }, 60_000);
+
+  test('builds the request URL from the argument value', () => {
+    const consumer = outdent`
+      import { configure, getWidget, getItem } from './client.ts';
+
+      const urls: string[] = [];
+      configure({
+        fetch: (async (url: string) => {
+          urls.push(url);
+          return new Response('{"id":"x"}', { status: 200, headers: { 'content-type': 'application/json' } });
+        }) as unknown as typeof fetch,
+      });
+
+      await getWidget('abc');
+      await getItem('xyz');
+      console.log(JSON.stringify(urls));
+    `;
+    const urls = runConsumer(dir, consumer) as string[];
+    expect(urls[0]).toBe('https://api.example.com/widgets/abc');
+    expect(urls[1]).toBe('https://api.example.com/items/xyz');
+  }, 60_000);
+});
diff --git a/tests/e2e/generate-client/per-instance-auth.test.ts b/tests/e2e/generate-client/per-instance-auth.test.ts
new file mode 100644
index 0000000000..72d3e5ab62
--- /dev/null
+++ b/tests/e2e/generate-client/per-instance-auth.test.ts
@@ -0,0 +1,77 @@
+// Behavioral proof of per-instance auth: two `createClient` instances built over the
+// SAME generated descriptors carry different `config.auth` and send different
+// credentials — without touching the generated module's own client instance or its
+// setter sugar. A no-auth instance sends nothing. We capture the wire `Authorization`
+// header via an injected `config.fetch`, so no mock server is needed.
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { outdent } from 'outdent';
+
+import { generateInto, tsxBin } from './helpers.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const SPEC = outdent`
+  openapi: 3.1.0
+  info: { title: Thing API, version: '1.0.0' }
+  servers: [{ url: https://api.example.com }]
+  components:
+    securitySchemes:
+      basicAuth: { type: http, scheme: basic }
+  paths:
+    /thing:
+      get:
+        operationId: getThing
+        security: [{ basicAuth: [] }]
+        responses:
+          '200': { description: ok, content: { application/json: { schema: { type: object } } } }
+`;
+
+const DRIVER = outdent`
+  import { createClient } from '@redocly/client-generator';
+  import { OPERATIONS, type Ops } from './client.js';
+
+  const calls: (string | null)[] = [];
+  const fakeFetch = (async (_url: string, init?: RequestInit) => {
+    const h = (init?.headers ?? {}) as Record<string, string>;
+    calls.push(h['Authorization'] ?? null);
+    return new Response('{}', { status: 200, headers: { 'content-type': 'application/json' } });
+  }) as unknown as typeof fetch;
+
+  async function main() {
+    const authed = createClient<Ops>(OPERATIONS, {
+      fetch: fakeFetch,
+      auth: { basic: { username: 'alice', password: 'pw' } },
+    });
+    const anon = createClient<Ops>(OPERATIONS, { fetch: fakeFetch });
+    await authed.getThing();
+    await anon.getThing();
+    console.log(JSON.stringify(calls));
+  }
+  void main();
+`;
+
+describe('per-instance auth (createClient config.auth)', () => {
+  it('two instances send different credentials; a no-auth instance sends none', () => {
+    // The temp dir lives INSIDE the repo so the driver's import of
+    // `@redocly/client-generator` resolves through the workspace node_modules symlink.
+    const dir = mkdtempSync(join(__dirname, '.tmp-perinstance-'));
+    try {
+      writeFileSync(join(dir, 'openapi.yaml'), SPEC, 'utf-8');
+      generateInto(dir, join(dir, 'openapi.yaml'), ['--runtime', 'package']);
+
+      writeFileSync(join(dir, 'driver.ts'), DRIVER, 'utf-8');
+      const run = spawnSync(tsxBin, [join(dir, 'driver.ts')], { encoding: 'utf-8', cwd: dir });
+      expect(run.status, run.stderr).toBe(0);
+
+      const calls = JSON.parse(run.stdout.trim()) as (string | null)[];
+      const expected = 'Basic ' + Buffer.from('alice:pw').toString('base64');
+      expect(calls[0]).toBe(expected); // the authed instance sent its own basic credential
+      expect(calls[1]).toBeNull(); // the no-auth instance sent nothing (no shared state)
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  }, 60_000);
+});
diff --git a/tests/e2e/generate-client/plugin.test.ts b/tests/e2e/generate-client/plugin.test.ts
new file mode 100644
index 0000000000..4ff6a708ea
--- /dev/null
+++ b/tests/e2e/generate-client/plugin.test.ts
@@ -0,0 +1,91 @@
+// The experimental custom-generator (plugin) API end-to-end: a `generators` entry that is a path
+// specifier is dynamically imported and run alongside the built-ins, and a bad specifier fails fast.
+import { spawnSync } from 'node:child_process';
+import { cpSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { cliEntry, repoRoot } from './helpers.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const cafe = join(__dirname, 'fixtures', 'cafe.yaml');
+const plugin = join(__dirname, 'fixtures', 'route-map-plugin.mjs');
+
+function run(args: string[]): { status: number | null; out: string } {
+  const res = spawnSync('node', [cliEntry, 'generate-client', ...args], {
+    encoding: 'utf-8',
+    cwd: repoRoot,
+  });
+  return { status: res.status, out: `${res.stdout}\n${res.stderr}` };
+}
+
+describe('generate-client custom generator (plugin) API', () => {
+  it('loads a generator from a path specifier and runs it alongside the sdk', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'ots-plugin-'));
+    const output = join(dir, 'client.ts');
+    const { status, out } = run([
+      cafe,
+      '--output',
+      output,
+      '--generator',
+      'sdk',
+      '--generator',
+      plugin,
+    ]);
+
+    expect(status, out).toBe(0);
+    expect(existsSync(output)).toBe(true);
+    const routesFile = output.replace(/\.ts$/, '.routes.ts');
+    expect(existsSync(routesFile)).toBe(true);
+    const routes = readFileSync(routesFile, 'utf-8');
+    expect(routes).toContain('export const routes = {');
+    // The plugin walked the same IR the built-ins see (real operations from cafe.yaml).
+    expect(routes).toMatch(/: '(GET|POST|PUT|PATCH|DELETE) \//);
+    rmSync(dir, { recursive: true, force: true });
+  }, 60_000);
+
+  it('resolves a relative --generator path against the cwd, not the --config dir', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'ots-plugin-cwd-'));
+    const configDir = mkdtempSync(join(tmpdir(), 'ots-plugin-config-'));
+    cpSync(plugin, join(dir, 'route-map-plugin.mjs'));
+    writeFileSync(join(configDir, 'redocly.yaml'), 'extends: []\n');
+    const res = spawnSync(
+      'node',
+      [
+        cliEntry,
+        'generate-client',
+        cafe,
+        '--output',
+        join(dir, 'client.ts'),
+        '--generator',
+        'sdk',
+        '--generator',
+        './route-map-plugin.mjs',
+        '--config',
+        join(configDir, 'redocly.yaml'),
+      ],
+      { encoding: 'utf-8', cwd: dir }
+    );
+    expect(res.status, `${res.stdout}\n${res.stderr}`).toBe(0);
+    expect(existsSync(join(dir, 'client.routes.ts'))).toBe(true);
+    rmSync(dir, { recursive: true, force: true });
+    rmSync(configDir, { recursive: true, force: true });
+  }, 60_000);
+
+  it('fails fast with an actionable message when a specifier cannot be loaded', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'ots-plugin-'));
+    const { status, out } = run([
+      cafe,
+      '--output',
+      join(dir, 'client.ts'),
+      '--generator',
+      'sdk',
+      '--generator',
+      join(dir, 'missing-plugin.mjs'),
+    ]);
+    expect(status).not.toBe(0);
+    expect(out).toMatch(/Could not load generator/);
+    rmSync(dir, { recursive: true, force: true });
+  }, 60_000);
+});
diff --git a/tests/e2e/generate-client/query-styles.test.ts b/tests/e2e/generate-client/query-styles.test.ts
new file mode 100644
index 0000000000..054d053d47
--- /dev/null
+++ b/tests/e2e/generate-client/query-styles.test.ts
@@ -0,0 +1,92 @@
+// Query-parameter serialization styles (P3.8). Generates a client from a spec
+// declaring non-default query styles, strict-`tsc`s it (the descriptor `params`
+// hints must satisfy `ParamSpec`), asserts the emitted source, and proves the
+// WIRE FORMAT behaviorally.
+//
+// Behavioral approach: rather than stand up a mock server, we import the
+// generated client and stub `config.fetch` (via `configure`) to capture the
+// request URL, then assert it directly. This is the lightest harness that
+// proves the runtime's `buildUrl` output (literal delimiters + allowReserved
+// on the wire), which is the whole point of the feature.
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { generate, strictTypecheck } from './helpers.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const fixture = join(__dirname, 'fixtures', 'query-styles.yaml');
+
+describe('generate-client query serialization styles', () => {
+  let dir: string;
+  let generated: string;
+
+  beforeAll(() => {
+    dir = mkdtempSync(join(tmpdir(), 'ots-qstyles-'));
+    const out = join(dir, 'client.ts');
+    generate(fixture, out);
+    expect(existsSync(out)).toBe(true);
+    generated = readFileSync(out, 'utf-8');
+  }, 60_000);
+
+  afterAll(() => {
+    if (dir) rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('emits style hints on the descriptor params, and none for the default param', () => {
+    // Styled array params carry their explicit style/explode on the descriptor.
+    expect(generated).toContain(
+      '{ name: "tags", in: "query", style: "pipeDelimited", explode: false }'
+    );
+    expect(generated).toContain(
+      '{ name: "q", in: "query", style: "spaceDelimited", explode: false }'
+    );
+    expect(generated).toContain('{ name: "ids", in: "query", style: "form", explode: false }');
+    // allowReserved param keeps the default form+explode but flags allowReserved.
+    expect(generated).toContain('{ name: "filter", in: "query", allowReserved: true }');
+    // The default param `limit` carries NO style hints.
+    expect(generated).toContain('{ name: "limit", in: "query" }');
+  });
+
+  it('strict-tsc type-checks the generated client', () => {
+    strictTypecheck(dir, ['client.ts']);
+  }, 60_000);
+
+  it('serializes the wire format: literal delimiters + allowReserved', () => {
+    // A tiny consumer imports the generated client, stubs config.fetch to
+    // capture the URL, and writes it to stdout.
+    const runner = join(dir, 'run.mts');
+    writeFileSync(
+      runner,
+      [
+        `import { search, configure } from './client.ts';`,
+        `let captured = '';`,
+        `configure({`,
+        `  fetch: async (url) => {`,
+        `    captured = String(url);`,
+        `    return new Response('{"results":[]}', { status: 200, headers: { 'content-type': 'application/json' } });`,
+        `  },`,
+        `});`,
+        `await search({ tags: ['a', 'b'], q: ['x', 'y'], ids: ['1', '2'], filter: 'a/b', limit: 5 });`,
+        `process.stdout.write(captured);`,
+        ``,
+      ].join('\n'),
+      'utf-8'
+    );
+    const run = spawnSync('npx', ['tsx', runner], { encoding: 'utf-8', cwd: dir });
+    expect(run.status, `consumer stderr:\n${run.stderr}`).toBe(0);
+    const url = run.stdout.trim();
+    // pipeDelimited: literal `|` on the wire (NOT %7C).
+    expect(url).toContain('tags=a|b');
+    // spaceDelimited: literal `%20` space delimiter between values.
+    expect(url).toContain('q=x%20y');
+    // form + explode:false: literal `,` delimiter.
+    expect(url).toContain('ids=1,2');
+    // allowReserved: the `/` survives un-encoded (NOT %2F).
+    expect(url).toContain('filter=a/b');
+    // The default param still encodes normally.
+    expect(url).toContain('limit=5');
+  }, 60_000);
+});
diff --git a/tests/e2e/generate-client/redocly-config.test.ts b/tests/e2e/generate-client/redocly-config.test.ts
new file mode 100644
index 0000000000..8bdaf484a1
--- /dev/null
+++ b/tests/e2e/generate-client/redocly-config.test.ts
@@ -0,0 +1,530 @@
+// generate-client reads its settings from a `redocly.yaml` `client` block (top-level
+// shared defaults) and per-API `apis.<name>.client` / `clientOutput`. Invocation modes:
+// fan-out (no arg, over apis with a `client` block) and an `apis:` alias or file path,
+// resolved like `bundle`/`lint`. CLI flags override the config.
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { cliEntry, repoRoot } from './helpers.js';
+
+// The smallest spec these tests need: `listOrders` fits the cursor convention
+// (an `after` query param + `/page/endCursor` + `/items` pointers), `getRevenue`
+// does not (no `after` param), and the named schemas give `zod` something to emit.
+const SPEC =
+  [
+    'openapi: 3.1.0',
+    'info: { title: Test, version: 1.0.0 }',
+    'servers:',
+    '  - url: https://api.example.com',
+    'paths:',
+    '  /orders:',
+    '    get:',
+    '      operationId: listOrders',
+    '      tags: [Orders]',
+    '      parameters:',
+    '        - { name: after, in: query, schema: { type: string } }',
+    '        - { name: limit, in: query, schema: { type: integer } }',
+    '      responses:',
+    "        '200':",
+    '          description: ok',
+    '          content:',
+    '            application/json:',
+    "              schema: { $ref: '#/components/schemas/OrderPage' }",
+    '  /revenue:',
+    '    get:',
+    '      operationId: getRevenue',
+    '      tags: [Revenue]',
+    '      responses:',
+    "        '200':",
+    '          description: ok',
+    '          content:',
+    '            application/json:',
+    '              schema: { type: object, properties: { total: { type: number } } }',
+    'components:',
+    '  schemas:',
+    '    Order:',
+    '      type: object',
+    '      properties:',
+    '        id: { type: string }',
+    '    OrderPage:',
+    '      type: object',
+    '      properties:',
+    '        page:',
+    '          type: object',
+    '          properties:',
+    '            endCursor: { type: string }',
+    '        items:',
+    '          type: array',
+    "          items: { $ref: '#/components/schemas/Order' }",
+  ].join('\n') + '\n';
+
+/** Write a temp project: the minimal spec + a redocly.yaml with the given contents. */
+function project(redoclyYaml: string): string {
+  const dir = mkdtempSync(join(tmpdir(), 'ots-redocly-'));
+  writeFileSync(join(dir, 'openapi.yaml'), SPEC, 'utf-8');
+  writeFileSync(join(dir, 'redocly.yaml'), redoclyYaml, 'utf-8');
+  return dir;
+}
+const run = (dir: string, args: string[] = []) =>
+  spawnSync('node', [cliEntry, 'generate-client', ...args], { cwd: dir, encoding: 'utf-8' });
+
+describe('generate-client redocly.yaml config', () => {
+  it('fan-out (no arg) builds every api with a `client` block or `clientOutput`', () => {
+    const dir = project(
+      [
+        'client:', // shared defaults, inherited by apis without their own block
+        '  generators: [sdk]',
+        '  serverUrl: https://shared.example.com',
+        'apis:',
+        '  cafe:',
+        '    root: ./openapi.yaml',
+        '    clientOutput: ./src/cafe.ts',
+        '    client:',
+        '      generators: [sdk]',
+        '  outputOnly:', // `clientOutput` alone also opts in
+        '    root: ./openapi.yaml',
+        '    clientOutput: ./src/output-only.ts',
+        '  lintOnly:', // neither -> skipped by the fan-out
+        '    root: ./openapi.yaml',
+      ].join('\n') + '\n'
+    );
+    const res = run(dir);
+    expect(res.status, res.stderr).toBe(0);
+    expect(existsSync(join(dir, 'src/cafe.ts'))).toBe(true);
+    expect(existsSync(join(dir, 'lintOnly.client.ts'))).toBe(false);
+    expect(readFileSync(join(dir, 'src/cafe.ts'), 'utf-8')).toContain(
+      'export const client = createClient<Ops, OperationId, OperationPath, OperationTag>(OPERATIONS,'
+    );
+    // The clientOutput-only api inherits the top-level `client` defaults.
+    expect(readFileSync(join(dir, 'src/output-only.ts'), 'utf-8')).toContain(
+      'serverUrl: "https://shared.example.com"'
+    );
+    rmSync(dir, { recursive: true, force: true });
+  }, 60_000);
+
+  it('defaults the output to `<name>.client.ts` in the config dir when clientOutput is omitted', () => {
+    const dir = project(
+      [
+        'apis:',
+        '  cafe:',
+        '    root: ./openapi.yaml',
+        '    client:',
+        '      generators: [sdk]',
+      ].join('\n') + '\n'
+    );
+    const res = run(dir);
+    expect(res.status, res.stderr).toBe(0);
+    expect(existsSync(join(dir, 'cafe.client.ts'))).toBe(true);
+    rmSync(dir, { recursive: true, force: true });
+  }, 60_000);
+
+  it('resolves an `apis:` alias passed as <api>, using its client block + clientOutput', () => {
+    const dir = project(
+      [
+        'apis:',
+        '  cafe:',
+        '    root: ./openapi.yaml',
+        '    clientOutput: ./out.ts',
+        '    client:',
+        '      generators: [sdk]',
+        '      serverUrl: https://per-api.example.com',
+      ].join('\n') + '\n'
+    );
+    const res = run(dir, ['cafe']);
+    expect(res.status, res.stderr).toBe(0);
+    expect(readFileSync(join(dir, 'out.ts'), 'utf-8')).toContain(
+      'serverUrl: "https://per-api.example.com"'
+    );
+    rmSync(dir, { recursive: true, force: true });
+  }, 60_000);
+
+  it('a named alias falls back to the top-level `client` when it has no per-api block', () => {
+    const dir = project(
+      [
+        'client:',
+        '  generators: [sdk]',
+        '  serverUrl: https://top-level.example.com',
+        'apis:',
+        '  cafe:',
+        '    root: ./openapi.yaml',
+        '    clientOutput: ./out.ts',
+      ].join('\n') + '\n'
+    );
+    const res = run(dir, ['cafe']);
+    expect(res.status, res.stderr).toBe(0);
+    // serverUrl came from the top-level client block (the api declares none).
+    expect(readFileSync(join(dir, 'out.ts'), 'utf-8')).toContain(
+      'serverUrl: "https://top-level.example.com"'
+    );
+    rmSync(dir, { recursive: true, force: true });
+  }, 60_000);
+
+  it("a file path matching an api root uses that api's config (like `bundle`); an unmatched path uses the top-level defaults", () => {
+    const dir = project(
+      [
+        'client:',
+        '  generators: [sdk, zod]', // shared defaults that must survive the per-api override
+        '  serverUrl: https://top-level.example.com',
+        '  pagination:',
+        '    style: cursor',
+        '    cursorParam: after',
+        '    nextCursor: /page/endCursor',
+        '    items: /items',
+        'apis:',
+        '  cafe:',
+        '    root: ./openapi.yaml',
+        '    client:',
+        '      serverUrl: https://per-api.example.com',
+        '      pagination:', // partial: must layer onto the shared convention, not replace it
+        '        exclude: [getRevenue]',
+      ].join('\n') + '\n'
+    );
+    writeFileSync(join(dir, 'standalone.yaml'), SPEC, 'utf-8'); // not registered under `apis:`
+
+    const matched = run(dir, ['./openapi.yaml', '--output', './matched.ts']);
+    expect(matched.status, matched.stderr).toBe(0);
+    const matchedOut = readFileSync(join(dir, 'matched.ts'), 'utf-8');
+    expect(matchedOut).toContain('serverUrl: "https://per-api.example.com"');
+    expect(matchedOut).toContain('pagination: {'); // top-level convention kept, field by field
+    // The shared `generators` default kept too: the zod module is emitted alongside.
+    expect(existsSync(join(dir, 'matched.zod.ts'))).toBe(true);
+
+    const unmatched = run(dir, ['./standalone.yaml', '--output', './unmatched.ts']);
+    expect(unmatched.status, unmatched.stderr).toBe(0);
+    expect(readFileSync(join(dir, 'unmatched.ts'), 'utf-8')).toContain(
+      'serverUrl: "https://top-level.example.com"'
+    );
+    rmSync(dir, { recursive: true, force: true });
+  }, 60_000);
+
+  it('CLI flags override the client block', () => {
+    const dir = project(
+      [
+        'apis:',
+        '  cafe:',
+        '    root: ./openapi.yaml',
+        '    clientOutput: ./out.ts',
+        '    client:',
+        '      generators: [sdk]',
+        '      serverUrl: https://per-api.example.com',
+      ].join('\n') + '\n'
+    );
+    const res = run(dir, ['cafe', '--server-url', 'https://flag.example.com']);
+    expect(res.status, res.stderr).toBe(0);
+    expect(readFileSync(join(dir, 'out.ts'), 'utf-8')).toContain(
+      'serverUrl: "https://flag.example.com"'
+    );
+    rmSync(dir, { recursive: true, force: true });
+  }, 60_000);
+
+  it('warns on a removed `facade` key (config struct rule) but still generates', () => {
+    const dir = project(
+      [
+        'apis:',
+        '  cafe:',
+        '    root: ./openapi.yaml',
+        '    clientOutput: ./out.ts',
+        '    client:',
+        '      generators: [sdk]',
+        '      facade: service-class', // removed option -> property-not-expected warning
+      ].join('\n') + '\n'
+    );
+    const res = run(dir, ['cafe']);
+    expect(res.status, res.stderr).toBe(0);
+    expect(res.stdout + res.stderr).toContain('Property `facade` is not expected here.');
+    expect(res.stderr).toContain('Your config has 1 warning');
+    expect(existsSync(join(dir, 'out.ts'))).toBe(true);
+    rmSync(dir, { recursive: true, force: true });
+  }, 60_000);
+
+  it('applies a `client.pagination` convention rule (descriptor + flat-sugar iterators)', () => {
+    const dir = project(
+      [
+        'apis:',
+        '  cafe:',
+        '    root: ./openapi.yaml',
+        '    clientOutput: ./out.ts',
+        '    client:',
+        '      generators: [sdk]',
+        '      pagination:',
+        '        style: cursor',
+        '        cursorParam: after',
+        '        nextCursor: /page/endCursor',
+        '        limitParam: limit',
+        '        items: /items',
+      ].join('\n') + '\n'
+    );
+    const res = run(dir, ['cafe']);
+    expect(res.status, res.stderr).toBe(0);
+    // The pagination block is part of the config schema -> no struct-rule warning.
+    expect(res.stdout + res.stderr).not.toContain('is not expected here');
+    const out = readFileSync(join(dir, 'out.ts'), 'utf-8');
+    // The convention fits the cursor-style list operations -> descriptor pagination…
+    expect(out).toContain('pagination: {');
+    // …and the flat sugar preserves the method-attached iterators.
+    expect(out).toContain('items: client.listOrders.items');
+    rmSync(dir, { recursive: true, force: true });
+  }, 60_000);
+
+  it('fails generation when an explicit `pagination.operations` rule does not fit', () => {
+    const dir = project(
+      [
+        'apis:',
+        '  cafe:',
+        '    root: ./openapi.yaml',
+        '    clientOutput: ./out.ts',
+        '    client:',
+        '      generators: [sdk]',
+        '      pagination:',
+        '        operations:',
+        '          getRevenue:', // has no `after` query param -> explicit misfit = error
+        '            style: cursor',
+        '            cursorParam: after',
+        '            nextCursor: /page/endCursor',
+        '            items: /items',
+      ].join('\n') + '\n'
+    );
+    const res = run(dir, ['cafe']);
+    expect(res.status).not.toBe(0);
+    expect(res.stderr).toContain('Invalid pagination configuration');
+    expect(res.stderr).toContain(
+      'Pagination for operation "getRevenue" (pagination.operations["getRevenue"]): query parameter "after" is not declared on the operation'
+    );
+    rmSync(dir, { recursive: true, force: true });
+  }, 60_000);
+
+  it('warns on an unknown key inside `client.pagination` (config struct rule) but still generates', () => {
+    const dir = project(
+      [
+        'apis:',
+        '  cafe:',
+        '    root: ./openapi.yaml',
+        '    clientOutput: ./out.ts',
+        '    client:',
+        '      generators: [sdk]',
+        '      pagination:',
+        '        style: cursor',
+        '        cursor_param: after', // unknown key -> property-not-expected warning
+        '        cursorParam: after',
+        '        nextCursor: /page/endCursor',
+        '        items: /items',
+      ].join('\n') + '\n'
+    );
+    const res = run(dir, ['cafe']);
+    expect(res.status, res.stderr).toBe(0);
+    expect(res.stdout + res.stderr).toContain('Property `cursor_param` is not expected here.');
+    expect(res.stderr).toContain('Your config has 1 warning');
+    expect(existsSync(join(dir, 'out.ts'))).toBe(true);
+    rmSync(dir, { recursive: true, force: true });
+  }, 60_000);
+
+  it('rejects --output in fan-out mode', () => {
+    const dir = project(
+      [
+        'apis:',
+        '  cafe:',
+        '    root: ./openapi.yaml',
+        '    client:',
+        '      generators: [sdk]',
+      ].join('\n') + '\n'
+    );
+    const res = run(dir, ['--output', './out.ts']);
+    expect(res.status).not.toBe(0);
+    expect(res.stderr).toContain("--output can't target multiple APIs");
+    rmSync(dir, { recursive: true, force: true });
+  }, 60_000);
+
+  it('errors when no api has a `client` block and none is named', () => {
+    const dir = project(['apis:', '  cafe:', '    root: ./openapi.yaml'].join('\n') + '\n');
+    const res = run(dir);
+    expect(res.status).not.toBe(0);
+    expect(res.stderr).toContain('No API to generate');
+    rmSync(dir, { recursive: true, force: true });
+  }, 60_000);
+
+  it('errors when two fan-out apis resolve to the same clientOutput', () => {
+    const dir = project(
+      [
+        'apis:',
+        '  a:',
+        '    root: ./openapi.yaml',
+        '    clientOutput: ./dupe.ts',
+        '    client: { generators: [sdk] }',
+        '  b:',
+        '    root: ./openapi.yaml',
+        '    clientOutput: ./dupe.ts',
+        '    client: { generators: [sdk] }',
+      ].join('\n') + '\n'
+    );
+    const res = run(dir);
+    expect(res.status).not.toBe(0);
+    expect(res.stderr).toContain('resolve to the same output path');
+    rmSync(dir, { recursive: true, force: true });
+  }, 60_000);
+
+  it('rejects a bare-hostname serverUrl but accepts absolute and root-relative', () => {
+    const withServerUrl = (serverUrl: string) =>
+      project(
+        [
+          'apis:',
+          '  cafe:',
+          '    root: ./openapi.yaml',
+          '    clientOutput: ./out.ts',
+          '    client:',
+          '      generators: [sdk]',
+          `      serverUrl: ${serverUrl}`,
+        ].join('\n') + '\n'
+      );
+    const bare = withServerUrl('api.example.com');
+    const bad = run(bare, ['cafe']);
+    expect(bad.status).not.toBe(0);
+    expect(bad.stderr).toContain('--server-url must be an absolute URL');
+    rmSync(bare, { recursive: true, force: true });
+
+    for (const ok of ['https://api.example.com', '/v1']) {
+      const dir = withServerUrl(ok);
+      const res = run(dir, ['cafe']);
+      expect(res.status, res.stderr).toBe(0);
+      rmSync(dir, { recursive: true, force: true });
+    }
+
+    // Non-http(s) schemes and protocol-relative hosts are rejected too — the value is
+    // inlined as the client's default fetch base.
+    for (const hostile of ['javascript:alert(1)', 'file:///etc/passwd', '//evil.example.com']) {
+      const dir = withServerUrl(`"${hostile}"`);
+      const res = run(dir, ['cafe']);
+      expect(res.status, `expected rejection for ${hostile}`).not.toBe(0);
+      expect(res.stderr).toContain('--server-url must be an absolute URL');
+      rmSync(dir, { recursive: true, force: true });
+    }
+  }, 60_000);
+
+  it('rejects a URL `client.setup` upfront (setup is a local module baked into the client)', () => {
+    const dir = project(
+      [
+        'apis:',
+        '  cafe:',
+        '    root: ./openapi.yaml',
+        '    clientOutput: ./out.ts',
+        '    client:',
+        '      generators: [sdk]',
+        '      setup: https://cdn.example.com/setup.ts',
+      ].join('\n') + '\n'
+    );
+    const res = run(dir, ['cafe']);
+    expect(res.status).not.toBe(0);
+    expect(res.stderr).toContain('must be a local file path');
+    rmSync(dir, { recursive: true, force: true });
+  }, 60_000);
+
+  it('a `client.runtime: package` config block reaches the writer', () => {
+    const dir = project(
+      [
+        'apis:',
+        '  cafe:',
+        '    root: ./openapi.yaml',
+        '    clientOutput: ./out.ts',
+        '    client:',
+        '      generators: [sdk]',
+        '      runtime: package',
+      ].join('\n') + '\n'
+    );
+    const res = run(dir, ['cafe']);
+    expect(res.status, res.stderr).toBe(0);
+    const out = readFileSync(join(dir, 'out.ts'), 'utf-8');
+    expect(out).toContain("from '@redocly/client-generator'");
+    expect(out).not.toContain('__send');
+    rmSync(dir, { recursive: true, force: true });
+  }, 60_000);
+
+  it('a per-api block holding only `runtime: package` inherits generators and outputMode', () => {
+    // The api's block sets one field; `generators: [sdk, zod]` and `outputMode: split`
+    // must still arrive from the top level (3 files), with the per-api runtime layered in.
+    const dir = project(
+      [
+        'client:',
+        '  generators: [sdk, zod]',
+        '  outputMode: split',
+        'apis:',
+        '  realm:',
+        '    root: ./openapi.yaml',
+        '    clientOutput: ./out/client.ts',
+        '    client:',
+        '      runtime: package',
+      ].join('\n') + '\n'
+    );
+    const res = run(dir, ['realm']);
+    expect(res.status, res.stderr).toBe(0);
+    expect(existsSync(join(dir, 'out/client.ts'))).toBe(true);
+    expect(existsSync(join(dir, 'out/client.schemas.ts'))).toBe(true); // outputMode inherited
+    expect(existsSync(join(dir, 'out/client.zod.ts'))).toBe(true); // generators inherited
+    expect(readFileSync(join(dir, 'out/client.ts'), 'utf-8')).toContain(
+      "from '@redocly/client-generator'" // the per-api runtime applied on top
+    );
+    rmSync(dir, { recursive: true, force: true });
+  }, 60_000);
+
+  it('resolves a relative clientOutput against the redocly.yaml dir (via --config)', () => {
+    const dir = project(
+      [
+        'apis:',
+        '  cafe:',
+        '    root: ./openapi.yaml',
+        '    clientOutput: ./out/client.ts',
+        '    client:',
+        '      generators: [sdk]',
+      ].join('\n') + '\n'
+    );
+    // Run from the repo root, pointing at the config elsewhere via --config.
+    const res = spawnSync(
+      'node',
+      [cliEntry, 'generate-client', '--config', join(dir, 'redocly.yaml')],
+      { cwd: repoRoot, encoding: 'utf-8' }
+    );
+    expect(res.status, res.stderr).toBe(0);
+    expect(existsSync(join(dir, 'out/client.ts'))).toBe(true);
+    rmSync(dir, { recursive: true, force: true });
+  }, 60_000);
+
+  it("applies the api's per-alias decorators to the input before generating", () => {
+    // The client is generated from the api's resolved config (like `bundle`/`lint`), so a
+    // per-api `remove-x-internal` decorator strips the x-internal operation before the IR
+    // is built — the generated client must not contain it.
+    const dir = mkdtempSync(join(tmpdir(), 'ots-redocly-decorators-'));
+    writeFileSync(
+      join(dir, 'openapi.yaml'),
+      [
+        'openapi: 3.1.0',
+        'info: { title: T, version: 1.0.0 }',
+        'paths:',
+        '  /public:',
+        '    get: { operationId: getPublic, responses: { 200: { description: ok } } }',
+        '  /secret:',
+        '    get: { operationId: getSecret, x-internal: true, responses: { 200: { description: ok } } }',
+      ].join('\n') + '\n',
+      'utf-8'
+    );
+    writeFileSync(
+      join(dir, 'redocly.yaml'),
+      [
+        'apis:',
+        '  main:',
+        '    root: ./openapi.yaml',
+        '    clientOutput: ./client.ts',
+        '    decorators:',
+        '      remove-x-internal: on',
+        '    client:',
+        '      generators: [sdk]',
+      ].join('\n') + '\n',
+      'utf-8'
+    );
+    const res = run(dir, ['main']);
+    expect(res.status, res.stderr).toBe(0);
+    const client = readFileSync(join(dir, 'client.ts'), 'utf-8');
+    expect(client).toContain('getPublic');
+    expect(client).not.toContain('getSecret');
+    rmSync(dir, { recursive: true, force: true });
+  }, 60_000);
+});
diff --git a/tests/e2e/generate-client/retry.test.ts b/tests/e2e/generate-client/retry.test.ts
new file mode 100644
index 0000000000..b4c9eb87e0
--- /dev/null
+++ b/tests/e2e/generate-client/retry.test.ts
@@ -0,0 +1,159 @@
+/**
+ * Behavioral e2e for retry. Injects a fake `fetch` via `configure()` so we can
+ * script transient failures and count attempts deterministically — no live server.
+ */
+import { existsSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { outdent } from 'outdent';
+
+import { generateInto, runConsumer } from './helpers.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const fixture = join(__dirname, 'fixtures/base.yaml');
+
+describe('retry behavior', () => {
+  let dir = '';
+  beforeAll(() => {
+    dir = mkdtempSync(join(tmpdir(), 'retry-'));
+    generateInto(dir, fixture);
+  }, 60_000);
+  afterAll(() => {
+    if (dir && existsSync(dir)) rmSync(dir, { recursive: true, force: true });
+  });
+
+  test('retries a GET on 503 then succeeds; default is no retry', () => {
+    const result = runConsumer(
+      dir,
+      outdent`
+        import { configure, listPets } from './client.ts';
+
+        let calls = 0;
+        const makeFetch = (failures: number) =>
+          (async () => {
+            calls++;
+            if (calls <= failures) {
+              return new Response('busy', { status: 503, headers: { 'content-type': 'text/plain' } });
+            }
+            return new Response('[]', { status: 200, headers: { 'content-type': 'application/json' } });
+          }) as unknown as typeof fetch;
+
+        // retries: 0 (default) → one call, throws.
+        calls = 0;
+        configure({ fetch: makeFetch(1) });
+        let defaultThrew = false;
+        try { await listPets(); } catch { defaultThrew = true; }
+        const defaultCalls = calls;
+
+        // retries: 3, fast backoff → recovers after 2 failures.
+        calls = 0;
+        configure({ fetch: makeFetch(2), retry: { retries: 3, retryDelay: 1 } });
+        await listPets();
+        const retryCalls = calls;
+
+        console.log(JSON.stringify({ defaultThrew, defaultCalls, retryCalls }));
+      `
+    ) as { defaultThrew: boolean; defaultCalls: number; retryCalls: number };
+
+    expect(result.defaultThrew).toBe(true);
+    expect(result.defaultCalls).toBe(1);
+    expect(result.retryCalls).toBe(3); // 2 failures + 1 success
+  }, 60_000);
+
+  test('drains the unread body of a retried response before the next attempt', () => {
+    const result = runConsumer(
+      dir,
+      outdent`
+        import { configure, listPets } from './client.ts';
+
+        let calls = 0;
+        let cancelled = 0;
+        // A 503 whose body cancellation is observable, then a 200 success.
+        const makeFetch = () =>
+          (async () => {
+            calls++;
+            if (calls === 1) {
+              const body = new ReadableStream({
+                start(c) { c.enqueue(new TextEncoder().encode('busy')); c.close(); },
+                cancel() { cancelled++; },
+              });
+              return new Response(body, { status: 503, headers: { 'content-type': 'text/plain' } });
+            }
+            return new Response('[]', { status: 200, headers: { 'content-type': 'application/json' } });
+          }) as unknown as typeof fetch;
+
+        configure({ fetch: makeFetch(), retry: { retries: 3, retryDelay: 1 } });
+        await listPets();
+
+        console.log(JSON.stringify({ calls, cancelled }));
+      `
+    ) as { calls: number; cancelled: number };
+
+    expect(result.calls).toBe(2); // 1 failure + 1 success
+    expect(result.cancelled).toBe(1); // the abandoned 503 body was cancelled before retrying
+  }, 60_000);
+
+  test('does NOT retry a non-idempotent POST by default, but does when retryOn opts in', () => {
+    const result = runConsumer(
+      dir,
+      outdent`
+        import { configure, createPet } from './client.ts';
+
+        let calls = 0;
+        const failing = (async () => {
+          calls++;
+          return new Response('err', { status: 503, headers: { 'content-type': 'text/plain' } });
+        }) as unknown as typeof fetch;
+
+        // default predicate: POST is not idempotent → no retry.
+        calls = 0;
+        configure({ fetch: failing, retry: { retries: 3, retryDelay: 1 } });
+        try { await createPet({ name: 'x' } as any); } catch {}
+        const defaultCalls = calls;
+
+        // retryOn: () => true → POST retried.
+        calls = 0;
+        configure({ fetch: failing, retry: { retries: 3, retryDelay: 1, retryOn: () => true } });
+        try { await createPet({ name: 'x' } as any); } catch {}
+        const optInCalls = calls;
+
+        console.log(JSON.stringify({ defaultCalls, optInCalls }));
+      `
+    ) as { defaultCalls: number; optInCalls: number };
+
+    expect(result.defaultCalls).toBe(1); // POST not retried by default
+    expect(result.optInCalls).toBe(4); // 1 + 3 retries
+  }, 60_000);
+
+  test('aborting during backoff stops retries and rejects', () => {
+    const result = runConsumer(
+      dir,
+      outdent`
+        import { configure, listPets } from './client.ts';
+
+        let calls = 0;
+        const failing = (async () => {
+          calls++;
+          return new Response('err', { status: 503, headers: { 'content-type': 'text/plain' } });
+        }) as unknown as typeof fetch;
+
+        configure({ fetch: failing, retry: { retries: 5, retryDelay: 50 } });
+        const controller = new AbortController();
+        setTimeout(() => controller.abort(), 10);
+
+        let aborted = false;
+        try {
+          // listPets takes (params, init); the signal belongs on init.
+          await listPets({}, { signal: controller.signal });
+        } catch (e) {
+          aborted = (e as Error).name === 'AbortError';
+        }
+        console.log(JSON.stringify({ aborted, calls }));
+      `
+    ) as { aborted: boolean; calls: number };
+
+    expect(result.aborted).toBe(true);
+    expect(result.calls).toBe(1); // aborted during the first backoff; no second attempt
+  }, 60_000);
+});
diff --git a/tests/e2e/generate-client/setup.test.ts b/tests/e2e/generate-client/setup.test.ts
new file mode 100644
index 0000000000..0d0d52abfc
--- /dev/null
+++ b/tests/e2e/generate-client/setup.test.ts
@@ -0,0 +1,133 @@
+/**
+ * Behavioral e2e for `--setup`: a publisher setup module baked into the generated client.
+ * Generates a client with `--setup`, then drives the baked runtime in a real consumer to prove
+ * the defaults apply with no consumer `configure`/`use`, that a consumer can still override, and
+ * that the baked setup also applies in the split two-file layout.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { outdent } from 'outdent';
+
+import { cliEntry, repoRoot, runConsumer } from './helpers.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const fixture = join(__dirname, 'fixtures/base.yaml');
+
+const SETUP = outdent`
+  import { defineClientSetup, type RequestContext } from '@redocly/client-generator';
+  export default defineClientSetup({
+    config: { serverUrl: 'https://baked.example.com' },
+    middleware: [{ onRequest: (ctx: RequestContext) => { ctx.headers['X-Baked'] = 'yes'; } }],
+  });
+`;
+
+function generate(
+  dir: string,
+  extraArgs: string[] = []
+): { status: number | null; stderr: string } {
+  writeFileSync(join(dir, 'package.json'), JSON.stringify({ type: 'module' }), 'utf-8');
+  writeFileSync(join(dir, 'setup.ts'), SETUP, 'utf-8');
+  return spawnSync(
+    'node',
+    [
+      cliEntry,
+      'generate-client',
+      fixture,
+      '--output',
+      join(dir, 'client.ts'),
+      '--setup',
+      join(dir, 'setup.ts'),
+      ...extraArgs,
+    ],
+    { encoding: 'utf-8', cwd: repoRoot }
+  );
+}
+
+describe('--setup rejects remote modules', () => {
+  test('a URL fails with the local-file-path error instead of a garbage path', () => {
+    const result = spawnSync(
+      'node',
+      [
+        cliEntry,
+        'generate-client',
+        fixture,
+        '--output',
+        join(tmpdir(), 'setup-url-client.ts'),
+        '--setup',
+        'https://evil.example/mod.ts',
+      ],
+      { encoding: 'utf-8', cwd: repoRoot }
+    );
+    expect(result.status).toBe(1);
+    expect(result.stderr).toContain('must be a local file path');
+  }, 60_000);
+});
+
+describe('--setup bakes publisher defaults into the single-file client', () => {
+  let dir = '';
+  beforeAll(() => {
+    dir = mkdtempSync(join(tmpdir(), 'setup-'));
+    const r = generate(dir);
+    if (r.status !== 0) throw new Error(`generate failed:\n${r.stderr}`);
+  }, 60_000);
+  afterAll(() => {
+    if (dir && existsSync(dir)) rmSync(dir, { recursive: true, force: true });
+  });
+
+  test('a consumer with no configure/use still sends the baked URL + header', () => {
+    const captured = runConsumer(
+      dir,
+      outdent`
+        import { listPets } from './client.ts';
+        let url = '', header = '';
+        globalThis.fetch = (async (u: string, init: RequestInit) => {
+          url = u; header = (init.headers as Record<string,string>)['X-Baked'];
+          return new Response('[]', { status: 200, headers: { 'content-type': 'application/json' } });
+        }) as unknown as typeof fetch;
+        await listPets();
+        console.log(JSON.stringify({ url, header }));
+      `
+    ) as { url: string; header: string };
+    expect(new URL(captured.url).origin).toBe('https://baked.example.com');
+    expect(captured.header).toBe('yes');
+  }, 60_000);
+
+  test('a consumer configure() overrides the baked default', () => {
+    const captured = runConsumer(
+      dir,
+      outdent`
+        import { configure, listPets } from './client.ts';
+        let url = '';
+        configure({ serverUrl: 'https://override.example.com', fetch: (async (u: string) => { url = u; return new Response('[]', { status: 200, headers: { 'content-type': 'application/json' } }); }) as unknown as typeof fetch });
+        await listPets();
+        console.log(JSON.stringify({ url }));
+      `
+    ) as { url: string };
+    expect(new URL(captured.url).origin).toBe('https://override.example.com');
+  }, 60_000);
+
+  test('applies in a multi-file layout (split) with no consumer setup', () => {
+    const dir2 = mkdtempSync(join(tmpdir(), 'setup-split-'));
+    try {
+      const r = generate(dir2, ['--output-mode', 'split']);
+      expect(r.status, r.stderr).toBe(0);
+      const captured = runConsumer(
+        dir2,
+        outdent`
+          import { listPets } from './client.ts';
+          let url = '', header = '';
+          globalThis.fetch = (async (u: string, init: RequestInit) => { url = u; header = (init.headers as Record<string,string>)['X-Baked']; return new Response('[]', { status: 200, headers: { 'content-type': 'application/json' } }); }) as unknown as typeof fetch;
+          await listPets();
+          console.log(JSON.stringify({ url, header }));
+        `
+      ) as { url: string; header: string };
+      expect(new URL(captured.url).origin).toBe('https://baked.example.com');
+      expect(captured.header).toBe('yes');
+    } finally {
+      rmSync(dir2, { recursive: true, force: true });
+    }
+  }, 60_000);
+});
diff --git a/tests/e2e/generate-client/spec-versions.test.ts b/tests/e2e/generate-client/spec-versions.test.ts
new file mode 100644
index 0000000000..7561331d5e
--- /dev/null
+++ b/tests/e2e/generate-client/spec-versions.test.ts
@@ -0,0 +1,42 @@
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { generate, strictTypecheck } from './helpers.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+function generateAndTypecheck(fixture: string): { generated: string } {
+  const dir = mkdtempSync(join(tmpdir(), 'ots-specver-'));
+  const out = join(dir, 'client.ts');
+  generate(join(__dirname, 'fixtures', fixture), out);
+  expect(existsSync(out)).toBe(true);
+  const generated = readFileSync(out, 'utf-8');
+  strictTypecheck(dir, ['client.ts']);
+  rmSync(dir, { recursive: true, force: true });
+  return { generated };
+}
+
+describe('generate-client spec versions', () => {
+  it('generates a type-checking client from a Swagger 2.0 document', () => {
+    const { generated } = generateAndTypecheck('swagger2.yaml');
+    expect(generated).toContain('export const getPet = (');
+    expect(generated).toContain('export const createPet = (');
+    expect(generated).toContain('export type Pet');
+    expect(generated).toContain('serverUrl: "https://api.example.com/v2"');
+  }, 60_000);
+
+  it('generates a type-checking client from an OpenAPI 3.2 document', () => {
+    const { generated } = generateAndTypecheck('oas3.2.yaml');
+    expect(generated).toContain('export const getThing = (');
+    expect(generated).toContain('export type Thing');
+    // 3.1/3.2 nullable enum renders as a nullable union.
+    expect(generated).toMatch(/status\?:\s*\("active" \| "archived"\) \| null;/);
+  }, 60_000);
+
+  it('synthesizes operation names from method+path when operationId is omitted', () => {
+    const { generated } = generateAndTypecheck('no-operationid.yaml');
+    expect(generated).toContain('export const getGiftcardsCardId = (');
+  }, 60_000);
+});
diff --git a/tests/e2e/generate-client/split.test.ts b/tests/e2e/generate-client/split.test.ts
new file mode 100644
index 0000000000..2ea790e224
--- /dev/null
+++ b/tests/e2e/generate-client/split.test.ts
@@ -0,0 +1,108 @@
+/**
+ * E2E for `--output-mode split`: the generated two-file set must compile under
+ * strict `tsc` with `--noUnusedLocals`, which proves both that cross-file imports
+ * resolve and that each file imports exactly what it uses (no over-importing).
+ *
+ * Uses cafe.yaml because it exercises the embedded runtime broadly (bearer + apiKey
+ * auth, header params) and the schemas module (named types + discriminated-union guards).
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { generate, tscBin } from './helpers.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const fixture = join(__dirname, 'fixtures/cafe.yaml');
+
+describe('generate-client end-to-end (--output-mode split)', () => {
+  let workDir = '';
+  let entry = '';
+  let schemasFile = '';
+
+  beforeAll(() => {
+    workDir = mkdtempSync(join(tmpdir(), 'split-client-'));
+    entry = join(workDir, 'client.ts');
+    schemasFile = join(workDir, 'client.schemas.ts');
+  });
+
+  afterAll(() => {
+    if (workDir && existsSync(workDir)) {
+      rmSync(workDir, { recursive: true, force: true });
+    }
+  });
+
+  test('writes two sibling files derived from --output', () => {
+    generate(fixture, entry, ['--output-mode', 'split']);
+    expect(existsSync(entry)).toBe(true);
+    expect(existsSync(schemasFile)).toBe(true);
+    // Split is exactly two files: no `.http.ts` module anymore.
+    expect(existsSync(join(workDir, 'client.http.ts'))).toBe(false);
+
+    const entrySrc = readFileSync(entry, 'utf-8');
+    // The entry embeds the runtime, holds the descriptor wiring, imports schema
+    // types, and re-exports the schemas module as the public type surface.
+    expect(entrySrc).toContain('// ─── Embedded runtime');
+    expect(entrySrc).toContain("from './client.schemas.js'");
+    expect(entrySrc).toContain("export * from './client.schemas.js';");
+    expect(entrySrc).toContain('as const satisfies Record<string, OperationDescriptor>');
+    expect(entrySrc).toContain(
+      'export const client = createClient<Ops, OperationId, OperationPath, OperationTag>(OPERATIONS,'
+    );
+    expect(entrySrc).toContain('export const { configure, use } = client;');
+    expect(entrySrc).toContain('export const setBearer = client.auth.bearer;');
+
+    // Schemas holds the model types and the discriminated-union guards.
+    const schemasSrc = readFileSync(schemasFile, 'utf-8');
+    expect(schemasSrc).toContain('export type ');
+    expect(schemasSrc).toContain('export function isBeverage(');
+  }, 90_000);
+
+  test('the two-file set type-checks under strict mode with no unused imports', () => {
+    expect(existsSync(entry), 'generation test must run first').toBe(true);
+
+    const tsc = spawnSync(
+      tscBin,
+      [
+        '--noEmit',
+        '--strict',
+        '--noUnusedLocals',
+        '--target',
+        'ES2020',
+        '--module',
+        'esnext',
+        '--moduleResolution',
+        'bundler',
+        '--lib',
+        'ES2020,DOM',
+        entry,
+        schemasFile,
+      ],
+      { encoding: 'utf-8', cwd: workDir }
+    );
+    expect(tsc.status, `tsc errors:\n${tsc.stdout}\n${tsc.stderr}`).toBe(0);
+  }, 90_000);
+
+  // `--import-ext ts` targets runtimes that resolve specifiers literally (no `.js` → `.ts`
+  // remap) — Node's built-in type stripping. Locked by actually executing `node main.ts`.
+  test('--import-ext ts produces a client Node runs natively', () => {
+    const tsEntry = join(workDir, 'client-ts.ts');
+    generate(fixture, tsEntry, ['--output-mode', 'split', '--import-ext', 'ts']);
+
+    const entrySrc = readFileSync(tsEntry, 'utf-8');
+    expect(entrySrc).toContain("export * from './client-ts.schemas.ts';");
+    expect(entrySrc).not.toContain('.schemas.js');
+
+    const mainFile = join(workDir, 'main.ts');
+    writeFileSync(
+      mainFile,
+      "import { isBeverage } from './client-ts.ts';\n" +
+        "console.log('isBeverage:', typeof isBeverage);\n"
+    );
+    const run = spawnSync('node', [mainFile], { encoding: 'utf-8', cwd: workDir });
+    expect(run.status, `node errors:\n${run.stderr}`).toBe(0);
+    expect(run.stdout).toContain('isBeverage: function');
+  }, 90_000);
+});
diff --git a/tests/e2e/generate-client/sse-consumer/.gitignore b/tests/e2e/generate-client/sse-consumer/.gitignore
new file mode 100644
index 0000000000..35d9162694
--- /dev/null
+++ b/tests/e2e/generate-client/sse-consumer/.gitignore
@@ -0,0 +1,2 @@
+# Generated fresh by the owning suite in beforeAll; excluded from the root typecheck.
+api.ts
diff --git a/tests/e2e/generate-client/sse-consumer/index-abort.ts b/tests/e2e/generate-client/sse-consumer/index-abort.ts
new file mode 100644
index 0000000000..f3f69e20f1
--- /dev/null
+++ b/tests/e2e/generate-client/sse-consumer/index-abort.ts
@@ -0,0 +1,33 @@
+import { configure, streamAbort } from './api.js';
+
+const serverUrl = process.argv[2] ?? process.env.SSE_BASE_URL ?? 'http://127.0.0.1:3104';
+
+// Aborting an SSE stream via AbortSignal must terminate the `for await` loop
+// cleanly — the iterator completes and NO AbortError escapes the loop.
+async function main(): Promise<void> {
+  configure({ serverUrl });
+
+  const controller = new AbortController();
+  let received = 0;
+  let error: string | null = null;
+
+  try {
+    for await (const ev of streamAbort({ signal: controller.signal })) {
+      void ev;
+      received++;
+      // Abort mid-stream, after the first event, while the server holds open.
+      if (received === 1) {
+        setTimeout(() => controller.abort(), 50);
+      }
+    }
+  } catch (e) {
+    error = e instanceof Error ? e.name : String(e);
+  }
+
+  process.stdout.write(JSON.stringify({ aborted: true, received, error }) + '\n');
+}
+
+main().catch((e) => {
+  process.stderr.write(`UNHANDLED: ${e instanceof Error ? e.message : String(e)}\n`);
+  process.exit(1);
+});
diff --git a/tests/e2e/generate-client/sse-consumer/index-connect-retry.ts b/tests/e2e/generate-client/sse-consumer/index-connect-retry.ts
new file mode 100644
index 0000000000..9e4542f47b
--- /dev/null
+++ b/tests/e2e/generate-client/sse-consumer/index-connect-retry.ts
@@ -0,0 +1,34 @@
+import { configure, streamMessages } from './api.js';
+
+// No real server: inject a `fetch` that fails the first attempt with a transport-style
+// error (as if the connection were refused/reset while opening the request), then
+// succeeds. The runtime's sse generator must treat a send failure as a dropped
+// connection and reconnect — not rethrow on the first error.
+let calls = 0;
+configure({
+  fetch: (async () => {
+    calls++;
+    if (calls === 1) throw new TypeError('simulated connection failure');
+    const body = new ReadableStream({
+      start(c) {
+        c.enqueue(new TextEncoder().encode('id: 1\ndata: {"text":"a","seq":1}\n\n'));
+        c.close();
+      },
+    });
+    return new Response(body, { status: 200, headers: { 'content-type': 'text/event-stream' } });
+  }) as unknown as typeof fetch,
+});
+
+async function main(): Promise<void> {
+  const events: string[] = [];
+  // Tiny reconnect backoff so the test doesn't wait on the 1s default.
+  for await (const ev of streamMessages({ reconnectDelay: 1 })) {
+    events.push(ev.data.text);
+  }
+  process.stdout.write(JSON.stringify({ calls, events, finished: true }) + '\n');
+}
+
+main().catch((error) => {
+  process.stderr.write(`UNHANDLED: ${error instanceof Error ? error.message : String(error)}\n`);
+  process.exit(1);
+});
diff --git a/tests/e2e/generate-client/sse-consumer/index-finite.ts b/tests/e2e/generate-client/sse-consumer/index-finite.ts
new file mode 100644
index 0000000000..eb635ec5d3
--- /dev/null
+++ b/tests/e2e/generate-client/sse-consumer/index-finite.ts
@@ -0,0 +1,30 @@
+import { configure, streamMessages } from './api.js';
+
+const serverUrl = process.argv[2] ?? process.env.SSE_BASE_URL ?? 'http://127.0.0.1:3104';
+
+// Iterate to natural completion — no `break`. The server drops the first connection
+// (client reconnects via Last-Event-ID), then delivers the final frame WITHOUT a
+// trailing delimiter and closes cleanly. Reaching the end of the `for await` proves
+// two things: the final dangling frame was flushed, and a clean close finished the
+// stream instead of looping forever on reconnect.
+async function main(): Promise<void> {
+  configure({ serverUrl });
+
+  const collected: Array<{ text: string; id: string | undefined }> = [];
+  for await (const ev of streamMessages()) {
+    collected.push({ text: ev.data.text, id: ev.id });
+  }
+
+  process.stdout.write(
+    JSON.stringify({
+      events: collected.map((e) => e.text),
+      ids: collected.map((e) => e.id),
+      finished: true,
+    }) + '\n'
+  );
+}
+
+main().catch((error) => {
+  process.stderr.write(`UNHANDLED: ${error instanceof Error ? error.message : String(error)}\n`);
+  process.exit(1);
+});
diff --git a/tests/e2e/generate-client/sse-consumer/index.ts b/tests/e2e/generate-client/sse-consumer/index.ts
new file mode 100644
index 0000000000..bf515d5658
--- /dev/null
+++ b/tests/e2e/generate-client/sse-consumer/index.ts
@@ -0,0 +1,37 @@
+import { configure, streamMessages } from './api.js';
+
+const serverUrl = process.argv[2] ?? process.env.SSE_BASE_URL ?? 'http://127.0.0.1:3104';
+
+type Collected = { text: string; id: string | undefined };
+
+async function main(): Promise<void> {
+  configure({ serverUrl });
+
+  // Collect events across an auto-reconnect: the server drops after `b`, the
+  // client resumes with `Last-Event-ID: 2` and receives `c`. `ev.data` is the
+  // typed `Message`, so `ev.data.text` is statically a string.
+  const collected: Collected[] = [];
+  for await (const ev of streamMessages()) {
+    collected.push({ text: ev.data.text, id: ev.id });
+    if (collected.length >= 3) break;
+  }
+
+  const logResponse = await fetch(`${serverUrl}/__test__/log`);
+  const log = (await logResponse.json()) as Array<{ path: string; lastEventId: string | null }>;
+  const lastEventIds = log
+    .filter((entry) => entry.path === '/messages')
+    .map((entry) => entry.lastEventId);
+
+  process.stdout.write(
+    JSON.stringify({
+      events: collected.map((e) => e.text),
+      ids: collected.map((e) => e.id),
+      lastEventIds,
+    }) + '\n'
+  );
+}
+
+main().catch((error) => {
+  process.stderr.write(`UNHANDLED: ${error instanceof Error ? error.message : String(error)}\n`);
+  process.exit(1);
+});
diff --git a/tests/e2e/generate-client/sse-consumer/package.json b/tests/e2e/generate-client/sse-consumer/package.json
new file mode 100644
index 0000000000..494edc26ba
--- /dev/null
+++ b/tests/e2e/generate-client/sse-consumer/package.json
@@ -0,0 +1,6 @@
+{
+  "name": "sse-consumer",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module"
+}
diff --git a/tests/e2e/generate-client/sse-consumer/server.ts b/tests/e2e/generate-client/sse-consumer/server.ts
new file mode 100644
index 0000000000..144d07c2f9
--- /dev/null
+++ b/tests/e2e/generate-client/sse-consumer/server.ts
@@ -0,0 +1,93 @@
+import * as http from 'node:http';
+
+// A hand-written SSE server. The generated client streams frames; we drop the
+// first connection mid-stream (to exercise auto-reconnect via Last-Event-ID) and
+// keep a long-lived stream open for the abort scenario. Each connection records
+// the `Last-Event-ID` header it received (or null) so the test can assert resume.
+
+type LogEntry = { path: string; lastEventId: string | null };
+
+const PORT = Number.parseInt(process.env.SSE_SERVER_PORT ?? '3104', 10);
+
+const requestLog: LogEntry[] = [];
+
+function writeFrame(res: http.ServerResponse, frame: string): void {
+  res.write(frame);
+}
+
+const server = http.createServer((req, res) => {
+  const url = req.url ?? '';
+  const { pathname } = new URL(url, 'http://localhost');
+
+  if (pathname === '/__test__/ready') {
+    res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' });
+    res.end('ready');
+    return;
+  }
+  if (pathname === '/__test__/log') {
+    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+    res.end(JSON.stringify(requestLog));
+    return;
+  }
+
+  const lastEventId =
+    typeof req.headers['last-event-id'] === 'string' ? req.headers['last-event-id'] : null;
+  requestLog.push({ path: pathname, lastEventId });
+
+  // The reconnect stream: drop after two frames, then resume from `Last-Event-ID: 2`.
+  if (pathname === '/messages') {
+    res.writeHead(200, {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      Connection: 'keep-alive',
+    });
+    if (lastEventId === '2') {
+      // Reconnect: deliver the final frame WITHOUT a trailing delimiter, then close
+      // cleanly. The client must flush this dangling frame on stream end (final frame
+      // not dropped) and then finish — a clean close is not a dropped connection.
+      writeFrame(res, 'id: 3\ndata: {"text":"c","seq":3}');
+      res.end();
+      return;
+    }
+    // First connect: deliver two frames then abruptly destroy the socket (no chunked
+    // terminator) to simulate a real drop. The client's reader throws → it reconnects
+    // via Last-Event-ID. (A clean res.end() here would instead finish, not reconnect.)
+    writeFrame(res, 'id: 1\nevent: msg\ndata: {"text":"a","seq":1}\n\n');
+    writeFrame(res, 'id: 2\ndata: {"text":"b","seq":2}\n\n');
+    setTimeout(() => res.destroy(), 100);
+    return;
+  }
+
+  // The abort stream: emit one frame, then hold the connection open so the
+  // client can abort mid-stream.
+  if (pathname === '/abort-messages') {
+    res.writeHead(200, {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      Connection: 'keep-alive',
+    });
+    writeFrame(res, 'id: 1\ndata: {"text":"a","seq":1}\n\n');
+    // Hold open: a periodic comment keeps the stream alive without new events.
+    const keepAlive = setInterval(() => {
+      res.write(': keep-alive\n\n');
+    }, 200);
+    res.on('close', () => clearInterval(keepAlive));
+    return;
+  }
+
+  res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
+  res.end('not found');
+});
+
+server.listen(PORT, () => {
+  process.stdout.write(`READY ${PORT}\n`);
+});
+
+const shutdown = (): void => {
+  server.close(() => {
+    process.exit(0);
+  });
+};
+
+process.on('SIGTERM', shutdown);
+process.on('SIGINT', shutdown);
diff --git a/tests/e2e/generate-client/sse-consumer/tsconfig.json b/tests/e2e/generate-client/sse-consumer/tsconfig.json
new file mode 100644
index 0000000000..3e2badaaea
--- /dev/null
+++ b/tests/e2e/generate-client/sse-consumer/tsconfig.json
@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "target": "es2022",
+    "lib": ["ES2022", "DOM"],
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "types": ["node"]
+  },
+  "include": ["./**/*.ts"]
+}
diff --git a/tests/e2e/generate-client/sse.runtime.test.ts b/tests/e2e/generate-client/sse.runtime.test.ts
new file mode 100644
index 0000000000..76740f60ae
--- /dev/null
+++ b/tests/e2e/generate-client/sse.runtime.test.ts
@@ -0,0 +1,159 @@
+// Behavioral e2e for SSE: a hand-written `node:http` server streams real
+// `text/event-stream` frames, drops mid-stream, and the generated client
+// auto-reconnects (resuming via `Last-Event-ID`). A second scenario aborts the
+// stream mid-flight and asserts the loop completes WITHOUT throwing.
+import { spawnSync, type ChildProcess } from 'node:child_process';
+import { existsSync, rmSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { generate, killServer, repoRoot, startServer } from './helpers.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const fixture = join(__dirname, 'fixtures/sse.yaml');
+const consumerDir = join(__dirname, 'sse-consumer');
+const generatedFile = join(consumerDir, 'api.ts');
+const serverScript = join(consumerDir, 'server.ts');
+const indexScript = join(consumerDir, 'index.ts');
+const abortScript = join(consumerDir, 'index-abort.ts');
+const finiteScript = join(consumerDir, 'index-finite.ts');
+const connectRetryScript = join(consumerDir, 'index-connect-retry.ts');
+
+const SERVER_PORT = 3104;
+const SERVER_BASE = `http://127.0.0.1:${SERVER_PORT}`;
+
+describe('generate-client SSE consumer (reconnect + abort)', () => {
+  let serverProcess: ChildProcess | undefined;
+
+  beforeAll(async () => {
+    if (existsSync(generatedFile)) {
+      rmSync(generatedFile, { force: true });
+    }
+
+    generate(fixture, generatedFile);
+    expect(existsSync(generatedFile)).toBe(true);
+
+    // The consumer dir is excluded from the root typecheck (api.ts is gitignored),
+    // so type-check it here against the fresh generation.
+    const typecheckResult = spawnSync('npx', ['tsc', '--noEmit', '-p', consumerDir], {
+      encoding: 'utf-8',
+      cwd: repoRoot,
+    });
+    expect(
+      typecheckResult.status,
+      `tsc stdout:\n${typecheckResult.stdout}\nstderr:\n${typecheckResult.stderr}`
+    ).toBe(0);
+
+    serverProcess = await startServer(
+      serverScript,
+      consumerDir,
+      { SSE_SERVER_PORT: String(SERVER_PORT) },
+      SERVER_BASE,
+      'sse-server'
+    );
+  }, 30_000);
+
+  afterAll(async () => {
+    if (serverProcess) {
+      await killServer(serverProcess);
+    }
+  });
+
+  test('reconnect: events stream across a dropped connection, resuming via Last-Event-ID', () => {
+    const runResult = spawnSync('npx', ['tsx', indexScript, SERVER_BASE], {
+      encoding: 'utf-8',
+      cwd: consumerDir,
+      timeout: 20_000,
+    });
+    expect(
+      runResult.status,
+      `consumer stdout:\n${runResult.stdout}\nstderr:\n${runResult.stderr}`
+    ).toBe(0);
+
+    const parsed = JSON.parse(runResult.stdout.trim()) as {
+      events: string[];
+      ids: Array<string | undefined>;
+      lastEventIds: Array<string | null>;
+    };
+
+    // Typed `data.text` parsed across a reconnect: a, b (first connection), c (resume).
+    expect(parsed.events).toEqual(['a', 'b', 'c']);
+    // Event ids surfaced on the typed event.
+    expect(parsed.ids).toEqual(['1', '2', '3']);
+    // The reconnect carried `Last-Event-ID: 2` (1st connection: none; 2nd: '2').
+    expect(parsed.lastEventIds).toEqual([null, '2']);
+  }, 30_000);
+
+  test('clean close: a finite stream finishes (no endless reconnect) and flushes the final undelimited frame', () => {
+    const runResult = spawnSync('npx', ['tsx', finiteScript, SERVER_BASE], {
+      encoding: 'utf-8',
+      cwd: consumerDir,
+      timeout: 20_000,
+    });
+    expect(
+      runResult.status,
+      `finite consumer stdout:\n${runResult.stdout}\nstderr:\n${runResult.stderr}`
+    ).toBe(0);
+
+    const parsed = JSON.parse(runResult.stdout.trim()) as {
+      events: string[];
+      ids: Array<string | undefined>;
+      finished: boolean;
+    };
+
+    // The loop ran to completion: a clean server close finished the stream rather than
+    // reconnecting forever. `c` was delivered only via the final-frame flush (the third
+    // frame had no trailing delimiter before the server closed).
+    expect(parsed.finished).toBe(true);
+    expect(parsed.events).toEqual(['a', 'b', 'c']);
+    expect(parsed.ids).toEqual(['1', '2', '3']);
+  }, 30_000);
+
+  test('reconnect: a transport failure opening the stream reconnects (not just mid-stream errors)', () => {
+    const runResult = spawnSync('npx', ['tsx', connectRetryScript], {
+      encoding: 'utf-8',
+      cwd: consumerDir,
+      timeout: 20_000,
+    });
+    expect(
+      runResult.status,
+      `connect-retry consumer stdout:\n${runResult.stdout}\nstderr:\n${runResult.stderr}`
+    ).toBe(0);
+
+    const parsed = JSON.parse(runResult.stdout.trim()) as {
+      calls: number;
+      events: string[];
+      finished: boolean;
+    };
+
+    // The first send attempt threw (simulated connection failure); the iterator reconnected
+    // and the second attempt streamed the event, then finished.
+    expect(parsed.calls).toBe(2);
+    expect(parsed.events).toEqual(['a']);
+    expect(parsed.finished).toBe(true);
+  }, 30_000);
+
+  test('abort: aborting the stream via AbortSignal completes the loop without throwing', () => {
+    const runResult = spawnSync('npx', ['tsx', abortScript, SERVER_BASE], {
+      encoding: 'utf-8',
+      cwd: consumerDir,
+      timeout: 20_000,
+    });
+    expect(
+      runResult.status,
+      `abort consumer stdout:\n${runResult.stdout}\nstderr:\n${runResult.stderr}`
+    ).toBe(0);
+
+    const parsed = JSON.parse(runResult.stdout.trim()) as {
+      aborted: boolean;
+      received: number;
+      error: string | null;
+    };
+
+    // The loop saw the first event, then the abort terminated it cleanly: no
+    // AbortError escaped the `for await`.
+    expect(parsed.aborted).toBe(true);
+    expect(parsed.received).toBeGreaterThanOrEqual(1);
+    expect(parsed.error).toBeNull();
+  }, 30_000);
+});
diff --git a/tests/e2e/generate-client/sse.test.ts b/tests/e2e/generate-client/sse.test.ts
new file mode 100644
index 0000000000..367dfa2a2d
--- /dev/null
+++ b/tests/e2e/generate-client/sse.test.ts
@@ -0,0 +1,118 @@
+// e2e for SSE (`text/event-stream`) operations: the typed flat async-iterator
+// surface (`for await (const ev of streamMessages())`). We assert on the generated
+// source (string checks) and strict-tsc the output (single-file, plus the split
+// two-file set) — the same lightweight harness used by error-mode.test.ts. The
+// behavioral reconnect/abort path is covered separately by the sse-consumer
+// harness in sse.runtime.test.ts.
+import { spawnSync } from 'node:child_process';
+import {
+  existsSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { generate, strictTypecheck, tscBin } from './helpers.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/** Recursively collect every generated `.ts` file under `dir`. */
+function collectTsFiles(dir: string): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) out.push(...collectTsFiles(full));
+    else if (entry.endsWith('.ts')) out.push(full);
+  }
+  return out;
+}
+
+const fixture = join(__dirname, 'fixtures', 'sse.yaml');
+
+describe('generate-client SSE', () => {
+  it('single-file: embedded sse capability + flat typed stream sugar, strict tsc passes', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'ots-sse-single-'));
+    const out = join(dir, 'client.ts');
+    generate(fixture, out);
+    expect(existsSync(out)).toBe(true);
+
+    const generated = readFileSync(out, 'utf-8');
+    // The embedded runtime carries the sse capability generator.
+    expect(generated).toContain('async function* sse<T>(');
+    // Stream operations are typed `kind: "sse"` in Ops and marked in the descriptors.
+    expect(generated).toContain('kind: "sse";');
+    expect(generated).toContain('responseKind: "sse"');
+    // JSON payloads decode as json; the typeless stream falls back to text/string.
+    expect(generated).toContain(
+      'streamMessages: { id: "streamMessages", method: "GET", path: "/messages", tags: ["Messages"], responseKind: "sse", sseDataKind: "json" }'
+    );
+    expect(generated).toContain(
+      'streamTicks: { id: "streamTicks", method: "GET", path: "/ticks", tags: ["Ticks"], responseKind: "sse", sseDataKind: "text" }'
+    );
+    expect(generated).toMatch(/streamTicks: \{\s*args: \{\};\s*result: string;\s*kind: "sse";/);
+    // Flat call sugar: an SSE op is a top-level export returning the async generator.
+    expect(generated).toContain(
+      'export const streamMessages = (init: SseOptions = {}) => client.streamMessages({}, init);'
+    );
+
+    // A type-usage snippet proving `ServerSentEvent<Message>.data.text` is typed
+    // and that `SseOptions` (reconnect/reconnectDelay) is accepted.
+    writeFileSync(
+      join(dir, 'usage.ts'),
+      [
+        `import { streamMessages, configure } from './client.js';`,
+        `async function check() {`,
+        `  for await (const ev of streamMessages()) { const t: string = ev.data.text; void t; const id: string | undefined = ev.id; void id; }`,
+        `  const it = streamMessages({ reconnect: false, reconnectDelay: 500 });`,
+        `  void it;`,
+        `}`,
+        `void check; void configure;`,
+        ``,
+      ].join('\n'),
+      'utf-8'
+    );
+
+    strictTypecheck(dir, ['client.ts', 'usage.ts']);
+    rmSync(dir, { recursive: true, force: true });
+  }, 60_000);
+
+  it('split: SSE ops live in the entry beside the embedded runtime, strict tsc passes over both files', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'ots-sse-split-'));
+    const entry = join(dir, 'client.ts');
+    generate(fixture, entry, ['--output-mode', 'split']);
+    expect(existsSync(entry)).toBe(true);
+
+    const entrySrc = readFileSync(entry, 'utf-8');
+    expect(entrySrc).toContain('async function* sse<T>(');
+    expect(entrySrc).toContain('export const streamMessages = (init: SseOptions = {})');
+
+    const files = collectTsFiles(dir);
+    expect(files.map((f) => f.split('/').pop()).sort()).toEqual(['client.schemas.ts', 'client.ts']);
+    const tsc = spawnSync(
+      tscBin,
+      [
+        '--noEmit',
+        '--strict',
+        '--noUnusedLocals',
+        '--target',
+        'ES2020',
+        '--module',
+        'esnext',
+        '--moduleResolution',
+        'bundler',
+        '--lib',
+        'ES2020,DOM',
+        ...files,
+      ],
+      { encoding: 'utf-8', cwd: dir }
+    );
+    expect(tsc.status, `tsc failed:\n${tsc.stdout}\n${tsc.stderr}`).toBe(0);
+    rmSync(dir, { recursive: true, force: true });
+  }, 60_000);
+});
diff --git a/tests/e2e/generate-client/swr.test.ts b/tests/e2e/generate-client/swr.test.ts
new file mode 100644
index 0000000000..3790d53a3a
--- /dev/null
+++ b/tests/e2e/generate-client/swr.test.ts
@@ -0,0 +1,71 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { generate, repoRoot, tscBin } from './helpers.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// `swr` is hoisted to the repo root node_modules (a repo devDependency); map it
+// explicitly so tsc resolves the generated module's `import useSWR from "swr"` and
+// `import useSWRMutation from "swr/mutation"` from the temp dir.
+const swrPath = join(repoRoot, 'node_modules/swr');
+
+describe('generate-client swr generator', () => {
+  it('emits a *.swr.ts module that strict-tsc-checks against real swr and composes with the sdk', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'ots-swr-'));
+    const out = join(dir, 'client.ts');
+    const swrOut = join(dir, 'client.swr.ts');
+
+    generate(join(__dirname, 'fixtures', 'base.yaml'), out, [
+      '--generator',
+      'sdk',
+      '--generator',
+      'swr',
+    ]);
+
+    // Both the sdk client and the standalone swr module are produced.
+    expect(existsSync(out)).toBe(true);
+    expect(existsSync(swrOut)).toBe(true);
+
+    const source = readFileSync(swrOut, 'utf-8');
+    expect(source).toContain('import useSWR from "swr"');
+    expect(source).toContain('import useSWRMutation from "swr/mutation"');
+    // A GET op (path param) → key factory + useSWR hook.
+    expect(source).toContain('export const getPetByIdKey');
+    expect(source).toContain('export function useGetPetById');
+    expect(source).toContain('useSWR(');
+    // A POST op → useSWRMutation hook.
+    expect(source).toContain('export function useCreatePet');
+    expect(source).toContain('useSWRMutation(');
+
+    // strict-tsc the whole temp project: the emitted swr module against REAL swr,
+    // plus the generated sdk client. The hooks are React hooks; type-checking the
+    // module proves the emitted useSWR/useSWRMutation calls match swr's real API.
+    writeFileSync(
+      join(dir, 'tsconfig.json'),
+      JSON.stringify({
+        compilerOptions: {
+          module: 'nodenext',
+          moduleResolution: 'nodenext',
+          target: 'es2022',
+          lib: ['ES2022', 'DOM'],
+          strict: true,
+          noEmit: true,
+          skipLibCheck: true,
+          jsx: 'react-jsx',
+          types: [],
+          paths: { swr: [swrPath], 'swr/*': [join(swrPath, '*')] },
+        },
+        include: ['client.ts', 'client.swr.ts'],
+      }),
+      'utf-8'
+    );
+
+    const tsc = spawnSync(tscBin, ['--noEmit', '-p', dir], { encoding: 'utf-8', cwd: repoRoot });
+    expect(tsc.status, `tsc failed:\n${tsc.stdout}\n${tsc.stderr}`).toBe(0);
+
+    rmSync(dir, { recursive: true, force: true });
+  }, 60_000);
+});
diff --git a/tests/e2e/generate-client/tanstack-consumer/.gitignore b/tests/e2e/generate-client/tanstack-consumer/.gitignore
new file mode 100644
index 0000000000..1d171661f2
--- /dev/null
+++ b/tests/e2e/generate-client/tanstack-consumer/.gitignore
@@ -0,0 +1,3 @@
+# Generated fresh by tanstack-query.runtime.test.ts in beforeAll and removed in afterAll.
+client.ts
+client.tanstack.ts
diff --git a/tests/e2e/generate-client/tanstack-query.runtime.test.ts b/tests/e2e/generate-client/tanstack-query.runtime.test.ts
new file mode 100644
index 0000000000..befc7b3d43
--- /dev/null
+++ b/tests/e2e/generate-client/tanstack-query.runtime.test.ts
@@ -0,0 +1,118 @@
+/** @vitest-environment jsdom */
+//
+// Tier-3 runtime React-hook integration for the tanstack-query generator.
+//
+// MECHANISM (documented choice): we generate `sdk,tanstack-query` into a fixed,
+// checked-in consumer dir (`tanstack-consumer/`) and dynamic-`import()` the
+// generated `client.tanstack.ts` directly — vite transforms it and resolves its
+// `./client.js` import to the sibling `.ts` reliably (verified). The data is
+// driven by a STUBBED `fetch` installed via the generated sdk's `configure()`
+// (no mock server): the tanstack `queryFn` forwards to the sdk operation
+// function, which uses that fetch. This proves the real React render path —
+// `renderHook` + `QueryClientProvider` + `useQuery(getXOptions(vars))` — fires
+// the queryFn and resolves the hook with the canned data, without mock-server
+// flakiness or cross-process plumbing.
+
+import { QueryClient, QueryClientProvider, useMutation, useQuery } from '@tanstack/react-query';
+import { renderHook, waitFor } from '@testing-library/react';
+import { existsSync, rmSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createElement, type ReactNode } from 'react';
+
+import { generate } from './helpers.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const consumerDir = join(__dirname, 'tanstack-consumer');
+const sdkFile = join(consumerDir, 'client.ts');
+const tanstackFile = join(consumerDir, 'client.tanstack.ts');
+
+const PET = { id: 1, name: 'rex', status: 'available' as const };
+
+function wrapper(client: QueryClient) {
+  return ({ children }: { children: ReactNode }) =>
+    createElement(QueryClientProvider, { client }, children);
+}
+
+function newClient(): QueryClient {
+  // Retries off so a query/mutation settles deterministically within the test.
+  return new QueryClient({
+    defaultOptions: { queries: { retry: false }, mutations: { retry: false } },
+  });
+}
+
+describe('generate-client tanstack-query runtime (React hooks, jsdom)', () => {
+  beforeAll(() => {
+    for (const f of [sdkFile, tanstackFile]) {
+      if (existsSync(f)) rmSync(f, { force: true });
+    }
+    generate(join(__dirname, 'fixtures', 'base.yaml'), sdkFile, [
+      '--generator',
+      'sdk',
+      '--generator',
+      'tanstack-query',
+    ]);
+    expect(existsSync(tanstackFile)).toBe(true);
+  });
+
+  afterAll(() => {
+    for (const f of [sdkFile, tanstackFile]) {
+      if (existsSync(f)) rmSync(f, { force: true });
+    }
+  });
+
+  it('useQuery(getPetByIdOptions(vars)) fires the queryFn and resolves with the response data', async () => {
+    const sdk = await import(join(consumerDir, 'client.ts'));
+    const mod = await import(join(consumerDir, 'client.tanstack.ts'));
+
+    sdk.configure({
+      fetch: (input: RequestInfo | URL) => {
+        // The sdk built the URL from the path param; assert the queryFn forwarded it.
+        expect(String(input)).toContain('/pets/1');
+        return Promise.resolve(
+          new Response(JSON.stringify(PET), {
+            status: 200,
+            headers: { 'Content-Type': 'application/json' },
+          })
+        );
+      },
+    });
+
+    const { result } = renderHook(() => useQuery(mod.getPetByIdOptions({ id: 1 })), {
+      wrapper: wrapper(newClient()),
+    });
+
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+    expect(result.current.data).toEqual(PET);
+  }, 30_000);
+
+  it('useMutation(createPetMutation()) fires the mutationFn and resolves with the created resource', async () => {
+    const sdk = await import(join(consumerDir, 'client.ts'));
+    const mod = await import(join(consumerDir, 'client.tanstack.ts'));
+
+    sdk.configure({
+      fetch: (input: RequestInfo | URL, init?: RequestInit) => {
+        expect(init?.method).toBe('POST');
+        return Promise.resolve(
+          new Response(JSON.stringify(PET), {
+            status: 201,
+            headers: { 'Content-Type': 'application/json' },
+          })
+        );
+      },
+    });
+
+    const { result } = renderHook(
+      () =>
+        useMutation<unknown, Error, { body: { name: string; status: string } }>(
+          mod.createPetMutation()
+        ),
+      { wrapper: wrapper(newClient()) }
+    );
+
+    const created = await result.current.mutateAsync({
+      body: { name: 'rex', status: 'available' },
+    });
+    expect(created).toEqual(PET);
+  }, 30_000);
+});
diff --git a/tests/e2e/generate-client/tanstack-query.test.ts b/tests/e2e/generate-client/tanstack-query.test.ts
new file mode 100644
index 0000000000..ec98ee5153
--- /dev/null
+++ b/tests/e2e/generate-client/tanstack-query.test.ts
@@ -0,0 +1,194 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { generate, repoRoot, tscBin } from './helpers.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// `@tanstack/react-query` is hoisted to the repo root node_modules (a repo
+// devDependency); map it explicitly so tsc resolves the generated module's
+// `import { queryOptions } from "@tanstack/react-query"` from the temp dir.
+const tanstackPath = join(repoRoot, 'node_modules/@tanstack/react-query');
+// The package-runtime case resolves the sdk's `@redocly/client-generator` import against the
+// BUILT package types (the temp project lives outside the workspace, so no node_modules walk).
+const generatorTypes = join(repoRoot, 'packages/client-generator/lib/index.d.ts');
+
+describe('generate-client tanstack-query generator', () => {
+  it('emits a *.tanstack.ts module that strict-tsc-checks against real @tanstack/react-query and composes with the sdk', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'ots-tanstack-'));
+    const out = join(dir, 'client.ts');
+    const tanstackOut = join(dir, 'client.tanstack.ts');
+
+    generate(join(__dirname, 'fixtures', 'base.yaml'), out, [
+      '--generator',
+      'sdk',
+      '--generator',
+      'tanstack-query',
+    ]);
+
+    // Both the sdk client and the standalone tanstack module are produced.
+    expect(existsSync(out)).toBe(true);
+    expect(existsSync(tanstackOut)).toBe(true);
+
+    const source = readFileSync(tanstackOut, 'utf-8');
+    expect(source).toContain('import { queryOptions } from "@tanstack/react-query"');
+    // A GET op (path param) → query factories.
+    expect(source).toContain('export const getPetByIdQueryKey');
+    expect(source).toContain('export const getPetByIdOptions');
+    expect(source).toContain('queryOptions({');
+    // A POST op → mutation factory.
+    expect(source).toContain('export const createPetMutation');
+    expect(source).toContain('mutationFn:');
+
+    // A consumer that composes the generated factories with TanStack's real
+    // useQuery/useMutation types — proves the emitted hooks type-check against
+    // the actual @tanstack/react-query API surface, not just in isolation.
+    writeFileSync(
+      join(dir, 'check.ts'),
+      [
+        "import { useMutation, useQuery } from '@tanstack/react-query';",
+        "import { createPetMutation, getPetByIdOptions, listPetsOptions } from './client.tanstack.js';",
+        'export function useGetPet(id: number) {',
+        '  return useQuery(getPetByIdOptions({ id }));',
+        '}',
+        'export function useListPets() {',
+        "  return useQuery(listPetsOptions({ params: { filter: { name: 'rex' } } }));",
+        '}',
+        'export function useCreatePet() {',
+        '  return useMutation(createPetMutation());',
+        '}',
+        '',
+      ].join('\n'),
+      'utf-8'
+    );
+
+    // strict-tsc the whole temp project: the emitted tanstack module against
+    // REAL @tanstack/react-query, plus the useQuery/useMutation composition.
+    writeFileSync(
+      join(dir, 'tsconfig.json'),
+      JSON.stringify({
+        compilerOptions: {
+          module: 'nodenext',
+          moduleResolution: 'nodenext',
+          target: 'es2022',
+          lib: ['ES2022', 'DOM'],
+          strict: true,
+          noEmit: true,
+          skipLibCheck: true,
+          types: [],
+          paths: { '@tanstack/react-query': [tanstackPath] },
+        },
+        include: ['client.ts', 'client.tanstack.ts', 'check.ts'],
+      }),
+      'utf-8'
+    );
+
+    const tsc = spawnSync(tscBin, ['--noEmit', '-p', dir], { encoding: 'utf-8', cwd: repoRoot });
+    expect(tsc.status, `tsc failed:\n${tsc.stdout}\n${tsc.stderr}`).toBe(0);
+
+    rmSync(dir, { recursive: true, force: true });
+  }, 60_000);
+
+  it('--runtime package: the tanstack wrapper composes with the package-runtime sdk and strict-tsc-checks', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'ots-tanstack-pkg-'));
+    const out = join(dir, 'client.ts');
+    const tanstackOut = join(dir, 'client.tanstack.ts');
+
+    generate(join(__dirname, 'fixtures', 'base.yaml'), out, [
+      '--runtime',
+      'package',
+      '--generator',
+      'sdk',
+      '--generator',
+      'tanstack-query',
+      '--query-framework',
+      'react',
+    ]);
+
+    // The sdk entry imports the runtime instead of embedding it; the wrapper is unchanged
+    // in shape — it consumes the same free functions + <Op>Variables surface.
+    const sdkSource = readFileSync(out, 'utf-8');
+    expect(sdkSource).toContain("from '@redocly/client-generator'");
+    expect(sdkSource).not.toContain('__send');
+    const source = readFileSync(tanstackOut, 'utf-8');
+    expect(source).toContain('import { queryOptions } from "@tanstack/react-query"');
+    expect(source).toContain('export const getPetByIdOptions');
+    expect(source).toContain('export const createPetMutation');
+
+    // Same composition consumer as the inline case — the runtime choice must be
+    // invisible to wrapper consumers.
+    writeFileSync(
+      join(dir, 'check.ts'),
+      [
+        "import { useMutation, useQuery } from '@tanstack/react-query';",
+        "import { createPetMutation, getPetByIdOptions, listPetsOptions } from './client.tanstack.js';",
+        'export function useGetPet(id: number) {',
+        '  return useQuery(getPetByIdOptions({ id }));',
+        '}',
+        'export function useListPets() {',
+        "  return useQuery(listPetsOptions({ params: { filter: { name: 'rex' } } }));",
+        '}',
+        'export function useCreatePet() {',
+        '  return useMutation(createPetMutation());',
+        '}',
+        '',
+      ].join('\n'),
+      'utf-8'
+    );
+
+    // strict-tsc gate: the wrapper + the package-runtime sdk (resolved against the BUILT
+    // @redocly/client-generator types) + the composition consumer, all in one project.
+    writeFileSync(
+      join(dir, 'tsconfig.json'),
+      JSON.stringify({
+        compilerOptions: {
+          module: 'nodenext',
+          moduleResolution: 'nodenext',
+          target: 'es2022',
+          lib: ['ES2022', 'DOM'],
+          strict: true,
+          noEmit: true,
+          skipLibCheck: true,
+          types: [],
+          paths: {
+            '@tanstack/react-query': [tanstackPath],
+            '@redocly/client-generator': [generatorTypes],
+          },
+        },
+        include: ['client.ts', 'client.tanstack.ts', 'check.ts'],
+      }),
+      'utf-8'
+    );
+
+    const tsc = spawnSync(tscBin, ['--noEmit', '-p', dir], { encoding: 'utf-8', cwd: repoRoot });
+    expect(tsc.status, `tsc failed:\n${tsc.stdout}\n${tsc.stderr}`).toBe(0);
+
+    rmSync(dir, { recursive: true, force: true });
+  }, 60_000);
+
+  it('--query-framework vue swaps only the import specifier to @tanstack/vue-query', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'ots-tanstack-vue-'));
+    const out = join(dir, 'client.ts');
+    const tanstackOut = join(dir, 'client.tanstack.ts');
+
+    generate(join(__dirname, 'fixtures', 'base.yaml'), out, [
+      '--generator',
+      'sdk',
+      '--generator',
+      'tanstack-query',
+      '--query-framework',
+      'vue',
+    ]);
+
+    // No strict-tsc compile here: @tanstack/vue-query isn't a dev dependency, and the
+    // react test already proves the queryOptions output type-checks against a real
+    // adapter — the only per-framework difference is this import string.
+    const source = readFileSync(tanstackOut, 'utf-8');
+    expect(source).toContain('import { queryOptions } from "@tanstack/vue-query"');
+    expect(source).not.toContain('@tanstack/react-query');
+
+    rmSync(dir, { recursive: true, force: true });
+  }, 60_000);
+});
diff --git a/tests/e2e/generate-client/transformers-consumer/.gitignore b/tests/e2e/generate-client/transformers-consumer/.gitignore
new file mode 100644
index 0000000000..7264a69518
--- /dev/null
+++ b/tests/e2e/generate-client/transformers-consumer/.gitignore
@@ -0,0 +1,3 @@
+# Generated fresh by transformers.test.ts in beforeAll and removed in afterAll.
+client.ts
+client.transformers.ts
diff --git a/tests/e2e/generate-client/transformers.test.ts b/tests/e2e/generate-client/transformers.test.ts
new file mode 100644
index 0000000000..5f9b34793c
--- /dev/null
+++ b/tests/e2e/generate-client/transformers.test.ts
@@ -0,0 +1,105 @@
+//
+// e2e for the `transformers` generator paired with the sdk `--date-type Date`
+// knob. Two tiers:
+//
+//  - TYPE-CHECK: generate `sdk,transformers --date-type Date` into a temp dir,
+//    assert the sdk types `Date` for date fields and the transformers module has
+//    `transform<Name>` with `new Date(`, then strict-`tsc` `client.ts` +
+//    `client.transformers.ts` TOGETHER. tsc exit 0 proves each generated
+//    `transform<Name>(data: <Name>): <Name>` type-checks against the Date-typed
+//    sdk schema (incl. the union-ref guarded-cast and the collection write-backs).
+//
+//  - RUNTIME: generate into a fixed, checked-in consumer dir and dynamic-
+//    `import()` the generated `client.transformers.ts` (its only import of
+//    `./client.js` is `import type`, erased at runtime — no sdk needed at
+//    runtime). Call `transformPet` on WIRE data and assert the date positions
+//    became `Date` instances: top-level scalar, array elements, and the ref'd
+//    nested date (proving composition + write-back at runtime).
+//
+//  - DEFAULT UNCHANGED: without `--date-type Date` the sdk date field stays
+//    typed `string` (the byte-identical default).
+
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { generate as generateClient, strictTypecheck } from './helpers.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const fixture = join(__dirname, 'fixtures', 'transformers.yaml');
+const consumerDir = join(__dirname, 'transformers-consumer');
+
+function generate(out: string, args: string[]): void {
+  // args[0] is a comma-separated generator list; the rest are extra flags.
+  const [generators, ...rest] = args;
+  const generatorFlags = generators.split(',').flatMap((g) => ['--generator', g]);
+  generateClient(fixture, out, [...generatorFlags, ...rest]);
+}
+
+describe('generate-client transformers generator', () => {
+  it('emits Date-typed sdk + a transformers module that strict-tsc-checks together', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'ots-transformers-'));
+    const out = join(dir, 'client.ts');
+    const transformersOut = join(dir, 'client.transformers.ts');
+
+    generate(out, ['sdk,transformers', '--date-type', 'Date']);
+
+    expect(existsSync(out)).toBe(true);
+    expect(existsSync(transformersOut)).toBe(true);
+
+    // The sdk emits `Date` (not `string`) for the date-time field under --date-type Date.
+    const sdkSource = readFileSync(out, 'utf-8');
+    expect(sdkSource).toContain('createdAt?: Date;');
+
+    // The transformers module: a type-only import, the transform fn, and `new Date(`.
+    const transformersSource = readFileSync(transformersOut, 'utf-8');
+    expect(transformersSource).toContain('import type {');
+    expect(transformersSource).toContain('export const transformPet');
+    expect(transformersSource).toContain('new Date(');
+
+    // strict-tsc the sdk + transformers TOGETHER: proves transform<Name>(data:
+    // <Name>): <Name> type-checks against the Date-typed sdk schema.
+    strictTypecheck(dir, ['client.ts', 'client.transformers.ts']);
+
+    rmSync(dir, { recursive: true, force: true });
+  }, 60_000);
+
+  it('transformPet converts top-level, array, and ref nested dates at runtime', async () => {
+    const sdkFile = join(consumerDir, 'client.ts');
+    const transformersFile = join(consumerDir, 'client.transformers.ts');
+    for (const f of [sdkFile, transformersFile]) if (existsSync(f)) rmSync(f, { force: true });
+
+    generate(sdkFile, ['sdk,transformers', '--date-type', 'Date']);
+    expect(existsSync(transformersFile)).toBe(true);
+
+    const mod = await import(transformersFile);
+
+    const result = mod.transformPet({
+      id: 1,
+      name: 'rex',
+      createdAt: '2020-01-02T03:04:05Z',
+      dates: ['2021-01-01T00:00:00Z', '2022-02-02T00:00:00Z'],
+      owner: { name: 'sam', since: '2019-06-01' },
+    });
+
+    // Top-level scalar.
+    expect(result.createdAt).toBeInstanceOf(Date);
+    expect((result.createdAt as Date).toISOString()).toBe('2020-01-02T03:04:05.000Z');
+    // Array elements (write-back via map).
+    expect(Array.isArray(result.dates)).toBe(true);
+    for (const d of result.dates) expect(d).toBeInstanceOf(Date);
+    // Ref'd nested date (composition: transformPet -> transformOwner).
+    expect(result.owner.since).toBeInstanceOf(Date);
+
+    for (const f of [sdkFile, transformersFile]) if (existsSync(f)) rmSync(f, { force: true });
+  }, 60_000);
+
+  it('without --date-type Date the sdk date field stays typed string (default)', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'ots-transformers-default-'));
+    const out = join(dir, 'client.ts');
+    generate(out, ['sdk']);
+    expect(readFileSync(out, 'utf-8')).toContain('createdAt?: string;');
+    rmSync(dir, { recursive: true, force: true });
+  }, 60_000);
+});
diff --git a/tests/e2e/generate-client/zod.test.ts b/tests/e2e/generate-client/zod.test.ts
new file mode 100644
index 0000000000..321ca66db5
--- /dev/null
+++ b/tests/e2e/generate-client/zod.test.ts
@@ -0,0 +1,250 @@
+import { spawnSync } from 'node:child_process';
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { outdent } from 'outdent';
+
+import { generate, repoRoot, tscBin } from './helpers.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// `zod` is hoisted to the repo root node_modules (a repo devDependency); map it
+// explicitly so tsc resolves `import { z } from 'zod'` from the out-of-tree temp dir.
+const zodPath = join(repoRoot, 'node_modules/zod');
+
+describe('generate-client zod generator', () => {
+  it('emits a *.zod.ts module that strict-tsc-checks against real zod and agrees with the sdk types', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'ots-zod-'));
+    const out = join(dir, 'client.ts');
+    const zodOut = join(dir, 'client.zod.ts');
+
+    generate(join(__dirname, 'fixtures', 'cafe.yaml'), out, [
+      '--generator',
+      'sdk',
+      '--generator',
+      'zod',
+    ]);
+
+    // Both the sdk client and the standalone zod module are produced.
+    expect(existsSync(out)).toBe(true);
+    expect(existsSync(zodOut)).toBe(true);
+
+    const zodSource = readFileSync(zodOut, 'utf-8');
+    expect(zodSource).toContain('import { z } from "zod"');
+    expect(zodSource).toContain('export const PageSchema = z.object(');
+
+    // z.infer<typeof PageSchema> must be assignable to the sdk's Page type
+    // (schema ↔ type agreement). For `Page` (all-required scalars) the
+    // assignability is in fact bidirectional; we assert the z.infer → sdk
+    // direction, which is the one the schema is expected to guarantee.
+    writeFileSync(
+      join(dir, 'check.ts'),
+      [
+        "import type { z } from 'zod';",
+        "import type { Page } from './client.js';",
+        "import type { PageSchema } from './client.zod.js';",
+        'const _x: Page = {} as z.infer<typeof PageSchema>;',
+        'void _x;',
+        '',
+      ].join('\n'),
+      'utf-8'
+    );
+
+    // strict-tsc the whole temp project: the emitted zod module against REAL
+    // zod, plus the schema ↔ type agreement check.
+    writeFileSync(
+      join(dir, 'tsconfig.json'),
+      JSON.stringify({
+        compilerOptions: {
+          module: 'nodenext',
+          moduleResolution: 'nodenext',
+          target: 'es2022',
+          lib: ['ES2022', 'DOM'],
+          strict: true,
+          noEmit: true,
+          skipLibCheck: true,
+          types: [],
+          paths: { zod: [zodPath] },
+        },
+        include: ['client.ts', 'client.zod.ts', 'check.ts'],
+      }),
+      'utf-8'
+    );
+
+    const tsc = spawnSync(tscBin, ['--noEmit', '-p', dir], { encoding: 'utf-8', cwd: repoRoot });
+    expect(tsc.status, `tsc failed:\n${tsc.stdout}\n${tsc.stderr}`).toBe(0);
+
+    rmSync(dir, { recursive: true, force: true });
+  }, 60_000);
+
+  it('zodValidation middleware validates requests before the wire and JSON responses after it', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'ots-zod-run-'));
+    writeFileSync(join(dir, 'package.json'), '{"name":"zod-run","private":true,"type":"module"}\n');
+    mkdirSync(join(dir, 'node_modules'), { recursive: true });
+    symlinkSync(zodPath, join(dir, 'node_modules/zod'));
+    writeFileSync(
+      join(dir, 'openapi.yaml'),
+      outdent`
+        openapi: 3.0.3
+        info: { title: test, version: 1.0.0 }
+        paths:
+          /orders:
+            post:
+              operationId: createOrder
+              requestBody:
+                required: true
+                content:
+                  application/json:
+                    schema:
+                      $ref: '#/components/schemas/OrderInput'
+              responses:
+                '200':
+                  description: ok
+                  content:
+                    application/json:
+                      schema:
+                        type: object
+                        required: [id]
+                        properties:
+                          id: { type: string }
+          /health:
+            get:
+              operationId: health
+              responses:
+                '204': { description: no content }
+        components:
+          schemas:
+            OrderBase:
+              type: object
+              properties:
+                id: { type: string, readOnly: true }
+            OrderInput:
+              # allOf with a readOnly field: the derived request schema must distribute
+              # the omission into the intersection members (ZodIntersection has no .omit).
+              allOf:
+                - $ref: '#/components/schemas/OrderBase'
+                - type: object
+                  required: [name, quantity]
+                  properties:
+                    name: { type: string }
+                    quantity: { type: integer, minimum: 1 }
+      `
+    );
+    generate(join(dir, 'openapi.yaml'), join(dir, 'client.ts'), [
+      '--generator',
+      'sdk',
+      '--generator',
+      'zod',
+    ]);
+
+    writeFileSync(
+      join(dir, 'driver.ts'),
+      outdent`
+        import { client, configure, use } from './client.js';
+        import { operationSchemas, zodValidation, ZodValidationError } from './client.zod.js';
+
+        const results: string[] = [];
+        let fetchCalls = 0;
+        let nextBody = '{"id":"o1"}';
+        let nextStatus = 200;
+        configure({
+          serverUrl: 'https://api.example.com',
+          fetch: async () => {
+            fetchCalls++;
+            return new Response(nextStatus === 204 ? null : nextBody, {
+              status: nextStatus,
+              headers: nextStatus === 204 ? {} : { 'content-type': 'application/json' },
+            });
+          },
+        });
+
+        async function main() {
+          // Direct schema access: the map is importable on its own.
+          operationSchemas.createOrder.request.parse({ name: 'direct', quantity: 2 });
+
+          use(zodValidation({ response: false }));
+
+          // An invalid request throws BEFORE any network call.
+          try {
+            await client.createOrder({ body: { name: 'x', quantity: 0 } });
+            results.push('request-not-validated');
+          } catch (error) {
+            results.push(
+              error instanceof ZodValidationError
+                ? 'request-rejected:' + error.direction + ':calls=' + fetchCalls
+                : 'wrong-error:' + String(error)
+            );
+          }
+
+          // With response validation off, a mismatched response resolves untouched.
+          nextBody = '{"wrong":true}';
+          await client.createOrder({ body: { name: 'x', quantity: 2 } });
+          results.push('response-off-passes');
+
+          // A second middleware turns response validation on; the mismatch now throws.
+          use(zodValidation({ request: false }));
+          try {
+            await client.createOrder({ body: { name: 'x', quantity: 2 } });
+            results.push('response-not-validated');
+          } catch (error) {
+            results.push(
+              error instanceof ZodValidationError
+                ? 'response-rejected:' + error.direction
+                : 'wrong-error:' + String(error)
+            );
+          }
+
+          // A valid round trip passes both directions; a schema-less operation is untouched.
+          nextBody = '{"id":"o2"}';
+          const order = await client.createOrder({ body: { name: 'ok', quantity: 3 } });
+          results.push('valid:' + order.id);
+          nextStatus = 204;
+          await client.health();
+          results.push('schema-less-ok');
+
+          console.log(JSON.stringify(results));
+        }
+        // An unhandled rejection exits non-zero, so a driver failure fails the test.
+        void main();
+      `
+    );
+    writeFileSync(
+      join(dir, 'tsconfig.json'),
+      JSON.stringify({
+        compilerOptions: {
+          module: 'nodenext',
+          moduleResolution: 'nodenext',
+          target: 'es2022',
+          lib: ['ES2022', 'DOM'],
+          strict: true,
+          skipLibCheck: true,
+          types: [],
+          declaration: true,
+        },
+        include: ['client.ts', 'client.zod.ts', 'driver.ts'],
+      }),
+      'utf-8'
+    );
+    const tsc = spawnSync(tscBin, ['-p', dir], { encoding: 'utf-8', cwd: dir });
+    expect(tsc.status, `tsc failed:\n${tsc.stdout}\n${tsc.stderr}`).toBe(0);
+
+    const run = spawnSync('node', ['driver.js'], { cwd: dir, encoding: 'utf-8' });
+    expect(run.status, run.stderr).toBe(0);
+    expect(JSON.parse(run.stdout)).toEqual([
+      'request-rejected:request:calls=0',
+      'response-off-passes',
+      'response-rejected:response',
+      'valid:o2',
+      'schema-less-ok',
+    ]);
+    rmSync(dir, { recursive: true, force: true });
+  }, 60_000);
+});
diff --git a/tests/e2e/respect/local-json-server/local-json-server.test.ts b/tests/e2e/respect/local-json-server/local-json-server.test.ts
index 1f36e20c48..2d397b00c6 100644
--- a/tests/e2e/respect/local-json-server/local-json-server.test.ts
+++ b/tests/e2e/respect/local-json-server/local-json-server.test.ts
@@ -18,7 +18,21 @@ describe('local-json-server', () => {
 
     // Store original state of fake-bd.json
     originalData = fs.readFileSync(dbPath, 'utf8');
-  });
+
+    // Wait until the server actually accepts connections — spawning is not readiness,
+    // and the workflow run starts immediately after (ECONNREFUSED race otherwise).
+    const deadline = Date.now() + 30_000;
+    for (;;) {
+      try {
+        const response = await fetch('http://localhost:3000/items');
+        if (response.ok) break;
+      } catch {
+        // not listening yet
+      }
+      if (Date.now() > deadline) throw new Error('json-server did not become ready within 30s');
+      await new Promise((resolve) => setTimeout(resolve, 200));
+    }
+  }, 40_000);
 
   afterAll(() => {
     try {
diff --git a/tsconfig.build.json b/tsconfig.build.json
index fa1cf4618d..233febd62f 100644
--- a/tsconfig.build.json
+++ b/tsconfig.build.json
@@ -1,4 +1,8 @@
 {
   "files": [],
-  "references": [{ "path": "packages/core" }, { "path": "packages/respect-core" }]
+  "references": [
+    { "path": "packages/core" },
+    { "path": "packages/respect-core" },
+    { "path": "packages/client-generator" }
+  ]
 }
diff --git a/tsconfig.json b/tsconfig.json
index 2f77b31f08..de6decf878 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -22,5 +22,6 @@
     "skipLibCheck": true,
     "moduleResolution": "nodenext",
     "esModuleInterop": true
-  }
+  },
+  "exclude": ["tests/e2e/generate-client/examples", "tests/e2e/generate-client/*-consumer"]
 }
diff --git a/vitest.config.ts b/vitest.config.ts
index b271c32b8e..c0f73e3a0c 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -12,6 +12,7 @@ const configExtension: { [key: string]: ViteUserConfig } = {
           'packages/cli/src/**/*.ts',
           'packages/core/src/**/*.ts',
           'packages/respect-core/src/**/*.ts',
+          'packages/client-generator/src/**/*.ts',
         ],
         provider: 'istanbul',
         exclude: [