diff --git a/.changeset/generate-spec-command.md b/.changeset/generate-spec-command.md
new file mode 100644
index 0000000000..d2cf3c6a4d
--- /dev/null
+++ b/.changeset/generate-spec-command.md
@@ -0,0 +1,5 @@
+---
+'@redocly/cli': minor
+---
+
+Added an experimental `generate-spec` command that infers an OpenAPI description from recorded HTTP traffic.
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
index a516482b11..e7a9e9b595 100644
--- a/.github/CODEOWNERS
+++ b/.github/CODEOWNERS
@@ -5,4 +5,5 @@ docs/ @Redocly/technical-writers
 packages/cli/src/utils/otel.ts @Redocly/hot-dogs
 packages/cli/src/utils/telemetry.ts @Redocly/hot-dogs
 packages/cli/src/commands/drift/ @Redocly/cyberpunks
+packages/cli/src/commands/generate-spec/ @Redocly/cyberpunks
 packages/cli/src/commands/proxy/ @Redocly/cyberpunks
\ No newline at end of file
diff --git a/docs/@v2/commands/drift.md b/docs/@v2/commands/drift.md
index 36e0f3a9f4..edd522ff5a 100644
--- a/docs/@v2/commands/drift.md
+++ b/docs/@v2/commands/drift.md
@@ -114,3 +114,4 @@ redocly drift ./traffic.har --api ./openapi.yaml --format json -o ./drift-report
 ## Related commands
 
 - [`proxy`](./proxy.md) captures live HTTP traffic into a HAR file that can be replayed through `drift`.
+- [`generate-spec`](./generate-spec.md) infers an OpenAPI description from the same traffic formats.
diff --git a/docs/@v2/commands/generate-spec.md b/docs/@v2/commands/generate-spec.md
new file mode 100644
index 0000000000..482c6cdc62
--- /dev/null
+++ b/docs/@v2/commands/generate-spec.md
@@ -0,0 +1,119 @@
+# `generate-spec`
+
+The `generate-spec` command infers an OpenAPI description from recorded HTTP traffic.
+The command reads a traffic log (or a folder of logs), builds a deterministic baseline description from the observed exchanges, and can optionally refine that baseline with an AI provider.
+
+{% admonition type="warning" name="Experimental" %}
+This is an experimental feature.
+Its behavior, command, flags, and output may change in future releases.
+
+The `generate-spec` command generates OpenAPI 3.1 descriptions only.
+{% /admonition %}
+
+## Supported traffic formats
+
+The traffic input can be provided in any of the following formats.
+By default the format is detected automatically from the file contents:
+
+- HAR
+- Kong
+- Nginx JSON
+- Apache JSON
+- NDJSON
+
+Traffic parsing is shared with the [`drift`](./drift.md) command, so any log that works with `drift` works here too.
+
+## How it works
+
+The baseline description is inferred directly from the recorded exchanges: identifier-like path segments become named path parameters, request and response schemas are merged across all observations, repeated object shapes are extracted into `components/schemas`, and consistently formatted string values get `format` or `enum` hints.
+
+A description inferred from traffic alone is a hypothesis: types are coarse and there are no descriptions, enums, or examples beyond what was observed.
+With `--with-ai`, the command sends each operation together with sample exchanges to an AI provider, which narrows types and adds formats, enums, descriptions, and examples.
+
+The AI's answer is never trusted blindly: a refined operation is only accepted when it keeps the operation's path, method, and observed response status codes, and passes validation with the `spec` ruleset.
+Rejected refinements keep their baseline version, and if refinement fails entirely the command falls back to the baseline description.
+The validation uses the built-in `spec` ruleset, not your project's `redocly.yaml` — lint the generated description with your own configuration afterward.
+
+{% admonition type="warning" name="Data sharing" %}
+`--with-ai` sends samples of the recorded traffic (URLs, query strings, request and response bodies) to the selected AI provider.
+Make sure the traffic contains no secrets or personal data you are not allowed to share.
+{% /admonition %}
+
+### AI providers
+
+Refinement runs a locally installed AI CLI in non-interactive mode: `claude` (Claude Code), `codex` (Codex CLI), or `cursor` (Cursor CLI).
+The selected CLI must be installed and authenticated on the machine running the command.
+
+The provider runs in isolation: project context the CLIs normally load (such as `CLAUDE.md`, `AGENTS.md`, or `.cursor/rules`) and settings like a configured model do not apply.
+Use `--ai-model` to choose a model, or the provider's default is used.
+
+## Usage
+
+```bash
+redocly generate-spec <traffic>
+redocly generate-spec <traffic> [--traffic-format=<option>] [--server=<url>]
+redocly generate-spec <traffic> [--title=<string>] [--output=<file>]
+redocly generate-spec <traffic> --with-ai [--ai-provider=<option>] [--ai-model=<string>] [--ai-concurrency=<number>]
+```
+
+## Options
+
+| Option           | Type    | Description                                                                                                                                                                                                                                                      |
+| ---------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| traffic          | string  | **REQUIRED.** Path to a traffic log file or folder (HAR, Kong, Nginx/Apache JSON, NDJSON).                                                                                                                                                                       |
+| --type           | string  | Target API description type.<br/>**Possible values:** `openapi`. Default value is `openapi`.                                                                                                                                                                     |
+| --traffic-format | string  | Traffic input format.<br/>**Possible values:** `auto`, `har`, `kong`, `nginx-json`, `apache-json`, `ndjson`. Default value is `auto`.                                                                                                                            |
+| --server         | string  | Server URL the traffic was captured against (host, host + base path, or a path-only prefix like `/api`). Only requests under it are considered, the rest of their URL is treated as the API path, and it becomes the `servers` URL of the generated description. |
+| --title          | string  | Title for the generated API description. Default value is `Generated API`.                                                                                                                                                                                       |
+| --with-ai        | boolean | Refine the inferred description with an AI provider. Default value is `false`.                                                                                                                                                                                   |
+| --ai-provider    | string  | AI provider used with `--with-ai`. Runs the corresponding CLI in non-interactive mode.<br/>**Possible values:** `claude`, `codex`, `cursor`. Default value is `claude`.                                                                                          |
+| --ai-model       | string  | Model passed to the selected AI provider. If not set, the provider's default model is used.                                                                                                                                                                      |
+| --ai-concurrency | number  | Number of operations refined in parallel with `--with-ai`. Default value is `4`.                                                                                                                                                                                 |
+| --output, -o     | string  | Write the generated description to this file instead of stdout.                                                                                                                                                                                                  |
+| --config         | string  | Specify path to the [configuration file](../configuration/index.md).                                                                                                                                                                                             |
+| --help           | boolean | Display help.                                                                                                                                                                                                                                                    |
+| --version        | boolean | Display version number.                                                                                                                                                                                                                                          |
+
+## Examples
+
+### Generate a description from a HAR capture
+
+```bash
+redocly generate-spec ./traffic.har -o ./openapi.yaml
+```
+
+### Scope the traffic to a server
+
+When the capture contains traffic for more than one host, or the API lives behind a base path (for example, a gateway that adds `/api`), use `--server` to declare the server the traffic was captured against.
+Only requests under it are considered, and the remaining path becomes the API path:
+
+```bash
+redocly generate-spec ./traffic.har --server https://api.example.com/api -o ./openapi.yaml
+```
+
+### Refine the description with AI
+
+```bash
+redocly generate-spec ./traffic.har --with-ai --ai-provider claude -o ./openapi.yaml
+```
+
+### Speed up refinement for large APIs
+
+For descriptions with many operations, raise the concurrency and pick a faster model to shorten the run:
+
+```bash
+redocly generate-spec ./traffic-logs/ --with-ai --ai-concurrency 12 --ai-model claude-sonnet-5 -o ./openapi.yaml
+```
+
+### Capture traffic and generate a description
+
+```bash
+redocly proxy --target https://api.example.com --har ./capture.har
+# point your client at http://127.0.0.1:4040, then press Ctrl+C to stop
+redocly generate-spec ./capture.har -o ./openapi.yaml
+```
+
+## Related commands
+
+- [`proxy`](./proxy.md) captures live HTTP traffic into a HAR file that can be fed into `generate-spec`.
+- [`drift`](./drift.md) detects drift between recorded HTTP traffic and an existing OpenAPI description.
diff --git a/docs/@v2/commands/index.md b/docs/@v2/commands/index.md
index 8f730333a4..f8de5f7a07 100644
--- a/docs/@v2/commands/index.md
+++ b/docs/@v2/commands/index.md
@@ -30,6 +30,7 @@ Testing commands:
 - [`generate-arazzo`](generate-arazzo.md) Generate an Arazzo description from an OpenAPI description.
 - [`drift`](drift.md) Detect drift between recorded HTTP traffic and an OpenAPI description [experimental feature].
 - [`proxy`](proxy.md) Capture live HTTP traffic through a reverse proxy into a HAR file [experimental feature].
+- [`generate-spec`](generate-spec.md) Infer an OpenAPI description from recorded HTTP traffic [experimental feature].
 
 Redocly platform commands:
 
diff --git a/docs/@v2/commands/proxy.md b/docs/@v2/commands/proxy.md
index 0811f18c72..a2f53a2f87 100644
--- a/docs/@v2/commands/proxy.md
+++ b/docs/@v2/commands/proxy.md
@@ -82,3 +82,4 @@ redocly drift ./capture.har --api ./openapi.yaml
 ## Related commands
 
 - [`drift`](./drift.md) replays a recorded HAR (or other traffic log) against an OpenAPI description.
+- [`generate-spec`](./generate-spec.md) infers an OpenAPI description from a captured HAR.
diff --git a/docs/@v2/v2.sidebars.yaml b/docs/@v2/v2.sidebars.yaml
index 99da0aac1e..ba5ae64193 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-spec
+          page: commands/generate-spec.md
         - label: join
           page: commands/join.md
         - label: lint
diff --git a/packages/cli/src/commands/generate-spec/README.md b/packages/cli/src/commands/generate-spec/README.md
new file mode 100644
index 0000000000..c361322966
--- /dev/null
+++ b/packages/cli/src/commands/generate-spec/README.md
@@ -0,0 +1,142 @@
+# generate-spec [experimental]
+
+Infer an OpenAPI description from recorded HTTP traffic, optionally refined with AI.
+
+Traffic alone can only ever produce a _hypothesis_ about an API's real shape: types are coarse, every observed property looks required, and there are no descriptions, enums, or formats.
+`generate-spec` first builds that hypothesis deterministically, then can hand it to an AI provider together with real sample exchanges to narrow it toward the true definition.
+
+## Usage
+
+```bash
+# Deterministic inference only
+redocly generate-spec ./traffic.har
+
+# Refine the hypothesis with AI
+redocly generate-spec ./traffic.har --with-ai --ai-provider claude -o openapi.yaml
+```
+
+The `<traffic>` argument is a file or folder of recorded traffic.
+The supported formats are:
+
+- HAR
+- Kong
+- Nginx/Apache JSON
+- NDJSON
+
+Formats are auto-detected, or can be forced with `--traffic-format`.
+The traffic parsing infrastructure is shared with the `drift` command.
+The command generates OpenAPI 3.2 descriptions only.
+
+## Deterministic inference
+
+The baseline is derived from every exchange in the traffic:
+
+- Identifier-like path segments (numeric, UUID, ULID, CUID, prefixed and opaque tokens) become named path parameters.
+- Body schemas are merged across all observations.
+  A property becomes optional as soon as one sample omits it.
+- Alternative body shapes for the same operation are preserved as `oneOf` variants instead of being collapsed.
+- Values observed as `null` produce type unions such as `["string", "null"]`.
+- Object shapes that repeat across the document are extracted into `components/schemas` and referenced with `$ref`.
+  - The same entity is recognized when it appears as a list item and as a single resource, with different `required` sets, or with near-identical properties (at least 75% shared, with compatible types).
+  - Components are named from the path entity, the enclosing property name, or `Error` for error responses.
+  - A shape repeated only because its parent shape repeats stays inline.
+- Observed string values are analyzed conservatively: when every value of a property (or parameter) matches the same well-known pattern it gets a `format` (`uuid`, `date-time`, `date`, `email`, `uri`, `ipv4`).
+  - When a string only ever takes a small set of identifier-like values with enough repetition it becomes an `enum`.
+    To trigger this conversion, the command needs at least 4 observations, at most 5 distinct values, each seen twice on average.
+  - Enums apply to body properties and query parameters.
+  - Path parameters and nullable unions get formats only.
+  - Evidence is pooled across all operations a shared component was observed in.
+- Responses that were never received (status `0` in HAR captures) are ignored.
+
+## AI refinement
+
+The description is refined one operation at a time.
+The prompt and response stay small regardless of the volume of recorded traffic or the resulting description's size.
+
+Each prompt carries:
+
+- a single operation from the baseline
+- component schemas it references
+- names of other components (reserved against collisions)
+- a capped, shape-diverse sample of the real exchanges recorded for that operation
+
+The sample of exchanges is grouped by status and body shape, selected round-robin to represent every observed payload variant.
+
+The AI is instructed to:
+
+- narrow types
+- add formats, enums, descriptions and examples
+- refine or add `components/schemas`
+- model alternative payloads explicitly with `oneOf` (plus `discriminator`) and `allOf` composition.
+
+You can set the number of operations refined in parallel using `--ai-concurrency`.
+The default value is `4`.
+Every accepted refinement is merged back as it arrives: operations prompted later see already-refined shared components.
+
+When two concurrent refinements touch the same shared component, the one merged last wins.
+The final whole-document lint still guards the result.
+
+To process operations strictly sequentially, set `--ai-concurrency 1`.
+Progress is reported per operation as refinements complete.
+
+The AI's answer is never trusted blindly.
+A refined operation is only accepted when it:
+
+- keeps the exact path template and method — the AI cannot invent, drop, or rename operations because only the requested operation is merged back
+- keeps every response status code observed in the traffic
+- keeps an `operationId`
+- does not redefine reserved components (those used only by other operations)
+- passes validation with the `spec` ruleset (checked against the description's full component set)
+
+An operation whose refinement is rejected keeps its deterministic baseline and the reason for rejection is reported.
+Components that no operation references are pruned.
+The final document is linted again as a whole.
+
+If refinement fails for every operation, the command falls back to the deterministic baseline.
+Each provider call times out after 5 minutes.
+
+The acceptance lint is intentionally pinned to the `spec` ruleset and does not use the project's `redocly.yaml`.
+A stricter governance config would reject refinements for problems the baseline itself has.
+A looser one could let structurally broken output through.
+Lint the generated description with your own config afterward.
+
+> **Warning:** `--with-ai` sends samples of the recorded traffic (URLs, query strings, request and response bodies) to the selected AI provider.
+> Make sure the traffic contains no secrets or personal data you are not allowed to share.
+
+## Options
+
+| Option             | Description                                                                                           |
+| ------------------ | ----------------------------------------------------------------------------------------------------- |
+| `--type`           | Target description type. Only `openapi` is supported.                                                 |
+| `--traffic-format` | Traffic input format (`auto`, `har`, `kong`, `nginx-json`, `apache-json`, `ndjson`).                  |
+| `--server`         | Server URL the traffic was captured against. Scopes which requests are considered and sets `servers`. |
+| `--title`          | Title for the generated description.                                                                  |
+| `--with-ai`        | Refine the inferred description with an AI provider.                                                  |
+| `--ai-provider`    | `claude`, `codex`, or `cursor` (default `claude`).                                                    |
+| `--ai-model`       | Model passed to the selected provider.                                                                |
+| `--ai-concurrency` | Number of operations refined in parallel. Default: `4`.                                               |
+| `-o, --output`     | Write the result to a file instead of stdout.                                                         |
+
+## AI providers
+
+Every provider CLI is spawned in an empty temporary directory.
+The project context the CLIs normally auto-load from the working directory (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules`) never enters the prompts.
+Otherwise, it would slow every call down and could steer the refinement.
+
+- **`claude`** — runs the local `claude` CLI in headless mode (`claude -p`), with built-in tools, MCP servers, settings (hooks, skills, plugins), and session persistence disabled so every call is a plain completion.
+  Because settings are not loaded, a model configured there does not apply: pass `--ai-model`, or the CLI's built-in default model is used.
+- **`codex`** — runs the local `codex` CLI in non-interactive mode (`codex exec`) with MCP servers and `AGENTS.md` discovery disabled and a read-only sandbox.
+  Other settings from `~/.codex/config.toml`, such as `model_reasoning_effort`, still apply.
+- **`cursor`** — runs the local Cursor CLI in print mode: `cursor-agent -p`.
+  The renamed `agent` binary is tried as a fallback.
+
+All providers require the respective CLI to be installed and authenticated on the machine running the command.
+
+## Performance for large APIs
+
+The total time is roughly the per-operation AI time multiplied by the number of operations and divided by `--ai-concurrency`.
+For descriptions with many operations:
+
+- Raise `--ai-concurrency` (for example to `12`) — calls are network-bound and the provider CLIs retry rate-limit responses themselves.
+- Pick a faster model with `--ai-model`.
+  Smaller models roughly halve the per-operation time compared to the largest ones at some cost in refinement depth.
diff --git a/packages/cli/src/commands/generate-spec/__tests__/__snapshots__/prompt.test.ts.snap b/packages/cli/src/commands/generate-spec/__tests__/__snapshots__/prompt.test.ts.snap
new file mode 100644
index 0000000000..db59421632
--- /dev/null
+++ b/packages/cli/src/commands/generate-spec/__tests__/__snapshots__/prompt.test.ts.snap
@@ -0,0 +1,80 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`buildOperationPrompt > renders the full prompt for an operation with components and samples 1`] = `
+"You are an expert API designer. You are given one operation from an OpenAPI 3.2 description that was inferred mechanically from recorded HTTP traffic, the component schemas it references, and a sample of the real recorded HTTP exchanges for that operation. The inferred description is only a hypothesis: types are coarse, every observed property is marked required, and descriptions are missing. Alternative body shapes observed in the traffic appear as "oneOf" variants or type unions. Common string formats (uuid, date-time, date, email, uri, ipv4) and small closed enums are detected conservatively from the observed values.
+
+Refine the operation into the most accurate OpenAPI 3.2 definition you can justify from the evidence, while staying conservative:
+- Keep the path template and the HTTP method exactly as given. Do not rename path parameters, do not move parameters to the path item level, and keep every response status code. The result is programmatically checked and rejected otherwise.
+- Keep the operationId unless it is clearly wrong.
+- Narrow property types where the samples clearly support it (formats such as date-time, uuid, email, uri; integer vs number; enums when a field only ever takes a small fixed set of values). Verify the formats and enums already detected against the samples; correct or extend them where justified. The detected formats and enums were derived from the full recorded traffic while you see only a subset of it, so never remove a detected format or enum value merely because the samples do not show it — correct one only when a sample contradicts it.
+- Relax "required" for properties that are plausibly optional (e.g. absent in some samples, or clearly nullable). Express nullable values as type unions such as ["string", "null"].
+- When a request or response body has alternative shapes — the baseline shows "oneOf" variants, or the samples show clearly different payloads — model them explicitly with "oneOf". Name each variant in components/schemas, and add a "discriminator" when a property (such as "type" or "kind") selects the variant.
+- Factor structure shared between variants or schemas with "allOf": extract the common base into components/schemas and compose each variant as "allOf" of the base plus its specific properties.
+- Keep the $ref references to the component schemas you were given. You may refine the definition of a referenced component when the samples justify it, and you may add new components, but never rename an existing component and never reuse a reserved component name listed in the input.
+- Add concise, useful "summary" and "description" fields to the operation, its parameters and important schema properties.
+- Add example values drawn from the real samples where helpful, but never copy values that look like secrets or personal data (tokens, API keys, passwords, session identifiers, email addresses, personal names); use clearly fictional placeholder values instead.
+
+Output ONLY a YAML document with this exact top-level structure:
+
+paths:
+  <the path template exactly as given>:
+    <the method>:
+      ...the refined operation...
+components:
+  schemas:
+    ...only the component schemas you changed or added; omit "components" entirely when there are none...
+
+Do not wrap the output in Markdown code fences. Do not add any commentary before or after the document."
+`;
+
+exports[`buildOperationPrompt > renders the full prompt for an operation with components and samples 2`] = `
+"# Operation to refine (inferred from traffic)
+
+\`\`\`yaml
+paths:
+  /users/{userId}:
+    get:
+      operationId: get-users-userId
+      parameters:
+        - name: userId
+          in: path
+          required: true
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/User'
+\`\`\`
+
+# Component schemas referenced by this operation (current definitions)
+
+\`\`\`yaml
+components:
+  schemas:
+    User:
+      type: object
+      properties:
+        id:
+          type: integer
+        name:
+          type: string
+\`\`\`
+
+# Reserved component names (used elsewhere in the description; do not redefine or reuse them)
+
+Order, Error
+
+# Recorded HTTP exchanges for this operation
+
+### Exchange 1
+GET /users/42?expand=profile
+Response status: 200
+Response Content-Type: application/json
+Response body: {"id":42,"name":"Jane"}
+
+Refine GET /users/{userId} as instructed and output only the YAML document."
+`;
diff --git a/packages/cli/src/commands/generate-spec/__tests__/components.test.ts b/packages/cli/src/commands/generate-spec/__tests__/components.test.ts
new file mode 100644
index 0000000000..a9839e64ce
--- /dev/null
+++ b/packages/cli/src/commands/generate-spec/__tests__/components.test.ts
@@ -0,0 +1,350 @@
+import { extractSchemaComponents } from '../components.js';
+import { type GeneratedDocument, inferSchema, type JsonSchema } from '../generator.js';
+
+type Operation = GeneratedDocument['paths'][string][string];
+
+function makeDocument(paths: GeneratedDocument['paths']): GeneratedDocument {
+  return { openapi: '3.2.0', info: { title: 'Test API', version: '1.0.0' }, paths };
+}
+
+function jsonOperation(
+  operationId: string,
+  responseSchema: JsonSchema,
+  options: { status?: string; requestSchema?: JsonSchema } = {}
+): Operation {
+  const operation: Operation = {
+    operationId,
+    responses: {
+      [options.status ?? '200']: {
+        description: 'ok',
+        content: { 'application/json': { schema: responseSchema } },
+      },
+    },
+  };
+  if (options.requestSchema) {
+    operation.requestBody = { content: { 'application/json': { schema: options.requestSchema } } };
+  }
+  return operation;
+}
+
+function responseSchema(document: GeneratedDocument, path: string, method = 'get'): JsonSchema {
+  const responses = Object.values(document.paths[path][method].responses);
+  return responses[0].content!['application/json'].schema;
+}
+
+describe('extractSchemaComponents', () => {
+  it('extracts a shape repeated across operations and names it after the path entity', () => {
+    const document = extractSchemaComponents(
+      makeDocument({
+        '/users': {
+          get: jsonOperation('list', {
+            type: 'array',
+            items: inferSchema({ id: 1, name: 'Ada', email: 'ada@example.com' }),
+          }),
+          post: jsonOperation('create', inferSchema({ id: 3, name: 'Linus', email: 'l@e.com' }), {
+            status: '201',
+          }),
+        },
+        '/users/{userId}': {
+          get: jsonOperation('read', inferSchema({ id: 42, name: 'Ada', email: 'a@e.com' })),
+        },
+      })
+    );
+
+    expect(document.components?.schemas).toEqual({
+      User: {
+        type: 'object',
+        properties: {
+          id: { type: 'integer' },
+          name: { type: 'string' },
+          email: { type: 'string' },
+        },
+        required: ['id', 'name', 'email'],
+      },
+    });
+    expect(responseSchema(document, '/users')).toEqual({
+      type: 'array',
+      items: { $ref: '#/components/schemas/User' },
+    });
+    expect(responseSchema(document, '/users/{userId}')).toEqual({
+      $ref: '#/components/schemas/User',
+    });
+    expect(responseSchema(document, '/users', 'post')).toEqual({
+      $ref: '#/components/schemas/User',
+    });
+  });
+
+  it('groups shapes that differ only in required properties and intersects required', () => {
+    const document = extractSchemaComponents(
+      makeDocument({
+        '/users': {
+          get: jsonOperation('list', {
+            type: 'object',
+            properties: { id: { type: 'integer' }, name: { type: 'string' } },
+            required: ['id', 'name'],
+          }),
+        },
+        '/users/{userId}': {
+          get: jsonOperation('read', {
+            type: 'object',
+            properties: { id: { type: 'integer' }, name: { type: 'string' } },
+            required: ['id'],
+          }),
+        },
+      })
+    );
+
+    expect(document.components?.schemas.User).toEqual({
+      type: 'object',
+      properties: { id: { type: 'integer' }, name: { type: 'string' } },
+      required: ['id'],
+    });
+  });
+
+  it('unifies near-identical shapes into one component', () => {
+    const document = extractSchemaComponents(
+      makeDocument({
+        '/users': {
+          get: jsonOperation('list', inferSchema({ id: 1, name: 'a', email: 'e' })),
+        },
+        '/users/{userId}': {
+          get: jsonOperation(
+            'read',
+            inferSchema({ id: 1, name: 'a', email: 'e', createdAt: 'now' })
+          ),
+        },
+      })
+    );
+
+    expect(Object.keys(document.components?.schemas ?? {})).toEqual(['User']);
+    expect(document.components?.schemas.User).toEqual({
+      type: 'object',
+      properties: {
+        id: { type: 'integer' },
+        name: { type: 'string' },
+        email: { type: 'string' },
+        createdAt: { type: 'string' },
+      },
+      required: ['id', 'name', 'email'],
+    });
+    expect(responseSchema(document, '/users')).toEqual({ $ref: '#/components/schemas/User' });
+    expect(responseSchema(document, '/users/{userId}')).toEqual({
+      $ref: '#/components/schemas/User',
+    });
+  });
+
+  it('keeps dissimilar shapes separate and falls back to a Request-suffixed name', () => {
+    const request = () => inferSchema({ name: 'Linus', email: 'l@e.com' });
+    const response = () => inferSchema({ id: 3, name: 'Linus', email: 'l@e.com' });
+    const document = extractSchemaComponents(
+      makeDocument({
+        '/users': {
+          post: jsonOperation('create', response(), { status: '201', requestSchema: request() }),
+        },
+        '/users/{userId}': {
+          put: jsonOperation('update', response(), { requestSchema: request() }),
+        },
+      })
+    );
+
+    expect(Object.keys(document.components?.schemas ?? {})).toEqual(['User', 'UserRequest']);
+    expect(document.components?.schemas.UserRequest.properties).toEqual({
+      name: { type: 'string' },
+      email: { type: 'string' },
+    });
+    expect(document.paths['/users'].post.requestBody?.content['application/json'].schema).toEqual({
+      $ref: '#/components/schemas/UserRequest',
+    });
+  });
+
+  it('extracts a nested shape shared across different parents and names it after the property', () => {
+    const address = () => inferSchema({ street: 'Main St', city: 'Springfield' });
+    const document = extractSchemaComponents(
+      makeDocument({
+        '/users/{userId}': {
+          get: jsonOperation('readUser', {
+            type: 'object',
+            properties: { id: { type: 'integer' }, address: address() },
+            required: ['id', 'address'],
+          }),
+        },
+        '/companies/{companyId}': {
+          get: jsonOperation('readCompany', {
+            type: 'object',
+            properties: { vat: { type: 'string' }, address: address() },
+            required: ['vat', 'address'],
+          }),
+        },
+      })
+    );
+
+    expect(Object.keys(document.components?.schemas ?? {})).toEqual(['Address']);
+    expect(responseSchema(document, '/users/{userId}').properties?.address).toEqual({
+      $ref: '#/components/schemas/Address',
+    });
+    expect(responseSchema(document, '/companies/{companyId}').properties?.address).toEqual({
+      $ref: '#/components/schemas/Address',
+    });
+  });
+
+  it('keeps a shape inline when it repeats only because its parent shape repeats', () => {
+    const user = () =>
+      inferSchema({ id: 1, name: 'a', address: { street: 'Main St', city: 'Springfield' } });
+    const document = extractSchemaComponents(
+      makeDocument({
+        '/users': { get: jsonOperation('list', user()) },
+        '/users/{userId}': { get: jsonOperation('read', user()) },
+      })
+    );
+
+    expect(Object.keys(document.components?.schemas ?? {})).toEqual(['User']);
+    expect(document.components?.schemas.User.properties?.address).toEqual({
+      type: 'object',
+      properties: { street: { type: 'string' }, city: { type: 'string' } },
+      required: ['street', 'city'],
+    });
+  });
+
+  it('names shapes returned by error responses "Error"', () => {
+    const problem = () => inferSchema({ code: 'not_found', message: 'Not found' });
+    const document = extractSchemaComponents(
+      makeDocument({
+        '/users/{userId}': {
+          get: jsonOperation('readUser', problem(), { status: '404' }),
+        },
+        '/orders/{orderId}': {
+          get: jsonOperation('readOrder', problem(), { status: '404' }),
+        },
+      })
+    );
+
+    expect(Object.keys(document.components?.schemas ?? {})).toEqual(['Error']);
+  });
+
+  it('replaces oneOf variants shared across operations with refs', () => {
+    const payment = () => ({
+      oneOf: [
+        inferSchema({ kind: 'card', cardNumber: '41' }),
+        inferSchema({ kind: 'bank', iban: 'DE89' }),
+      ],
+    });
+    const document = extractSchemaComponents(
+      makeDocument({
+        '/payments': { post: jsonOperation('create', payment(), { status: '201' }) },
+        '/payments/{paymentId}': { get: jsonOperation('read', payment()) },
+      })
+    );
+
+    const schemas = document.components?.schemas ?? {};
+    expect(Object.keys(schemas)).toEqual(['Payment', 'Payment2']);
+    const variants = responseSchema(document, '/payments/{paymentId}').oneOf;
+    expect(variants).toHaveLength(2);
+    for (const variant of variants ?? []) {
+      expect(variant.$ref).toMatch(/^#\/components\/schemas\/Payment2?$/);
+    }
+  });
+
+  it('references extracted shapes from map values', () => {
+    const user = () => inferSchema({ id: 1, name: 'a' });
+    const document = extractSchemaComponents(
+      makeDocument({
+        '/user-index': {
+          get: jsonOperation('index', { type: 'object', additionalProperties: user() }),
+        },
+        '/users/{userId}': { get: jsonOperation('read', user()) },
+      })
+    );
+
+    expect(Object.keys(document.components?.schemas ?? {})).toEqual(['User']);
+    expect(responseSchema(document, '/user-index')).toEqual({
+      type: 'object',
+      additionalProperties: { $ref: '#/components/schemas/User' },
+    });
+  });
+
+  it('models a self-similar nested shape as a recursive component', () => {
+    const document = extractSchemaComponents(
+      makeDocument({
+        '/employees/{employeeId}': {
+          get: jsonOperation('read', {
+            type: 'object',
+            properties: {
+              id: { type: 'integer' },
+              name: { type: 'string' },
+              email: { type: 'string' },
+              manager: inferSchema({ id: 2, name: 'b', email: 'm@e.com' }),
+            },
+            required: ['id', 'name', 'email', 'manager'],
+          }),
+        },
+      })
+    );
+
+    expect(Object.keys(document.components?.schemas ?? {})).toEqual(['Employee']);
+    const employee = document.components?.schemas.Employee;
+    expect(employee?.properties?.manager).toEqual({ $ref: '#/components/schemas/Employee' });
+    expect(employee?.required).toEqual(['id', 'name', 'email']);
+    expect(responseSchema(document, '/employees/{employeeId}')).toEqual({
+      $ref: '#/components/schemas/Employee',
+    });
+  });
+
+  it('keeps a list envelope inline when unrelated endpoints share it only because items were never observed', () => {
+    const emptyList = () => inferSchema({ object: 'list', page: { total: 0 }, items: [] });
+    const document = extractSchemaComponents(
+      makeDocument({
+        '/ai-jobs': { get: jsonOperation('listAiJobs', emptyList()) },
+        '/announcements': { get: jsonOperation('listAnnouncements', emptyList()) },
+        '/subscription-status': {
+          get: jsonOperation(
+            'readSubscriptionStatus',
+            inferSchema({
+              object: 'list',
+              page: { total: 1 },
+              items: [{ isValid: true, organizationId: 'org_1' }],
+            })
+          ),
+        },
+      })
+    );
+
+    expect(document.components).toBeUndefined();
+    expect(responseSchema(document, '/subscription-status').properties?.items).toEqual({
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: { isValid: { type: 'boolean' }, organizationId: { type: 'string' } },
+        required: ['isValid', 'organizationId'],
+      },
+    });
+  });
+
+  it('still extracts a shape with unobserved list items when its contexts agree on a name', () => {
+    const emptyList = () => inferSchema({ object: 'list', page: { total: 0 }, items: [] });
+    const document = extractSchemaComponents(
+      makeDocument({
+        '/jobs': { get: jsonOperation('listJobs', emptyList()) },
+        '/projects/{projectId}/jobs': { get: jsonOperation('listProjectJobs', emptyList()) },
+      })
+    );
+
+    expect(Object.keys(document.components?.schemas ?? {})).toEqual(['Job']);
+    expect(responseSchema(document, '/jobs')).toEqual({ $ref: '#/components/schemas/Job' });
+  });
+
+  it('leaves the document untouched when no shape repeats', () => {
+    const document = extractSchemaComponents(
+      makeDocument({
+        '/users/{userId}': {
+          get: jsonOperation('read', inferSchema({ id: 1, name: 'a' })),
+        },
+        '/orders/{orderId}': {
+          get: jsonOperation('readOrder', inferSchema({ total: 9.99, currency: 'EUR' })),
+        },
+      })
+    );
+
+    expect(document.components).toBeUndefined();
+    expect(responseSchema(document, '/users/{userId}').$ref).toBeUndefined();
+  });
+});
diff --git a/packages/cli/src/commands/generate-spec/__tests__/generator.test.ts b/packages/cli/src/commands/generate-spec/__tests__/generator.test.ts
new file mode 100644
index 0000000000..6a40616910
--- /dev/null
+++ b/packages/cli/src/commands/generate-spec/__tests__/generator.test.ts
@@ -0,0 +1,207 @@
+import { inferMultipartSchema, inferSchema, mergeSchemas, templatizePath } from '../generator.js';
+
+describe('templatizePath', () => {
+  it('replaces identifier-like segments with parameters named after the parent segment', () => {
+    expect(templatizePath('/users/42/posts/7')).toEqual({
+      template: '/users/{userId}/posts/{postId}',
+      params: [
+        { name: 'userId', value: '42' },
+        { name: 'postId', value: '7' },
+      ],
+    });
+  });
+
+  it('recognizes UUID, ULID, cuid and prefixed identifiers', () => {
+    expect(templatizePath('/items/f47ac10b-58cc-4372-a567-0e02b2c3d479').template).toBe(
+      '/items/{itemId}'
+    );
+    expect(templatizePath('/orders/01ARZ3NDEKTSV4RRFFQ69G5FAV').template).toBe('/orders/{orderId}');
+    expect(templatizePath('/orgs/org_01ks7rnqsyy0g6h37rfmen7zv9').template).toBe('/orgs/{orgId}');
+    expect(templatizePath('/orders/cjld2cjxh0000qzrmn831i7rn').template).toBe('/orders/{orderId}');
+    expect(templatizePath('/orders/tz4a98xxat96iws9zmbrgj3a').template).toBe('/orders/{orderId}');
+  });
+
+  it('keeps long plain words that contain no digits', () => {
+    expect(templatizePath('/categories/internationalizations').template).toBe(
+      '/categories/internationalizations'
+    );
+  });
+
+  it('deduplicates parameter names within a path', () => {
+    expect(templatizePath('/orgs/1/orgs/2').template).toBe('/orgs/{orgId}/orgs/{orgId2}');
+  });
+
+  it('singularizes irregular plural parent segments', () => {
+    expect(templatizePath('/people/42').template).toBe('/people/{personId}');
+    expect(templatizePath('/series/42').template).toBe('/series/{seriesId}');
+  });
+
+  it('names a parameter with no parent segment "id" and keeps plain segments', () => {
+    expect(templatizePath('/f47ac10b-58cc-4372-a567-0e02b2c3d479').template).toBe('/{id}');
+    expect(templatizePath('/users/profile').template).toBe('/users/profile');
+  });
+});
+
+describe('inferMultipartSchema', () => {
+  it('parses form fields and file parts into an object schema', () => {
+    const body = [
+      '--demo-boundary',
+      'Content-Disposition: form-data; name="name"',
+      '',
+      'espresso-doppio',
+      '--demo-boundary',
+      'Content-Disposition: form-data; name="price"',
+      '',
+      '300',
+      '--demo-boundary',
+      'Content-Disposition: form-data; name="photo"; filename="cup.png"',
+      'Content-Type: image/png',
+      '',
+      'PNGDATA',
+      '--demo-boundary--',
+      '',
+    ].join('\r\n');
+
+    expect(inferMultipartSchema(body, 'multipart/form-data; boundary=demo-boundary')).toEqual({
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+        price: { type: 'string' },
+        photo: { type: 'string', format: 'binary' },
+      },
+      required: ['name', 'price', 'photo'],
+    });
+  });
+});
+
+describe('inferSchema', () => {
+  it('infers primitive types', () => {
+    expect(inferSchema('x')).toEqual({ type: 'string' });
+    expect(inferSchema(3)).toEqual({ type: 'integer' });
+    expect(inferSchema(3.5)).toEqual({ type: 'number' });
+    expect(inferSchema(true)).toEqual({ type: 'boolean' });
+    expect(inferSchema(null)).toEqual({ type: 'null' });
+  });
+
+  it('infers objects with all observed properties required', () => {
+    expect(inferSchema({ a: 1, b: 'x' })).toEqual({
+      type: 'object',
+      properties: { a: { type: 'integer' }, b: { type: 'string' } },
+      required: ['a', 'b'],
+    });
+  });
+
+  it('merges array item samples', () => {
+    expect(inferSchema([1, 2.5])).toEqual({ type: 'array', items: { type: 'number' } });
+    expect(inferSchema([])).toEqual({ type: 'array' });
+  });
+
+  it('describes arrays of alternative shapes with oneOf items', () => {
+    expect(inferSchema([{ a: 1 }, { b: 'x' }])).toEqual({
+      type: 'array',
+      items: {
+        oneOf: [
+          { type: 'object', properties: { a: { type: 'integer' } }, required: ['a'] },
+          { type: 'object', properties: { b: { type: 'string' } }, required: ['b'] },
+        ],
+      },
+    });
+  });
+
+  it('describes identifier-keyed objects as maps', () => {
+    expect(inferSchema({ '1': 'a', '2': 'b' })).toEqual({
+      type: 'object',
+      additionalProperties: { type: 'string' },
+    });
+  });
+});
+
+describe('mergeSchemas', () => {
+  const card = inferSchema({ type: 'card', amount: 100, cardNumber: '41', cvv: '123' });
+  const bank = inferSchema({ type: 'bank_transfer', amount: 75, iban: 'DE89' });
+
+  it('widens integer and number to number', () => {
+    expect(mergeSchemas([{ type: 'integer' }, { type: 'number' }])).toEqual({ type: 'number' });
+  });
+
+  it('folds null observations into a type union', () => {
+    expect(mergeSchemas([{ type: 'string' }, { type: 'null' }])).toEqual({
+      type: ['string', 'null'],
+    });
+    expect(mergeSchemas([inferSchema({ a: 1 }), { type: 'null' }])).toEqual({
+      type: ['object', 'null'],
+      properties: { a: { type: 'integer' } },
+      required: ['a'],
+    });
+  });
+
+  it('merges similar object shapes and relaxes required to the intersection', () => {
+    expect(
+      mergeSchemas([inferSchema({ a: 1, b: 'x', c: true }), inferSchema({ a: 2, b: 'y' })])
+    ).toEqual({
+      type: 'object',
+      properties: { a: { type: 'integer' }, b: { type: 'string' }, c: { type: 'boolean' } },
+      required: ['a', 'b'],
+    });
+  });
+
+  it('keeps dissimilar object shapes as oneOf variants', () => {
+    const merged = mergeSchemas([card, bank]);
+    expect(merged.oneOf).toHaveLength(2);
+    expect(merged.oneOf?.[0].properties).toHaveProperty('cardNumber');
+    expect(merged.oneOf?.[1].properties).toHaveProperty('iban');
+  });
+
+  it('clusters later samples into the matching variant', () => {
+    const cardWithReceipt = inferSchema({
+      type: 'card',
+      amount: 250.5,
+      cardNumber: '55',
+      cvv: '999',
+      receiptEmail: 'a@b.c',
+    });
+    const merged = mergeSchemas([card, bank, cardWithReceipt]);
+    expect(merged.oneOf).toHaveLength(2);
+    const [mergedCard] = merged.oneOf ?? [];
+    expect(mergedCard.properties).toHaveProperty('receiptEmail');
+    expect(mergedCard.properties?.amount).toEqual({ type: 'number' });
+    expect(mergedCard.required).not.toContain('receiptEmail');
+  });
+
+  it('retains information observed after a divergent sample', () => {
+    const merged = mergeSchemas([
+      inferSchema({ a: 1 }),
+      { type: 'string' },
+      inferSchema({ a: 1, b: 'x' }),
+    ]);
+    expect(merged.oneOf).toEqual([
+      {
+        type: 'object',
+        properties: { a: { type: 'integer' }, b: { type: 'string' } },
+        required: ['a'],
+      },
+      { type: 'string' },
+    ]);
+  });
+
+  it('merges maps with maps but keeps maps and records as separate variants', () => {
+    const map = inferSchema({ '1': 1, '2': 2 });
+    expect(mergeSchemas([map, inferSchema({ '3': 2.5 })])).toEqual({
+      type: 'object',
+      additionalProperties: { type: 'number' },
+    });
+    expect(mergeSchemas([map, inferSchema({ name: 'x' })]).oneOf).toHaveLength(2);
+  });
+
+  it('caps the number of object variants by folding the most similar ones', () => {
+    const disjoint = [
+      inferSchema({ a1: 1, a2: 1 }),
+      inferSchema({ b1: 1, b2: 1 }),
+      inferSchema({ c1: 1, c2: 1 }),
+      inferSchema({ d1: 1, d2: 1 }),
+      inferSchema({ e1: 1, e2: 1 }),
+    ];
+    const merged = mergeSchemas(disjoint);
+    expect(merged.oneOf).toHaveLength(3);
+  });
+});
diff --git a/packages/cli/src/commands/generate-spec/__tests__/prompt.test.ts b/packages/cli/src/commands/generate-spec/__tests__/prompt.test.ts
new file mode 100644
index 0000000000..07a9b19854
--- /dev/null
+++ b/packages/cli/src/commands/generate-spec/__tests__/prompt.test.ts
@@ -0,0 +1,37 @@
+import { buildOperationPrompt } from '../ai/prompt.js';
+
+describe('buildOperationPrompt', () => {
+  it('renders the full prompt for an operation with components and samples', () => {
+    const { system, user } = buildOperationPrompt({
+      path: '/users/{userId}',
+      method: 'get',
+      operation: {
+        operationId: 'get-users-userId',
+        parameters: [{ name: 'userId', in: 'path', required: true, schema: { type: 'integer' } }],
+        responses: {
+          '200': {
+            description: 'OK',
+            content: { 'application/json': { schema: { $ref: '#/components/schemas/User' } } },
+          },
+        },
+      },
+      components: {
+        User: { type: 'object', properties: { id: { type: 'integer' }, name: { type: 'string' } } },
+      },
+      reservedComponentNames: ['Order', 'Error'],
+      samples: [
+        {
+          method: 'GET',
+          path: '/users/42',
+          query: 'expand=profile',
+          status: 200,
+          responseContentType: 'application/json',
+          responseBody: '{"id":42,"name":"Jane"}',
+        },
+      ],
+    });
+
+    expect(system).toMatchSnapshot();
+    expect(user).toMatchSnapshot();
+  });
+});
diff --git a/packages/cli/src/commands/generate-spec/__tests__/providers.test.ts b/packages/cli/src/commands/generate-spec/__tests__/providers.test.ts
new file mode 100644
index 0000000000..8284a09449
--- /dev/null
+++ b/packages/cli/src/commands/generate-spec/__tests__/providers.test.ts
@@ -0,0 +1,94 @@
+import { spawn } from 'node:child_process';
+import { EventEmitter } from 'node:events';
+
+import { runProvider } from '../ai/providers.js';
+
+vi.mock('node:child_process', () => ({ spawn: vi.fn() }));
+vi.mock('node:fs/promises', () => ({
+  mkdtemp: vi.fn(async () => '/tmp/generate-spec-empty'),
+}));
+
+function stubChildProcess(stdout: string) {
+  const child = new EventEmitter() as EventEmitter & {
+    stdout: EventEmitter;
+    stderr: EventEmitter;
+    stdin: EventEmitter & { end: (input: string) => void };
+  };
+  child.stdout = new EventEmitter();
+  child.stderr = new EventEmitter();
+  child.stdin = Object.assign(new EventEmitter(), {
+    end: () => {
+      child.stdout.emit('data', Buffer.from(stdout));
+      child.emit('close', 0);
+    },
+  });
+  return child;
+}
+
+describe('runProvider', () => {
+  beforeEach(() => {
+    vi.mocked(spawn).mockClear();
+    // The stub is not a full ChildProcess; only the pieces runCommand touches.
+    vi.mocked(spawn).mockReturnValue(
+      stubChildProcess('refined output') as unknown as ReturnType<typeof spawn>
+    );
+  });
+
+  it('runs the claude CLI isolated from the local configuration', async () => {
+    const result = await runProvider('claude', { system: 'sys prompt', user: 'user prompt' });
+
+    expect(result.text).toBe('refined output');
+    expect(spawn).toHaveBeenCalledWith(
+      'claude',
+      [
+        '-p',
+        '--output-format',
+        'text',
+        '--tools',
+        '',
+        '--strict-mcp-config',
+        '--setting-sources',
+        '',
+        '--no-session-persistence',
+        '--append-system-prompt',
+        'sys prompt',
+      ],
+      expect.objectContaining({
+        cwd: '/tmp/generate-spec-empty',
+        env: expect.objectContaining({ CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: '1' }),
+      })
+    );
+  });
+
+  it('runs the codex CLI without MCP servers and project docs', async () => {
+    await runProvider('codex', { system: 'sys prompt', user: 'user prompt', model: 'gpt-5' });
+
+    expect(spawn).toHaveBeenCalledWith(
+      'codex',
+      [
+        'exec',
+        '--skip-git-repo-check',
+        '--sandbox',
+        'read-only',
+        '-c',
+        'mcp_servers={}',
+        '-c',
+        'project_doc_max_bytes=0',
+        '--model',
+        'gpt-5',
+        '-',
+      ],
+      expect.objectContaining({ cwd: '/tmp/generate-spec-empty' })
+    );
+  });
+
+  it('runs the cursor CLI with the workspace trusted', async () => {
+    await runProvider('cursor', { system: 'sys prompt', user: 'user prompt' });
+
+    expect(spawn).toHaveBeenCalledWith(
+      'cursor-agent',
+      ['-p', '--output-format', 'text', '--trust', 'sys prompt'],
+      expect.objectContaining({ cwd: '/tmp/generate-spec-empty' })
+    );
+  });
+});
diff --git a/packages/cli/src/commands/generate-spec/__tests__/refine.test.ts b/packages/cli/src/commands/generate-spec/__tests__/refine.test.ts
new file mode 100644
index 0000000000..001965ab77
--- /dev/null
+++ b/packages/cli/src/commands/generate-spec/__tests__/refine.test.ts
@@ -0,0 +1,290 @@
+import { logger } from '@redocly/openapi-core';
+
+import { CliNotFoundError, runProvider } from '../ai/providers.js';
+import { refineSpecWithAi } from '../ai/refine.js';
+import type { GeneratedDocument } from '../generator.js';
+
+vi.mock('../ai/providers.js', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('../ai/providers.js')>()),
+  runProvider: vi.fn(),
+}));
+
+function baseline(): GeneratedDocument {
+  return {
+    openapi: '3.2.0',
+    info: { title: 'Test API', version: '1.0.0' },
+    paths: {
+      '/users': {
+        get: {
+          operationId: 'get-users',
+          responses: {
+            '200': {
+              description: 'OK',
+              content: {
+                'application/json': { schema: { $ref: '#/components/schemas/User' } },
+              },
+            },
+          },
+        },
+        post: {
+          operationId: 'post-users',
+          responses: { '201': { description: 'Created' } },
+        },
+      },
+    },
+    components: {
+      schemas: {
+        User: {
+          type: 'object',
+          properties: { id: { type: 'integer' }, name: { type: 'string' } },
+          required: ['id', 'name'],
+        },
+      },
+    },
+  };
+}
+
+const refinedGetUsers = `paths:
+  /users:
+    get:
+      operationId: listUsers
+      summary: List users
+      responses:
+        '200':
+          description: A list of users
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/User'
+components:
+  schemas:
+    User:
+      type: object
+      description: A user account
+      properties:
+        id:
+          type: integer
+        name:
+          type: string
+      required:
+        - id
+`;
+
+const refinedPostUsers = `paths:
+  /users:
+    post:
+      operationId: createUser
+      summary: Create a user
+      responses:
+        '201':
+          description: Created
+`;
+
+function mockResponses(...texts: string[]) {
+  for (const text of texts) {
+    vi.mocked(runProvider).mockResolvedValueOnce({ text });
+  }
+}
+
+async function refine(document = baseline()) {
+  return refineSpecWithAi({
+    provider: 'claude',
+    baseline: document,
+    samplesByOperation: new Map(),
+  });
+}
+
+describe('refineSpecWithAi', () => {
+  beforeEach(() => {
+    vi.mocked(runProvider).mockReset();
+    vi.spyOn(logger, 'info').mockImplementation(() => true);
+    vi.spyOn(logger, 'warn').mockImplementation(() => true);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('refines operations one by one and merges the results', async () => {
+    mockResponses(refinedGetUsers, refinedPostUsers);
+    const result = await refine();
+    expect(vi.mocked(runProvider)).toHaveBeenCalledTimes(2);
+    expect(result.refined).toBe(2);
+    expect(result.total).toBe(2);
+    expect(result.yaml).toContain('summary: List users');
+    expect(result.yaml).toContain('operationId: createUser');
+    expect(result.yaml).toContain('description: A user account');
+  });
+
+  it('sends each operation a focused prompt with only its referenced components', async () => {
+    mockResponses(refinedGetUsers, refinedPostUsers);
+    await refine();
+    const [firstRequest, secondRequest] = vi
+      .mocked(runProvider)
+      .mock.calls.map(([, request]) => request);
+    expect(firstRequest.user).toContain('Component schemas referenced by this operation');
+    expect(firstRequest.user).toContain('User:');
+    expect(secondRequest.user).not.toContain('Component schemas referenced by this operation');
+    expect(secondRequest.user).toContain('Reserved component names');
+  });
+
+  it('lets later operations see components refined earlier', async () => {
+    const document = baseline();
+    document.paths['/users/{userId}'] = {
+      get: {
+        operationId: 'get-users-userId',
+        parameters: [{ name: 'userId', in: 'path', required: true, schema: { type: 'integer' } }],
+        responses: {
+          '200': {
+            description: 'OK',
+            content: { 'application/json': { schema: { $ref: '#/components/schemas/User' } } },
+          },
+        },
+      },
+    };
+    const refinedGetUser = `paths:
+  /users/{userId}:
+    get:
+      operationId: getUser
+      parameters:
+        - name: userId
+          in: path
+          required: true
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: A user
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/User'
+`;
+    mockResponses(refinedGetUsers, refinedPostUsers, refinedGetUser);
+    const result = await refine(document);
+    expect(result.refined).toBe(3);
+    const thirdRequest = vi.mocked(runProvider).mock.calls[2][1];
+    expect(thirdRequest.user).toContain('description: A user account');
+  });
+
+  it('refines operations in parallel when concurrency is greater than 1', async () => {
+    const resolvers: ((result: { text: string }) => void)[] = [];
+    vi.mocked(runProvider).mockImplementation(
+      () =>
+        new Promise((resolve) => {
+          resolvers.push(resolve);
+        })
+    );
+    const resultPromise = refineSpecWithAi({
+      provider: 'claude',
+      baseline: baseline(),
+      samplesByOperation: new Map(),
+      concurrency: 2,
+    });
+    await vi.waitFor(() => expect(resolvers).toHaveLength(2));
+    resolvers[0]({ text: refinedGetUsers });
+    resolvers[1]({ text: refinedPostUsers });
+    const result = await resultPromise;
+    expect(result.refined).toBe(2);
+    expect(result.yaml).toContain('summary: List users');
+    expect(result.yaml).toContain('operationId: createUser');
+  });
+
+  it('strips Markdown code fences before parsing', async () => {
+    mockResponses(`\`\`\`yaml\n${refinedGetUsers}\n\`\`\``, refinedPostUsers);
+    const result = await refine();
+    expect(result.refined).toBe(2);
+    expect(result.yaml).toContain('summary: List users');
+  });
+
+  it('keeps the baseline operation when the provider returns invalid YAML', async () => {
+    mockResponses('paths: [invalid', refinedPostUsers);
+    const result = await refine();
+    expect(result.refined).toBe(1);
+    expect(result.yaml).toContain('operationId: get-users');
+    expect(result.yaml).toContain('operationId: createUser');
+    expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining('kept the baseline'));
+  });
+
+  it('keeps the baseline operation when the response misses the operation', async () => {
+    mockResponses(refinedPostUsers, refinedPostUsers);
+    const result = await refine();
+    expect(result.refined).toBe(1);
+    expect(logger.warn).toHaveBeenCalledWith(
+      expect.stringContaining('does not contain the GET operation')
+    );
+  });
+
+  it('keeps the baseline operation when the operationId is dropped', async () => {
+    mockResponses(refinedGetUsers.replace('      operationId: listUsers\n', ''), refinedPostUsers);
+    const result = await refine();
+    expect(result.refined).toBe(1);
+    expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining('dropped the operationId'));
+  });
+
+  it('keeps the baseline operation when the response redefines a reserved component', async () => {
+    const redefiningUser = `${refinedPostUsers}components:
+  schemas:
+    User:
+      type: string
+`;
+    mockResponses(refinedGetUsers, redefiningUser);
+    const result = await refine();
+    expect(result.refined).toBe(1);
+    expect(logger.warn).toHaveBeenCalledWith(
+      expect.stringContaining('redefines reserved component(s): User')
+    );
+  });
+
+  it('keeps the baseline operation when an observed status code is dropped', async () => {
+    mockResponses(refinedGetUsers.replace("'200':", "'404':"), refinedPostUsers);
+    const result = await refine();
+    expect(result.refined).toBe(1);
+    expect(logger.warn).toHaveBeenCalledWith(
+      expect.stringContaining('dropped observed response status(es): 200')
+    );
+  });
+
+  it('keeps the baseline operation when the refined operation fails validation', async () => {
+    mockResponses(
+      refinedGetUsers.replace('description: A list of users', 'descriptio: A list of users'),
+      refinedPostUsers
+    );
+    const result = await refine();
+    expect(result.refined).toBe(1);
+    expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining('validation problem'));
+  });
+
+  it('prunes components that are no longer referenced', async () => {
+    const inlineGetUsers = `paths:
+  /users:
+    get:
+      operationId: listUsers
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+`;
+    mockResponses(inlineGetUsers, refinedPostUsers);
+    const result = await refine();
+    expect(result.refined).toBe(2);
+    expect(result.document.components).toBeUndefined();
+    expect(result.yaml).not.toContain('components:');
+  });
+
+  it('aborts refinement when the provider CLI is not installed', async () => {
+    vi.mocked(runProvider).mockRejectedValue(
+      new CliNotFoundError('Could not find the "claude" CLI on PATH. Is it installed?')
+    );
+    await expect(refine()).rejects.toThrow('Could not find the "claude" CLI');
+    expect(vi.mocked(runProvider)).toHaveBeenCalledTimes(1);
+  });
+
+  it('rejects when no operation could be refined', async () => {
+    vi.mocked(runProvider).mockResolvedValue({ text: 'Sorry, I cannot help with that.' });
+    await expect(refine()).rejects.toThrow('did not produce a usable refinement for any operation');
+  });
+});
diff --git a/packages/cli/src/commands/generate-spec/__tests__/samples.test.ts b/packages/cli/src/commands/generate-spec/__tests__/samples.test.ts
new file mode 100644
index 0000000000..272c8438ca
--- /dev/null
+++ b/packages/cli/src/commands/generate-spec/__tests__/samples.test.ts
@@ -0,0 +1,132 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { collectTrafficSamples } from '../samples.js';
+
+function exchange(method: string, url: string, requestBody?: object, responseBody?: object) {
+  return JSON.stringify({
+    request: {
+      method,
+      url,
+      headers: {
+        host: 'api.example.com',
+        ...(requestBody ? { 'content-type': 'application/json' } : {}),
+      },
+      ...(requestBody ? { body: JSON.stringify(requestBody) } : {}),
+    },
+    response: {
+      status: 200,
+      headers: { 'content-type': 'application/json' },
+      ...(responseBody ? { body: JSON.stringify(responseBody) } : {}),
+    },
+  });
+}
+
+describe('collectTrafficSamples', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'generate-spec-samples-'));
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  function writeTraffic(lines: string[]): string {
+    const file = join(dir, 'traffic.ndjson');
+    writeFileSync(file, lines.join('\n'));
+    return file;
+  }
+
+  it('groups samples by operation and caps repeated identical shapes', async () => {
+    const lines = Array.from({ length: 45 }, (_, i) =>
+      exchange('GET', `http://api.example.com/users/${i + 1}`, undefined, { id: i + 1 })
+    );
+    lines.push(exchange('GET', 'http://api.example.com/orders', undefined, { orders: [] }));
+
+    const samples = await collectTrafficSamples({
+      trafficPath: writeTraffic(lines),
+      format: 'auto',
+    });
+
+    expect([...samples.keys()].sort()).toEqual(['GET /orders', 'GET /users/{userId}']);
+    expect(samples.get('GET /orders')).toHaveLength(1);
+    expect(samples.get('GET /users/{userId}')).toHaveLength(2);
+  });
+
+  it('keeps samples of each observed body shape and fills groups round-robin', async () => {
+    const lines = [
+      exchange('POST', 'http://api.example.com/payments', { type: 'card', cardNumber: '41' }),
+      exchange('POST', 'http://api.example.com/payments', { type: 'card', cardNumber: '55' }),
+      exchange('POST', 'http://api.example.com/payments', { type: 'bank', iban: 'DE' }),
+      exchange('POST', 'http://api.example.com/payments', { type: 'bank', iban: 'FR' }),
+    ];
+
+    const samples = await collectTrafficSamples({
+      trafficPath: writeTraffic(lines),
+      format: 'auto',
+      perOperation: 2,
+    });
+
+    const payments = samples.get('POST /payments');
+    expect(payments).toHaveLength(2);
+    expect(payments?.some((sample) => sample.requestBody?.includes('cardNumber'))).toBe(true);
+    expect(payments?.some((sample) => sample.requestBody?.includes('iban'))).toBe(true);
+  });
+
+  it('truncates long bodies', async () => {
+    const lines = [exchange('POST', 'http://api.example.com/blobs', { data: 'x'.repeat(500) })];
+
+    const samples = await collectTrafficSamples({
+      trafficPath: writeTraffic(lines),
+      format: 'auto',
+      maxBodyChars: 50,
+    });
+
+    const blob = samples.get('POST /blobs')?.[0];
+    expect(blob?.requestBody).toHaveLength(50 + '…[truncated]'.length);
+    expect(blob?.requestBody?.endsWith('…[truncated]')).toBe(true);
+  });
+
+  it('ignores response data for statuses below 100', async () => {
+    const neverReceived = JSON.stringify({
+      request: {
+        method: 'GET',
+        url: 'http://api.example.com/users',
+        headers: { host: 'api.example.com' },
+      },
+      response: {
+        status: 0,
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ error: 'aborted' }),
+      },
+    });
+
+    const samples = await collectTrafficSamples({
+      trafficPath: writeTraffic([neverReceived]),
+      format: 'auto',
+    });
+
+    const users = samples.get('GET /users');
+    expect(users).toHaveLength(1);
+    expect(users?.[0].status).toBeUndefined();
+    expect(users?.[0].responseBody).toBeUndefined();
+    expect(users?.[0].responseContentType).toBeUndefined();
+  });
+
+  it('ignores exchanges with unsupported HTTP methods', async () => {
+    const lines = [
+      exchange('CONNECT', 'http://api.example.com/tunnel'),
+      exchange('GET', 'http://api.example.com/users'),
+    ];
+
+    const samples = await collectTrafficSamples({
+      trafficPath: writeTraffic(lines),
+      format: 'auto',
+    });
+
+    expect([...samples.keys()]).toEqual(['GET /users']);
+  });
+});
diff --git a/packages/cli/src/commands/generate-spec/__tests__/value-inference.test.ts b/packages/cli/src/commands/generate-spec/__tests__/value-inference.test.ts
new file mode 100644
index 0000000000..9ac5465acb
--- /dev/null
+++ b/packages/cli/src/commands/generate-spec/__tests__/value-inference.test.ts
@@ -0,0 +1,250 @@
+import { extractSchemaComponents } from '../components.js';
+import {
+  type GeneratedDocument,
+  inferSchema,
+  type JsonSchema,
+  mergeSchemas,
+} from '../generator.js';
+import { applyValueInference } from '../value-inference.js';
+
+function documentWithSchema(schema: JsonSchema, path = '/things/{thingId}'): GeneratedDocument {
+  return {
+    openapi: '3.2.0',
+    info: { title: 'Test API', version: '1.0.0' },
+    paths: {
+      [path]: {
+        get: {
+          operationId: 'read',
+          responses: {
+            '200': { description: 'ok', content: { 'application/json': { schema } } },
+          },
+        },
+      },
+    },
+  };
+}
+
+function inferredResponseSchema(
+  document: GeneratedDocument,
+  path = '/things/{thingId}'
+): JsonSchema {
+  return document.paths[path].get.responses['200'].content!['application/json'].schema;
+}
+
+function inferMerged(values: unknown[]): JsonSchema {
+  return mergeSchemas(values.map(inferSchema));
+}
+
+describe('applyValueInference', () => {
+  it('detects well-known string formats from a single observation', () => {
+    const schema = inferredResponseSchema(
+      applyValueInference(
+        documentWithSchema(
+          inferSchema({
+            id: 'f47ac10b-58cc-4372-a567-0e02b2c3d479',
+            createdAt: '2024-06-01T10:30:00Z',
+            birthday: '1990-01-31',
+            email: 'ada@example.com',
+            website: 'https://example.com/ada',
+            lastIp: '192.168.0.1',
+            name: 'Ada',
+          })
+        )
+      )
+    );
+
+    expect(schema.properties?.id).toEqual({ type: 'string', format: 'uuid' });
+    expect(schema.properties?.createdAt).toEqual({ type: 'string', format: 'date-time' });
+    expect(schema.properties?.birthday).toEqual({ type: 'string', format: 'date' });
+    expect(schema.properties?.email).toEqual({ type: 'string', format: 'email' });
+    expect(schema.properties?.website).toEqual({ type: 'string', format: 'uri' });
+    expect(schema.properties?.lastIp).toEqual({ type: 'string', format: 'ipv4' });
+    expect(schema.properties?.name).toEqual({ type: 'string' });
+  });
+
+  it('drops a format as soon as one observed value does not match it', () => {
+    const schema = inferredResponseSchema(
+      applyValueInference(
+        documentWithSchema(
+          inferMerged([{ ref: 'f47ac10b-58cc-4372-a567-0e02b2c3d479' }, { ref: 'latest' }])
+        )
+      )
+    );
+
+    expect(schema.properties?.ref).toEqual({ type: 'string' });
+  });
+
+  it('detects an enum from repeated identifier-like values', () => {
+    const schema = inferredResponseSchema(
+      applyValueInference(
+        documentWithSchema(
+          inferMerged([
+            { status: 'active' },
+            { status: 'inactive' },
+            { status: 'active' },
+            { status: 'inactive' },
+          ])
+        )
+      )
+    );
+
+    expect(schema.properties?.status).toEqual({ type: 'string', enum: ['active', 'inactive'] });
+  });
+
+  it('does not emit an enum without enough repeated observations', () => {
+    const twoObservations = inferredResponseSchema(
+      applyValueInference(
+        documentWithSchema(inferMerged([{ status: 'active' }, { status: 'inactive' }]))
+      )
+    );
+    expect(twoObservations.properties?.status).toEqual({ type: 'string' });
+
+    const noRepetition = inferredResponseSchema(
+      applyValueInference(
+        documentWithSchema(
+          inferMerged([{ name: 'Ada' }, { name: 'Grace' }, { name: 'Linus' }, { name: 'Barbara' }])
+        )
+      )
+    );
+    expect(noRepetition.properties?.name).toEqual({ type: 'string' });
+  });
+
+  it('does not emit an enum for free-text or identifier-token values', () => {
+    const freeText = inferredResponseSchema(
+      applyValueInference(
+        documentWithSchema(
+          inferMerged([
+            { note: 'out of stock' },
+            { note: 'out of stock' },
+            { note: 'back soon' },
+            { note: 'back soon' },
+          ])
+        )
+      )
+    );
+    expect(freeText.properties?.note).toEqual({ type: 'string' });
+
+    const hexTokens = inferredResponseSchema(
+      applyValueInference(
+        documentWithSchema(
+          inferMerged([
+            { blob: 'a3f5c9d2e8b1470f' },
+            { blob: 'a3f5c9d2e8b1470f' },
+            { blob: 'b4e6d0e3f9c2581a' },
+            { blob: 'b4e6d0e3f9c2581a' },
+          ])
+        )
+      )
+    );
+    expect(hexTokens.properties?.blob).toEqual({ type: 'string' });
+  });
+
+  it('applies formats but not enums to nullable string unions', () => {
+    const schema = inferredResponseSchema(
+      applyValueInference(
+        documentWithSchema(
+          inferMerged([
+            { deletedAt: '2024-06-01T10:30:00Z', kind: 'a' },
+            { deletedAt: null, kind: 'b' },
+            { deletedAt: '2024-06-02T11:00:00Z', kind: 'a' },
+            { deletedAt: null, kind: 'b' },
+          ])
+        )
+      )
+    );
+
+    expect(schema.properties?.deletedAt).toEqual({ type: ['string', 'null'], format: 'date-time' });
+    expect(schema.properties?.kind).toEqual({ type: 'string', enum: ['a', 'b'] });
+  });
+
+  it('prefers a format over an enum when both would apply', () => {
+    const schema = inferredResponseSchema(
+      applyValueInference(
+        documentWithSchema(
+          inferMerged([
+            { contact: 'a@example.com' },
+            { contact: 'b@example.com' },
+            { contact: 'a@example.com' },
+            { contact: 'b@example.com' },
+          ])
+        )
+      )
+    );
+
+    expect(schema.properties?.contact).toEqual({ type: 'string', format: 'email' });
+  });
+
+  it('gives up on an enum once too many distinct values were observed', () => {
+    const samples = Array.from({ length: 24 }, (_, index) => ({ code: `code${index % 12}` }));
+    const schema = inferredResponseSchema(
+      applyValueInference(documentWithSchema(inferMerged(samples)))
+    );
+
+    expect(schema.properties?.code).toEqual({ type: 'string' });
+  });
+
+  it('pools observations across operations into an extracted component', () => {
+    const document: GeneratedDocument = {
+      openapi: '3.2.0',
+      info: { title: 'Test API', version: '1.0.0' },
+      paths: {
+        '/users': {
+          get: {
+            operationId: 'list',
+            responses: {
+              '200': {
+                description: 'ok',
+                content: {
+                  'application/json': {
+                    schema: inferMerged([
+                      { id: 1, role: 'admin' },
+                      { id: 2, role: 'member' },
+                    ]),
+                  },
+                },
+              },
+            },
+          },
+        },
+        '/users/{userId}': {
+          get: {
+            operationId: 'read',
+            responses: {
+              '200': {
+                description: 'ok',
+                content: {
+                  'application/json': {
+                    schema: inferMerged([
+                      { id: 3, role: 'admin' },
+                      { id: 4, role: 'admin' },
+                    ]),
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    };
+
+    const result = applyValueInference(extractSchemaComponents(document));
+
+    expect(result.components?.schemas.User.properties?.role).toEqual({
+      type: 'string',
+      enum: ['admin', 'member'],
+    });
+  });
+
+  it('infers enums for repeated array item values', () => {
+    const schema = inferredResponseSchema(
+      applyValueInference(
+        documentWithSchema(inferSchema({ tags: ['new', 'sale', 'new', 'sale'], id: 1 }))
+      )
+    );
+
+    expect(schema.properties?.tags).toEqual({
+      type: 'array',
+      items: { type: 'string', enum: ['new', 'sale'] },
+    });
+  });
+});
diff --git a/packages/cli/src/commands/generate-spec/ai/prompt.ts b/packages/cli/src/commands/generate-spec/ai/prompt.ts
new file mode 100644
index 0000000000..47434208bf
--- /dev/null
+++ b/packages/cli/src/commands/generate-spec/ai/prompt.ts
@@ -0,0 +1,112 @@
+import { stringifyYaml } from '@redocly/openapi-core';
+
+import type { TrafficSample } from '../samples.js';
+
+const SYSTEM_INSTRUCTIONS = `You are an expert API designer. You are given one operation from an OpenAPI 3.2 description that was inferred mechanically from recorded HTTP traffic, the component schemas it references, and a sample of the real recorded HTTP exchanges for that operation. The inferred description is only a hypothesis: types are coarse, every observed property is marked required, and descriptions are missing. Alternative body shapes observed in the traffic appear as "oneOf" variants or type unions. Common string formats (uuid, date-time, date, email, uri, ipv4) and small closed enums are detected conservatively from the observed values.
+
+Refine the operation into the most accurate OpenAPI 3.2 definition you can justify from the evidence, while staying conservative:
+- Keep the path template and the HTTP method exactly as given. Do not rename path parameters, do not move parameters to the path item level, and keep every response status code. The result is programmatically checked and rejected otherwise.
+- Keep the operationId unless it is clearly wrong.
+- Narrow property types where the samples clearly support it (formats such as date-time, uuid, email, uri; integer vs number; enums when a field only ever takes a small fixed set of values). Verify the formats and enums already detected against the samples; correct or extend them where justified. The detected formats and enums were derived from the full recorded traffic while you see only a subset of it, so never remove a detected format or enum value merely because the samples do not show it — correct one only when a sample contradicts it.
+- Relax "required" for properties that are plausibly optional (e.g. absent in some samples, or clearly nullable). Express nullable values as type unions such as ["string", "null"].
+- When a request or response body has alternative shapes — the baseline shows "oneOf" variants, or the samples show clearly different payloads — model them explicitly with "oneOf". Name each variant in components/schemas, and add a "discriminator" when a property (such as "type" or "kind") selects the variant.
+- Factor structure shared between variants or schemas with "allOf": extract the common base into components/schemas and compose each variant as "allOf" of the base plus its specific properties.
+- Keep the $ref references to the component schemas you were given. You may refine the definition of a referenced component when the samples justify it, and you may add new components, but never rename an existing component and never reuse a reserved component name listed in the input.
+- Add concise, useful "summary" and "description" fields to the operation, its parameters and important schema properties.
+- Add example values drawn from the real samples where helpful, but never copy values that look like secrets or personal data (tokens, API keys, passwords, session identifiers, email addresses, personal names); use clearly fictional placeholder values instead.
+
+Output ONLY a YAML document with this exact top-level structure:
+
+paths:
+  <the path template exactly as given>:
+    <the method>:
+      ...the refined operation...
+components:
+  schemas:
+    ...only the component schemas you changed or added; omit "components" entirely when there are none...
+
+Do not wrap the output in Markdown code fences. Do not add any commentary before or after the document.`;
+
+function renderSamples(samples: TrafficSample[]): string {
+  if (samples.length === 0) {
+    return '(no sample exchanges were captured)';
+  }
+  return samples
+    .map((sample, index) => {
+      const lines: string[] = [];
+      const query = sample.query ? `?${sample.query}` : '';
+      lines.push(`### Exchange ${index + 1}`);
+      lines.push(`${sample.method} ${sample.path}${query}`);
+      if (sample.requestContentType) {
+        lines.push(`Request Content-Type: ${sample.requestContentType}`);
+      }
+      if (sample.requestBody) {
+        lines.push(`Request body: ${sample.requestBody}`);
+      }
+      if (sample.status !== undefined) {
+        lines.push(`Response status: ${sample.status}`);
+      }
+      if (sample.responseContentType) {
+        lines.push(`Response Content-Type: ${sample.responseContentType}`);
+      }
+      if (sample.responseBody) {
+        lines.push(`Response body: ${sample.responseBody}`);
+      }
+      return lines.join('\n');
+    })
+    .join('\n\n');
+}
+
+export interface BuildOperationPromptOptions {
+  path: string;
+  method: string;
+  operation: unknown;
+  /** Current definitions of the components the operation references (transitively). */
+  components: Record<string, unknown>;
+  /** Names of all other components in the description; the AI must not reuse them. */
+  reservedComponentNames: string[];
+  samples: TrafficSample[];
+}
+
+/**
+ * Build a self-contained prompt for refining a single operation. The claude
+ * and cursor providers receive the instructions and the content separately;
+ * codex receives them concatenated on stdin.
+ */
+export function buildOperationPrompt(options: BuildOperationPromptOptions): {
+  system: string;
+  user: string;
+} {
+  const sections: string[] = [];
+
+  sections.push(
+    `# Operation to refine (inferred from traffic)\n\n\`\`\`yaml\n${stringifyYaml({
+      paths: { [options.path]: { [options.method]: options.operation } },
+    })}\`\`\``
+  );
+
+  if (Object.keys(options.components).length > 0) {
+    sections.push(
+      `# Component schemas referenced by this operation (current definitions)\n\n\`\`\`yaml\n${stringifyYaml(
+        { components: { schemas: options.components } }
+      )}\`\`\``
+    );
+  }
+
+  if (options.reservedComponentNames.length > 0) {
+    sections.push(
+      `# Reserved component names (used elsewhere in the description; do not redefine or reuse them)\n\n${options.reservedComponentNames.join(
+        ', '
+      )}`
+    );
+  }
+
+  sections.push(
+    `# Recorded HTTP exchanges for this operation\n\n${renderSamples(options.samples)}`
+  );
+  sections.push(
+    `Refine ${options.method.toUpperCase()} ${options.path} as instructed and output only the YAML document.`
+  );
+
+  return { system: SYSTEM_INSTRUCTIONS, user: sections.join('\n\n') };
+}
diff --git a/packages/cli/src/commands/generate-spec/ai/providers.ts b/packages/cli/src/commands/generate-spec/ai/providers.ts
new file mode 100644
index 0000000000..2d86b7fe23
--- /dev/null
+++ b/packages/cli/src/commands/generate-spec/ai/providers.ts
@@ -0,0 +1,213 @@
+import { spawn } from 'node:child_process';
+import { mkdtemp } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+export type AiProvider = 'claude' | 'codex' | 'cursor';
+
+export const AI_RESPONSE_TIMEOUT_MS = 300_000;
+
+export class CliNotFoundError extends Error {}
+
+export interface ProviderRequest {
+  system: string;
+  user: string;
+  model?: string;
+}
+
+export interface ProviderResult {
+  text: string;
+}
+
+// All provider CLIs pull project context (CLAUDE.md, AGENTS.md, .cursor/rules)
+// from the working directory into every prompt; running them from an empty
+// directory keeps that context out and each invocation fast.
+let emptyCwdPromise: Promise<string> | undefined;
+
+function getEmptyCwd(): Promise<string> {
+  emptyCwdPromise ??= mkdtemp(path.join(tmpdir(), 'redocly-generate-spec-'));
+  return emptyCwdPromise;
+}
+
+async function runCommand(
+  command: string,
+  args: string[],
+  stdin: string,
+  env?: Record<string, string>
+): Promise<{ stdout: string; stderr: string; code: number | null }> {
+  const cwd = await getEmptyCwd();
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      cwd,
+      env: { ...process.env, ...env },
+    });
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill('SIGKILL');
+    }, AI_RESPONSE_TIMEOUT_MS);
+
+    child.stdout.on('data', (chunk: Buffer) => {
+      stdout += chunk.toString();
+    });
+    child.stderr.on('data', (chunk: Buffer) => {
+      stderr += chunk.toString();
+    });
+    child.on('error', (error: NodeJS.ErrnoException) => {
+      clearTimeout(timer);
+      if (error.code === 'ENOENT') {
+        reject(
+          new CliNotFoundError(`Could not find the "${command}" CLI on PATH. Is it installed?`)
+        );
+        return;
+      }
+      reject(error);
+    });
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      if (timedOut) {
+        reject(
+          new Error(
+            `The "${command}" CLI did not respond within ${AI_RESPONSE_TIMEOUT_MS / 1000} seconds.`
+          )
+        );
+        return;
+      }
+      resolve({ stdout, stderr, code });
+    });
+
+    // The CLI may exit before consuming the prompt; without a listener the
+    // resulting EPIPE on stdin would crash the process instead of surfacing
+    // through the "error"/"close" handlers above.
+    child.stdin.on('error', () => {});
+    child.stdin.end(stdin);
+  });
+}
+
+async function runClaude(request: ProviderRequest): Promise<ProviderResult> {
+  // The prompt is a pure text transform: disabling built-in tools, MCP
+  // servers, settings (with their hooks, skills, and plugins), and session
+  // persistence keeps each invocation a single-shot completion without the
+  // startup cost of the user's Claude Code configuration. Because settings
+  // are skipped, a model configured there does not apply — only --ai-model
+  // or the CLI's built-in default. The environment variable additionally
+  // skips update checks and auxiliary telemetry calls.
+  const args = [
+    '-p',
+    '--output-format',
+    'text',
+    '--tools',
+    '',
+    '--strict-mcp-config',
+    '--setting-sources',
+    '',
+    '--no-session-persistence',
+    '--append-system-prompt',
+    request.system,
+  ];
+  if (request.model) {
+    args.push('--model', request.model);
+  }
+  const { stdout, stderr, code } = await runCommand('claude', args, request.user, {
+    CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: '1',
+  });
+  if (code !== 0) {
+    throw new Error(`claude CLI exited with code ${code}: ${stderr.trim()}`);
+  }
+  if (!stdout.trim()) {
+    throw new Error('claude CLI returned no output.');
+  }
+  return { text: stdout };
+}
+
+async function runCodex(request: ProviderRequest): Promise<ProviderResult> {
+  // The config overrides skip the user's MCP servers and AGENTS.md discovery;
+  // the git-repo check must be skipped because the command runs from an empty
+  // temporary directory, which also makes the read-only sandbox safe.
+  const args = [
+    'exec',
+    '--skip-git-repo-check',
+    '--sandbox',
+    'read-only',
+    '-c',
+    'mcp_servers={}',
+    '-c',
+    'project_doc_max_bytes=0',
+  ];
+  if (request.model) {
+    args.push('--model', request.model);
+  }
+  args.push('-');
+  const prompt = `${request.system}\n\n${request.user}`;
+  const { stdout, stderr, code } = await runCommand('codex', args, prompt);
+  if (code !== 0) {
+    throw new Error(`codex CLI exited with code ${code}: ${stderr.trim()}`);
+  }
+  if (!stdout.trim()) {
+    throw new Error('codex CLI returned no output.');
+  }
+  return { text: stdout };
+}
+
+async function runCursor(request: ProviderRequest): Promise<ProviderResult> {
+  // --trust skips the workspace-trust prompt that would hang a headless run
+  // in the empty working directory. The Cursor CLI has no per-invocation
+  // option to disable MCP servers or rules; the empty directory at least
+  // keeps project-level configuration out.
+  const args = ['-p', '--output-format', 'text', '--trust'];
+  if (request.model) {
+    args.push('--model', request.model);
+  }
+  // The instructions go in as the prompt argument; the piped stdin is
+  // attached as context, mirroring how the claude provider splits the two.
+  args.push(request.system);
+
+  // The Cursor CLI originally installed a "cursor-agent" binary and later
+  // renamed it to "agent"; accept either.
+  let result;
+  try {
+    result = await runCommand('cursor-agent', args, request.user);
+  } catch (error) {
+    if (!(error instanceof CliNotFoundError)) {
+      throw error;
+    }
+    try {
+      result = await runCommand('agent', args, request.user);
+    } catch (fallbackError) {
+      if (fallbackError instanceof CliNotFoundError) {
+        throw new CliNotFoundError(
+          'Could not find the Cursor CLI ("cursor-agent" or "agent") on PATH. Is it installed?'
+        );
+      }
+      throw fallbackError;
+    }
+  }
+
+  const { stdout, stderr, code } = result;
+  if (code !== 0) {
+    throw new Error(`cursor CLI exited with code ${code}: ${stderr.trim()}`);
+  }
+  if (!stdout.trim()) {
+    throw new Error('cursor CLI returned no output.');
+  }
+  return { text: stdout };
+}
+
+export async function runProvider(
+  provider: AiProvider,
+  request: ProviderRequest
+): Promise<ProviderResult> {
+  switch (provider) {
+    case 'claude':
+      return runClaude(request);
+    case 'codex':
+      return runCodex(request);
+    case 'cursor':
+      return runCursor(request);
+    default:
+      throw new Error(`Unknown AI provider: ${provider}`);
+  }
+}
diff --git a/packages/cli/src/commands/generate-spec/ai/refine.ts b/packages/cli/src/commands/generate-spec/ai/refine.ts
new file mode 100644
index 0000000000..7daf60371b
--- /dev/null
+++ b/packages/cli/src/commands/generate-spec/ai/refine.ts
@@ -0,0 +1,358 @@
+import {
+  type Config,
+  createConfig,
+  isPlainObject,
+  lintFromString,
+  logger,
+  parseYaml,
+  stringifyYaml,
+} from '@redocly/openapi-core';
+import * as process from 'node:process';
+
+import { Spinner } from '../../../utils/spinner.js';
+import type { GeneratedDocument, GeneratedOperation } from '../generator.js';
+import { operationSampleKey, type TrafficSample } from '../samples.js';
+import { buildOperationPrompt } from './prompt.js';
+import { type AiProvider, CliNotFoundError, runProvider } from './providers.js';
+
+export interface RefineOptions {
+  provider: AiProvider;
+  model?: string;
+  baseline: GeneratedDocument;
+  samplesByOperation: Map<string, TrafficSample[]>;
+  /** Number of operations refined in parallel; defaults to 1 (sequential). */
+  concurrency?: number;
+}
+
+/** The baseline document with AI-refined operations and components merged in. */
+export type RefinedDocument = {
+  openapi: string;
+  info: { title: string; version: string };
+  servers?: { url: string }[];
+  paths: Record<string, Record<string, unknown>>;
+  components?: { schemas: Record<string, unknown> };
+};
+
+export interface RefineResult {
+  /** The refined description, normalized back to canonical YAML. */
+  yaml: string;
+  document: RefinedDocument;
+  /** Operations whose refinement was accepted; the rest kept their baseline. */
+  refined: number;
+  total: number;
+}
+
+interface OperationFragment {
+  operation: Record<string, unknown>;
+  components: Record<string, unknown>;
+}
+
+/** Strip Markdown code fences the model may have added despite instructions. */
+function stripCodeFences(text: string): string {
+  const trimmed = text.trim();
+  const fenceMatch = trimmed.match(/^```(?:ya?ml|json)?\s*\n([\s\S]*?)\n```$/);
+  return fenceMatch ? fenceMatch[1] : trimmed;
+}
+
+const COMPONENT_REF_RE = /^#\/components\/schemas\/(.+)$/;
+
+function collectComponentRefs(value: unknown, into: Set<string>): void {
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      collectComponentRefs(item, into);
+    }
+    return;
+  }
+  if (!isPlainObject(value)) {
+    return;
+  }
+  if (typeof value.$ref === 'string') {
+    const refMatch = value.$ref.match(COMPONENT_REF_RE);
+    if (refMatch) {
+      into.add(refMatch[1]);
+    }
+  }
+  for (const child of Object.values(value)) {
+    collectComponentRefs(child, into);
+  }
+}
+
+function transitivelyReferencedComponents(
+  root: unknown,
+  schemas: Record<string, unknown>
+): Set<string> {
+  const referenced = new Set<string>();
+  const pending: unknown[] = [root];
+  while (pending.length > 0) {
+    const names = new Set<string>();
+    collectComponentRefs(pending.pop(), names);
+    for (const name of names) {
+      if (!referenced.has(name) && name in schemas) {
+        referenced.add(name);
+        pending.push(schemas[name]);
+      }
+    }
+  }
+  return referenced;
+}
+
+/** Drop components no operation references anymore after refinement. */
+function pruneUnusedComponents(document: RefinedDocument): void {
+  const schemas = document.components?.schemas;
+  if (!schemas) {
+    return;
+  }
+  const used = transitivelyReferencedComponents(document.paths, schemas);
+  for (const name of Object.keys(schemas)) {
+    if (!used.has(name)) {
+      delete schemas[name];
+    }
+  }
+  if (Object.keys(schemas).length === 0) {
+    delete document.components;
+  }
+}
+
+function parseOperationFragment(text: string, path: string, method: string): OperationFragment {
+  const cleaned = stripCodeFences(text);
+  let parsed: unknown;
+  try {
+    parsed = parseYaml(cleaned);
+  } catch (error) {
+    throw new Error(
+      `the provider did not return valid YAML: ${
+        error instanceof Error ? error.message : String(error)
+      }`
+    );
+  }
+
+  if (!isPlainObject(parsed)) {
+    throw new Error('the response is not a YAML document with a "paths" object');
+  }
+  const paths = parsed.paths;
+  if (!isPlainObject(paths)) {
+    throw new Error('the response is not a YAML document with a "paths" object');
+  }
+  const pathItem = paths[path];
+  if (!isPlainObject(pathItem)) {
+    throw new Error(`the response does not keep the path template "${path}"`);
+  }
+  const operation = pathItem[method];
+  if (!isPlainObject(operation)) {
+    throw new Error(`the response does not contain the ${method.toUpperCase()} operation`);
+  }
+
+  const components = parsed.components;
+  const schemas = isPlainObject(components) ? components.schemas : undefined;
+  return { operation, components: isPlainObject(schemas) ? schemas : {} };
+}
+
+function missingStatuses(
+  baselineOperation: GeneratedOperation,
+  refinedOperation: Record<string, unknown>
+): string[] {
+  const responses = isPlainObject(refinedOperation.responses) ? refinedOperation.responses : {};
+  return Object.keys(baselineOperation.responses).filter((status) => !(status in responses));
+}
+
+async function lintDocumentSource(source: string, config: Config): Promise<void> {
+  const problems = await lintFromString({ source, config });
+  const errors = problems.filter((problem) => problem.severity === 'error');
+  if (errors.length > 0) {
+    const summary = errors
+      .slice(0, 5)
+      .map((problem) => `${problem.ruleId}: ${problem.message}`)
+      .join('; ');
+    throw new Error(`the result has ${errors.length} validation problem(s): ${summary}`);
+  }
+}
+
+interface RefineOperationOptions {
+  provider: AiProvider;
+  model?: string;
+  document: RefinedDocument;
+  path: string;
+  method: string;
+  operation: GeneratedOperation;
+  samples: TrafficSample[];
+  config: Config;
+}
+
+async function refineOperation(options: RefineOperationOptions): Promise<OperationFragment> {
+  const schemas = options.document.components?.schemas ?? {};
+  const referenced = transitivelyReferencedComponents(options.operation, schemas);
+  const components: Record<string, unknown> = {};
+  for (const name of referenced) {
+    components[name] = schemas[name];
+  }
+
+  const reservedComponentNames = Object.keys(schemas).filter((name) => !referenced.has(name));
+
+  const { system, user } = buildOperationPrompt({
+    path: options.path,
+    method: options.method,
+    operation: options.operation,
+    components,
+    reservedComponentNames,
+    samples: options.samples,
+  });
+
+  const { text } = await runProvider(options.provider, { system, user, model: options.model });
+  const fragment = parseOperationFragment(text, options.path, options.method);
+
+  const dropped = missingStatuses(options.operation, fragment.operation);
+  if (dropped.length > 0) {
+    throw new Error(`the response dropped observed response status(es): ${dropped.join(', ')}`);
+  }
+
+  if (typeof fragment.operation.operationId !== 'string') {
+    throw new Error('the response dropped the operationId');
+  }
+
+  const redefined = Object.keys(fragment.components).filter((name) =>
+    reservedComponentNames.includes(name)
+  );
+  if (redefined.length > 0) {
+    throw new Error(`the response redefines reserved component(s): ${redefined.join(', ')}`);
+  }
+
+  // Lint the refined operation against the description's full component set,
+  // so $refs to unchanged shared components still resolve.
+  const fragmentDocument = {
+    openapi: options.document.openapi,
+    info: options.document.info,
+    paths: { [options.path]: { [options.method]: fragment.operation } },
+    components: { schemas: { ...schemas, ...fragment.components } },
+  };
+  await lintDocumentSource(stringifyYaml(fragmentDocument), options.config);
+
+  return fragment;
+}
+
+function applyFragment(
+  document: RefinedDocument,
+  path: string,
+  method: string,
+  fragment: OperationFragment
+): void {
+  document.paths[path][method] = fragment.operation;
+  if (Object.keys(fragment.components).length > 0) {
+    document.components ??= { schemas: {} };
+    Object.assign(document.components.schemas, fragment.components);
+  }
+}
+
+function finishProgress(spinner: Spinner): void {
+  spinner.stop();
+  if (process.stderr.isTTY) {
+    // Erase the leftover spinner frame so the result line prints clean.
+    logger.info('\x1b[2K');
+  }
+}
+
+/**
+ * Refine the baseline one operation per prompt: each prompt carries only that
+ * operation, the components it references, and its own traffic samples, so
+ * prompt and response stay small no matter how large the description is.
+ * Up to `concurrency` operations are in flight at once and each accepted
+ * refinement is merged back as it arrives, so operations prompted later see
+ * already-refined shared components; when two concurrent refinements touch
+ * the same shared component the one merged last wins, and the final document
+ * lint still guards the result. An operation whose refinement is rejected
+ * keeps its baseline.
+ */
+export async function refineSpecWithAi(options: RefineOptions): Promise<RefineResult> {
+  const document: RefinedDocument = structuredClone(options.baseline);
+  const config = await createConfig({ extends: ['spec'] });
+
+  const operations: { path: string; method: string; operation: GeneratedOperation }[] = [];
+  for (const [path, pathItem] of Object.entries(options.baseline.paths)) {
+    for (const [method, operation] of Object.entries(pathItem)) {
+      operations.push({ path, method, operation });
+    }
+  }
+
+  const spinner = new Spinner();
+  const inFlight = new Set<string>();
+  let completed = 0;
+  let refined = 0;
+
+  const updateSpinner = () => {
+    const [firstLabel] = inFlight;
+    if (!firstLabel) {
+      return;
+    }
+    const others = inFlight.size > 1 ? ` (+${inFlight.size - 1} more)` : '';
+    spinner.start(`[${completed + 1}/${operations.length}] Refining ${firstLabel}${others}`);
+  };
+
+  let nextIndex = 0;
+  let aborted = false;
+  const worker = async () => {
+    while (!aborted && nextIndex < operations.length) {
+      const { path, method, operation } = operations[nextIndex++];
+      const label = `${method.toUpperCase()} ${path}`;
+      const startedAt = Date.now();
+      inFlight.add(label);
+      updateSpinner();
+      try {
+        const fragment = await refineOperation({
+          provider: options.provider,
+          model: options.model,
+          document,
+          path,
+          method,
+          operation,
+          samples: options.samplesByOperation.get(operationSampleKey(method, path)) ?? [],
+          config,
+        });
+        applyFragment(document, path, method, fragment);
+        refined += 1;
+        completed += 1;
+        inFlight.delete(label);
+        finishProgress(spinner);
+        logger.info(
+          `[${completed}/${operations.length}] ${label} — refined (${Math.round(
+            (Date.now() - startedAt) / 1000
+          )}s)\n`
+        );
+      } catch (error) {
+        completed += 1;
+        inFlight.delete(label);
+        finishProgress(spinner);
+        if (error instanceof CliNotFoundError) {
+          aborted = true;
+          throw error;
+        }
+        logger.warn(
+          `[${completed}/${operations.length}] ${label} — kept the baseline: ${
+            error instanceof Error ? error.message : String(error)
+          }\n`
+        );
+      }
+      updateSpinner();
+    }
+  };
+
+  const workers = Math.max(1, Math.min(options.concurrency ?? 1, operations.length));
+  // allSettled instead of all: when one worker aborts, the others finish the
+  // operation they are refining before the error propagates, so no worker is
+  // still logging progress after the command has fallen back to the baseline.
+  for (const result of await Promise.allSettled(Array.from({ length: workers }, worker))) {
+    if (result.status === 'rejected') {
+      throw result.reason;
+    }
+  }
+
+  if (refined === 0) {
+    throw new Error(
+      `the ${options.provider} provider did not produce a usable refinement for any operation`
+    );
+  }
+
+  pruneUnusedComponents(document);
+  const yaml = stringifyYaml(document);
+  await lintDocumentSource(yaml, config);
+
+  return { yaml, document, refined, total: operations.length };
+}
diff --git a/packages/cli/src/commands/generate-spec/components.ts b/packages/cli/src/commands/generate-spec/components.ts
new file mode 100644
index 0000000000..c952a1a68d
--- /dev/null
+++ b/packages/cli/src/commands/generate-spec/components.ts
@@ -0,0 +1,486 @@
+import { pluralize } from '@redocly/openapi-core';
+
+import { type GeneratedDocument, type JsonSchema, mergeSchemas } from './generator.js';
+import { copyObservations } from './value-inference.js';
+
+const MIN_COMPONENT_PROPERTIES = 2;
+const MIN_DISTINCT_CONTEXTS = 2;
+const NEAR_DUPLICATE_SIMILARITY = 0.75;
+const MAX_ENVELOPE_PROPERTIES = 2;
+const NUMERIC_TYPES = new Set(['integer', 'number']);
+
+type ShapeGroup = {
+  keys: string[];
+  schemas: JsonSchema[];
+  merged: JsonSchema;
+  contexts: Set<string>;
+  primaryVotes: Map<string, number>;
+  fallbackVotes: Map<string, number>;
+};
+
+type NamedGroup = {
+  group: ShapeGroup;
+  name: string;
+};
+
+type WalkContext = {
+  container: string;
+  path: string;
+  primaryHints: string[];
+  fallbackHints: string[];
+};
+
+const shapeKeyCache = new WeakMap<JsonSchema, string>();
+
+/**
+ * Canonical fingerprint of a schema's structure. `required` is intentionally
+ * excluded so that the same shape observed with different optionality (e.g. a
+ * list item vs a single resource) lands in the same group.
+ */
+function shapeKey(schema: JsonSchema): string {
+  const cached = shapeKeyCache.get(schema);
+  if (cached !== undefined) {
+    return cached;
+  }
+
+  let key: string;
+  if (schema.$ref !== undefined) {
+    key = `ref(${schema.$ref})`;
+  } else if (schema.oneOf) {
+    key = `oneOf(${schema.oneOf.map(shapeKey).sort().join('|')})`;
+  } else {
+    const type = Array.isArray(schema.type) ? [...schema.type].sort().join(',') : schema.type;
+    const parts = [`type=${type ?? ''}`];
+    if (schema.properties) {
+      const properties = Object.entries(schema.properties)
+        .map(([name, property]) => `${JSON.stringify(name)}:${shapeKey(property)}`)
+        .sort()
+        .join(',');
+      parts.push(`props{${properties}}`);
+    }
+    if (schema.additionalProperties) {
+      parts.push(`values(${shapeKey(schema.additionalProperties)})`);
+    }
+    if (schema.items) {
+      parts.push(`items(${shapeKey(schema.items)})`);
+    }
+    key = parts.join(';');
+  }
+
+  shapeKeyCache.set(schema, key);
+  return key;
+}
+
+function isExtractionCandidate(schema: JsonSchema): boolean {
+  return (
+    schema.$ref === undefined &&
+    schema.type === 'object' &&
+    schema.oneOf === undefined &&
+    schema.additionalProperties === undefined &&
+    Object.keys(schema.properties ?? {}).length >= MIN_COMPONENT_PROPERTIES
+  );
+}
+
+function addVotes(votes: Map<string, number>, hints: string[]): void {
+  for (const hint of hints) {
+    votes.set(hint, (votes.get(hint) ?? 0) + 1);
+  }
+}
+
+function collectShapes(
+  schema: JsonSchema,
+  context: WalkContext,
+  groups: Map<string, ShapeGroup>
+): void {
+  if (schema.oneOf) {
+    schema.oneOf.forEach((member, index) =>
+      collectShapes(
+        member,
+        { ...context, path: `${context.path}/oneOf/${index}`, fallbackHints: [] },
+        groups
+      )
+    );
+    return;
+  }
+
+  let childContainer = context.container;
+  let childPathPrefix = `${context.path}/`;
+
+  if (isExtractionCandidate(schema)) {
+    const key = shapeKey(schema);
+    let group = groups.get(key);
+    if (!group) {
+      group = {
+        keys: [key],
+        schemas: [],
+        merged: {},
+        contexts: new Set(),
+        primaryVotes: new Map(),
+        fallbackVotes: new Map(),
+      };
+      groups.set(key, group);
+    }
+    group.schemas.push(schema);
+    group.contexts.add(`${context.container}#${context.path}`);
+    addVotes(group.primaryVotes, context.primaryHints);
+    addVotes(group.fallbackVotes, context.fallbackHints);
+    childContainer = key;
+    childPathPrefix = '';
+  }
+
+  for (const [name, property] of Object.entries(schema.properties ?? {})) {
+    collectShapes(
+      property,
+      {
+        container: childContainer,
+        path: `${childPathPrefix}${name}`,
+        primaryHints: [name],
+        fallbackHints: [],
+      },
+      groups
+    );
+  }
+  if (schema.additionalProperties) {
+    collectShapes(
+      schema.additionalProperties,
+      {
+        container: childContainer,
+        path: `${childPathPrefix}additionalProperties`,
+        primaryHints: context.primaryHints.map((hint) => pluralize(hint, 1)),
+        fallbackHints: context.fallbackHints.map((hint) => pluralize(hint, 1)),
+      },
+      groups
+    );
+  }
+  if (schema.items) {
+    collectShapes(
+      schema.items,
+      {
+        container: childContainer,
+        path: `${childPathPrefix}items`,
+        primaryHints: context.primaryHints.map((hint) => pluralize(hint, 1)),
+        fallbackHints: context.fallbackHints.map((hint) => pluralize(hint, 1)),
+      },
+      groups
+    );
+  }
+}
+
+function lastStaticSegment(template: string): string | undefined {
+  const staticSegments = template
+    .split('/')
+    .filter((segment) => segment && !segment.startsWith('{'));
+  return staticSegments.at(-1);
+}
+
+function collectGroups(document: GeneratedDocument): Map<string, ShapeGroup> {
+  const groups = new Map<string, ShapeGroup>();
+
+  for (const [template, pathItem] of Object.entries(document.paths)) {
+    const entity = lastStaticSegment(template);
+    const base = entity ? pluralize(entity, 1) : undefined;
+
+    for (const [method, operation] of Object.entries(pathItem)) {
+      for (const [mime, media] of Object.entries(operation.requestBody?.content ?? {})) {
+        collectShapes(
+          media.schema,
+          {
+            container: `request ${method} ${template} ${mime}`,
+            path: '',
+            primaryHints: base ? [base] : [],
+            fallbackHints: base ? [`${base} request`] : [],
+          },
+          groups
+        );
+      }
+
+      for (const [status, response] of Object.entries(operation.responses)) {
+        const isError = Number(status) >= 400;
+        for (const [mime, media] of Object.entries(response.content ?? {})) {
+          collectShapes(
+            media.schema,
+            {
+              container: `response ${method} ${template} ${status} ${mime}`,
+              path: '',
+              primaryHints: isError ? ['error'] : base ? [base] : [],
+              fallbackHints: isError
+                ? base
+                  ? [`${base} error`]
+                  : []
+                : base
+                  ? [`${base} response`]
+                  : [],
+            },
+            groups
+          );
+        }
+      }
+    }
+  }
+
+  return groups;
+}
+
+function propertyNames(schema: JsonSchema): string[] {
+  return Object.keys(schema.properties ?? {});
+}
+
+function nameSimilarity(a: JsonSchema, b: JsonSchema): number {
+  const namesA = propertyNames(a);
+  const namesB = new Set(propertyNames(b));
+  const shared = namesA.filter((name) => namesB.has(name)).length;
+  const unionSize = namesA.length + namesB.size - shared;
+  return unionSize === 0 ? 0 : shared / unionSize;
+}
+
+function scalarTypes(schema: JsonSchema): string[] | undefined {
+  if (
+    schema.$ref !== undefined ||
+    schema.properties ||
+    schema.additionalProperties ||
+    schema.items ||
+    schema.oneOf
+  ) {
+    return undefined;
+  }
+  const types = typeof schema.type === 'string' ? [schema.type] : schema.type;
+  if (!types || types.some((type) => type === 'object' || type === 'array')) {
+    return undefined;
+  }
+  return types;
+}
+
+function isUnconstrained(schema: JsonSchema): boolean {
+  return Object.keys(schema).length === 0;
+}
+
+function compatibleProperty(a: JsonSchema, b: JsonSchema): boolean {
+  if (shapeKey(a) === shapeKey(b)) {
+    return true;
+  }
+  if (isUnconstrained(a) || isUnconstrained(b)) {
+    return true;
+  }
+  const scalarsA = scalarTypes(a);
+  const scalarsB = scalarTypes(b);
+  if (scalarsA && scalarsB) {
+    const typesA = new Set(scalarsA.filter((type) => type !== 'null'));
+    const typesB = new Set(scalarsB.filter((type) => type !== 'null'));
+    if (typesA.size === typesB.size && [...typesA].every((type) => typesB.has(type))) {
+      return true;
+    }
+    return (
+      [...typesA].every((type) => NUMERIC_TYPES.has(type)) &&
+      [...typesB].every((type) => NUMERIC_TYPES.has(type))
+    );
+  }
+  const isArrayLike = (schema: JsonSchema) => schema.type === 'array' || schema.items !== undefined;
+  if (isArrayLike(a) && isArrayLike(b)) {
+    return !a.items || !b.items || compatibleProperty(a.items, b.items);
+  }
+  return false;
+}
+
+function canUnify(a: ShapeGroup, b: ShapeGroup): boolean {
+  const propertiesB = b.merged.properties ?? {};
+  return Object.entries(a.merged.properties ?? {}).every(
+    ([name, property]) => !(name in propertiesB) || compatibleProperty(property, propertiesB[name])
+  );
+}
+
+function unifyNearDuplicates(groups: ShapeGroup[]): ShapeGroup[] {
+  const result = [...groups];
+  while (result.length > 1) {
+    let bestA = -1;
+    let bestB = -1;
+    let bestScore = 0;
+    for (let i = 0; i < result.length; i++) {
+      for (let j = i + 1; j < result.length; j++) {
+        const score = nameSimilarity(result[i].merged, result[j].merged);
+        if (
+          score >= NEAR_DUPLICATE_SIMILARITY &&
+          score > bestScore &&
+          canUnify(result[i], result[j])
+        ) {
+          bestScore = score;
+          bestA = i;
+          bestB = j;
+        }
+      }
+    }
+    if (bestA === -1) {
+      break;
+    }
+
+    const target = result[bestA];
+    const source = result[bestB];
+    target.keys.push(...source.keys);
+    target.schemas.push(...source.schemas);
+    target.merged = mergeSchemas([target.merged, source.merged]);
+    for (const context of source.contexts) {
+      target.contexts.add(context);
+    }
+    for (const [hint, votes] of source.primaryVotes) {
+      target.primaryVotes.set(hint, (target.primaryVotes.get(hint) ?? 0) + votes);
+    }
+    for (const [hint, votes] of source.fallbackVotes) {
+      target.fallbackVotes.set(hint, (target.fallbackVotes.get(hint) ?? 0) + votes);
+    }
+    result.splice(bestB, 1);
+  }
+  return result;
+}
+
+function compareStrings(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+function pascalCase(value: string): string {
+  return value
+    .split(/[^a-zA-Z0-9]+/)
+    .filter(Boolean)
+    .map((word) => word[0].toUpperCase() + word.slice(1))
+    .join('');
+}
+
+function rankHints(votes: Map<string, number>): string[] {
+  return [...votes.entries()]
+    .sort(([hintA, votesA], [hintB, votesB]) => votesB - votesA || compareStrings(hintA, hintB))
+    .map(([hint]) => hint);
+}
+
+function assignNames(groups: ShapeGroup[]): NamedGroup[] {
+  const ordered = [...groups].sort(
+    (a, b) =>
+      b.contexts.size - a.contexts.size ||
+      b.schemas.length - a.schemas.length ||
+      compareStrings(a.keys[0], b.keys[0])
+  );
+
+  const used = new Set<string>();
+  return ordered.map((group) => {
+    const candidates = [...rankHints(group.primaryVotes), ...rankHints(group.fallbackVotes)]
+      .map(pascalCase)
+      .filter((candidate) => candidate.length > 0);
+    if (candidates.length === 0) {
+      candidates.push('Schema');
+    }
+    let name = candidates.find((candidate) => !used.has(candidate));
+    for (let suffix = 2; name === undefined; suffix++) {
+      const numbered = `${candidates[0]}${suffix}`;
+      if (!used.has(numbered)) {
+        name = numbered;
+      }
+    }
+    used.add(name);
+    return { group, name };
+  });
+}
+
+function withRefs(
+  schema: JsonSchema,
+  refs: Map<string, string>,
+  isComponentRoot = false
+): JsonSchema {
+  if (!isComponentRoot) {
+    const name = refs.get(shapeKey(schema));
+    if (name !== undefined) {
+      return { $ref: `#/components/schemas/${name}` };
+    }
+  }
+
+  const result: JsonSchema = { ...schema };
+  copyObservations(schema, result);
+  if (schema.properties) {
+    result.properties = Object.fromEntries(
+      Object.entries(schema.properties).map(([name, property]) => [name, withRefs(property, refs)])
+    );
+  }
+  if (schema.additionalProperties) {
+    result.additionalProperties = withRefs(schema.additionalProperties, refs);
+  }
+  if (schema.items) {
+    result.items = withRefs(schema.items, refs);
+  }
+  if (schema.oneOf) {
+    result.oneOf = schema.oneOf.map((member) => withRefs(member, refs));
+  }
+  return result;
+}
+
+function isUnobservedListEnvelope(schema: JsonSchema): boolean {
+  const properties = Object.values(schema.properties ?? {});
+  const unobservedArrays = properties.filter(
+    (property) => property.type === 'array' && (!property.items || isUnconstrained(property.items))
+  );
+  return (
+    unobservedArrays.length > 0 &&
+    properties.length - unobservedArrays.length <= MAX_ENVELOPE_PROPERTIES
+  );
+}
+
+function hasDominantNameHint(group: ShapeGroup): boolean {
+  let total = 0;
+  let top = 0;
+  for (const count of group.primaryVotes.values()) {
+    total += count;
+    top = Math.max(top, count);
+  }
+  return top * 2 > total;
+}
+
+/**
+ * Extract object shapes that repeat across the document into named
+ * `components/schemas` entries and replace every occurrence with a `$ref`.
+ * Occurrences are counted per distinct context (enclosing shape + position),
+ * so a shape repeated only because its parent repeats stays inline. A list
+ * envelope whose payload was never observed (only empty arrays recorded, few
+ * other properties) also stays inline unless its contexts agree on a name —
+ * matching envelopes alone are no evidence that unrelated endpoints return
+ * the same thing.
+ */
+export function extractSchemaComponents(document: GeneratedDocument): GeneratedDocument {
+  const groups = collectGroups(document);
+  for (const group of groups.values()) {
+    group.merged = mergeSchemas(group.schemas);
+  }
+
+  const unified = unifyNearDuplicates([...groups.values()]);
+  const extracted = unified.filter(
+    (group) =>
+      group.contexts.size >= MIN_DISTINCT_CONTEXTS &&
+      (hasDominantNameHint(group) || !group.schemas.some(isUnobservedListEnvelope))
+  );
+  if (extracted.length === 0) {
+    return document;
+  }
+
+  const named = assignNames(extracted);
+  const refs = new Map<string, string>();
+  for (const { group, name } of named) {
+    for (const key of group.keys) {
+      refs.set(key, name);
+    }
+  }
+
+  const schemas: Record<string, JsonSchema> = {};
+  for (const { group, name } of [...named].sort((a, b) => compareStrings(a.name, b.name))) {
+    schemas[name] = withRefs(group.merged, refs, true);
+  }
+
+  for (const pathItem of Object.values(document.paths)) {
+    for (const operation of Object.values(pathItem)) {
+      for (const media of Object.values(operation.requestBody?.content ?? {})) {
+        media.schema = withRefs(media.schema, refs);
+      }
+      for (const response of Object.values(operation.responses)) {
+        for (const media of Object.values(response.content ?? {})) {
+          media.schema = withRefs(media.schema, refs);
+        }
+      }
+    }
+  }
+
+  document.components = { schemas };
+  return document;
+}
diff --git a/packages/cli/src/commands/generate-spec/generator.ts b/packages/cli/src/commands/generate-spec/generator.ts
new file mode 100644
index 0000000000..18b388b9b2
--- /dev/null
+++ b/packages/cli/src/commands/generate-spec/generator.ts
@@ -0,0 +1,779 @@
+import { logger, pluralize } from '@redocly/openapi-core';
+
+import { selectTrafficParser } from '../drift/log-formats/registry.js';
+import type {
+  NormalizedExchange,
+  NormalizedHttpMessage,
+  TrafficFormat,
+} from '../drift/types/index.js';
+import { listFilesRecursively } from '../drift/utils/files.js';
+import {
+  getPathWithoutTrailingSlash,
+  isJsonMime,
+  isSyntheticHost,
+  normalizeContentType,
+} from '../drift/utils/http.js';
+import { normalizeServerPrefix, resolvePathForServer } from '../drift/utils/server.js';
+import { OPENAPI3_METHOD_NAMES } from '../split/oas/constants.js';
+import {
+  copyObservations,
+  distillObservations,
+  getObservations,
+  mergeObservations,
+  observeString,
+  setObservations,
+  type StringObservations,
+} from './value-inference.js';
+
+export interface GenerateSpecOptions {
+  trafficPath: string;
+  format: TrafficFormat;
+  title?: string;
+  server?: string;
+}
+
+export interface JsonSchema {
+  $ref?: string;
+  type?: string | string[];
+  format?: string;
+  enum?: string[];
+  properties?: Record<string, JsonSchema>;
+  additionalProperties?: JsonSchema;
+  required?: string[];
+  items?: JsonSchema;
+  oneOf?: JsonSchema[];
+}
+
+interface GeneratedParameter {
+  name: string;
+  in: 'path' | 'query';
+  required: boolean;
+  schema: JsonSchema;
+}
+
+interface GeneratedResponse {
+  description: string;
+  content?: Record<string, { schema: JsonSchema }>;
+}
+
+export interface GeneratedOperation {
+  operationId: string;
+  responses: Record<string, GeneratedResponse>;
+  parameters?: GeneratedParameter[];
+  requestBody?: { content: Record<string, { schema: JsonSchema }> };
+}
+
+export interface GeneratedDocument {
+  openapi: string;
+  info: { title: string; version: string };
+  servers?: { url: string }[];
+  paths: Record<string, Record<string, GeneratedOperation>>;
+  components?: { schemas: Record<string, JsonSchema> };
+}
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const NUMERIC_RE = /^\d+$/;
+// Crockford base32 (ULID alphabet, no I/L/O/U), e.g. 01ARZ3NDEKTSV4RRFFQ69G5FAV.
+const ULID_RE = /^[0-9a-hjkmnp-tv-z]{26}$/i;
+// Type-prefixed opaque token with at least one digit, e.g. org_01ks7rnqsyy0g6h37rfmen7zv9.
+const PREFIXED_ID_RE = /^[a-z][a-z0-9]*_(?=[0-9a-z]*\d)[0-9a-z]{10,}$/i;
+// cuid ("cjld2cjxh0000qzrmn831i7rn") and cuid2 ("tz4a98xxat96iws9zmbrgj3a") as
+// generated by Prisma: 24-25 lowercase alphanumerics with at least one digit.
+const CUID_RE = /^[a-z](?=[a-z0-9]*\d)[a-z0-9]{23,24}$/;
+export const HTTP_METHODS = new Set<string>(OPENAPI3_METHOD_NAMES);
+const BODYLESS_METHODS = new Set(['get', 'head']);
+const FORM_URLENCODED_MIME = 'application/x-www-form-urlencoded';
+const MULTIPART_FORM_MIME = 'multipart/form-data';
+
+function looksLikeIdentifier(segment: string): boolean {
+  if (!segment) return false;
+  if (NUMERIC_RE.test(segment)) return true;
+  if (UUID_RE.test(segment)) return true;
+  if (ULID_RE.test(segment)) return true;
+  if (PREFIXED_ID_RE.test(segment)) return true;
+  if (CUID_RE.test(segment)) return true;
+  // long hex / opaque token
+  return /^[0-9a-f]{16,}$/i.test(segment);
+}
+
+interface TemplatizedParam {
+  name: string;
+  value: string;
+}
+
+/**
+ * Turn a concrete request path into an OpenAPI path template, replacing
+ * identifier-like segments with named path parameters.
+ */
+export function templatizePath(rawPath: string): { template: string; params: TemplatizedParam[] } {
+  const segments = rawPath.split('/');
+  const params: TemplatizedParam[] = [];
+  const used = new Set<string>();
+
+  const templated = segments.map((segment, index) => {
+    if (!looksLikeIdentifier(segment)) {
+      return segment;
+    }
+
+    const previous = segments[index - 1];
+    let name = previous ? `${pluralize(previous, 1)}Id` : 'id';
+    let suffix = 1;
+    while (used.has(name)) {
+      suffix += 1;
+      name = previous ? `${pluralize(previous, 1)}Id${suffix}` : `id${suffix}`;
+    }
+    used.add(name);
+    params.push({ name, value: segment });
+    return `{${name}}`;
+  });
+
+  return { template: templated.join('/') || '/', params };
+}
+
+export function inferSchema(value: unknown): JsonSchema {
+  if (value === null) {
+    return { type: 'null' };
+  }
+
+  if (Array.isArray(value)) {
+    if (value.length === 0) {
+      return { type: 'array' };
+    }
+    const itemSchemas = value.slice(0, 20).map(inferSchema);
+    return { type: 'array', items: mergeSchemas(itemSchemas) };
+  }
+
+  switch (typeof value) {
+    case 'string': {
+      const schema: JsonSchema = { type: 'string' };
+      setObservations(schema, observeString(value));
+      return schema;
+    }
+    case 'boolean':
+      return { type: 'boolean' };
+    case 'number':
+      return Number.isInteger(value) ? { type: 'integer' } : { type: 'number' };
+    case 'object': {
+      const entries = Object.entries(value as Record<string, unknown>);
+
+      // Objects keyed by identifiers (all-numeric or all-UUID keys) are maps,
+      // not fixed shapes — describe them with additionalProperties.
+      if (entries.length > 0) {
+        const keysAreGeneric =
+          entries.every(([key]) => NUMERIC_RE.test(key)) ||
+          entries.every(([key]) => UUID_RE.test(key));
+        if (keysAreGeneric) {
+          return {
+            type: 'object',
+            additionalProperties: mergeSchemas(
+              entries.map(([, propValue]) => inferSchema(propValue))
+            ),
+          };
+        }
+      }
+
+      const properties: Record<string, JsonSchema> = {};
+      const required: string[] = [];
+      for (const [key, propValue] of entries) {
+        properties[key] = inferSchema(propValue);
+        required.push(key);
+      }
+      const schema: JsonSchema = { type: 'object', properties };
+      if (required.length > 0) {
+        schema.required = required;
+      }
+      return schema;
+    }
+    default:
+      return {};
+  }
+}
+
+/** Shallow merge of inferred schemas observed across multiple samples. */
+export function mergeSchemas(schemas: JsonSchema[]): JsonSchema {
+  if (schemas.length === 0) {
+    return {};
+  }
+
+  const [first, ...rest] = schemas;
+  let merged: JsonSchema = first;
+  for (const next of rest) {
+    merged = mergeTwo(merged, next);
+  }
+  return merged;
+}
+
+function isUnconstrainedSchema(schema: JsonSchema): boolean {
+  return Object.keys(schema).length === 0;
+}
+
+type VariantKind = 'scalar' | 'object' | 'map' | 'array';
+
+/**
+ * A variant is a schema with a single `type` string and no `oneOf`. Divergent
+ * observations are kept as separate variants so that alternative body shapes
+ * survive to the generated description as `oneOf` instead of collapsing into
+ * an unconstrained schema.
+ */
+function variantKind(variant: JsonSchema): VariantKind {
+  if (variant.additionalProperties) {
+    return 'map';
+  }
+  if (variant.type === 'object') {
+    return 'object';
+  }
+  if (variant.type === 'array') {
+    return 'array';
+  }
+  return 'scalar';
+}
+
+function toVariants(schema: JsonSchema): JsonSchema[] {
+  if (schema.oneOf) {
+    return schema.oneOf.flatMap(toVariants);
+  }
+  if (Array.isArray(schema.type)) {
+    return schema.type.map((type): JsonSchema => {
+      if (type === 'object') {
+        const variant: JsonSchema = { type: 'object' };
+        if (schema.properties) {
+          variant.properties = schema.properties;
+        }
+        if (schema.required) {
+          variant.required = schema.required;
+        }
+        if (schema.additionalProperties) {
+          variant.additionalProperties = schema.additionalProperties;
+        }
+        return variant;
+      }
+      if (type === 'array') {
+        return schema.items ? { type: 'array', items: schema.items } : { type: 'array' };
+      }
+      const scalar: JsonSchema = { type };
+      if (type === 'string') {
+        copyObservations(schema, scalar);
+      }
+      return scalar;
+    });
+  }
+  return [schema];
+}
+
+const OBJECT_MERGE_SIMILARITY = 0.5;
+const MAX_OBJECT_VARIANTS = 3;
+
+function objectSimilarity(a: JsonSchema, b: JsonSchema): number {
+  const keysA = Object.keys(a.properties ?? {});
+  const keysB = Object.keys(b.properties ?? {});
+  // An object with no known properties is compatible with any shape.
+  if (keysA.length === 0 || keysB.length === 0) {
+    return 1;
+  }
+  const setB = new Set(keysB);
+  const shared = keysA.filter((key) => setB.has(key)).length;
+  return shared / (keysA.length + keysB.length - shared);
+}
+
+function areCompatibleVariants(a: JsonSchema, b: JsonSchema): boolean {
+  const kind = variantKind(a);
+  if (kind !== variantKind(b)) {
+    return false;
+  }
+  switch (kind) {
+    case 'scalar':
+      return (
+        a.type === b.type ||
+        (a.type === 'integer' && b.type === 'number') ||
+        (a.type === 'number' && b.type === 'integer')
+      );
+    case 'object':
+      return objectSimilarity(a, b) >= OBJECT_MERGE_SIMILARITY;
+    default:
+      return true;
+  }
+}
+
+function mergeVariantPair(a: JsonSchema, b: JsonSchema): JsonSchema {
+  switch (variantKind(a)) {
+    case 'scalar': {
+      if (a.type !== b.type) {
+        return { type: 'number' };
+      }
+      if (a.type === 'string') {
+        const observations = mergeObservations(getObservations(a), getObservations(b));
+        if (observations) {
+          const merged: JsonSchema = { type: 'string' };
+          setObservations(merged, observations);
+          return merged;
+        }
+      }
+      return a;
+    }
+    case 'map':
+      return {
+        type: 'object',
+        additionalProperties: mergeTwo(a.additionalProperties ?? {}, b.additionalProperties ?? {}),
+      };
+    case 'object': {
+      const properties: Record<string, JsonSchema> = { ...(a.properties ?? {}) };
+      for (const [key, schema] of Object.entries<JsonSchema>(b.properties ?? {})) {
+        properties[key] = properties[key] ? mergeTwo(properties[key], schema) : schema;
+      }
+      // required = intersection of observed required sets
+      const requiredB = new Set<string>(b.required ?? []);
+      const required = (a.required ?? []).filter((key) => requiredB.has(key));
+      const merged: JsonSchema = { type: 'object', properties };
+      if (required.length > 0) {
+        merged.required = required;
+      }
+      return merged;
+    }
+    case 'array': {
+      if (!a.items || !b.items) {
+        const items = a.items ?? b.items;
+        return items ? { type: 'array', items } : { type: 'array' };
+      }
+      return { type: 'array', items: mergeTwo(a.items, b.items) };
+    }
+  }
+}
+
+function foldExcessObjectVariants(variants: JsonSchema[]): JsonSchema[] {
+  const result = [...variants];
+  const objectCount = () => result.filter((v) => variantKind(v) === 'object').length;
+  while (objectCount() > MAX_OBJECT_VARIANTS) {
+    let bestA = -1;
+    let bestB = -1;
+    let bestScore = -1;
+    for (let i = 0; i < result.length; i++) {
+      if (variantKind(result[i]) !== 'object') continue;
+      for (let j = i + 1; j < result.length; j++) {
+        if (variantKind(result[j]) !== 'object') continue;
+        const score = objectSimilarity(result[i], result[j]);
+        if (score > bestScore) {
+          bestScore = score;
+          bestA = i;
+          bestB = j;
+        }
+      }
+    }
+    result[bestA] = mergeVariantPair(result[bestA], result[bestB]);
+    result.splice(bestB, 1);
+  }
+  return result;
+}
+
+const SCALAR_TYPE_ORDER = ['boolean', 'integer', 'number', 'string', 'null'];
+
+function finalizeVariants(variants: JsonSchema[]): JsonSchema {
+  if (variants.length === 1) {
+    return variants[0];
+  }
+
+  const structured: JsonSchema[] = [];
+  const scalarTypes = new Set<string>();
+  let stringObservations: StringObservations | undefined;
+  for (const variant of variants) {
+    if (variantKind(variant) === 'scalar' && typeof variant.type === 'string') {
+      scalarTypes.add(variant.type);
+      if (variant.type === 'string') {
+        stringObservations = mergeObservations(stringObservations, getObservations(variant));
+      }
+    } else {
+      structured.push(variant);
+    }
+  }
+  const orderedScalars = SCALAR_TYPE_ORDER.filter((type) => scalarTypes.has(type));
+
+  const scalarSchema = (type: string | string[]): JsonSchema => {
+    const schema: JsonSchema = { type };
+    const includesString = typeof type === 'string' ? type === 'string' : type.includes('string');
+    if (includesString && stringObservations) {
+      setObservations(schema, stringObservations);
+    }
+    return schema;
+  };
+
+  if (structured.length === 0) {
+    return orderedScalars.length === 1
+      ? scalarSchema(orderedScalars[0])
+      : scalarSchema(orderedScalars);
+  }
+  if (
+    structured.length === 1 &&
+    orderedScalars.length === 1 &&
+    orderedScalars[0] === 'null' &&
+    typeof structured[0].type === 'string'
+  ) {
+    return { ...structured[0], type: [structured[0].type, 'null'] };
+  }
+
+  const members = [...structured];
+  if (orderedScalars.length === 1) {
+    members.push(scalarSchema(orderedScalars[0]));
+  } else if (orderedScalars.length > 1) {
+    members.push(scalarSchema(orderedScalars));
+  }
+  return { oneOf: members };
+}
+
+function mergeTwo(a: JsonSchema, b: JsonSchema): JsonSchema {
+  if (isUnconstrainedSchema(a) || isUnconstrainedSchema(b)) {
+    return {};
+  }
+
+  const variants = toVariants(a);
+  for (const candidate of toVariants(b)) {
+    const index = variants.findIndex((variant) => areCompatibleVariants(variant, candidate));
+    if (index === -1) {
+      variants.push(candidate);
+    } else {
+      variants[index] = mergeVariantPair(variants[index], candidate);
+    }
+  }
+  return finalizeVariants(foldExcessObjectVariants(variants));
+}
+
+function sniffJson(bodyText: string | undefined): unknown {
+  if (!bodyText) {
+    return undefined;
+  }
+
+  const trimmed = bodyText.trim();
+  if (!trimmed.startsWith('{') && !trimmed.startsWith('[')) {
+    return undefined;
+  }
+
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return undefined;
+  }
+}
+
+export function inferMultipartSchema(
+  bodyText: string,
+  contentType: string | undefined
+): JsonSchema | undefined {
+  const boundary = contentType?.match(/boundary="?([^";,]+)"?/i)?.[1];
+  if (!boundary) {
+    return undefined;
+  }
+
+  const properties: Record<string, JsonSchema> = {};
+  for (const section of bodyText.split(`--${boundary}`)) {
+    const partMatch = section.match(/^\r?\n([\s\S]*?)\r?\n\r?\n([\s\S]*)\r?\n$/);
+    if (!partMatch) {
+      continue;
+    }
+    const [, partHeaders, value] = partMatch;
+    const fieldName = partHeaders.match(/\bname="([^"]*)"/i)?.[1];
+    if (fieldName === undefined) {
+      continue;
+    }
+    properties[fieldName] = /\bfilename="/i.test(partHeaders)
+      ? { type: 'string', format: 'binary' }
+      : inferSchema(value);
+  }
+
+  if (Object.keys(properties).length === 0) {
+    return undefined;
+  }
+  return { type: 'object', properties, required: Object.keys(properties) };
+}
+
+/**
+ * Infer a body schema and the content type to file it under. JSON declared via
+ * the content type wins; form-urlencoded and multipart bodies are parsed into
+ * flat objects; undeclared JSON (e.g. sent as text/plain) is detected by
+ * sniffing the body.
+ */
+function inferBodySchema(
+  message: NormalizedHttpMessage
+): { mime: string; schema: JsonSchema } | undefined {
+  const mime = normalizeContentType(message.contentType);
+
+  if (message.bodyJson !== undefined) {
+    return {
+      mime: isJsonMime(mime) ? mime : 'application/json',
+      schema: inferSchema(message.bodyJson),
+    };
+  }
+
+  if (mime === FORM_URLENCODED_MIME && message.bodyText) {
+    const fields: Record<string, unknown> = {};
+    for (const [key, value] of new URLSearchParams(message.bodyText)) {
+      fields[key] = value;
+    }
+    if (Object.keys(fields).length === 0) {
+      return undefined;
+    }
+    return { mime: FORM_URLENCODED_MIME, schema: inferSchema(fields) };
+  }
+
+  if (mime === MULTIPART_FORM_MIME && message.bodyText) {
+    const schema = inferMultipartSchema(message.bodyText, message.contentType);
+    return schema ? { mime: MULTIPART_FORM_MIME, schema } : undefined;
+  }
+
+  const sniffed = sniffJson(message.bodyText);
+  if (sniffed !== undefined) {
+    return { mime: 'application/json', schema: inferSchema(sniffed) };
+  }
+
+  return undefined;
+}
+
+interface ResponseAccumulator {
+  statusText?: string;
+  /** Content type → schema merged incrementally across all observed bodies. */
+  bodies: Map<string, JsonSchema>;
+}
+
+interface ParameterAccumulator {
+  /** Whether every observed value was numeric. */
+  numeric: boolean;
+  observations?: StringObservations;
+}
+
+interface OperationAccumulator {
+  method: string;
+  template: string;
+  pathParams: Map<string, ParameterAccumulator>;
+  queryParams: Map<string, ParameterAccumulator>;
+  requestBodies: Map<string, JsonSchema>;
+  responses: Map<string, ResponseAccumulator>;
+}
+
+function accumulateBodySchema(target: Map<string, JsonSchema>, mime: string, schema: JsonSchema) {
+  const merged = target.get(mime);
+  target.set(mime, merged ? mergeSchemas([merged, schema]) : schema);
+}
+
+/**
+ * Generate an OpenAPI 3.2 document by observing recorded traffic. Returns the
+ * document object; the caller decides whether to print it, write it, or hand it
+ * to an AI provider for refinement.
+ */
+export async function generateSpecFromTraffic(
+  options: GenerateSpecOptions
+): Promise<GeneratedDocument> {
+  const trafficFiles = await listFilesRecursively(options.trafficPath);
+  if (trafficFiles.length === 0) {
+    throw new Error('No traffic files found in the provided traffic path.');
+  }
+
+  const server = normalizeServerPrefix(options.server);
+  const operations = new Map<string, OperationAccumulator>();
+  const observedServers = new Set<string>();
+  let supportedTrafficFileCount = 0;
+
+  const observe = (exchange: NormalizedExchange) => {
+    const method = exchange.request.method.toLowerCase();
+    if (!HTTP_METHODS.has(method)) {
+      return;
+    }
+
+    let rawPath = exchange.request.path || '/';
+    if (server) {
+      const serverRelativePath = resolvePathForServer(exchange.request, server);
+      if (serverRelativePath === undefined) {
+        return;
+      }
+      rawPath = serverRelativePath;
+    } else if (exchange.request.host && !isSyntheticHost(exchange.request.host)) {
+      observedServers.add(`${exchange.request.protocol}//${exchange.request.host}`);
+    }
+
+    const { template, params } = templatizePath(getPathWithoutTrailingSlash(rawPath));
+    const key = `${method} ${template}`;
+    let accumulator = operations.get(key);
+    if (!accumulator) {
+      accumulator = {
+        method,
+        template,
+        pathParams: new Map(),
+        queryParams: new Map(),
+        requestBodies: new Map(),
+        responses: new Map(),
+      };
+      operations.set(key, accumulator);
+    }
+
+    for (const { name, value } of params) {
+      const previous = accumulator.pathParams.get(name);
+      accumulator.pathParams.set(name, {
+        numeric: (previous?.numeric ?? true) && NUMERIC_RE.test(value),
+        observations: mergeObservations(previous?.observations, observeString(value)),
+      });
+    }
+    for (const queryKey of new Set(exchange.request.query.keys())) {
+      const values = exchange.request.query.getAll(queryKey);
+      const previous = accumulator.queryParams.get(queryKey);
+      const isNumeric = values.length > 0 && values.every((value) => NUMERIC_RE.test(value));
+      let observations = previous?.observations;
+      for (const value of values) {
+        observations = mergeObservations(observations, observeString(value));
+      }
+      accumulator.queryParams.set(queryKey, {
+        numeric: (previous?.numeric ?? true) && isNumeric,
+        observations,
+      });
+    }
+
+    if (!BODYLESS_METHODS.has(method)) {
+      const requestBody = inferBodySchema(exchange.request);
+      if (requestBody) {
+        accumulateBodySchema(accumulator.requestBodies, requestBody.mime, requestBody.schema);
+      }
+    }
+
+    // Status codes below 100 (e.g. 0 in HAR) mean the response was never
+    // received — they carry no information about the API's real responses.
+    if (exchange.response && exchange.response.status >= 100) {
+      const status = String(exchange.response.status);
+      let responseAccumulator = accumulator.responses.get(status);
+      if (!responseAccumulator) {
+        responseAccumulator = { bodies: new Map() };
+        accumulator.responses.set(status, responseAccumulator);
+      }
+      responseAccumulator.statusText ??= exchange.response.statusText || undefined;
+
+      const responseBody = inferBodySchema(exchange.response);
+      if (responseBody) {
+        accumulateBodySchema(responseAccumulator.bodies, responseBody.mime, responseBody.schema);
+      }
+    }
+  };
+
+  for (const trafficFile of trafficFiles) {
+    const parser = await selectTrafficParser(trafficFile, options.format);
+    if (!parser) {
+      logger.warn(`Skipping traffic file with unrecognized format: ${trafficFile}\n`);
+      continue;
+    }
+
+    supportedTrafficFileCount += 1;
+    for await (const exchange of parser.parse(trafficFile)) {
+      observe(exchange);
+    }
+  }
+
+  if (supportedTrafficFileCount === 0) {
+    throw new Error('No supported traffic files found to generate an OpenAPI description from.');
+  }
+
+  if (operations.size === 0) {
+    throw new Error(
+      server
+        ? `No HTTP exchanges in the traffic matched the server "${server}".`
+        : 'No HTTP exchanges were observed in the traffic. Cannot generate an OpenAPI description.'
+    );
+  }
+
+  const serverUrls = server ? [server] : Array.from(observedServers).sort();
+  return buildDocument(operations, options.title ?? 'Generated API', serverUrls);
+}
+
+export function countOperations(document: GeneratedDocument): number {
+  return Object.values(document.paths).reduce(
+    (total, pathItem) => total + Object.keys(pathItem).length,
+    0
+  );
+}
+
+function parameterSchema(param: ParameterAccumulator, allowEnum: boolean): JsonSchema {
+  if (param.numeric) {
+    return { type: 'integer' };
+  }
+  const schema: JsonSchema = { type: 'string' };
+  if (param.observations) {
+    Object.assign(schema, distillObservations(param.observations, allowEnum));
+  }
+  return schema;
+}
+
+function buildDocument(
+  operations: Map<string, OperationAccumulator>,
+  title: string,
+  serverUrls: string[]
+): GeneratedDocument {
+  const paths: Record<string, Record<string, GeneratedOperation>> = {};
+
+  for (const accumulator of operations.values()) {
+    const pathItem = (paths[accumulator.template] ??= {});
+
+    const parameters: GeneratedParameter[] = [
+      ...Array.from(accumulator.pathParams).map(
+        ([name, param]): GeneratedParameter => ({
+          name,
+          in: 'path',
+          required: true,
+          schema: parameterSchema(param, false),
+        })
+      ),
+      ...Array.from(accumulator.queryParams).map(
+        ([name, param]): GeneratedParameter => ({
+          name,
+          in: 'query',
+          required: false,
+          schema: parameterSchema(param, true),
+        })
+      ),
+    ];
+
+    const operation: GeneratedOperation = {
+      operationId: deriveOperationId(accumulator.method, accumulator.template),
+      responses: {},
+    };
+
+    if (parameters.length > 0) {
+      operation.parameters = parameters;
+    }
+
+    if (accumulator.requestBodies.size > 0) {
+      const content: Record<string, { schema: JsonSchema }> = {};
+      for (const [mime, schema] of accumulator.requestBodies) {
+        content[mime] = { schema };
+      }
+      operation.requestBody = { content };
+    }
+
+    if (accumulator.responses.size === 0) {
+      operation.responses['default'] = { description: 'Observed response' };
+    } else {
+      for (const [status, responseAccumulator] of accumulator.responses) {
+        const response: GeneratedResponse = {
+          description: responseAccumulator.statusText || 'Observed response',
+        };
+        if (responseAccumulator.bodies.size > 0) {
+          const content: Record<string, { schema: JsonSchema }> = {};
+          for (const [mime, schema] of responseAccumulator.bodies) {
+            content[mime] = { schema };
+          }
+          response.content = content;
+        }
+        operation.responses[status] = response;
+      }
+    }
+
+    pathItem[accumulator.method] = operation;
+  }
+
+  return {
+    openapi: '3.2.0',
+    info: { title, version: '1.0.0' },
+    ...(serverUrls.length > 0 ? { servers: serverUrls.map((url) => ({ url })) } : {}),
+    paths,
+  };
+}
+
+function deriveOperationId(method: string, template: string): string {
+  const cleaned = template
+    .split('/')
+    .filter(Boolean)
+    .map((segment) => segment.replace(/[{}]/g, ''))
+    .join('-');
+  return `${method}-${cleaned || 'root'}`;
+}
diff --git a/packages/cli/src/commands/generate-spec/index.ts b/packages/cli/src/commands/generate-spec/index.ts
new file mode 100644
index 0000000000..ab42fd8ac8
--- /dev/null
+++ b/packages/cli/src/commands/generate-spec/index.ts
@@ -0,0 +1,114 @@
+import { logger, stringifyYaml } from '@redocly/openapi-core';
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { exitWithError } from '../../utils/error.js';
+import type { CommandArgs } from '../../wrapper.js';
+import type { TrafficFormat } from '../drift/types/index.js';
+import { normalizeFsPath } from '../drift/utils/files.js';
+import { type AiProvider } from './ai/providers.js';
+import { refineSpecWithAi } from './ai/refine.js';
+import { extractSchemaComponents } from './components.js';
+import { countOperations, generateSpecFromTraffic } from './generator.js';
+import { collectTrafficSamples } from './samples.js';
+import { applyValueInference } from './value-inference.js';
+
+export type GenerateSpecArgv = {
+  traffic: string;
+  type: 'openapi';
+  'traffic-format': TrafficFormat;
+  server?: string;
+  title?: string;
+  output?: string;
+  'with-ai'?: boolean;
+  'ai-provider': AiProvider;
+  'ai-model'?: string;
+  'ai-concurrency': number;
+  config?: string;
+};
+
+async function writeOutput(outputPath: string, contents: string): Promise<void> {
+  const normalized = normalizeFsPath(outputPath);
+  await mkdir(path.dirname(normalized), { recursive: true });
+  await writeFile(normalized, contents, 'utf8');
+}
+
+function formatElapsed(milliseconds: number): string {
+  const totalSeconds = Math.round(milliseconds / 1000);
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  return minutes > 0 ? `${minutes}m ${seconds}s` : `${seconds}s`;
+}
+
+export async function handleGenerateSpec({ argv }: CommandArgs<GenerateSpecArgv>) {
+  if (argv.type !== 'openapi') {
+    return exitWithError(`Unsupported spec type "${argv.type}". Only "openapi" is supported.`);
+  }
+
+  const startedAt = Date.now();
+
+  const trafficPath = normalizeFsPath(argv.traffic);
+  const trafficFormat = argv['traffic-format'];
+
+  const baseline = applyValueInference(
+    extractSchemaComponents(
+      await generateSpecFromTraffic({
+        trafficPath,
+        format: trafficFormat,
+        title: argv.title,
+        server: argv.server,
+      })
+    )
+  );
+
+  logger.info(
+    `Inferred a baseline OpenAPI description from traffic: ${countOperations(
+      baseline
+    )} operation(s).\n`
+  );
+
+  let resultYaml = stringifyYaml(baseline);
+
+  if (argv['with-ai']) {
+    const provider = argv['ai-provider'];
+    logger.info(`Refining the description with AI provider "${provider}"...\n`);
+    logger.warn(
+      'Note: --with-ai sends samples of the recorded traffic (URLs, query strings, request and response bodies) to the selected AI provider. Make sure the traffic contains no secrets or personal data you are not allowed to share.\n'
+    );
+
+    const samplesByOperation = await collectTrafficSamples({
+      trafficPath,
+      format: trafficFormat,
+      server: argv.server,
+    });
+
+    try {
+      const refined = await refineSpecWithAi({
+        provider,
+        model: argv['ai-model'],
+        baseline,
+        samplesByOperation,
+        concurrency: argv['ai-concurrency'],
+      });
+      resultYaml = refined.yaml;
+      logger.info(
+        `AI refinement complete: ${refined.refined} of ${refined.total} operation(s) refined (${provider}).\n`
+      );
+    } catch (error) {
+      logger.warn(
+        `AI refinement failed, falling back to the baseline description: ${
+          error instanceof Error ? error.message : String(error)
+        }\n`
+      );
+    }
+  }
+
+  if (argv.output) {
+    await writeOutput(argv.output, resultYaml);
+    logger.info(`Written to: ${normalizeFsPath(argv.output)}\n`);
+  } else {
+    logger.output(resultYaml);
+  }
+
+  logger.info(`Done in ${formatElapsed(Date.now() - startedAt)}.\n`);
+}
diff --git a/packages/cli/src/commands/generate-spec/samples.ts b/packages/cli/src/commands/generate-spec/samples.ts
new file mode 100644
index 0000000000..a80d8dbad9
--- /dev/null
+++ b/packages/cli/src/commands/generate-spec/samples.ts
@@ -0,0 +1,181 @@
+import { isPlainObject } from '@redocly/openapi-core';
+
+import { selectTrafficParser } from '../drift/log-formats/registry.js';
+import type { NormalizedHttpMessage, TrafficFormat } from '../drift/types/index.js';
+import { listFilesRecursively } from '../drift/utils/files.js';
+import { getPathWithoutTrailingSlash, normalizeContentType } from '../drift/utils/http.js';
+import { normalizeServerPrefix, resolvePathForServer } from '../drift/utils/server.js';
+import { HTTP_METHODS, templatizePath } from './generator.js';
+
+export interface TrafficSample {
+  method: string;
+  path: string;
+  query: string;
+  status?: number;
+  requestContentType?: string;
+  requestBody?: string;
+  responseContentType?: string;
+  responseBody?: string;
+}
+
+export interface CollectSamplesOptions {
+  trafficPath: string;
+  format: TrafficFormat;
+  server?: string;
+  /** Maximum samples kept per distinct status + body shape within an operation. */
+  perGroup?: number;
+  /** Maximum samples handed to the AI for a single operation. */
+  perOperation?: number;
+  /** Maximum characters retained from any single body before truncation. */
+  maxBodyChars?: number;
+}
+
+export function operationSampleKey(method: string, template: string): string {
+  return `${method.toUpperCase()} ${template}`;
+}
+
+function snapshotBody(message: NormalizedHttpMessage, maxBodyChars: number): string | undefined {
+  let text: string | undefined;
+  if (message.bodyJson !== undefined) {
+    try {
+      text = JSON.stringify(message.bodyJson);
+    } catch {
+      text = undefined;
+    }
+  }
+  text ??= message.bodyText;
+  if (!text) {
+    return undefined;
+  }
+  const trimmed = text.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+  return trimmed.length > maxBodyChars ? `${trimmed.slice(0, maxBodyChars)}…[truncated]` : trimmed;
+}
+
+/**
+ * Coarse signature of a body's top-level shape, so that exchanges carrying
+ * different payload variants of the same operation land in different sample
+ * groups and each variant reaches the AI.
+ */
+function shapeSignature(message: NormalizedHttpMessage | undefined): string {
+  if (!message) {
+    return '';
+  }
+  const value = message.bodyJson;
+  if (value === undefined) {
+    return message.bodyText ? normalizeContentType(message.contentType) || 'text' : '';
+  }
+  if (value === null) {
+    return 'null';
+  }
+  if (Array.isArray(value)) {
+    return `array<${value.length > 0 ? shapeOfValue(value[0]) : ''}>`;
+  }
+  return shapeOfValue(value);
+}
+
+function shapeOfValue(value: unknown): string {
+  if (isPlainObject(value)) {
+    return Object.keys(value).sort().join(',');
+  }
+  return value === null ? 'null' : typeof value;
+}
+
+/**
+ * Re-read the traffic to collect a small, representative set of concrete
+ * exchanges per operation. The deterministic generator only retains merged
+ * schemas; the AI benefits from seeing real request/response payloads to
+ * narrow the hypothesis.
+ *
+ * Within an operation, exchanges are grouped by status + body shape and the
+ * result is filled round-robin across groups, so every observed payload
+ * variant is represented before any group gets a second sample. Keying the
+ * result by operation keeps each AI prompt small no matter how large the
+ * recorded traffic is.
+ */
+export async function collectTrafficSamples(
+  options: CollectSamplesOptions
+): Promise<Map<string, TrafficSample[]>> {
+  const perGroup = options.perGroup ?? 2;
+  const perOperation = options.perOperation ?? 4;
+  const maxBodyChars = options.maxBodyChars ?? 2000;
+  const server = normalizeServerPrefix(options.server);
+
+  const trafficFiles = await listFilesRecursively(options.trafficPath);
+
+  const operations = new Map<string, Map<string, TrafficSample[]>>();
+
+  for (const trafficFile of trafficFiles) {
+    const parser = await selectTrafficParser(trafficFile, options.format);
+    if (!parser) {
+      continue;
+    }
+
+    for await (const exchange of parser.parse(trafficFile)) {
+      const method = exchange.request.method.toUpperCase();
+      if (!HTTP_METHODS.has(method.toLowerCase())) {
+        continue;
+      }
+      let rawPath = exchange.request.path || '/';
+      if (server) {
+        const serverRelativePath = resolvePathForServer(exchange.request, server);
+        if (serverRelativePath === undefined) {
+          continue;
+        }
+        rawPath = serverRelativePath;
+      }
+      const path = getPathWithoutTrailingSlash(rawPath);
+      const { template } = templatizePath(path);
+      // Statuses below 100 (e.g. 0) mean the response was never received;
+      // ignore such responses, mirroring the baseline generator.
+      const response =
+        exchange.response && exchange.response.status >= 100 ? exchange.response : undefined;
+      const status = response?.status;
+      const shape = `${shapeSignature(exchange.request)}→${shapeSignature(response)}`;
+
+      let groups = operations.get(operationSampleKey(method, template));
+      if (!groups) {
+        groups = new Map();
+        operations.set(operationSampleKey(method, template), groups);
+      }
+      const groupKey = `${status ?? ''} ${shape}`;
+      let group = groups.get(groupKey);
+      if (!group) {
+        group = [];
+        groups.set(groupKey, group);
+      }
+      if (group.length >= perGroup) {
+        continue;
+      }
+      group.push({
+        method,
+        path,
+        query: exchange.request.query.toString(),
+        status,
+        requestContentType: exchange.request.contentType,
+        requestBody: snapshotBody(exchange.request, maxBodyChars),
+        responseContentType: response?.contentType,
+        responseBody: response ? snapshotBody(response, maxBodyChars) : undefined,
+      });
+    }
+  }
+
+  const samplesByOperation = new Map<string, TrafficSample[]>();
+  for (const [operationKey, groups] of operations) {
+    const samples: TrafficSample[] = [];
+    for (let round = 0; round < perGroup && samples.length < perOperation; round++) {
+      for (const group of groups.values()) {
+        if (samples.length >= perOperation) {
+          break;
+        }
+        if (group[round]) {
+          samples.push(group[round]);
+        }
+      }
+    }
+    samplesByOperation.set(operationKey, samples);
+  }
+  return samplesByOperation;
+}
diff --git a/packages/cli/src/commands/generate-spec/value-inference.ts b/packages/cli/src/commands/generate-spec/value-inference.ts
new file mode 100644
index 0000000000..4f749092a6
--- /dev/null
+++ b/packages/cli/src/commands/generate-spec/value-inference.ts
@@ -0,0 +1,159 @@
+import type { GeneratedDocument, JsonSchema } from './generator.js';
+
+const MAX_TRACKED_VALUES = 10;
+const MIN_ENUM_OBSERVATIONS = 4;
+const MAX_ENUM_VALUES = 5;
+const MAX_ENUM_VALUE_LENGTH = 30;
+const ENUM_VALUE_RE = /^[a-zA-Z][a-zA-Z0-9]*(?:[_\-.][a-zA-Z0-9]+)*$/;
+const HEXISH_RE = /^[0-9a-f-]{8,}$/i;
+
+const FORMAT_MATCHERS: [string, RegExp][] = [
+  ['uuid', /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i],
+  ['date-time', /^\d{4}-\d{2}-\d{2}[Tt]\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:[Zz]|[+-]\d{2}:\d{2})$/],
+  ['date', /^\d{4}-\d{2}-\d{2}$/],
+  ['email', /^[^\s@]+@[^\s@]+\.[^\s@]+$/],
+  ['uri', /^https?:\/\/\S+$/],
+  ['ipv4', /^(?:(?:25[0-5]|2[0-4]\d|1?\d?\d)\.){3}(?:25[0-5]|2[0-4]\d|1?\d?\d)$/],
+];
+
+export type StringObservations = {
+  /** Formats every observed value matched so far, in detection priority order. */
+  formats: string[];
+  /** Distinct observed values; emptied once `overflow` is set. */
+  values: string[];
+  count: number;
+  overflow: boolean;
+};
+
+/**
+ * Observations live outside the schema nodes so they never leak into the
+ * serialized document; merge paths and node copies must propagate them
+ * explicitly via mergeObservations/copyObservations.
+ */
+const observationsByNode = new WeakMap<JsonSchema, StringObservations>();
+
+export function observeString(value: string): StringObservations {
+  return {
+    formats: FORMAT_MATCHERS.filter(([, pattern]) => pattern.test(value)).map(([format]) => format),
+    values: [value],
+    count: 1,
+    overflow: false,
+  };
+}
+
+export function mergeObservations(
+  a: StringObservations | undefined,
+  b: StringObservations | undefined
+): StringObservations | undefined {
+  if (!a) return b;
+  if (!b) return a;
+
+  const merged: StringObservations = {
+    formats: a.formats.filter((format) => b.formats.includes(format)),
+    values: [],
+    count: a.count + b.count,
+    overflow: a.overflow || b.overflow,
+  };
+  if (!merged.overflow) {
+    const values = [...a.values];
+    for (const value of b.values) {
+      if (!values.includes(value)) {
+        values.push(value);
+      }
+    }
+    if (values.length > MAX_TRACKED_VALUES) {
+      merged.overflow = true;
+    } else {
+      merged.values = values;
+    }
+  }
+  return merged;
+}
+
+export function setObservations(schema: JsonSchema, observations: StringObservations): void {
+  observationsByNode.set(schema, observations);
+}
+
+export function getObservations(schema: JsonSchema): StringObservations | undefined {
+  return observationsByNode.get(schema);
+}
+
+export function copyObservations(source: JsonSchema, target: JsonSchema): void {
+  const observations = observationsByNode.get(source);
+  if (observations) {
+    observationsByNode.set(target, observations);
+  }
+}
+
+function isEnumLikeValue(value: string): boolean {
+  return (
+    value.length <= MAX_ENUM_VALUE_LENGTH && !HEXISH_RE.test(value) && ENUM_VALUE_RE.test(value)
+  );
+}
+
+export function distillObservations(
+  observations: StringObservations,
+  allowEnum: boolean
+): Pick<JsonSchema, 'format' | 'enum'> {
+  if (observations.formats.length > 0) {
+    return { format: observations.formats[0] };
+  }
+  if (
+    allowEnum &&
+    !observations.overflow &&
+    observations.count >= MIN_ENUM_OBSERVATIONS &&
+    observations.values.length > 0 &&
+    observations.values.length <= MAX_ENUM_VALUES &&
+    observations.values.length * 2 <= observations.count &&
+    observations.values.every(isEnumLikeValue)
+  ) {
+    return { enum: [...observations.values].sort() };
+  }
+  return {};
+}
+
+function applyToSchema(schema: JsonSchema): void {
+  const observations = observationsByNode.get(schema);
+  if (observations) {
+    const types = typeof schema.type === 'string' ? [schema.type] : (schema.type ?? []);
+    if (types.includes('string')) {
+      Object.assign(schema, distillObservations(observations, types.length === 1));
+    }
+  }
+  for (const property of Object.values(schema.properties ?? {})) {
+    applyToSchema(property);
+  }
+  if (schema.additionalProperties) {
+    applyToSchema(schema.additionalProperties);
+  }
+  if (schema.items) {
+    applyToSchema(schema.items);
+  }
+  for (const member of schema.oneOf ?? []) {
+    applyToSchema(member);
+  }
+}
+
+/**
+ * Turn the string values observed in the traffic into `format` and `enum`
+ * constraints. Runs after component extraction so that a component pools the
+ * evidence from every operation it was observed in.
+ */
+export function applyValueInference(document: GeneratedDocument): GeneratedDocument {
+  for (const pathItem of Object.values(document.paths)) {
+    for (const operation of Object.values(pathItem)) {
+      for (const media of Object.values(operation.requestBody?.content ?? {})) {
+        applyToSchema(media.schema);
+      }
+      for (const response of Object.values(operation.responses)) {
+        for (const media of Object.values(response.content ?? {})) {
+          applyToSchema(media.schema);
+        }
+      }
+    }
+  }
+  for (const schema of Object.values(document.components?.schemas ?? {})) {
+    applyToSchema(schema);
+  }
+  return document;
+}
diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts
index 776804ad9b..a74e5dfa88 100644
--- a/packages/cli/src/index.ts
+++ b/packages/cli/src/index.ts
@@ -23,6 +23,7 @@ import {
   handleGenerateArazzo,
   type GenerateArazzoCommandArgv,
 } from './commands/generate-arazzo.js';
+import { type GenerateSpecArgv } from './commands/generate-spec/index.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 +856,80 @@ yargs(hideBin(process.argv))
       commandWrapper(handleGenerateArazzo)(argv as Arguments<GenerateArazzoCommandArgv>);
     }
   )
+  .command(
+    'generate-spec <traffic>',
+    'Infer an OpenAPI description from recorded HTTP traffic, optionally refined with AI [experimental].',
+    (yargs) =>
+      yargs
+        .env('REDOCLY_CLI_GENERATE_SPEC')
+        .positional('traffic', {
+          describe: 'Path to a traffic log file or folder (HAR, Kong, Nginx/Apache JSON, NDJSON).',
+          type: 'string',
+        })
+        .option({
+          type: {
+            describe: 'Target API description type.',
+            choices: ['openapi'] as const,
+            default: 'openapi' as const,
+          },
+          'traffic-format': {
+            describe: 'Traffic input format.',
+            choices: [
+              'auto',
+              'har',
+              'kong',
+              'nginx-json',
+              'apache-json',
+              'ndjson',
+            ] as ReadonlyArray<TrafficFormat>,
+            default: 'auto' as TrafficFormat,
+          },
+          server: {
+            describe:
+              'Server URL the traffic was captured against: only requests under it are considered, the rest of their URL becomes the API path, and it becomes the servers URL of the generated description.',
+            type: 'string',
+          },
+          title: {
+            describe: 'Title for the generated API description.',
+            type: 'string',
+          },
+          'with-ai': {
+            describe:
+              'Refine the inferred description with an AI provider to narrow the hypothesis.',
+            type: 'boolean',
+            default: false,
+          },
+          'ai-provider': {
+            describe:
+              'AI provider used with --with-ai; runs the "claude", "codex", or "cursor" CLI in non-interactive mode.',
+            choices: ['claude', 'codex', 'cursor'] as ReadonlyArray<
+              GenerateSpecArgv['ai-provider']
+            >,
+            default: 'claude' as GenerateSpecArgv['ai-provider'],
+          },
+          'ai-model': {
+            describe:
+              'Model passed to the selected AI provider (provider-specific default applies).',
+            type: 'string',
+          },
+          'ai-concurrency': {
+            describe: 'Number of operations refined in parallel with --with-ai.',
+            type: 'number',
+            default: 4,
+            coerce: validatePositiveNumber('ai-concurrency', true),
+          },
+          output: {
+            alias: 'o',
+            describe: 'Write the generated description to this file instead of stdout.',
+            type: 'string',
+          },
+          config: { describe: 'Path to the config file.', type: 'string' },
+        }),
+    async (argv) => {
+      const { handleGenerateSpec } = await import('./commands/generate-spec/index.js');
+      commandWrapper(handleGenerateSpec)(argv as Arguments<GenerateSpecArgv>);
+    }
+  )
   .command(
     'scorecard-classic [api]',
     'Run quality scorecards with multiple rule levels to validate and maintain API description standards.',
diff --git a/tests/e2e/generate-spec/__snapshots__/ai-refined-polymorphic.txt b/tests/e2e/generate-spec/__snapshots__/ai-refined-polymorphic.txt
new file mode 100644
index 0000000000..401a6d72df
--- /dev/null
+++ b/tests/e2e/generate-spec/__snapshots__/ai-refined-polymorphic.txt
@@ -0,0 +1,110 @@
+openapi: 3.2.0
+info:
+  title: Generated API
+  version: 1.0.0
+servers:
+  - url: http://api.example.com
+paths:
+  /payments:
+    post:
+      operationId: createPayment
+      summary: Create a payment
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              oneOf:
+                - $ref: '#/components/schemas/CardPayment'
+                - $ref: '#/components/schemas/BankTransferPayment'
+              discriminator:
+                propertyName: type
+                mapping:
+                  card: '#/components/schemas/CardPayment'
+                  bank_transfer: '#/components/schemas/BankTransferPayment'
+      responses:
+        '201':
+          description: The created payment
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Payment'
+  /payments/{paymentId}:
+    get:
+      operationId: getPayment
+      summary: Get a payment by ID
+      parameters:
+        - name: paymentId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: The requested payment
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Payment'
+components:
+  schemas:
+    PaymentBase:
+      type: object
+      required:
+        - type
+        - amount
+      properties:
+        type:
+          type: string
+          enum:
+            - card
+            - bank_transfer
+          description: Selects the payment method variant.
+        amount:
+          type: number
+    CardPayment:
+      allOf:
+        - $ref: '#/components/schemas/PaymentBase'
+        - type: object
+          required:
+            - cardNumber
+            - cvv
+          properties:
+            cardNumber:
+              type: string
+            cvv:
+              type: string
+    BankTransferPayment:
+      allOf:
+        - $ref: '#/components/schemas/PaymentBase'
+        - type: object
+          required:
+            - iban
+          properties:
+            iban:
+              type: string
+    Payment:
+      type: object
+      required:
+        - id
+        - status
+      properties:
+        id:
+          type: string
+        status:
+          type: string
+        note:
+          type:
+            - string
+            - 'null'
+          description: Optional processing note.
+
+Inferred a baseline OpenAPI description from traffic: 2 operation(s).
+Refining the description with AI provider "claude"...
+Note: --with-ai sends samples of the recorded traffic (URLs, query strings, request and response bodies) to the selected AI provider. Make sure the traffic contains no secrets or personal data you are not allowed to share.
+[1/2] Refining POST /payments...
+[1/2] POST /payments — refined (<t>s)
+[2/2] Refining GET /payments/{paymentId}...
+[2/2] GET /payments/{paymentId} — refined (<t>s)
+AI refinement complete: 2 of 2 operation(s) refined (claude).
+Done in <t>.
diff --git a/tests/e2e/generate-spec/__snapshots__/ai-refined.txt b/tests/e2e/generate-spec/__snapshots__/ai-refined.txt
new file mode 100644
index 0000000000..02e08f274f
--- /dev/null
+++ b/tests/e2e/generate-spec/__snapshots__/ai-refined.txt
@@ -0,0 +1,149 @@
+openapi: 3.2.0
+info:
+  title: Generated API
+  version: 1.0.0
+servers:
+  - url: http://api.example.com
+paths:
+  /users:
+    get:
+      operationId: listUsers
+      summary: List users
+      parameters:
+        - name: limit
+          in: query
+          required: false
+          description: Maximum number of users returned.
+          schema:
+            type: integer
+        - name: sort
+          in: query
+          required: false
+          description: Field to sort the returned users by.
+          schema:
+            type: string
+      responses:
+        '200':
+          description: A page of users
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/User'
+    post:
+      operationId: createUser
+      summary: Create a user
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/NewUser'
+      responses:
+        '201':
+          description: The created user
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/User'
+  /users/{userId}:
+    get:
+      operationId: getUser
+      summary: Get a user by ID
+      parameters:
+        - name: userId
+          in: path
+          required: true
+          description: ID of the user.
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: The requested user
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/User'
+    delete:
+      operationId: deleteUser
+      summary: Delete a user
+      parameters:
+        - name: userId
+          in: path
+          required: true
+          description: ID of the user.
+          schema:
+            type: integer
+      responses:
+        '204':
+          description: User deleted
+  /sessions:
+    post:
+      operationId: createSession
+      summary: Log in and create a session
+      requestBody:
+        required: true
+        content:
+          application/x-www-form-urlencoded:
+            schema:
+              type: object
+              required:
+                - username
+                - password
+              properties:
+                username:
+                  type: string
+                password:
+                  type: string
+                  format: password
+      responses:
+        '200':
+          description: The created session token
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - token
+                properties:
+                  token:
+                    type: string
+components:
+  schemas:
+    User:
+      allOf:
+        - $ref: '#/components/schemas/NewUser'
+        - type: object
+          required:
+            - id
+          properties:
+            id:
+              type: integer
+    NewUser:
+      type: object
+      required:
+        - name
+      properties:
+        name:
+          type: string
+          description: Full display name.
+        email:
+          type: string
+          format: email
+
+Inferred a baseline OpenAPI description from traffic: 5 operation(s).
+Refining the description with AI provider "claude"...
+Note: --with-ai sends samples of the recorded traffic (URLs, query strings, request and response bodies) to the selected AI provider. Make sure the traffic contains no secrets or personal data you are not allowed to share.
+[1/5] Refining GET /users...
+[1/5] GET /users — refined (<t>s)
+[2/5] Refining POST /users...
+[2/5] POST /users — refined (<t>s)
+[3/5] Refining GET /users/{userId}...
+[3/5] GET /users/{userId} — refined (<t>s)
+[4/5] Refining DELETE /users/{userId}...
+[4/5] DELETE /users/{userId} — refined (<t>s)
+[5/5] Refining POST /sessions...
+[5/5] POST /sessions — refined (<t>s)
+AI refinement complete: 5 of 5 operation(s) refined (claude).
+Done in <t>.
diff --git a/tests/e2e/generate-spec/__snapshots__/infer-har.txt b/tests/e2e/generate-spec/__snapshots__/infer-har.txt
new file mode 100644
index 0000000000..781d03665d
--- /dev/null
+++ b/tests/e2e/generate-spec/__snapshots__/infer-har.txt
@@ -0,0 +1,59 @@
+openapi: 3.2.0
+info:
+  title: Generated API
+  version: 1.0.0
+servers:
+  - url: http://api.example.com
+paths:
+  /pets:
+    get:
+      operationId: get-pets
+      responses:
+        '200':
+          description: Observed response
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Pet'
+    post:
+      operationId: post-pets
+      responses:
+        '201':
+          description: Observed response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Pet'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                name:
+                  type: string
+                tag:
+                  type: string
+              required:
+                - name
+                - tag
+components:
+  schemas:
+    Pet:
+      type: object
+      properties:
+        id:
+          type: integer
+        name:
+          type: string
+        tag:
+          type: string
+      required:
+        - id
+        - name
+        - tag
+
+Inferred a baseline OpenAPI description from traffic: 2 operation(s).
+Done in <t>.
diff --git a/tests/e2e/generate-spec/__snapshots__/infer-id-templates.txt b/tests/e2e/generate-spec/__snapshots__/infer-id-templates.txt
new file mode 100644
index 0000000000..5a96117a7c
--- /dev/null
+++ b/tests/e2e/generate-spec/__snapshots__/infer-id-templates.txt
@@ -0,0 +1,138 @@
+openapi: 3.2.0
+info:
+  title: Generated API
+  version: 1.0.0
+servers:
+  - url: http://api.example.com
+paths:
+  /orgs/{orgId}/members:
+    get:
+      operationId: get-orgs-orgId-members
+      responses:
+        '200':
+          description: Observed response
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    id:
+                      type: string
+                    role:
+                      type: string
+                  required:
+                    - id
+                    - role
+      parameters:
+        - name: orgId
+          in: path
+          required: true
+          schema:
+            type: string
+  /items/{itemId}:
+    get:
+      operationId: get-items-itemId
+      responses:
+        '200':
+          description: Observed response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  sku:
+                    type: string
+                required:
+                  - sku
+      parameters:
+        - name: itemId
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+  /jobs/{jobId}:
+    get:
+      operationId: get-jobs-jobId
+      responses:
+        '200':
+          description: Observed response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  state:
+                    type: string
+                required:
+                  - state
+      parameters:
+        - name: jobId
+          in: path
+          required: true
+          schema:
+            type: string
+  /blobs/{blobId}:
+    get:
+      operationId: get-blobs-blobId
+      responses:
+        '200':
+          description: Observed response
+      parameters:
+        - name: blobId
+          in: path
+          required: true
+          schema:
+            type: string
+  /users/{userId}/orders/{orderId}:
+    get:
+      operationId: get-users-userId-orders-orderId
+      responses:
+        '200':
+          description: Observed response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  total:
+                    type: number
+                required:
+                  - total
+      parameters:
+        - name: userId
+          in: path
+          required: true
+          schema:
+            type: integer
+        - name: orderId
+          in: path
+          required: true
+          schema:
+            type: integer
+  /categories/{categoryId}:
+    get:
+      operationId: get-categories-categoryId
+      responses:
+        '200':
+          description: Observed response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  name:
+                    type: string
+                required:
+                  - name
+      parameters:
+        - name: categoryId
+          in: path
+          required: true
+          schema:
+            type: integer
+
+Inferred a baseline OpenAPI description from traffic: 6 operation(s).
+Done in <t>.
diff --git a/tests/e2e/generate-spec/__snapshots__/infer-ndjson.txt b/tests/e2e/generate-spec/__snapshots__/infer-ndjson.txt
new file mode 100644
index 0000000000..ac3b262a50
--- /dev/null
+++ b/tests/e2e/generate-spec/__snapshots__/infer-ndjson.txt
@@ -0,0 +1,126 @@
+openapi: 3.2.0
+info:
+  title: Generated API
+  version: 1.0.0
+servers:
+  - url: http://api.example.com
+paths:
+  /users:
+    get:
+      operationId: get-users
+      responses:
+        '200':
+          description: Observed response
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/User'
+      parameters:
+        - name: limit
+          in: query
+          required: false
+          schema:
+            type: integer
+        - name: sort
+          in: query
+          required: false
+          schema:
+            type: string
+    post:
+      operationId: post-users
+      responses:
+        '201':
+          description: Observed response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/User'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                name:
+                  type: string
+                email:
+                  type: string
+                  format: email
+              required:
+                - name
+                - email
+  /users/{userId}:
+    get:
+      operationId: get-users-userId
+      responses:
+        '200':
+          description: Observed response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/User'
+      parameters:
+        - name: userId
+          in: path
+          required: true
+          schema:
+            type: integer
+    delete:
+      operationId: delete-users-userId
+      responses:
+        '204':
+          description: Observed response
+      parameters:
+        - name: userId
+          in: path
+          required: true
+          schema:
+            type: integer
+  /sessions:
+    post:
+      operationId: post-sessions
+      responses:
+        '200':
+          description: Observed response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  token:
+                    type: string
+                required:
+                  - token
+      requestBody:
+        content:
+          application/x-www-form-urlencoded:
+            schema:
+              type: object
+              properties:
+                username:
+                  type: string
+                password:
+                  type: string
+              required:
+                - username
+                - password
+components:
+  schemas:
+    User:
+      type: object
+      properties:
+        id:
+          type: integer
+        name:
+          type: string
+        email:
+          type: string
+          format: email
+      required:
+        - id
+        - name
+
+Inferred a baseline OpenAPI description from traffic: 5 operation(s).
+Done in <t>.
diff --git a/tests/e2e/generate-spec/__snapshots__/infer-polymorphic.txt b/tests/e2e/generate-spec/__snapshots__/infer-polymorphic.txt
new file mode 100644
index 0000000000..ae7de45b7c
--- /dev/null
+++ b/tests/e2e/generate-spec/__snapshots__/infer-polymorphic.txt
@@ -0,0 +1,92 @@
+openapi: 3.2.0
+info:
+  title: Generated API
+  version: 1.0.0
+servers:
+  - url: http://api.example.com
+paths:
+  /payments:
+    post:
+      operationId: post-payments
+      responses:
+        '201':
+          description: Observed response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  id:
+                    type: string
+                  status:
+                    type: string
+                    enum:
+                      - pending
+                      - succeeded
+                required:
+                  - id
+                  - status
+      requestBody:
+        content:
+          application/json:
+            schema:
+              oneOf:
+                - type: object
+                  properties:
+                    type:
+                      type: string
+                    amount:
+                      type: number
+                    cardNumber:
+                      type: string
+                    cvv:
+                      type: string
+                  required:
+                    - type
+                    - amount
+                    - cardNumber
+                    - cvv
+                - type: object
+                  properties:
+                    type:
+                      type: string
+                    amount:
+                      type: integer
+                    iban:
+                      type: string
+                  required:
+                    - type
+                    - amount
+                    - iban
+  /payments/{paymentId}:
+    get:
+      operationId: get-payments-paymentId
+      responses:
+        '200':
+          description: Observed response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  id:
+                    type: string
+                  status:
+                    type: string
+                  note:
+                    type:
+                      - string
+                      - 'null'
+                required:
+                  - id
+                  - status
+                  - note
+      parameters:
+        - name: paymentId
+          in: path
+          required: true
+          schema:
+            type: string
+
+Inferred a baseline OpenAPI description from traffic: 2 operation(s).
+Done in <t>.
diff --git a/tests/e2e/generate-spec/__snapshots__/infer-server-scoped.txt b/tests/e2e/generate-spec/__snapshots__/infer-server-scoped.txt
new file mode 100644
index 0000000000..0b6c6c0163
--- /dev/null
+++ b/tests/e2e/generate-spec/__snapshots__/infer-server-scoped.txt
@@ -0,0 +1,50 @@
+openapi: 3.2.0
+info:
+  title: Generated API
+  version: 1.0.0
+servers:
+  - url: http://api.example.com/v2
+paths:
+  /products:
+    get:
+      operationId: get-products
+      responses:
+        '200':
+          description: Observed response
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Product'
+  /products/{productId}:
+    get:
+      operationId: get-products-productId
+      responses:
+        '200':
+          description: Observed response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Product'
+      parameters:
+        - name: productId
+          in: path
+          required: true
+          schema:
+            type: integer
+components:
+  schemas:
+    Product:
+      type: object
+      properties:
+        id:
+          type: integer
+        name:
+          type: string
+      required:
+        - id
+        - name
+
+Inferred a baseline OpenAPI description from traffic: 2 operation(s).
+Done in <t>.
diff --git a/tests/e2e/generate-spec/fixtures/bin-bad/claude b/tests/e2e/generate-spec/fixtures/bin-bad/claude
new file mode 100755
index 0000000000..ac4d323674
--- /dev/null
+++ b/tests/e2e/generate-spec/fixtures/bin-bad/claude
@@ -0,0 +1,4 @@
+#!/bin/sh
+# Stub of the "claude" CLI that returns something that is not an OpenAPI document.
+cat > /dev/null
+echo "Sorry, I cannot produce an OpenAPI description for this traffic."
diff --git a/tests/e2e/generate-spec/fixtures/bin-fail/claude b/tests/e2e/generate-spec/fixtures/bin-fail/claude
new file mode 100755
index 0000000000..7cc107eab9
--- /dev/null
+++ b/tests/e2e/generate-spec/fixtures/bin-fail/claude
@@ -0,0 +1,5 @@
+#!/bin/sh
+# Stub of the "claude" CLI that crashes.
+cat > /dev/null
+echo "stub provider crashed" >&2
+exit 7
diff --git a/tests/e2e/generate-spec/fixtures/bin-ok-polymorphic/claude b/tests/e2e/generate-spec/fixtures/bin-ok-polymorphic/claude
new file mode 100755
index 0000000000..d6d15adcba
--- /dev/null
+++ b/tests/e2e/generate-spec/fixtures/bin-ok-polymorphic/claude
@@ -0,0 +1,14 @@
+#!/bin/sh
+# Stub of the "claude" CLI: return the raw fragment fixture (no code fences)
+# for the operation named on the last line of the prompt read from stdin.
+operation=$(sed -n 's/^Refine \([A-Z]*\) \([^ ]*\) as instructed.*/\1 \2/p' | tail -n 1)
+method=$(printf '%s' "$operation" | cut -d' ' -f1 | tr '[:upper:]' '[:lower:]')
+path_slug=$(printf '%s' "$operation" | cut -d' ' -f2 | tr -cs '[:alnum:]' '-')
+path_slug=${path_slug#-}
+path_slug=${path_slug%-}
+fragment="$(dirname "$0")/fragments/$method-$path_slug.yaml"
+if [ ! -f "$fragment" ]; then
+  echo "stub: no fragment fixture for '$operation'" >&2
+  exit 1
+fi
+cat "$fragment"
diff --git a/tests/e2e/generate-spec/fixtures/bin-ok-polymorphic/fragments/get-payments-paymentId.yaml b/tests/e2e/generate-spec/fixtures/bin-ok-polymorphic/fragments/get-payments-paymentId.yaml
new file mode 100644
index 0000000000..d62d5e9701
--- /dev/null
+++ b/tests/e2e/generate-spec/fixtures/bin-ok-polymorphic/fragments/get-payments-paymentId.yaml
@@ -0,0 +1,18 @@
+paths:
+  /payments/{paymentId}:
+    get:
+      operationId: getPayment
+      summary: Get a payment by ID
+      parameters:
+        - name: paymentId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: The requested payment
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Payment'
diff --git a/tests/e2e/generate-spec/fixtures/bin-ok-polymorphic/fragments/post-payments.yaml b/tests/e2e/generate-spec/fixtures/bin-ok-polymorphic/fragments/post-payments.yaml
new file mode 100644
index 0000000000..d2660c367d
--- /dev/null
+++ b/tests/e2e/generate-spec/fixtures/bin-ok-polymorphic/fragments/post-payments.yaml
@@ -0,0 +1,77 @@
+paths:
+  /payments:
+    post:
+      operationId: createPayment
+      summary: Create a payment
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              oneOf:
+                - $ref: '#/components/schemas/CardPayment'
+                - $ref: '#/components/schemas/BankTransferPayment'
+              discriminator:
+                propertyName: type
+                mapping:
+                  card: '#/components/schemas/CardPayment'
+                  bank_transfer: '#/components/schemas/BankTransferPayment'
+      responses:
+        '201':
+          description: The created payment
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Payment'
+components:
+  schemas:
+    PaymentBase:
+      type: object
+      required:
+        - type
+        - amount
+      properties:
+        type:
+          type: string
+          enum:
+            - card
+            - bank_transfer
+          description: Selects the payment method variant.
+        amount:
+          type: number
+    CardPayment:
+      allOf:
+        - $ref: '#/components/schemas/PaymentBase'
+        - type: object
+          required:
+            - cardNumber
+            - cvv
+          properties:
+            cardNumber:
+              type: string
+            cvv:
+              type: string
+    BankTransferPayment:
+      allOf:
+        - $ref: '#/components/schemas/PaymentBase'
+        - type: object
+          required:
+            - iban
+          properties:
+            iban:
+              type: string
+    Payment:
+      type: object
+      required:
+        - id
+        - status
+      properties:
+        id:
+          type: string
+        status:
+          type: string
+        note:
+          type:
+            - string
+            - 'null'
+          description: Optional processing note.
diff --git a/tests/e2e/generate-spec/fixtures/bin-ok/claude b/tests/e2e/generate-spec/fixtures/bin-ok/claude
new file mode 100755
index 0000000000..824d137559
--- /dev/null
+++ b/tests/e2e/generate-spec/fixtures/bin-ok/claude
@@ -0,0 +1,17 @@
+#!/bin/sh
+# Stub of the "claude" CLI for the per-operation refinement flow: read the
+# prompt from stdin, find the operation named on its last line, and return the
+# matching fragment fixture, wrapped in code fences like a chatty model would.
+operation=$(sed -n 's/^Refine \([A-Z]*\) \([^ ]*\) as instructed.*/\1 \2/p' | tail -n 1)
+method=$(printf '%s' "$operation" | cut -d' ' -f1 | tr '[:upper:]' '[:lower:]')
+path_slug=$(printf '%s' "$operation" | cut -d' ' -f2 | tr -cs '[:alnum:]' '-')
+path_slug=${path_slug#-}
+path_slug=${path_slug%-}
+fragment="$(dirname "$0")/fragments/$method-$path_slug.yaml"
+if [ ! -f "$fragment" ]; then
+  echo "stub: no fragment fixture for '$operation'" >&2
+  exit 1
+fi
+echo '```yaml'
+cat "$fragment"
+echo '```'
diff --git a/tests/e2e/generate-spec/fixtures/bin-ok/cursor-agent b/tests/e2e/generate-spec/fixtures/bin-ok/cursor-agent
new file mode 100755
index 0000000000..7ad7ebcfcc
--- /dev/null
+++ b/tests/e2e/generate-spec/fixtures/bin-ok/cursor-agent
@@ -0,0 +1,3 @@
+#!/bin/sh
+# Stub of the Cursor CLI: same fragment-serving behavior as the claude stub.
+exec "$(dirname "$0")/claude"
diff --git a/tests/e2e/generate-spec/fixtures/bin-ok/fragments/delete-users-userId.yaml b/tests/e2e/generate-spec/fixtures/bin-ok/fragments/delete-users-userId.yaml
new file mode 100644
index 0000000000..f10baa994c
--- /dev/null
+++ b/tests/e2e/generate-spec/fixtures/bin-ok/fragments/delete-users-userId.yaml
@@ -0,0 +1,15 @@
+paths:
+  /users/{userId}:
+    delete:
+      operationId: deleteUser
+      summary: Delete a user
+      parameters:
+        - name: userId
+          in: path
+          required: true
+          description: ID of the user.
+          schema:
+            type: integer
+      responses:
+        '204':
+          description: User deleted
diff --git a/tests/e2e/generate-spec/fixtures/bin-ok/fragments/get-users-userId.yaml b/tests/e2e/generate-spec/fixtures/bin-ok/fragments/get-users-userId.yaml
new file mode 100644
index 0000000000..487e433d45
--- /dev/null
+++ b/tests/e2e/generate-spec/fixtures/bin-ok/fragments/get-users-userId.yaml
@@ -0,0 +1,19 @@
+paths:
+  /users/{userId}:
+    get:
+      operationId: getUser
+      summary: Get a user by ID
+      parameters:
+        - name: userId
+          in: path
+          required: true
+          description: ID of the user.
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: The requested user
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/User'
diff --git a/tests/e2e/generate-spec/fixtures/bin-ok/fragments/get-users.yaml b/tests/e2e/generate-spec/fixtures/bin-ok/fragments/get-users.yaml
new file mode 100644
index 0000000000..77e2dbf39b
--- /dev/null
+++ b/tests/e2e/generate-spec/fixtures/bin-ok/fragments/get-users.yaml
@@ -0,0 +1,49 @@
+paths:
+  /users:
+    get:
+      operationId: listUsers
+      summary: List users
+      parameters:
+        - name: limit
+          in: query
+          required: false
+          description: Maximum number of users returned.
+          schema:
+            type: integer
+        - name: sort
+          in: query
+          required: false
+          description: Field to sort the returned users by.
+          schema:
+            type: string
+      responses:
+        '200':
+          description: A page of users
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/User'
+components:
+  schemas:
+    User:
+      allOf:
+        - $ref: '#/components/schemas/NewUser'
+        - type: object
+          required:
+            - id
+          properties:
+            id:
+              type: integer
+    NewUser:
+      type: object
+      required:
+        - name
+      properties:
+        name:
+          type: string
+          description: Full display name.
+        email:
+          type: string
+          format: email
diff --git a/tests/e2e/generate-spec/fixtures/bin-ok/fragments/post-sessions.yaml b/tests/e2e/generate-spec/fixtures/bin-ok/fragments/post-sessions.yaml
new file mode 100644
index 0000000000..dd3d964242
--- /dev/null
+++ b/tests/e2e/generate-spec/fixtures/bin-ok/fragments/post-sessions.yaml
@@ -0,0 +1,32 @@
+paths:
+  /sessions:
+    post:
+      operationId: createSession
+      summary: Log in and create a session
+      requestBody:
+        required: true
+        content:
+          application/x-www-form-urlencoded:
+            schema:
+              type: object
+              required:
+                - username
+                - password
+              properties:
+                username:
+                  type: string
+                password:
+                  type: string
+                  format: password
+      responses:
+        '200':
+          description: The created session token
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - token
+                properties:
+                  token:
+                    type: string
diff --git a/tests/e2e/generate-spec/fixtures/bin-ok/fragments/post-users.yaml b/tests/e2e/generate-spec/fixtures/bin-ok/fragments/post-users.yaml
new file mode 100644
index 0000000000..87f4503cfd
--- /dev/null
+++ b/tests/e2e/generate-spec/fixtures/bin-ok/fragments/post-users.yaml
@@ -0,0 +1,18 @@
+paths:
+  /users:
+    post:
+      operationId: createUser
+      summary: Create a user
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/NewUser'
+      responses:
+        '201':
+          description: The created user
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/User'
diff --git a/tests/e2e/generate-spec/fixtures/bin-partial/claude b/tests/e2e/generate-spec/fixtures/bin-partial/claude
new file mode 100755
index 0000000000..9081177b78
--- /dev/null
+++ b/tests/e2e/generate-spec/fixtures/bin-partial/claude
@@ -0,0 +1,5 @@
+#!/bin/sh
+# Stub of the "claude" CLI that returns the same document containing only the
+# GET /users operation, whatever operation the prompt asks for.
+cat > /dev/null
+cat "$(dirname "$0")/partial.yaml"
diff --git a/tests/e2e/generate-spec/fixtures/bin-partial/partial.yaml b/tests/e2e/generate-spec/fixtures/bin-partial/partial.yaml
new file mode 100644
index 0000000000..43edac0924
--- /dev/null
+++ b/tests/e2e/generate-spec/fixtures/bin-partial/partial.yaml
@@ -0,0 +1,12 @@
+openapi: 3.2.0
+info:
+  title: Users API (refined by stub)
+  version: 1.0.0
+paths:
+  /users:
+    get:
+      operationId: listUsers
+      summary: List users
+      responses:
+        '200':
+          description: A page of users
diff --git a/tests/e2e/generate-spec/fixtures/traffic-ids.ndjson b/tests/e2e/generate-spec/fixtures/traffic-ids.ndjson
new file mode 100644
index 0000000000..7b3aac9fed
--- /dev/null
+++ b/tests/e2e/generate-spec/fixtures/traffic-ids.ndjson
@@ -0,0 +1,6 @@
+{"request":{"method":"GET","url":"http://api.example.com/orgs/org_01ks7rnqsyy0g6h37rfmen7zv9/members","headers":{"host":"api.example.com"}},"response":{"status":200,"headers":{"content-type":"application/json"},"body":"[{\"id\":\"usr_1\",\"role\":\"admin\"}]"}}
+{"request":{"method":"GET","url":"http://api.example.com/items/550e8400-e29b-41d4-a716-446655440000","headers":{"host":"api.example.com"}},"response":{"status":200,"headers":{"content-type":"application/json"},"body":"{\"sku\":\"A-1\"}"}}
+{"request":{"method":"GET","url":"http://api.example.com/jobs/01ARZ3NDEKTSV4RRFFQ69G5FAV","headers":{"host":"api.example.com"}},"response":{"status":200,"headers":{"content-type":"application/json"},"body":"{\"state\":\"done\"}"}}
+{"request":{"method":"GET","url":"http://api.example.com/blobs/a3f5c9d2e8b1470f9c2d5e8a7b3f1c4d","headers":{"host":"api.example.com"}},"response":{"status":200,"headers":{"content-type":"application/octet-stream"}}}
+{"request":{"method":"GET","url":"http://api.example.com/users/42/orders/1001","headers":{"host":"api.example.com"}},"response":{"status":200,"headers":{"content-type":"application/json"},"body":"{\"total\":9.99}"}}
+{"request":{"method":"GET","url":"http://api.example.com/categories/12","headers":{"host":"api.example.com"}},"response":{"status":200,"headers":{"content-type":"application/json"},"body":"{\"name\":\"books\"}"}}
diff --git a/tests/e2e/generate-spec/fixtures/traffic-polymorphic.ndjson b/tests/e2e/generate-spec/fixtures/traffic-polymorphic.ndjson
new file mode 100644
index 0000000000..9e0e017f0e
--- /dev/null
+++ b/tests/e2e/generate-spec/fixtures/traffic-polymorphic.ndjson
@@ -0,0 +1,6 @@
+{"request":{"method":"POST","url":"http://api.example.com/payments","headers":{"host":"api.example.com","content-type":"application/json"},"body":"{\"type\":\"card\",\"amount\":100,\"cardNumber\":\"4111111111111111\",\"cvv\":\"123\"}"},"response":{"status":201,"headers":{"content-type":"application/json"},"body":"{\"id\":\"pay_01hzy3kducb5cd8wnt42rk9gnf\",\"status\":\"succeeded\"}"}}
+{"request":{"method":"POST","url":"http://api.example.com/payments","headers":{"host":"api.example.com","content-type":"application/json"},"body":"{\"type\":\"card\",\"amount\":250.5,\"cardNumber\":\"5500000000000004\",\"cvv\":\"999\"}"},"response":{"status":201,"headers":{"content-type":"application/json"},"body":"{\"id\":\"pay_01hzy3kea7yj0v8m6qc5xrd2p1\",\"status\":\"succeeded\"}"}}
+{"request":{"method":"POST","url":"http://api.example.com/payments","headers":{"host":"api.example.com","content-type":"application/json"},"body":"{\"type\":\"bank_transfer\",\"amount\":75,\"iban\":\"DE89370400440532013000\"}"},"response":{"status":201,"headers":{"content-type":"application/json"},"body":"{\"id\":\"pay_01hzy3kfhx2b9t4k7se6wmz8q3\",\"status\":\"pending\"}"}}
+{"request":{"method":"POST","url":"http://api.example.com/payments","headers":{"host":"api.example.com","content-type":"application/json"},"body":"{\"type\":\"bank_transfer\",\"amount\":420,\"iban\":\"FR1420041010050500013M02606\"}"},"response":{"status":201,"headers":{"content-type":"application/json"},"body":"{\"id\":\"pay_01hzy3kg9r5n1c6v0xt3ypa7d4\",\"status\":\"pending\"}"}}
+{"request":{"method":"GET","url":"http://api.example.com/payments/pay_01hzy3kducb5cd8wnt42rk9gnf","headers":{"host":"api.example.com"}},"response":{"status":200,"headers":{"content-type":"application/json"},"body":"{\"id\":\"pay_01hzy3kducb5cd8wnt42rk9gnf\",\"status\":\"succeeded\",\"note\":null}"}}
+{"request":{"method":"GET","url":"http://api.example.com/payments/pay_01hzy3kfhx2b9t4k7se6wmz8q3","headers":{"host":"api.example.com"}},"response":{"status":200,"headers":{"content-type":"application/json"},"body":"{\"id\":\"pay_01hzy3kfhx2b9t4k7se6wmz8q3\",\"status\":\"pending\",\"note\":\"Awaiting bank confirmation\"}"}}
diff --git a/tests/e2e/generate-spec/fixtures/traffic-servers.ndjson b/tests/e2e/generate-spec/fixtures/traffic-servers.ndjson
new file mode 100644
index 0000000000..b8ab30f4c4
--- /dev/null
+++ b/tests/e2e/generate-spec/fixtures/traffic-servers.ndjson
@@ -0,0 +1,4 @@
+{"request":{"method":"GET","url":"http://api.example.com/v2/products","headers":{"host":"api.example.com"}},"response":{"status":200,"headers":{"content-type":"application/json"},"body":"[{\"id\":5,\"name\":\"Widget\"}]"}}
+{"request":{"method":"GET","url":"http://api.example.com/v2/products/5","headers":{"host":"api.example.com"}},"response":{"status":200,"headers":{"content-type":"application/json"},"body":"{\"id\":5,\"name\":\"Widget\"}"}}
+{"request":{"method":"GET","url":"http://internal.example.com/health","headers":{"host":"internal.example.com"}},"response":{"status":200,"headers":{"content-type":"application/json"},"body":"{\"ok\":true}"}}
+{"request":{"method":"GET","url":"http://api.example.com/legacy/ping","headers":{"host":"api.example.com"}},"response":{"status":200,"headers":{"content-type":"text/plain"},"body":"pong"}}
diff --git a/tests/e2e/generate-spec/fixtures/traffic.har b/tests/e2e/generate-spec/fixtures/traffic.har
new file mode 100644
index 0000000000..fa4a8ce31a
--- /dev/null
+++ b/tests/e2e/generate-spec/fixtures/traffic.har
@@ -0,0 +1,45 @@
+{
+  "log": {
+    "version": "1.2",
+    "creator": { "name": "generate-spec-test", "version": "1.0" },
+    "entries": [
+      {
+        "startedDateTime": "2024-01-01T00:00:00.000Z",
+        "request": {
+          "method": "GET",
+          "url": "http://api.example.com/pets",
+          "headers": [{ "name": "Host", "value": "api.example.com" }]
+        },
+        "response": {
+          "status": 200,
+          "content": {
+            "mimeType": "application/json",
+            "text": "[{\"id\":1,\"name\":\"Rex\",\"tag\":\"dog\"}]"
+          }
+        }
+      },
+      {
+        "startedDateTime": "2024-01-01T00:00:01.000Z",
+        "request": {
+          "method": "POST",
+          "url": "http://api.example.com/pets",
+          "headers": [
+            { "name": "Host", "value": "api.example.com" },
+            { "name": "Content-Type", "value": "application/json" }
+          ],
+          "postData": {
+            "mimeType": "application/json",
+            "text": "{\"name\":\"Whiskers\",\"tag\":\"cat\"}"
+          }
+        },
+        "response": {
+          "status": 201,
+          "content": {
+            "mimeType": "application/json",
+            "text": "{\"id\":2,\"name\":\"Whiskers\",\"tag\":\"cat\"}"
+          }
+        }
+      }
+    ]
+  }
+}
diff --git a/tests/e2e/generate-spec/fixtures/traffic.ndjson b/tests/e2e/generate-spec/fixtures/traffic.ndjson
new file mode 100644
index 0000000000..b4fae90157
--- /dev/null
+++ b/tests/e2e/generate-spec/fixtures/traffic.ndjson
@@ -0,0 +1,6 @@
+{"request":{"method":"GET","url":"http://api.example.com/users?limit=10&sort=name","headers":{"host":"api.example.com"}},"response":{"status":200,"headers":{"content-type":"application/json"},"body":"[{\"id\":1,\"name\":\"Ada\",\"email\":\"ada@example.com\"},{\"id\":2,\"name\":\"Grace\"}]"}}
+{"request":{"method":"GET","url":"http://api.example.com/users/42","headers":{"host":"api.example.com"}},"response":{"status":200,"headers":{"content-type":"application/json"},"body":"{\"id\":42,\"name\":\"Ada\",\"email\":\"ada@example.com\"}"}}
+{"request":{"method":"GET","url":"http://api.example.com/users/7","headers":{"host":"api.example.com"}},"response":{"status":200,"headers":{"content-type":"application/json"},"body":"{\"id\":7,\"name\":\"Grace\"}"}}
+{"request":{"method":"POST","url":"http://api.example.com/users","headers":{"host":"api.example.com","content-type":"application/json"},"body":"{\"name\":\"Linus\",\"email\":\"linus@example.com\"}"},"response":{"status":201,"headers":{"content-type":"application/json"},"body":"{\"id\":3,\"name\":\"Linus\",\"email\":\"linus@example.com\"}"}}
+{"request":{"method":"DELETE","url":"http://api.example.com/users/42","headers":{"host":"api.example.com"}},"response":{"status":204,"headers":{}}}
+{"request":{"method":"POST","url":"http://api.example.com/sessions","headers":{"host":"api.example.com","content-type":"application/x-www-form-urlencoded"},"body":"username=ada&password=secret"},"response":{"status":200,"headers":{"content-type":"application/json"},"body":"{\"token\":\"abc123\"}"}}
diff --git a/tests/e2e/generate-spec/generate-spec.test.ts b/tests/e2e/generate-spec/generate-spec.test.ts
new file mode 100644
index 0000000000..132925a6ae
--- /dev/null
+++ b/tests/e2e/generate-spec/generate-spec.test.ts
@@ -0,0 +1,207 @@
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { delimiter, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { cleanupOutput } from '../helpers.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const indexEntryPoint = join(process.cwd(), 'packages/cli/lib/index.js');
+const fixtures = join(__dirname, 'fixtures');
+const snapshots = join(__dirname, '__snapshots__');
+
+function runGenerateSpec(
+  args: string[],
+  env: Record<string, string> = {}
+): { output: string; code: number | null } {
+  const result = spawnSync('node', [indexEntryPoint, 'generate-spec', ...args], {
+    encoding: 'utf-8',
+    stdio: 'pipe',
+    cwd: fixtures,
+    env: { ...process.env, NODE_ENV: 'test', NO_COLOR: 'TRUE', FORCE_COLOR: '0', ...env },
+  });
+
+  if (result.error) {
+    throw new Error(`Command execution failed: ${result.error.message}`);
+  }
+
+  const out = result.stdout?.toString() ?? '';
+  const err = result.stderr?.toString() ?? '';
+  // Per-operation progress lines and the closing summary report wall-clock
+  // durations; normalize them.
+  const output = cleanupOutput(`${out}\n${err}`)
+    .replace(/\(\d+s\)/g, '(<t>s)')
+    .replace(/Done in (?:\d+m )?\d+s\./g, 'Done in <t>.');
+  return { output, code: result.status };
+}
+
+// Prepend a stub-provider bin directory to PATH so the spawned "claude" CLI
+// resolves to the fixture stub instead of a real installation.
+function withStub(binDir: string): Record<string, string> {
+  return { PATH: `${join(fixtures, binDir)}${delimiter}${process.env.PATH}` };
+}
+
+async function matchSnapshot(name: string, output: string): Promise<void> {
+  await expect(output).toMatchFileSnapshot(join(snapshots, `${name}.txt`));
+}
+
+describe('generate-spec - deterministic inference', () => {
+  test('infers an OpenAPI description from NDJSON traffic', async () => {
+    const { output, code } = runGenerateSpec(['traffic.ndjson']);
+    expect(code).toBe(0);
+    await matchSnapshot('infer-ndjson', output);
+  });
+
+  test('templatizes identifier-like path segments into path parameters', async () => {
+    const { output, code } = runGenerateSpec(['traffic-ids.ndjson']);
+    expect(code).toBe(0);
+    await matchSnapshot('infer-id-templates', output);
+  });
+
+  test('infers an OpenAPI description from HAR traffic', async () => {
+    const { output, code } = runGenerateSpec(['traffic.har', '--traffic-format', 'har']);
+    expect(code).toBe(0);
+    await matchSnapshot('infer-har', output);
+  });
+
+  test('describes alternative body shapes with oneOf and nullable type unions', async () => {
+    const { output, code } = runGenerateSpec(['traffic-polymorphic.ndjson']);
+    expect(code).toBe(0);
+    await matchSnapshot('infer-polymorphic', output);
+  });
+
+  test('scopes traffic to --server and rebases paths onto it', async () => {
+    const { output, code } = runGenerateSpec([
+      'traffic-servers.ndjson',
+      '--server',
+      'http://api.example.com/v2',
+    ]);
+    expect(code).toBe(0);
+    await matchSnapshot('infer-server-scoped', output);
+  });
+
+  test('uses --title for the generated description', () => {
+    const { output, code } = runGenerateSpec(['traffic.ndjson', '--title', 'Custom Users API']);
+    expect(code).toBe(0);
+    expect(output).toContain('title: Custom Users API');
+  });
+
+  test('writes the description to a file with --output', () => {
+    const outputDir = mkdtempSync(join(tmpdir(), 'generate-spec-'));
+    const outputFile = join(outputDir, 'nested', 'openapi.yaml');
+    try {
+      const { output, code } = runGenerateSpec(['traffic.ndjson', '--output', outputFile]);
+      expect(code).toBe(0);
+      expect(output).toContain('Written to:');
+      expect(output).not.toContain('openapi: 3.2.0');
+      const document = readFileSync(outputFile, 'utf-8');
+      expect(document).toContain('openapi: 3.2.0');
+      expect(document).toContain('/users/{userId}');
+    } finally {
+      rmSync(outputDir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('generate-spec - error handling', () => {
+  test('fails when no traffic matches the --server', () => {
+    const { output, code } = runGenerateSpec([
+      'traffic.ndjson',
+      '--server',
+      'http://unrelated.example.com',
+    ]);
+    expect(code).toBe(1);
+    expect(output).toContain('No HTTP exchanges in the traffic matched the server');
+  });
+
+  test('fails when the traffic path does not exist', () => {
+    const { code } = runGenerateSpec(['does-not-exist.ndjson']);
+    expect(code).toBe(1);
+  });
+});
+
+describe('generate-spec - AI refinement', () => {
+  test('refines every operation with the provider fragments', async () => {
+    // Sequential refinement keeps the per-operation progress lines in a
+    // deterministic order for the snapshot.
+    const { output, code } = runGenerateSpec(
+      ['traffic.ndjson', '--with-ai', '--ai-provider', 'claude', '--ai-concurrency', '1'],
+      withStub('bin-ok')
+    );
+    expect(code).toBe(0);
+    expect(output).toContain('AI refinement complete: 5 of 5 operation(s) refined (claude).');
+    await matchSnapshot('ai-refined', output);
+  });
+
+  test('accepts refined operations that use oneOf, allOf and discriminator', async () => {
+    const { output, code } = runGenerateSpec(
+      [
+        'traffic-polymorphic.ndjson',
+        '--with-ai',
+        '--ai-provider',
+        'claude',
+        '--ai-concurrency',
+        '1',
+      ],
+      withStub('bin-ok-polymorphic')
+    );
+    expect(code).toBe(0);
+    expect(output).toContain('AI refinement complete: 2 of 2 operation(s) refined (claude).');
+    await matchSnapshot('ai-refined-polymorphic', output);
+  });
+
+  test('runs the Cursor CLI when the cursor provider is selected', () => {
+    const { output, code } = runGenerateSpec(
+      ['traffic.ndjson', '--with-ai', '--ai-provider', 'cursor', '--ai-concurrency', '1'],
+      withStub('bin-ok')
+    );
+    expect(code).toBe(0);
+    expect(output).toContain('AI refinement complete: 5 of 5 operation(s) refined (cursor).');
+  });
+
+  test('keeps the baseline for operations the provider does not refine', () => {
+    const { output, code } = runGenerateSpec(
+      ['traffic.ndjson', '--with-ai', '--ai-provider', 'claude', '--ai-concurrency', '1'],
+      withStub('bin-partial')
+    );
+    expect(code).toBe(0);
+    expect(output).toContain('[1/5] GET /users — refined');
+    expect(output).toContain('kept the baseline');
+    expect(output).toContain('AI refinement complete: 1 of 5 operation(s) refined (claude).');
+    expect(output).toContain('operationId: post-sessions');
+  });
+
+  test('falls back to the baseline when the provider returns a non-YAML answer', () => {
+    const { output, code } = runGenerateSpec(
+      ['traffic.ndjson', '--with-ai', '--ai-provider', 'claude'],
+      withStub('bin-bad')
+    );
+    expect(code).toBe(0);
+    expect(output).toContain('AI refinement failed, falling back to the baseline description');
+    expect(output).toContain('did not produce a usable refinement for any operation');
+    expect(output).toContain('openapi: 3.2.0');
+    expect(output).toContain('/users/{userId}');
+  });
+
+  test('falls back to the baseline when the provider CLI exits with an error', () => {
+    const { output, code } = runGenerateSpec(
+      ['traffic.ndjson', '--with-ai', '--ai-provider', 'claude'],
+      withStub('bin-fail')
+    );
+    expect(code).toBe(0);
+    expect(output).toContain('claude CLI exited with code 7');
+    expect(output).toContain('openapi: 3.2.0');
+  });
+
+  test('falls back to the baseline when the provider CLI is not installed', () => {
+    const { output, code } = runGenerateSpec(
+      ['traffic.ndjson', '--with-ai', '--ai-provider', 'claude'],
+      // Restrict PATH to the node binary directory so "claude" cannot resolve.
+      { PATH: dirname(process.execPath) }
+    );
+    expect(code).toBe(0);
+    expect(output).toContain('Could not find the "claude" CLI on PATH');
+    expect(output).toContain('openapi: 3.2.0');
+  });
+});