From 2e19dd0cc520ac05b884a6a0aab62aa294687c42 Mon Sep 17 00:00:00 2001
From: DmitryAnansky <dmytro@redocly.com>
Date: Tue, 25 Aug 2026 18:34:27 +0300
Subject: [PATCH 1/6] feat: add the experimental `--with-ai` and
 `--ai-provider` options for `generate-arazzo` command

---
 .changeset/generate-arazzo-respect-hint.md    |   5 +
 .changeset/generate-arazzo-with-ai.md         |   7 +
 docs/@v2/commands/generate-arazzo.md          |  54 ++++-
 .../commands/generate-arazzo.test.ts          | 128 +++++++++++-
 packages/cli/src/commands/generate-arazzo.ts  |  45 -----
 .../__tests__/generate-workflows.test.ts      | 166 ++++++++++++++++
 .../generate-arazzo/ai/generate-workflows.ts  | 185 ++++++++++++++++++
 .../src/commands/generate-arazzo/ai/prompt.ts |  58 ++++++
 .../cli/src/commands/generate-arazzo/index.ts | 147 ++++++++++++++
 .../generate-spec/__tests__/refine.test.ts    |   6 +-
 .../src/commands/generate-spec/ai/refine.ts   |  23 +--
 .../cli/src/commands/generate-spec/index.ts   |   2 +-
 packages/cli/src/index.ts                     |  22 ++-
 packages/cli/src/types.ts                     |   2 +-
 .../ai}/__tests__/providers.test.ts           |  10 +-
 packages/cli/src/utils/ai/output.ts           |  21 ++
 .../generate-spec => utils}/ai/providers.ts   |   2 +-
 packages/respect-core/src/generate.ts         |   3 +-
 .../generate-arazzo-description.test.ts       |   8 +-
 .../generate-inputs-arazzo-components.test.ts |  46 ++++-
 .../generate-step-security.test.ts            | 100 ++++++++++
 ...erate-workflow-security-parameters.test.ts | 133 -------------
 .../generate-arazzo-description.ts            |   2 +-
 .../generate-inputs-arazzo-components.ts      |  34 ++--
 .../generate-step-security.ts                 |  73 +++++++
 .../generate-workflow-security-parameters.ts  |  52 -----
 .../generate-workflows-from-description.ts    |   9 +-
 .../arazzo-description-generator/index.ts     |   2 +-
 28 files changed, 1051 insertions(+), 294 deletions(-)
 create mode 100644 .changeset/generate-arazzo-respect-hint.md
 create mode 100644 .changeset/generate-arazzo-with-ai.md
 delete mode 100644 packages/cli/src/commands/generate-arazzo.ts
 create mode 100644 packages/cli/src/commands/generate-arazzo/__tests__/generate-workflows.test.ts
 create mode 100644 packages/cli/src/commands/generate-arazzo/ai/generate-workflows.ts
 create mode 100644 packages/cli/src/commands/generate-arazzo/ai/prompt.ts
 create mode 100644 packages/cli/src/commands/generate-arazzo/index.ts
 rename packages/cli/src/{commands/generate-spec => utils/ai}/__tests__/providers.test.ts (90%)
 create mode 100644 packages/cli/src/utils/ai/output.ts
 rename packages/cli/src/{commands/generate-spec => utils}/ai/providers.ts (98%)
 create mode 100644 packages/respect-core/src/modules/__tests__/arazzo-description-generator/generate-step-security.test.ts
 delete mode 100644 packages/respect-core/src/modules/__tests__/arazzo-description-generator/generate-workflow-security-parameters.test.ts
 create mode 100644 packages/respect-core/src/modules/arazzo-description-generator/generate-step-security.ts
 delete mode 100644 packages/respect-core/src/modules/arazzo-description-generator/generate-workflow-security-parameters.ts

diff --git a/.changeset/generate-arazzo-respect-hint.md b/.changeset/generate-arazzo-respect-hint.md
new file mode 100644
index 0000000000..c54592b914
--- /dev/null
+++ b/.changeset/generate-arazzo-respect-hint.md
@@ -0,0 +1,5 @@
+---
+'@redocly/cli': minor
+---
+
+The `generate-arazzo` command now prints a ready-to-run `respect` command after generation, including an `--input` placeholder for every workflow input.
diff --git a/.changeset/generate-arazzo-with-ai.md b/.changeset/generate-arazzo-with-ai.md
new file mode 100644
index 0000000000..ec73be67cb
--- /dev/null
+++ b/.changeset/generate-arazzo-with-ai.md
@@ -0,0 +1,7 @@
+---
+'@redocly/cli': minor
+---
+
+Added `--with-ai`, `--ai-provider`, and `--max-workflows` options to the `generate-arazzo` command.
+With `--with-ai`, the generated one-workflow-per-operation skeleton is redesigned by a locally installed AI CLI (`claude`, `codex`, or `cursor`) into realistic multi-step workflows that chain operations through outputs and runtime expressions, using the OpenAPI description as context.
+The AI designs at most `--max-workflows` workflows (default 10), and the generated file is marked as AI-inferred.
diff --git a/docs/@v2/commands/generate-arazzo.md b/docs/@v2/commands/generate-arazzo.md
index f903abb02a..38f808c63a 100644
--- a/docs/@v2/commands/generate-arazzo.md
+++ b/docs/@v2/commands/generate-arazzo.md
@@ -17,10 +17,16 @@ It acts as a starting point for a test file and needs to be extended to be funct
 
 The first HTTP response is used as the success criteria for each step.
 
+After writing the file, the command prints a ready-to-run [`respect`](./respect.md) command, including an `--input` placeholder for every workflow input — replace the placeholder values with real ones before running it.
+
+With `--with-ai`, the generated one-workflow-per-operation skeleton is redesigned by an AI provider into realistic multi-step workflows, using the OpenAPI description as context.
+See the [Redesign workflows with AI](#redesign-workflows-with-ai) section.
+
 ## Usage
 
 ```sh
 npx @redocly/cli@latest generate-arazzo <your-OAS-description-file> [-o | --output-file]
+npx @redocly/cli@latest generate-arazzo <your-OAS-description-file> --with-ai [--ai-provider=<option>]
 ```
 
 ## Options
@@ -37,6 +43,24 @@ npx @redocly/cli@latest generate-arazzo <your-OAS-description-file> [-o | --outp
 - string
 - Name for the generated output file. Defaults to `auto-generated.arazzo.yaml` **If the file already exists, it's overwritten.** See the [specify output file](#specify-output-file) section.
 
+---
+
+- --with-ai
+- boolean
+- Redesign the generated workflows with an AI provider, using the OpenAPI description as context. Default value is `false`. See the [redesign workflows with AI](#redesign-workflows-with-ai) section.
+
+---
+
+- --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`.
+
+---
+
+- --max-workflows
+- number
+- Most workflows the AI may design with `--with-ai`, so the output contains the most likely scenarios instead of every combination. Default value is `10`.
+
 {% /table %}
 
 ## Examples
@@ -48,7 +72,7 @@ The command generates an `auto-generated.arazzo.yaml` file in the current direct
 The contents of the generated file are:
 
 ```yaml {% title="auto-generated.arazzo.yaml" %}
-arazzo: 1.0.1
+arazzo: 1.1.0
 info:
   title: Warp API
   version: 1.0.0
@@ -123,6 +147,34 @@ By default, the CLI tool writes the generated file as `auto-generated.arazzo.yam
 redocly generate-arazzo <your-OAS-description-file> --output-file=arazzo-custom.yaml
 ```
 
+### Redesign workflows with AI
+
+Without AI, the generated file contains one workflow per operation and no dependencies between them.
+With `--with-ai`, the OpenAPI description and the generated skeleton are sent to an AI provider, which redesigns the workflows into realistic scenarios: related operations are grouped into multi-step workflows (for example create, read, update, then delete a resource), steps pass values to each other through `outputs` and runtime expressions, and workflows declare `inputs` for values a caller must provide.
+
+The AI designs at most `--max-workflows` workflows (default `10`), preferring to cover every operation and otherwise choosing the most likely scenarios.
+
+The AI's answer is never trusted blindly: the `arazzo`, `info`, and `sourceDescriptions` fields always come from the generated baseline, every step must reference an operation that exists in the OpenAPI description, the workflow count must stay within `--max-workflows`, and the result must pass validation with the `spec` ruleset.
+If the answer is rejected, the provider fails, or the description is too large to prompt with, the command keeps the auto-generated workflows.
+
+The generated file starts with a comment marking the workflows as AI-inferred — they are a guess derived from the description, not verified behavior, so review them before use.
+
+```bash
+redocly generate-arazzo openapi.yaml --with-ai --ai-provider claude --max-workflows 5
+```
+
+{% admonition type="warning" name="Data sharing" %}
+`--with-ai` sends the resolved OpenAPI description to the selected AI provider.
+Make sure it contains no secrets or personal data you are not allowed to share.
+{% /admonition %}
+
+#### AI providers
+
+The workflows are designed by a locally installed AI CLI running 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 — no API key is passed to or stored by Redocly CLI.
+
+The provider runs in isolation: project context the CLIs normally load (such as `CLAUDE.md`, `AGENTS.md`, or `.cursor/rules`) does not apply.
+
 ## Resources
 
 - [Learn more about Arazzo](/learn/arazzo/what-is-arazzo).
diff --git a/packages/cli/src/__tests__/commands/generate-arazzo.test.ts b/packages/cli/src/__tests__/commands/generate-arazzo.test.ts
index 7c514780eb..139c50e20f 100644
--- a/packages/cli/src/__tests__/commands/generate-arazzo.test.ts
+++ b/packages/cli/src/__tests__/commands/generate-arazzo.test.ts
@@ -3,10 +3,12 @@ import { generate } from '@redocly/respect-core';
 import { writeFileSync } from 'node:fs';
 import { vi, describe, it, expect, beforeEach } from 'vitest';
 
+import { generateWorkflowsWithAi } from '../../commands/generate-arazzo/ai/generate-workflows.js';
 import {
+  buildRespectHint,
   type GenerateArazzoCommandArgv,
   handleGenerateArazzo,
-} from '../../commands/generate-arazzo.js';
+} from '../../commands/generate-arazzo/index.js';
 
 vi.mock('@redocly/respect-core', async () => {
   const actual =
@@ -18,12 +20,17 @@ vi.mock('@redocly/respect-core', async () => {
   };
 });
 
+vi.mock('../../commands/generate-arazzo/ai/generate-workflows.js', () => ({
+  generateWorkflowsWithAi: vi.fn(),
+}));
+
 vi.mock('@redocly/openapi-core', async () => {
   const actual = await vi.importActual('@redocly/openapi-core');
   return {
     ...actual,
     logger: {
       info: vi.fn(),
+      warn: vi.fn(),
     },
     stringifyYaml: vi.fn(() => 'mocked yaml'),
   };
@@ -37,7 +44,7 @@ vi.mock('node:fs', () => ({
 describe('handleGenerateArazzo', () => {
   beforeEach(() => {
     vi.clearAllMocks();
-    vi.mocked(generate).mockResolvedValue('{"mocked": "arazzo"}');
+    vi.mocked(generate).mockResolvedValue({ workflows: [] });
   });
 
   it('should call generate with the correct arguments', async () => {
@@ -56,7 +63,7 @@ describe('handleGenerateArazzo', () => {
     expect(generate).toHaveBeenCalledWith({
       outputFile: 'auto-generated.arazzo.yaml',
       descriptionPath: 'openapi.yaml',
-      collectSpecData: commandArgs.collectSpecData,
+      collectSpecData: expect.any(Function),
       version: '1.0.0',
       config: mockConfig,
     });
@@ -80,7 +87,7 @@ describe('handleGenerateArazzo', () => {
     expect(generate).toHaveBeenCalledWith({
       outputFile: 'custom.arazzo.yaml',
       descriptionPath: 'openapi.yaml',
-      collectSpecData: commandArgs.collectSpecData,
+      collectSpecData: expect.any(Function),
       version: '1.0.0',
       config: mockConfig,
     });
@@ -106,4 +113,117 @@ describe('handleGenerateArazzo', () => {
     );
     expect(writeFileSync).not.toHaveBeenCalled();
   });
+
+  it('should write the AI-designed workflows when --with-ai succeeds', async () => {
+    const mockConfig = await openapiCore.createConfig({});
+    vi.mocked(generateWorkflowsWithAi).mockResolvedValueOnce({
+      yaml: 'ai yaml',
+      workflows: 2,
+    });
+    const commandArgs = {
+      argv: {
+        descriptionPath: 'openapi.yaml',
+        'with-ai': true,
+        'ai-provider': 'claude',
+        'max-workflows': 10,
+      } as GenerateArazzoCommandArgv,
+      config: mockConfig,
+      version: '1.0.0',
+      collectSpecData: vi.fn(),
+    };
+
+    await handleGenerateArazzo(commandArgs);
+
+    expect(generateWorkflowsWithAi).toHaveBeenCalledWith({
+      provider: 'claude',
+      baseline: { workflows: [] },
+      description: undefined,
+      maxWorkflows: 10,
+    });
+    expect(writeFileSync).toHaveBeenCalledWith(
+      'auto-generated.arazzo.yaml',
+      '# The workflows below were inferred by AI (--with-ai). Verify before use.\nai yaml'
+    );
+  });
+
+  it('should keep the auto-generated workflows when --with-ai fails', async () => {
+    const mockConfig = await openapiCore.createConfig({});
+    vi.mocked(generateWorkflowsWithAi).mockRejectedValueOnce(new Error('no usable answer'));
+    const commandArgs = {
+      argv: {
+        descriptionPath: 'openapi.yaml',
+        'with-ai': true,
+        'ai-provider': 'claude',
+        'max-workflows': 10,
+      } as GenerateArazzoCommandArgv,
+      config: mockConfig,
+      version: '1.0.0',
+      collectSpecData: vi.fn(),
+    };
+
+    await handleGenerateArazzo(commandArgs);
+
+    expect(writeFileSync).toHaveBeenCalledWith('auto-generated.arazzo.yaml', 'mocked yaml');
+    expect(openapiCore.logger.warn).toHaveBeenCalledWith(
+      expect.stringContaining('AI workflow design failed')
+    );
+  });
+
+  it('should print a hint with the respect command', async () => {
+    const mockConfig = await openapiCore.createConfig({});
+    const commandArgs = {
+      argv: {
+        descriptionPath: 'openapi.yaml',
+      } as GenerateArazzoCommandArgv,
+      config: mockConfig,
+      version: '1.0.0',
+      collectSpecData: vi.fn(),
+    };
+
+    await handleGenerateArazzo(commandArgs);
+
+    expect(openapiCore.logger.info).toHaveBeenCalledWith(
+      expect.stringContaining('npx @redocly/cli@latest respect auto-generated.arazzo.yaml')
+    );
+  });
+});
+
+describe('buildRespectHint', () => {
+  it('lists a placeholder for every workflow input, resolving component refs', () => {
+    const resultYaml = [
+      'workflows:',
+      '  - workflowId: first',
+      '    inputs:',
+      '      $ref: "#/components/inputs/bearerAuth"',
+      '  - workflowId: second',
+      '    inputs:',
+      '      type: object',
+      '      properties:',
+      '        userEmail:',
+      '          type: string',
+      'components:',
+      '  inputs:',
+      '    bearerAuth:',
+      '      type: object',
+      '      properties:',
+      '        bearerAuth:',
+      '          type: string',
+    ].join('\n');
+
+    const hint = buildRespectHint(resultYaml, 'museum.arazzo.yaml');
+
+    expect(hint).toContain(
+      'npx @redocly/cli@latest respect museum.arazzo.yaml --input bearerAuth=YOUR_BEARERAUTH --input userEmail=YOUR_USEREMAIL'
+    );
+    expect(hint).toContain('Replace the YOUR_* values');
+    expect(hint).toContain('REDOCLY_CLI_RESPECT_INPUT');
+  });
+
+  it('omits input flags when the workflows declare no inputs', () => {
+    const hint = buildRespectHint('workflows:\n  - workflowId: first\n', 'museum.arazzo.yaml');
+
+    expect(hint).toContain('npx @redocly/cli@latest respect museum.arazzo.yaml\n');
+    expect(hint).not.toContain('--input');
+    expect(hint).not.toContain('Replace the YOUR_* values');
+  });
 });
diff --git a/packages/cli/src/commands/generate-arazzo.ts b/packages/cli/src/commands/generate-arazzo.ts
deleted file mode 100644
index 2c711122d5..0000000000
--- a/packages/cli/src/commands/generate-arazzo.ts
+++ /dev/null
@@ -1,45 +0,0 @@
-import { HandledError, logger, stringifyYaml } from '@redocly/openapi-core';
-import { blue, gray, yellow } from 'colorette';
-import { writeFileSync } from 'node:fs';
-
-import { type CommandArgs } from '../wrapper.js';
-
-export type GenerateArazzoCommandArgv = {
-  descriptionPath: string;
-  'output-file'?: string;
-  config?: string;
-};
-
-export async function handleGenerateArazzo({
-  argv,
-  config,
-  version,
-  collectSpecData,
-}: CommandArgs<GenerateArazzoCommandArgv>) {
-  const outputFile = argv['output-file'] || 'auto-generated.arazzo.yaml';
-  const options = {
-    outputFile,
-    descriptionPath: argv.descriptionPath,
-    collectSpecData,
-    version,
-    config,
-  };
-
-  try {
-    const { generate } = await import('@redocly/respect-core');
-
-    logger.info(gray('\n  Generating Arazzo description... \n'));
-
-    const generatedArazzo = await generate(options);
-    writeFileSync(outputFile, stringifyYaml(generatedArazzo));
-
-    logger.info(
-      '\n' + blue(`Arazzo description ${yellow(outputFile)} successfully generated.`) + '\n'
-    );
-  } catch (error) {
-    throw new HandledError(
-      '\n' +
-        '❌  Failed to generate Arazzo description. Check the output file path you provided, or the OpenAPI file content.'
-    );
-  }
-}
diff --git a/packages/cli/src/commands/generate-arazzo/__tests__/generate-workflows.test.ts b/packages/cli/src/commands/generate-arazzo/__tests__/generate-workflows.test.ts
new file mode 100644
index 0000000000..79a500273a
--- /dev/null
+++ b/packages/cli/src/commands/generate-arazzo/__tests__/generate-workflows.test.ts
@@ -0,0 +1,166 @@
+import { logger } from '@redocly/openapi-core';
+import type { TestDescription } from '@redocly/respect-core';
+
+import { runProvider } from '../../../utils/ai/providers.js';
+import { generateWorkflowsWithAi } from '../ai/generate-workflows.js';
+
+vi.mock('../../../utils/ai/providers.js', async (importOriginal) => ({
+  // oxlint-disable-next-line typescript/consistent-type-imports
+  ...(await importOriginal<typeof import('../../../utils/ai/providers.js')>()),
+  runProvider: vi.fn(),
+}));
+
+function baseline(): TestDescription {
+  return {
+    arazzo: '1.1.0',
+    info: { title: 'Test API', version: '1.0.0' },
+    sourceDescriptions: [{ name: 'test-api', type: 'openapi', url: 'openapi.yaml' }],
+    workflows: [
+      {
+        workflowId: 'post-users-workflow',
+        steps: [
+          {
+            stepId: 'post-users-step',
+            operationId: '$sourceDescriptions.test-api.createUser',
+            successCriteria: [{ condition: '$statusCode == 201' }],
+          },
+        ],
+      },
+      {
+        workflowId: 'get-users-{id}-workflow',
+        steps: [
+          {
+            stepId: 'get-users-step',
+            operationId: '$sourceDescriptions.test-api.getUser',
+            successCriteria: [{ condition: '$statusCode == 200' }],
+          },
+        ],
+      },
+    ] as TestDescription['workflows'],
+  };
+}
+
+const redesignedWorkflows = `workflows:
+  - workflowId: user-lifecycle
+    summary: Create a user, then read it
+    description: Creates a user and verifies it can be fetched back.
+    steps:
+      - stepId: create-user
+        operationId: $sourceDescriptions.test-api.createUser
+        outputs:
+          id: $response.body#/id
+        successCriteria:
+          - condition: $statusCode == 201
+      - stepId: get-user
+        operationId: $sourceDescriptions.test-api.getUser
+        successCriteria:
+          - condition: $statusCode == 200
+`;
+
+async function generateWorkflows(text: string, maxWorkflows = 10) {
+  vi.mocked(runProvider).mockResolvedValueOnce({ text });
+  return generateWorkflowsWithAi({
+    provider: 'claude',
+    baseline: baseline(),
+    description: { openapi: '3.1.0', paths: {} },
+    maxWorkflows,
+  });
+}
+
+describe('generateWorkflowsWithAi', () => {
+  beforeEach(() => {
+    vi.mocked(runProvider).mockReset();
+    vi.spyOn(logger, 'info').mockImplementation(() => true);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('accepts the redesigned workflows and keeps the baseline header fields', async () => {
+    const result = await generateWorkflows(redesignedWorkflows);
+    expect(result.workflows).toBe(1);
+    expect(result.yaml).toContain('workflowId: user-lifecycle');
+    expect(result.yaml).toContain('id: $response.body#/id');
+    expect(result.yaml).toContain('arazzo: 1.1.0');
+    expect(result.yaml).toContain('url: openapi.yaml');
+    expect(vi.mocked(runProvider).mock.calls[0][1].system).toContain('at most 10 workflow(s)');
+  });
+
+  it('rejects an answer with more workflows than --max-workflows allows', async () => {
+    const secondWorkflow = `  - workflowId: read-user
+    summary: Read a user
+    steps:
+      - stepId: read-user-step
+        operationId: $sourceDescriptions.test-api.getUser
+        successCriteria:
+          - condition: $statusCode == 200
+`;
+    await expect(generateWorkflows(redesignedWorkflows + secondWorkflow, 1)).rejects.toThrow(
+      'the response contains 2 workflows, more than the --max-workflows limit of 1'
+    );
+  });
+
+  it('rejects a description too large to prompt with, without calling the provider', async () => {
+    await expect(
+      generateWorkflowsWithAi({
+        provider: 'claude',
+        baseline: baseline(),
+        description: { padding: 'x'.repeat(400_001) },
+        maxWorkflows: 10,
+      })
+    ).rejects.toThrow('the OpenAPI description is too large to send to the AI provider');
+    expect(runProvider).not.toHaveBeenCalled();
+  });
+
+  it('strips Markdown code fences before parsing', async () => {
+    const result = await generateWorkflows(`\`\`\`yaml\n${redesignedWorkflows}\n\`\`\``);
+    expect(result.workflows).toBe(1);
+  });
+
+  it('keeps the baseline components when the answer omits them', async () => {
+    vi.mocked(runProvider).mockResolvedValueOnce({ text: redesignedWorkflows });
+    const baselineWithComponents = {
+      ...baseline(),
+      components: { inputs: { basicAuth: { type: 'object' } } },
+    };
+    const result = await generateWorkflowsWithAi({
+      provider: 'claude',
+      baseline: baselineWithComponents,
+      description: {},
+      maxWorkflows: 10,
+    });
+    expect(result.yaml).toContain('basicAuth');
+  });
+
+  it('rejects an answer that is not a workflows document', async () => {
+    await expect(generateWorkflows('Sorry, I cannot help with that.')).rejects.toThrow(
+      'the response is not a YAML document with a non-empty "workflows" list'
+    );
+  });
+
+  it('rejects an answer that references an operation missing from the description', async () => {
+    const hallucinated = redesignedWorkflows.replace(
+      '$sourceDescriptions.test-api.getUser',
+      '$sourceDescriptions.test-api.listUsers'
+    );
+    await expect(generateWorkflows(hallucinated)).rejects.toThrow(
+      'references operation(s) missing from the OpenAPI description: $sourceDescriptions.test-api.listUsers'
+    );
+  });
+
+  it('rejects an answer whose step transfers to an undefined workflow', async () => {
+    const danglingWorkflow = redesignedWorkflows.replace(
+      'operationId: $sourceDescriptions.test-api.getUser',
+      'workflowId: cleanup-workflow'
+    );
+    await expect(generateWorkflows(danglingWorkflow)).rejects.toThrow(
+      'references workflow(s) it does not define: cleanup-workflow'
+    );
+  });
+
+  it('rejects an answer that fails validation with the spec ruleset', async () => {
+    const duplicatedStepId = redesignedWorkflows.replace('stepId: get-user', 'stepId: create-user');
+    await expect(generateWorkflows(duplicatedStepId)).rejects.toThrow('validation problem');
+  });
+});
diff --git a/packages/cli/src/commands/generate-arazzo/ai/generate-workflows.ts b/packages/cli/src/commands/generate-arazzo/ai/generate-workflows.ts
new file mode 100644
index 0000000000..6844a9daba
--- /dev/null
+++ b/packages/cli/src/commands/generate-arazzo/ai/generate-workflows.ts
@@ -0,0 +1,185 @@
+import {
+  createConfig,
+  isPlainObject,
+  logger,
+  parseYaml,
+  stringifyYaml,
+} from '@redocly/openapi-core';
+import type { TestDescription } from '@redocly/respect-core';
+import * as process from 'node:process';
+
+import { lintDocumentSource, stripCodeFences } from '../../../utils/ai/output.js';
+import { type AiProvider, runProvider } from '../../../utils/ai/providers.js';
+import { Spinner } from '../../../utils/spinner.js';
+import { buildWorkflowsPrompt } from './prompt.js';
+
+export interface GenerateWorkflowsOptions {
+  provider: AiProvider;
+  /** The mechanically generated Arazzo description the AI redesigns. */
+  baseline: TestDescription;
+  /** The bundled OpenAPI description, sent to the AI as context. */
+  description: unknown;
+  /** The most workflows the AI may design; more get the answer rejected. */
+  maxWorkflows: number;
+}
+
+// The whole prompt must fit the provider's context window with room left for
+// the answer; ~400k characters is roughly 100k tokens.
+export const MAX_PROMPT_CHARS = 400_000;
+
+export interface GeneratedWorkflowsResult {
+  /** The Arazzo description with the AI-designed workflows, as YAML. */
+  yaml: string;
+  workflows: number;
+}
+
+interface StepReferences {
+  operationRefs: Set<string>;
+  workflowRefs: Set<string>;
+  workflowIds: Set<string>;
+}
+
+function collectReferences(workflows: unknown): StepReferences {
+  const references: StepReferences = {
+    operationRefs: new Set(),
+    workflowRefs: new Set(),
+    workflowIds: new Set(),
+  };
+  if (!Array.isArray(workflows)) {
+    return references;
+  }
+  for (const workflow of workflows) {
+    if (!isPlainObject(workflow)) {
+      continue;
+    }
+    if (typeof workflow.workflowId === 'string') {
+      references.workflowIds.add(workflow.workflowId);
+    }
+    if (!Array.isArray(workflow.steps)) {
+      continue;
+    }
+    for (const step of workflow.steps) {
+      if (!isPlainObject(step)) {
+        continue;
+      }
+      if (typeof step.operationId === 'string') {
+        references.operationRefs.add(step.operationId);
+      }
+      if (typeof step.operationPath === 'string') {
+        references.operationRefs.add(step.operationPath);
+      }
+      if (typeof step.workflowId === 'string') {
+        references.workflowRefs.add(step.workflowId);
+      }
+    }
+  }
+  return references;
+}
+
+function parseWorkflowsDocument(text: string): { workflows: unknown[]; components?: unknown } {
+  let parsed: unknown;
+  try {
+    parsed = parseYaml(stripCodeFences(text));
+  } catch (error) {
+    throw new Error(
+      `the provider did not return valid YAML: ${
+        error instanceof Error ? error.message : String(error)
+      }`
+    );
+  }
+
+  if (!isPlainObject(parsed) || !Array.isArray(parsed.workflows) || parsed.workflows.length === 0) {
+    throw new Error('the response is not a YAML document with a non-empty "workflows" list');
+  }
+
+  return { workflows: parsed.workflows, components: parsed.components };
+}
+
+/**
+ * Every operation the baseline covers appears in exactly one of its steps, so
+ * the baseline's operationId/operationPath values are the complete list of
+ * valid operation references — anything else is hallucinated.
+ */
+function validateReferences(workflows: unknown[], baseline: TestDescription): void {
+  const valid = collectReferences(baseline.workflows);
+  const generated = collectReferences(workflows);
+
+  const unknownOperations = [...generated.operationRefs].filter(
+    (reference) => !valid.operationRefs.has(reference)
+  );
+  if (unknownOperations.length > 0) {
+    throw new Error(
+      `the response references operation(s) missing from the OpenAPI description: ${unknownOperations.join(
+        ', '
+      )}`
+    );
+  }
+
+  const unknownWorkflows = [...generated.workflowRefs].filter(
+    (reference) => !generated.workflowIds.has(reference)
+  );
+  if (unknownWorkflows.length > 0) {
+    throw new Error(
+      `the response references workflow(s) it does not define: ${unknownWorkflows.join(', ')}`
+    );
+  }
+}
+
+/**
+ * Ask the AI provider to redesign the baseline's one-workflow-per-operation
+ * skeleton into realistic multi-step workflows. The answer is never trusted
+ * blindly: the header fields (`arazzo`, `info`, `sourceDescriptions`) always
+ * come from the baseline, every operation reference must exist in the
+ * description, and the result must pass validation with the `spec` ruleset.
+ * Any rejection throws, and the command falls back to the baseline.
+ */
+export async function generateWorkflowsWithAi(
+  options: GenerateWorkflowsOptions
+): Promise<GeneratedWorkflowsResult> {
+  const { system, user } = buildWorkflowsPrompt({
+    description: options.description,
+    baseline: options.baseline,
+    maxWorkflows: options.maxWorkflows,
+  });
+
+  if (system.length + user.length > MAX_PROMPT_CHARS) {
+    throw new Error('the OpenAPI description is too large to send to the AI provider');
+  }
+
+  const spinner = new Spinner();
+  spinner.start('Waiting for the AI-designed workflows');
+  let text: string;
+  try {
+    ({ text } = await runProvider(options.provider, { system, user }));
+  } finally {
+    spinner.stop();
+    if (process.stderr.isTTY) {
+      // Erase the leftover spinner frame so the result line prints clean.
+      logger.info('\x1b[2K');
+    }
+  }
+
+  const parsed = parseWorkflowsDocument(text);
+  if (parsed.workflows.length > options.maxWorkflows) {
+    throw new Error(
+      `the response contains ${parsed.workflows.length} workflows, more than the --max-workflows limit of ${options.maxWorkflows}`
+    );
+  }
+  validateReferences(parsed.workflows, options.baseline);
+
+  // An answer that omits the baseline's components (security inputs) would
+  // break the "$components..." references the prompt asks to keep.
+  const components = parsed.components ?? options.baseline.components;
+  const document = {
+    arazzo: options.baseline.arazzo,
+    info: options.baseline.info,
+    sourceDescriptions: options.baseline.sourceDescriptions,
+    workflows: parsed.workflows,
+    ...(components !== undefined && { components }),
+  };
+
+  const yaml = stringifyYaml(document);
+  await lintDocumentSource(yaml, await createConfig({ extends: ['spec'] }));
+
+  return { yaml, workflows: parsed.workflows.length };
+}
diff --git a/packages/cli/src/commands/generate-arazzo/ai/prompt.ts b/packages/cli/src/commands/generate-arazzo/ai/prompt.ts
new file mode 100644
index 0000000000..d8b8e154d2
--- /dev/null
+++ b/packages/cli/src/commands/generate-arazzo/ai/prompt.ts
@@ -0,0 +1,58 @@
+import { stringifyYaml } from '@redocly/openapi-core';
+
+// CI only exercises stub providers, so editing these instructions or the
+// prompt layout below can change workflow quality without failing any test.
+function buildSystemInstructions(maxWorkflows: number): string {
+  return `You are an expert in API testing and the Arazzo specification. You are given an OpenAPI description and a baseline Arazzo description that was generated mechanically from it: one workflow per operation, one step each, no dependencies between operations. Redesign the workflows so they reflect how the API is used in the real world.
+
+Follow these rules:
+- Reference operations exactly the way the baseline does: "operationId: $sourceDescriptions.<name>.<operationId>" for operations that have an operationId, or the baseline's "operationPath" value otherwise. Reference only operations that appear in the baseline. The result is programmatically checked and rejected otherwise.
+- Group related operations into multi-step scenario workflows — for example create a resource, read it, update it, and delete it. A workflow may also be a single step when an operation stands alone.
+- Design at most ${maxWorkflows} workflow(s); this limit is programmatically checked. Prefer covering every operation from the baseline in at least one workflow; when the limit does not allow that, choose the operations that form the most likely real-world scenarios.
+- When the API has authentication or token-issuing operations, run them first and pass their result to the steps that need it.
+- When a step registers or configures an OAuth2 client, request every grant type the security scheme's flows declare (for example both authorization_code and client_credentials), so the example works with any declared flow.
+- Prefer chains where every required parameter of a step comes from an earlier step's outputs, a workflow input, or a value documented in the OpenAPI description.
+- Chain steps through runtime expressions: declare step "outputs" taken from the response (for example "id: $response.body#/id") and use them in later steps as "$steps.<stepId>.outputs.<name>".
+- Declare workflow "inputs" as a JSON Schema for values a caller must provide and reference them as "$inputs.<name>".
+- Keep the baseline step's "x-security" on every step that uses that operation, along with the security-related workflow "inputs" and "parameters", and keep the baseline "components" if present.
+- Give every step "successCriteria" with a "$statusCode" check matching the response code the OpenAPI description documents for it.
+- Use kebab-case for every workflowId and stepId, and give every workflow a short "summary" and "description".
+
+Output ONLY a YAML document with this exact top-level structure:
+
+workflows:
+  - ...the redesigned workflows...
+components:
+  ...only when the baseline has components or new reusable inputs are needed; omit otherwise...
+
+Do not output "arazzo", "info", or "sourceDescriptions" — they are added programmatically. Do not wrap the output in Markdown code fences. Do not add any commentary before or after the document.`;
+}
+
+export interface BuildWorkflowsPromptOptions {
+  /** The bundled OpenAPI description the workflows are generated for. */
+  description: unknown;
+  /** The mechanically generated Arazzo description. */
+  baseline: unknown;
+  /** The most workflows the AI may design. */
+  maxWorkflows: number;
+}
+
+/**
+ * Build a single prompt covering the whole description: realistic workflows
+ * chain operations together, so the AI needs the full picture rather than
+ * one operation at a time.
+ */
+export function buildWorkflowsPrompt(options: BuildWorkflowsPromptOptions): {
+  system: string;
+  user: string;
+} {
+  const sections = [
+    `# OpenAPI description\n\n\`\`\`yaml\n${stringifyYaml(options.description)}\`\`\``,
+    `# Baseline Arazzo description (mechanically generated)\n\n\`\`\`yaml\n${stringifyYaml(
+      options.baseline
+    )}\`\`\``,
+    'Redesign the workflows as instructed and output only the YAML document.',
+  ];
+
+  return { system: buildSystemInstructions(options.maxWorkflows), user: sections.join('\n\n') };
+}
diff --git a/packages/cli/src/commands/generate-arazzo/index.ts b/packages/cli/src/commands/generate-arazzo/index.ts
new file mode 100644
index 0000000000..d23ad587f2
--- /dev/null
+++ b/packages/cli/src/commands/generate-arazzo/index.ts
@@ -0,0 +1,147 @@
+import {
+  type CollectSpecData,
+  HandledError,
+  isPlainObject,
+  logger,
+  parseYaml,
+  stringifyYaml,
+} from '@redocly/openapi-core';
+import { blue, gray, yellow } from 'colorette';
+import { writeFileSync } from 'node:fs';
+
+import { type AiProvider } from '../../utils/ai/providers.js';
+import { type CommandArgs } from '../../wrapper.js';
+import { generateWorkflowsWithAi } from './ai/generate-workflows.js';
+
+export type GenerateArazzoCommandArgv = {
+  descriptionPath: string;
+  'output-file'?: string;
+  'with-ai'?: boolean;
+  'ai-provider': AiProvider;
+  'max-workflows': number;
+  config?: string;
+};
+
+const INFERRED_NOTE = '# The workflows below were inferred by AI (--with-ai). Verify before use.\n';
+
+const COMPONENT_INPUT_REF_RE = /^#\/components\/inputs\/(.+)$/;
+
+/**
+ * Collect the top-level input property names across all workflows.
+ * The generator declares workflow inputs as a $ref into components.inputs,
+ * while AI-designed workflows declare them inline as a JSON Schema.
+ */
+function collectWorkflowInputNames(document: unknown): string[] {
+  if (!isPlainObject(document) || !Array.isArray(document.workflows)) {
+    return [];
+  }
+  const componentInputs =
+    isPlainObject(document.components) && isPlainObject(document.components.inputs)
+      ? document.components.inputs
+      : {};
+
+  const names = new Set<string>();
+  for (const workflow of document.workflows) {
+    if (!isPlainObject(workflow)) {
+      continue;
+    }
+    let inputs = workflow.inputs;
+    if (isPlainObject(inputs) && typeof inputs.$ref === 'string') {
+      const refMatch = inputs.$ref.match(COMPONENT_INPUT_REF_RE);
+      inputs = refMatch ? componentInputs[refMatch[1]] : undefined;
+    }
+    if (isPlainObject(inputs) && isPlainObject(inputs.properties)) {
+      for (const name of Object.keys(inputs.properties)) {
+        names.add(name);
+      }
+    }
+  }
+  return [...names];
+}
+
+/** A ready-to-run `respect` command with a placeholder for every input. */
+export function buildRespectHint(resultYaml: string, outputFile: string): string {
+  const inputNames = collectWorkflowInputNames(parseYaml(resultYaml));
+  const inputFlags = inputNames
+    .map((name) => ` --input ${name}=YOUR_${name.replace(/[^A-Za-z0-9]/g, '_').toUpperCase()}`)
+    .join('');
+  const replaceNote = inputNames.length
+    ? 'Replace the YOUR_* values with real ones; inputs can also come from the REDOCLY_CLI_RESPECT_INPUT environment variable.\n'
+    : '';
+  return (
+    '\nRun the generated workflows against the live API:\n\n' +
+    `  npx @redocly/cli@latest respect ${outputFile}${inputFlags}\n\n` +
+    replaceNote
+  );
+}
+
+export async function handleGenerateArazzo({
+  argv,
+  config,
+  version,
+  collectSpecData,
+}: CommandArgs<GenerateArazzoCommandArgv>) {
+  const outputFile = argv['output-file'] || 'auto-generated.arazzo.yaml';
+
+  // The generator reports the bundled OpenAPI document through collectSpecData;
+  // capture it so --with-ai can hand it to the AI provider as context.
+  let bundledDescription: unknown;
+  const collectBundledDescription: CollectSpecData = (document) => {
+    bundledDescription = document.parsed;
+    collectSpecData?.(document);
+  };
+
+  const options = {
+    outputFile,
+    descriptionPath: argv.descriptionPath,
+    collectSpecData: collectBundledDescription,
+    version,
+    config,
+  };
+
+  try {
+    const { generate } = await import('@redocly/respect-core');
+
+    logger.info(gray('\n  Generating Arazzo description... \n'));
+
+    const generatedArazzo = await generate(options);
+    let resultYaml = stringifyYaml(generatedArazzo);
+
+    if (argv['with-ai']) {
+      const provider = argv['ai-provider'];
+      logger.info(gray(`\n  Designing workflows with AI provider "${provider}"... \n`));
+      logger.warn(
+        'Note: --with-ai sends the resolved OpenAPI description to the selected AI provider. Make sure it contains no secrets or personal data you are not allowed to share.\n'
+      );
+
+      try {
+        const redesigned = await generateWorkflowsWithAi({
+          provider,
+          baseline: generatedArazzo,
+          description: bundledDescription,
+          maxWorkflows: argv['max-workflows'],
+        });
+        resultYaml = INFERRED_NOTE + redesigned.yaml;
+        logger.info(`AI designed ${redesigned.workflows} workflow(s) (${provider}).\n`);
+      } catch (error) {
+        logger.warn(
+          `AI workflow design failed, keeping the auto-generated workflows: ${
+            error instanceof Error ? error.message : String(error)
+          }\n`
+        );
+      }
+    }
+
+    writeFileSync(outputFile, resultYaml);
+
+    logger.info(
+      '\n' + blue(`Arazzo description ${yellow(outputFile)} successfully generated.`) + '\n'
+    );
+    logger.info(buildRespectHint(resultYaml, outputFile));
+  } catch (error) {
+    throw new HandledError(
+      '\n' +
+        '❌  Failed to generate Arazzo description. Check the output file path you provided, or the OpenAPI file content.'
+    );
+  }
+}
diff --git a/packages/cli/src/commands/generate-spec/__tests__/refine.test.ts b/packages/cli/src/commands/generate-spec/__tests__/refine.test.ts
index be060c1f6f..6c238c9a8d 100644
--- a/packages/cli/src/commands/generate-spec/__tests__/refine.test.ts
+++ b/packages/cli/src/commands/generate-spec/__tests__/refine.test.ts
@@ -1,12 +1,12 @@
 import { logger } from '@redocly/openapi-core';
 
-import { CliNotFoundError, runProvider } from '../ai/providers.js';
+import { CliNotFoundError, runProvider } from '../../../utils/ai/providers.js';
 import { refineSpecWithAi } from '../ai/refine.js';
 import type { GeneratedDocument } from '../generator.js';
 
-vi.mock('../ai/providers.js', async (importOriginal) => ({
+vi.mock('../../../utils/ai/providers.js', async (importOriginal) => ({
   // oxlint-disable-next-line typescript/consistent-type-imports
-  ...(await importOriginal<typeof import('../ai/providers.js')>()),
+  ...(await importOriginal<typeof import('../../../utils/ai/providers.js')>()),
   runProvider: vi.fn(),
 }));
 
diff --git a/packages/cli/src/commands/generate-spec/ai/refine.ts b/packages/cli/src/commands/generate-spec/ai/refine.ts
index 8a8e202de9..817d61a60e 100644
--- a/packages/cli/src/commands/generate-spec/ai/refine.ts
+++ b/packages/cli/src/commands/generate-spec/ai/refine.ts
@@ -2,18 +2,18 @@ import {
   type Config,
   createConfig,
   isPlainObject,
-  lintFromString,
   logger,
   parseYaml,
   stringifyYaml,
 } from '@redocly/openapi-core';
 import * as process from 'node:process';
 
+import { lintDocumentSource, stripCodeFences } from '../../../utils/ai/output.js';
+import { type AiProvider, CliNotFoundError, runProvider } from '../../../utils/ai/providers.js';
 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;
@@ -47,13 +47,6 @@ interface OperationFragment {
   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 {
@@ -165,18 +158,6 @@ function missingStatuses(
   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;
diff --git a/packages/cli/src/commands/generate-spec/index.ts b/packages/cli/src/commands/generate-spec/index.ts
index ab42fd8ac8..d1a86892e9 100644
--- a/packages/cli/src/commands/generate-spec/index.ts
+++ b/packages/cli/src/commands/generate-spec/index.ts
@@ -2,11 +2,11 @@ import { logger, stringifyYaml } from '@redocly/openapi-core';
 import { mkdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 
+import { type AiProvider } from '../../utils/ai/providers.js';
 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';
diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts
index 0993271f1b..2c469cc6b5 100644
--- a/packages/cli/src/index.ts
+++ b/packages/cli/src/index.ts
@@ -27,7 +27,7 @@ import { handleEject, type EjectArgv } from './commands/eject.js';
 import {
   handleGenerateArazzo,
   type GenerateArazzoCommandArgv,
-} from './commands/generate-arazzo.js';
+} from './commands/generate-arazzo/index.js';
 import {
   handleGenerateClient,
   type GenerateClientCommandArgv,
@@ -859,6 +859,26 @@ yargs(hideBin(process.argv))
             type: 'string',
             requiresArg: true,
           },
+          'with-ai': {
+            describe:
+              'Redesign the generated workflows with an AI provider, using the OpenAPI description as context.',
+            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<
+              GenerateArazzoCommandArgv['ai-provider']
+            >,
+            default: 'claude' as GenerateArazzoCommandArgv['ai-provider'],
+          },
+          'max-workflows': {
+            describe: 'Most workflows the AI may design with --with-ai.',
+            type: 'number',
+            default: 10,
+            coerce: validatePositiveNumber('max-workflows', true),
+          },
         });
     },
     async (argv) => {
diff --git a/packages/cli/src/types.ts b/packages/cli/src/types.ts
index ce487055af..465ee87110 100644
--- a/packages/cli/src/types.ts
+++ b/packages/cli/src/types.ts
@@ -6,7 +6,7 @@ import type { BundleArgv } from './commands/bundle.js';
 import type { DriftArgv } from './commands/drift/index.js';
 import type { EjectGeneratorCommandArgv } from './commands/eject-generator.js';
 import type { EjectArgv } from './commands/eject.js';
-import type { GenerateArazzoCommandArgv } from './commands/generate-arazzo.js';
+import type { GenerateArazzoCommandArgv } from './commands/generate-arazzo/index.js';
 import type { JoinArgv } from './commands/join/types.js';
 import type { LintArgv } from './commands/lint.js';
 import type { PreviewProjectArgv } from './commands/preview-project/types.js';
diff --git a/packages/cli/src/commands/generate-spec/__tests__/providers.test.ts b/packages/cli/src/utils/ai/__tests__/providers.test.ts
similarity index 90%
rename from packages/cli/src/commands/generate-spec/__tests__/providers.test.ts
rename to packages/cli/src/utils/ai/__tests__/providers.test.ts
index ec122ef347..57fa2c9601 100644
--- a/packages/cli/src/commands/generate-spec/__tests__/providers.test.ts
+++ b/packages/cli/src/utils/ai/__tests__/providers.test.ts
@@ -1,11 +1,11 @@
 import { spawn } from 'node:child_process';
 import { EventEmitter } from 'node:events';
 
-import { runProvider } from '../ai/providers.js';
+import { runProvider } from '../providers.js';
 
 vi.mock('node:child_process', () => ({ spawn: vi.fn() }));
 vi.mock('node:fs/promises', () => ({
-  mkdtemp: vi.fn(async () => '/tmp/generate-spec-empty'),
+  mkdtemp: vi.fn(async () => '/tmp/redocly-ai-empty'),
 }));
 
 function stubChildProcess(stdout: string) {
@@ -57,7 +57,7 @@ describe('runProvider', () => {
         'sys prompt',
       ],
       expect.objectContaining({
-        cwd: '/tmp/generate-spec-empty',
+        cwd: '/tmp/redocly-ai-empty',
         env: expect.objectContaining({ CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: '1' }),
       })
     );
@@ -82,7 +82,7 @@ describe('runProvider', () => {
         'gpt-5',
         '-',
       ],
-      expect.objectContaining({ cwd: '/tmp/generate-spec-empty' })
+      expect.objectContaining({ cwd: '/tmp/redocly-ai-empty' })
     );
     expect(child.pipedInput).toBe('sys prompt\n\nuser prompt');
   });
@@ -93,7 +93,7 @@ describe('runProvider', () => {
     expect(spawn).toHaveBeenCalledWith(
       'cursor-agent',
       ['-p', '--output-format', 'text', '--trust'],
-      expect.objectContaining({ cwd: '/tmp/generate-spec-empty' })
+      expect.objectContaining({ cwd: '/tmp/redocly-ai-empty' })
     );
     expect(child.pipedInput).toBe('sys prompt\n\nuser prompt');
   });
diff --git a/packages/cli/src/utils/ai/output.ts b/packages/cli/src/utils/ai/output.ts
new file mode 100644
index 0000000000..1174182cd7
--- /dev/null
+++ b/packages/cli/src/utils/ai/output.ts
@@ -0,0 +1,21 @@
+import { type Config, lintFromString } from '@redocly/openapi-core';
+
+/** Strip Markdown code fences the model may have added despite instructions. */
+export 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;
+}
+
+/** Reject an AI-produced document that does not pass validation. */
+export 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}`);
+  }
+}
diff --git a/packages/cli/src/commands/generate-spec/ai/providers.ts b/packages/cli/src/utils/ai/providers.ts
similarity index 98%
rename from packages/cli/src/commands/generate-spec/ai/providers.ts
rename to packages/cli/src/utils/ai/providers.ts
index 34d7793065..57b753be82 100644
--- a/packages/cli/src/commands/generate-spec/ai/providers.ts
+++ b/packages/cli/src/utils/ai/providers.ts
@@ -25,7 +25,7 @@ export interface ProviderResult {
 let emptyCwdPromise: Promise<string> | undefined;
 
 function getEmptyCwd(): Promise<string> {
-  emptyCwdPromise ??= mkdtemp(path.join(tmpdir(), 'redocly-generate-spec-'));
+  emptyCwdPromise ??= mkdtemp(path.join(tmpdir(), 'redocly-ai-'));
   return emptyCwdPromise;
 }
 
diff --git a/packages/respect-core/src/generate.ts b/packages/respect-core/src/generate.ts
index a842b70718..ecc087dbf5 100644
--- a/packages/respect-core/src/generate.ts
+++ b/packages/respect-core/src/generate.ts
@@ -1,6 +1,7 @@
 import { type BaseResolver, type CollectSpecData, type Config } from '@redocly/openapi-core';
 
 import { generateArazzoDescription } from './modules/arazzo-description-generator/index.js';
+import { type TestDescription } from './types.js';
 
 export type GenerateArazzoOptions = {
   descriptionPath: string;
@@ -12,6 +13,6 @@ export type GenerateArazzoOptions = {
   base?: string;
 };
 
-export async function generate(options: GenerateArazzoOptions): Promise<string> {
+export async function generate(options: GenerateArazzoOptions): Promise<TestDescription> {
   return await generateArazzoDescription(options);
 }
diff --git a/packages/respect-core/src/modules/__tests__/arazzo-description-generator/generate-arazzo-description.test.ts b/packages/respect-core/src/modules/__tests__/arazzo-description-generator/generate-arazzo-description.test.ts
index ba378e4f7f..a32fc2abd4 100644
--- a/packages/respect-core/src/modules/__tests__/arazzo-description-generator/generate-arazzo-description.test.ts
+++ b/packages/respect-core/src/modules/__tests__/arazzo-description-generator/generate-arazzo-description.test.ts
@@ -83,7 +83,7 @@ describe('generateArazzoDescription', () => {
         config: await createConfig({}),
       })
     ).toEqual({
-      arazzo: '1.0.1',
+      arazzo: '1.1.0',
       info: {
         title: 'Swagger Petstore',
         version: '1.0.0',
@@ -156,7 +156,7 @@ describe('generateArazzoDescription', () => {
         config: await createConfig({}),
       })
     ).toEqual({
-      arazzo: '1.0.1',
+      arazzo: '1.1.0',
       info: {
         title: 'Swagger Petstore',
         version: '1.0.0',
@@ -208,7 +208,7 @@ describe('generateArazzoDescription', () => {
         config: await createConfig({}),
       })
     ).toEqual({
-      arazzo: '1.0.1',
+      arazzo: '1.1.0',
       info: {
         title: '[REPLACE WITH API title]',
         version: '[REPLACE WITH API version]',
@@ -261,7 +261,7 @@ describe('generateArazzoDescription', () => {
         config: await createConfig({}),
       })
     ).toEqual({
-      arazzo: '1.0.1',
+      arazzo: '1.1.0',
       info: {
         title: 'Swagger Petstore',
         version: '1.0.0',
diff --git a/packages/respect-core/src/modules/__tests__/arazzo-description-generator/generate-inputs-arazzo-components.test.ts b/packages/respect-core/src/modules/__tests__/arazzo-description-generator/generate-inputs-arazzo-components.test.ts
index 3aa72d3aad..909b864f69 100644
--- a/packages/respect-core/src/modules/__tests__/arazzo-description-generator/generate-inputs-arazzo-components.test.ts
+++ b/packages/respect-core/src/modules/__tests__/arazzo-description-generator/generate-inputs-arazzo-components.test.ts
@@ -9,7 +9,7 @@ describe('generateSecurityInputsArazzoComponents', () => {
     expect(result).toEqual({ inputs: {} });
   });
 
-  it('should generate the correct inputs for the Basic auth security scheme', () => {
+  it('should generate username and password inputs for the Basic auth security scheme', () => {
     const securitySchemes = {
       basicAuth: {
         type: 'http' as const,
@@ -22,9 +22,13 @@ describe('generateSecurityInputsArazzoComponents', () => {
         basicAuth: {
           type: 'object',
           properties: {
-            basicAuth: {
+            username: {
               type: 'string',
-              description: 'Basic authentication',
+              description: 'Username for basicAuth',
+            },
+            password: {
+              type: 'string',
+              description: 'Password for basicAuth',
               format: 'password',
             },
           },
@@ -48,7 +52,31 @@ describe('generateSecurityInputsArazzoComponents', () => {
           properties: {
             bearerAuth: {
               type: 'string',
-              description: 'JWT Authentication token for ${name}',
+              description: 'JWT Authentication token for bearerAuth',
+              format: 'password',
+            },
+          },
+        },
+      },
+    });
+  });
+
+  it('should generate an access token input for the OAuth2 security scheme', () => {
+    const securitySchemes = {
+      OAuth2: {
+        type: 'oauth2' as const,
+        flows: {},
+      } as Oas3SecurityScheme,
+    };
+    const result = generateSecurityInputsArazzoComponents(securitySchemes);
+    expect(result).toEqual({
+      inputs: {
+        OAuth2: {
+          type: 'object',
+          properties: {
+            OAuth2: {
+              type: 'string',
+              description: 'Access token for OAuth2',
               format: 'password',
             },
           },
@@ -57,6 +85,16 @@ describe('generateSecurityInputsArazzoComponents', () => {
     });
   });
 
+  it('should generate no input for a mutualTLS security scheme', () => {
+    const securitySchemes = {
+      mtls: {
+        type: 'mutualTLS' as const,
+      } as Oas3SecurityScheme,
+    };
+    const result = generateSecurityInputsArazzoComponents(securitySchemes);
+    expect(result).toEqual({ inputs: {} });
+  });
+
   it('should generate the correct inputs for the ApiKey auth security scheme', () => {
     const securitySchemes = {
       apiKey: {
diff --git a/packages/respect-core/src/modules/__tests__/arazzo-description-generator/generate-step-security.test.ts b/packages/respect-core/src/modules/__tests__/arazzo-description-generator/generate-step-security.test.ts
new file mode 100644
index 0000000000..51bbe00614
--- /dev/null
+++ b/packages/respect-core/src/modules/__tests__/arazzo-description-generator/generate-step-security.test.ts
@@ -0,0 +1,100 @@
+import { generateStepSecurity } from '../../arazzo-description-generator/index.js';
+
+function inputsComponentsFor(name: string) {
+  return {
+    inputs: {
+      [name]: {
+        type: 'object',
+        properties: {
+          [name]: { type: 'string', format: 'password' },
+        },
+      },
+    },
+  };
+}
+
+describe('generateStepSecurity', () => {
+  it('should generate x-security with username and password for Basic authentication', () => {
+    const result = generateStepSecurity(inputsComponentsFor('basicAuth'), [{ basicAuth: [] }], {
+      basicAuth: { type: 'http', scheme: 'basic' },
+    } as any);
+
+    expect(result).toEqual({
+      xSecurity: [
+        {
+          schemeName: 'basicAuth',
+          values: { username: '$inputs.username', password: '$inputs.password' },
+        },
+      ],
+      parameters: [],
+    });
+  });
+
+  it('should generate x-security with a token for Bearer authentication', () => {
+    const result = generateStepSecurity(inputsComponentsFor('bearerAuth'), [{ bearerAuth: [] }], {
+      bearerAuth: { type: 'http', scheme: 'bearer' },
+    } as any);
+
+    expect(result).toEqual({
+      xSecurity: [{ schemeName: 'bearerAuth', values: { token: '$inputs.bearerAuth' } }],
+      parameters: [],
+    });
+  });
+
+  it('should generate x-security with an apiKey for ApiKey authentication', () => {
+    const result = generateStepSecurity(inputsComponentsFor('apiKey'), [{ apiKey: [] }], {
+      apiKey: { type: 'apiKey', name: 'X-API-Key', in: 'header' },
+    } as any);
+
+    expect(result).toEqual({
+      xSecurity: [{ schemeName: 'apiKey', values: { apiKey: '$inputs.apiKey' } }],
+      parameters: [],
+    });
+  });
+
+  it('should generate x-security with an accessToken for OAuth2 authentication', () => {
+    const result = generateStepSecurity(
+      inputsComponentsFor('OAuth2'),
+      [{ OAuth2: ['menu:write'] }],
+      {
+        OAuth2: { type: 'oauth2', flows: {} },
+      } as any
+    );
+
+    expect(result).toEqual({
+      xSecurity: [{ schemeName: 'OAuth2', values: { accessToken: '$inputs.OAuth2' } }],
+      parameters: [],
+    });
+  });
+
+  it('should fall back to an Authorization parameter for an HTTP scheme Respect does not support', () => {
+    const result = generateStepSecurity(
+      inputsComponentsFor('negotiateAuth'),
+      [{ negotiateAuth: [] }],
+      {
+        negotiateAuth: { type: 'http', scheme: 'negotiate' },
+      } as any
+    );
+
+    expect(result).toEqual({
+      xSecurity: [],
+      parameters: [
+        { name: 'Authorization', value: 'negotiate {$inputs.negotiateAuth}', in: 'header' },
+      ],
+    });
+  });
+
+  it('should generate nothing when the scheme cannot be satisfied by a value input', () => {
+    const result = generateStepSecurity(inputsComponentsFor('mtls'), [{ mtls: [] }], {
+      mtls: { type: 'mutualTLS' },
+    } as any);
+
+    expect(result).toEqual({ xSecurity: [], parameters: [] });
+  });
+
+  it('should generate nothing when there are no security requirements', () => {
+    const result = generateStepSecurity({ inputs: {} }, [], {});
+
+    expect(result).toEqual({ xSecurity: [], parameters: [] });
+  });
+});
diff --git a/packages/respect-core/src/modules/__tests__/arazzo-description-generator/generate-workflow-security-parameters.test.ts b/packages/respect-core/src/modules/__tests__/arazzo-description-generator/generate-workflow-security-parameters.test.ts
deleted file mode 100644
index 576e5946a2..0000000000
--- a/packages/respect-core/src/modules/__tests__/arazzo-description-generator/generate-workflow-security-parameters.test.ts
+++ /dev/null
@@ -1,133 +0,0 @@
-import { generateWorkflowSecurityParameters } from '../../arazzo-description-generator/index.js';
-
-describe('generateWorkflowSecurityParameters', () => {
-  it('should return the correct workflow security parameters for Basic authentication', () => {
-    const inputsComponents = {
-      inputs: {
-        basicAuth: {
-          type: 'object',
-          properties: {
-            basicAuth: {
-              type: 'string',
-              description: 'Basic authentication',
-              format: 'password',
-            },
-          },
-        },
-      },
-    };
-
-    const security = [{ basicAuth: [] }];
-
-    const securitySchemes = {
-      basicAuth: {
-        type: 'http',
-        scheme: 'basic',
-      },
-    } as any;
-
-    const result = generateWorkflowSecurityParameters(inputsComponents, security, securitySchemes);
-
-    expect(result).toEqual([
-      {
-        name: 'Authorization',
-        value: `Basic {$inputs.basicAuth}`,
-        in: 'header',
-      },
-    ]);
-  });
-
-  it('should return the correct workflow security parameters for Bearer authentication', () => {
-    const inputsComponents = {
-      inputs: {
-        bearerAuth: {
-          type: 'string',
-          description: 'Bearer token',
-          format: 'password',
-        },
-      },
-    };
-
-    const security = [{ bearerAuth: [] }];
-
-    const securitySchemes = {
-      bearerAuth: {
-        type: 'http',
-        scheme: 'bearer',
-      },
-    } as any;
-
-    const result = generateWorkflowSecurityParameters(inputsComponents, security, securitySchemes);
-
-    expect(result).toEqual([
-      {
-        name: 'Authorization',
-        value: `Bearer {$inputs.bearerAuth}`,
-        in: 'header',
-      },
-    ]);
-  });
-
-  it('should return the correct workflow security parameters for ApiKey authentication', () => {
-    const inputsComponents = {
-      inputs: {
-        apiKey: {
-          type: 'string',
-          description: 'ApiKey token',
-          format: 'password',
-        },
-      },
-    };
-
-    const security = [{ apiKey: [] }];
-
-    const securitySchemes = {
-      apiKey: {
-        type: 'apiKey',
-        name: 'X-API-Key',
-        in: 'header',
-      },
-    } as any;
-
-    const result = generateWorkflowSecurityParameters(inputsComponents, security, securitySchemes);
-
-    expect(result).toEqual([
-      {
-        name: 'X-API-Key',
-        value: `$inputs.apiKey`,
-        in: 'header',
-      },
-    ]);
-  });
-
-  it('should return an empty array if there are no security parameters', () => {
-    const inputsComponents = {};
-    const security = [] as any;
-    const securitySchemes = {};
-
-    const result = generateWorkflowSecurityParameters(inputsComponents, security, securitySchemes);
-
-    expect(result).toEqual([]);
-  });
-
-  it('should return an empty array if the security scheme is not supported', () => {
-    const inputsComponents = {
-      inputs: {
-        oauth2Auth: {
-          type: 'string',
-          description: 'OAuth2 token',
-        },
-      },
-    };
-    const security = [{ oauth2Auth: [] }] as any;
-    const securitySchemes = {
-      oauth2Auth: {
-        type: 'oauth2',
-      },
-    } as any;
-
-    const result = generateWorkflowSecurityParameters(inputsComponents, security, securitySchemes);
-
-    expect(result).toEqual([]);
-  });
-});
diff --git a/packages/respect-core/src/modules/arazzo-description-generator/generate-arazzo-description.ts b/packages/respect-core/src/modules/arazzo-description-generator/generate-arazzo-description.ts
index 78182192ae..04a014c905 100644
--- a/packages/respect-core/src/modules/arazzo-description-generator/generate-arazzo-description.ts
+++ b/packages/respect-core/src/modules/arazzo-description-generator/generate-arazzo-description.ts
@@ -33,7 +33,7 @@ export async function generateArazzoDescription(opts: GenerateArazzoOptions) {
     : undefined;
 
   const testDescription: TestDescription = {
-    arazzo: '1.0.1',
+    arazzo: '1.1.0',
     info: {
       title: info?.title || infoSubstitute.title,
       version: info?.version || infoSubstitute.version,
diff --git a/packages/respect-core/src/modules/arazzo-description-generator/generate-inputs-arazzo-components.ts b/packages/respect-core/src/modules/arazzo-description-generator/generate-inputs-arazzo-components.ts
index 88295ec9d3..4ffee52979 100644
--- a/packages/respect-core/src/modules/arazzo-description-generator/generate-inputs-arazzo-components.ts
+++ b/packages/respect-core/src/modules/arazzo-description-generator/generate-inputs-arazzo-components.ts
@@ -6,36 +6,47 @@ export function generateSecurityInputsArazzoComponents(
   const inputs: NonNullable<ArazzoDefinition['components']>['inputs'] = {};
 
   for (const [name, securityScheme] of Object.entries(securitySchemes)) {
-    if (securityScheme.type !== 'http' && securityScheme.type !== 'apiKey') {
-      continue;
-    }
+    const httpScheme =
+      securityScheme.type === 'http' ? securityScheme.scheme?.toLowerCase() : undefined;
 
-    if (securityScheme.type === 'http' && securityScheme.scheme?.toLowerCase() === 'basic') {
+    if (httpScheme === 'basic' || httpScheme === 'digest') {
+      inputs[name] = {
+        type: 'object',
+        properties: {
+          username: {
+            type: 'string',
+            description: `Username for ${name}`,
+          },
+          password: {
+            type: 'string',
+            description: `Password for ${name}`,
+            format: 'password',
+          },
+        },
+      };
+    } else if (httpScheme === 'bearer') {
       inputs[name] = {
         type: 'object',
         properties: {
           [name]: {
             type: 'string',
-            description: 'Basic authentication',
+            description: securityScheme?.description || `JWT Authentication token for ${name}`,
             format: 'password',
           },
         },
       };
-    } else if (
-      securityScheme.type === 'http' &&
-      securityScheme.scheme?.toLowerCase() === 'bearer'
-    ) {
+    } else if (securityScheme.type === 'oauth2' || securityScheme.type === 'openIdConnect') {
       inputs[name] = {
         type: 'object',
         properties: {
           [name]: {
             type: 'string',
-            description: 'JWT Authentication token for ${name}',
+            description: securityScheme?.description || `Access token for ${name}`,
             format: 'password',
           },
         },
       };
-    } else {
+    } else if (securityScheme.type === 'apiKey' || httpScheme) {
       inputs[name] = {
         type: 'object',
         properties: {
@@ -47,6 +58,7 @@ export function generateSecurityInputsArazzoComponents(
         },
       };
     }
+    // mutualTLS and unknown scheme types cannot be satisfied by a value input.
   }
 
   return { inputs };
diff --git a/packages/respect-core/src/modules/arazzo-description-generator/generate-step-security.ts b/packages/respect-core/src/modules/arazzo-description-generator/generate-step-security.ts
new file mode 100644
index 0000000000..4667e868f0
--- /dev/null
+++ b/packages/respect-core/src/modules/arazzo-description-generator/generate-step-security.ts
@@ -0,0 +1,73 @@
+import {
+  type ArazzoDefinition,
+  type Oas3SecurityRequirement,
+  type Oas3SecurityScheme,
+} from '@redocly/openapi-core';
+
+import { type ExtendedSecurity, type Parameter } from '../../types.js';
+
+export type GeneratedStepSecurity = {
+  xSecurity: ExtendedSecurity[];
+  parameters: Parameter[];
+};
+
+/**
+ * Express an operation's security requirements the way Respect can execute
+ * them: an `x-security` entry with `$inputs` values for every scheme type
+ * Respect supports (see flow-runner/validate-x-security-parameters.ts), a
+ * plain Authorization header parameter for other HTTP schemes, and nothing
+ * for schemes that a value input cannot satisfy (such as mutualTLS).
+ */
+export function generateStepSecurity(
+  inputsComponents: NonNullable<ArazzoDefinition['components']>,
+  security: Oas3SecurityRequirement[],
+  securitySchemes: Record<string, Oas3SecurityScheme>
+): GeneratedStepSecurity {
+  const xSecurity: ExtendedSecurity[] = [];
+  const parameters: Parameter[] = [];
+
+  for (const securityRequirement of security ?? []) {
+    for (const securityName of Object.keys(securityRequirement)) {
+      if (!inputsComponents?.inputs?.[securityName]) {
+        continue;
+      }
+
+      const securityScheme = securitySchemes[securityName];
+      const httpScheme =
+        securityScheme?.type === 'http' ? securityScheme.scheme?.toLowerCase() : undefined;
+
+      if (securityScheme?.type === 'apiKey') {
+        xSecurity.push({
+          schemeName: securityName,
+          values: { apiKey: `$inputs.${securityName}` },
+        });
+      } else if (securityScheme?.type === 'oauth2' || securityScheme?.type === 'openIdConnect') {
+        xSecurity.push({
+          schemeName: securityName,
+          values: { accessToken: `$inputs.${securityName}` },
+        });
+      } else if (httpScheme === 'bearer') {
+        xSecurity.push({
+          schemeName: securityName,
+          values: { token: `$inputs.${securityName}` },
+        });
+      } else if (httpScheme === 'basic' || httpScheme === 'digest') {
+        xSecurity.push({
+          schemeName: securityName,
+          values: { username: '$inputs.username', password: '$inputs.password' },
+        });
+      } else if (securityScheme?.type === 'http' && securityScheme.scheme) {
+        // Respect's x-security does not know this HTTP scheme; an RFC 7235
+        // Authorization header with the scheme's own prefix still expresses it.
+        parameters.push({
+          name: 'Authorization',
+          value: `${securityScheme.scheme} {$inputs.${securityName}}`,
+          in: 'header',
+        });
+      }
+      // Anything else cannot be determined from the description; skip it.
+    }
+  }
+
+  return { xSecurity, parameters };
+}
diff --git a/packages/respect-core/src/modules/arazzo-description-generator/generate-workflow-security-parameters.ts b/packages/respect-core/src/modules/arazzo-description-generator/generate-workflow-security-parameters.ts
deleted file mode 100644
index db7fac3a88..0000000000
--- a/packages/respect-core/src/modules/arazzo-description-generator/generate-workflow-security-parameters.ts
+++ /dev/null
@@ -1,52 +0,0 @@
-import { type Oas3SecurityRequirement, type Oas3SecurityScheme } from '@redocly/openapi-core';
-
-export function generateWorkflowSecurityParameters(
-  inputsComponents: any,
-  security: Oas3SecurityRequirement[],
-  securitySchemes: Record<string, Oas3SecurityScheme>
-) {
-  if (!security?.length) {
-    return [];
-  }
-
-  const parameters = [];
-
-  for (const securityRequirement of security) {
-    for (const securityName of Object.keys(securityRequirement)) {
-      if (!inputsComponents?.inputs?.[securityName]) {
-        continue;
-      }
-
-      const securityScheme = securitySchemes[securityName];
-
-      if (
-        securityScheme?.type &&
-        !['apikey', 'http'].includes(securityScheme?.type?.toLowerCase())
-      ) {
-        continue;
-      }
-
-      if (securityScheme?.type === 'apiKey') {
-        parameters.push({
-          name: securityScheme?.name,
-          value: `$inputs.${securityName}`,
-          in: securityScheme?.in || 'header',
-        });
-      } else if (securityScheme?.type === 'http' && securityScheme?.scheme === 'bearer') {
-        parameters.push({
-          name: 'Authorization',
-          value: `Bearer {$inputs.${securityName}}`,
-          in: 'header',
-        });
-      } else if (securityScheme?.type === 'http' && securityScheme?.scheme === 'basic') {
-        parameters.push({
-          name: 'Authorization',
-          value: `Basic {$inputs.${securityName}}`,
-          in: 'header',
-        });
-      }
-    }
-  }
-
-  return parameters;
-}
diff --git a/packages/respect-core/src/modules/arazzo-description-generator/generate-workflows-from-description.ts b/packages/respect-core/src/modules/arazzo-description-generator/generate-workflows-from-description.ts
index f77f97270e..75b8b21300 100644
--- a/packages/respect-core/src/modules/arazzo-description-generator/generate-workflows-from-description.ts
+++ b/packages/respect-core/src/modules/arazzo-description-generator/generate-workflows-from-description.ts
@@ -10,8 +10,8 @@ import {
 
 import { type OperationMethod, type Workflow, type Step } from '../../types.js';
 import { sortMethods } from '../../utils/sort.js';
+import { generateStepSecurity } from './generate-step-security.js';
 import { generateWorkflowSecurityInputs } from './generate-workflow-security-inputs.js';
-import { generateWorkflowSecurityParameters } from './generate-workflow-security-parameters.js';
 
 type HttpMethod = Lowercase<ExtendedOperation['method']>;
 
@@ -70,7 +70,7 @@ export function generateWorkflowsFromDescription({
           inputsComponents,
           operationSecurity || rootSecurity || []
         );
-        const workflowSecurityParameters = generateWorkflowSecurityParameters(
+        const stepSecurity = generateStepSecurity(
           inputsComponents,
           operationSecurity || rootSecurity || [],
           securitySchemes
@@ -79,13 +79,14 @@ export function generateWorkflowsFromDescription({
         workflows.push({
           workflowId: pathKey ? `${method}-${pathKey}-workflow` : `${method}-workflow`,
           ...(workflowSecurityInputs && { inputs: workflowSecurityInputs }),
-          ...(workflowSecurityParameters.length && {
-            parameters: workflowSecurityParameters,
+          ...(stepSecurity.parameters.length && {
+            parameters: stepSecurity.parameters,
           }),
           steps: [
             {
               stepId: pathKey ? `${method}-${pathKey}-step` : `${method}-step`,
               ...(operationId ? { operationId } : { operationPath }),
+              ...(stepSecurity.xSecurity.length && { 'x-security': stepSecurity.xSecurity }),
               ...generateParametersWithSuccessCriteria(
                 descriptionPaths[pathItemKey][methodToCheck.toLowerCase() as HttpMethod]?.responses
               ),
diff --git a/packages/respect-core/src/modules/arazzo-description-generator/index.ts b/packages/respect-core/src/modules/arazzo-description-generator/index.ts
index b538a4f161..8872e0ed30 100644
--- a/packages/respect-core/src/modules/arazzo-description-generator/index.ts
+++ b/packages/respect-core/src/modules/arazzo-description-generator/index.ts
@@ -5,4 +5,4 @@ export * from './generate-example-value.js';
 export * from './generate-workflows-from-description.js';
 export * from './generate-inputs-arazzo-components.js';
 export * from './generate-workflow-security-inputs.js';
-export * from './generate-workflow-security-parameters.js';
+export * from './generate-step-security.js';

From c0150ce71a7426df1a5aa6c71f80bf237ee6f6fc Mon Sep 17 00:00:00 2001
From: DmitryAnansky <dmytro@redocly.com>
Date: Wed, 26 Aug 2026 18:07:49 +0300
Subject: [PATCH 2/6] feat: update promt to consider tags grouping

---
 docs/@v2/commands/generate-arazzo.md          |  1 +
 .../__tests__/generate-workflows.test.ts      | 26 +++++++++++++
 .../generate-arazzo/ai/generate-workflows.ts  | 39 ++++++++++++++++++-
 .../src/commands/generate-arazzo/ai/prompt.ts |  1 +
 4 files changed, 66 insertions(+), 1 deletion(-)

diff --git a/docs/@v2/commands/generate-arazzo.md b/docs/@v2/commands/generate-arazzo.md
index 38f808c63a..61e0bdd6e6 100644
--- a/docs/@v2/commands/generate-arazzo.md
+++ b/docs/@v2/commands/generate-arazzo.md
@@ -158,6 +158,7 @@ The AI's answer is never trusted blindly: the `arazzo`, `info`, and `sourceDescr
 If the answer is rejected, the provider fails, or the description is too large to prompt with, the command keeps the auto-generated workflows.
 
 The generated file starts with a comment marking the workflows as AI-inferred — they are a guess derived from the description, not verified behavior, so review them before use.
+The result also varies between runs: the same description can produce different workflows each time.
 
 ```bash
 redocly generate-arazzo openapi.yaml --with-ai --ai-provider claude --max-workflows 5
diff --git a/packages/cli/src/commands/generate-arazzo/__tests__/generate-workflows.test.ts b/packages/cli/src/commands/generate-arazzo/__tests__/generate-workflows.test.ts
index 79a500273a..22a1fc9b46 100644
--- a/packages/cli/src/commands/generate-arazzo/__tests__/generate-workflows.test.ts
+++ b/packages/cli/src/commands/generate-arazzo/__tests__/generate-workflows.test.ts
@@ -101,6 +101,32 @@ describe('generateWorkflowsWithAi', () => {
     );
   });
 
+  it('drops description and example prose when the full description does not fit the prompt', async () => {
+    vi.mocked(runProvider).mockResolvedValueOnce({ text: redesignedWorkflows });
+    const result = await generateWorkflowsWithAi({
+      provider: 'claude',
+      baseline: baseline(),
+      description: {
+        openapi: '3.1.0',
+        info: { title: 'Test API', version: '1.0.0', description: 'x'.repeat(400_001) },
+        components: {
+          schemas: {
+            User: { type: 'object', properties: { description: { type: 'string' } } },
+          },
+        },
+      },
+      maxWorkflows: 10,
+    });
+    expect(result.workflows).toBe(1);
+    const request = vi.mocked(runProvider).mock.calls[0][1];
+    expect(request.user).not.toContain('xxxx');
+    // A schema property named "description" is data, not prose, and survives.
+    expect(request.user).toContain('description:');
+    expect(logger.info).toHaveBeenCalledWith(
+      expect.stringContaining('without description and example fields')
+    );
+  });
+
   it('rejects a description too large to prompt with, without calling the provider', async () => {
     await expect(
       generateWorkflowsWithAi({
diff --git a/packages/cli/src/commands/generate-arazzo/ai/generate-workflows.ts b/packages/cli/src/commands/generate-arazzo/ai/generate-workflows.ts
index 6844a9daba..de14b9d1cd 100644
--- a/packages/cli/src/commands/generate-arazzo/ai/generate-workflows.ts
+++ b/packages/cli/src/commands/generate-arazzo/ai/generate-workflows.ts
@@ -27,6 +27,30 @@ export interface GenerateWorkflowsOptions {
 // the answer; ~400k characters is roughly 100k tokens.
 export const MAX_PROMPT_CHARS = 400_000;
 
+const PROSE_KEYS = new Set(['description', 'example', 'examples', 'externalDocs']);
+
+/**
+ * Copy the description without its prose fields. Under a `properties` key the
+ * keys are schema property names, not OpenAPI keywords — a property named
+ * "description" must survive.
+ */
+function stripProse(value: unknown, keysArePropertyNames = false): unknown {
+  if (Array.isArray(value)) {
+    return value.map((item) => stripProse(item));
+  }
+  if (!isPlainObject(value)) {
+    return value;
+  }
+  const result: Record<string, unknown> = {};
+  for (const [key, child] of Object.entries(value)) {
+    if (!keysArePropertyNames && PROSE_KEYS.has(key)) {
+      continue;
+    }
+    result[key] = stripProse(child, !keysArePropertyNames && key === 'properties');
+  }
+  return result;
+}
+
 export interface GeneratedWorkflowsResult {
   /** The Arazzo description with the AI-designed workflows, as YAML. */
   yaml: string;
@@ -136,12 +160,25 @@ function validateReferences(workflows: unknown[], baseline: TestDescription): vo
 export async function generateWorkflowsWithAi(
   options: GenerateWorkflowsOptions
 ): Promise<GeneratedWorkflowsResult> {
-  const { system, user } = buildWorkflowsPrompt({
+  let { system, user } = buildWorkflowsPrompt({
     description: options.description,
     baseline: options.baseline,
     maxWorkflows: options.maxWorkflows,
   });
 
+  if (system.length + user.length > MAX_PROMPT_CHARS) {
+    // Chaining operations needs the description's structure, not its prose;
+    // dropping the prose lets much larger descriptions fit the prompt.
+    ({ system, user } = buildWorkflowsPrompt({
+      description: stripProse(options.description),
+      baseline: options.baseline,
+      maxWorkflows: options.maxWorkflows,
+    }));
+    logger.info(
+      'The OpenAPI description is large; sending it to the AI provider without description and example fields.\n'
+    );
+  }
+
   if (system.length + user.length > MAX_PROMPT_CHARS) {
     throw new Error('the OpenAPI description is too large to send to the AI provider');
   }
diff --git a/packages/cli/src/commands/generate-arazzo/ai/prompt.ts b/packages/cli/src/commands/generate-arazzo/ai/prompt.ts
index d8b8e154d2..af67db4d9d 100644
--- a/packages/cli/src/commands/generate-arazzo/ai/prompt.ts
+++ b/packages/cli/src/commands/generate-arazzo/ai/prompt.ts
@@ -8,6 +8,7 @@ function buildSystemInstructions(maxWorkflows: number): string {
 Follow these rules:
 - Reference operations exactly the way the baseline does: "operationId: $sourceDescriptions.<name>.<operationId>" for operations that have an operationId, or the baseline's "operationPath" value otherwise. Reference only operations that appear in the baseline. The result is programmatically checked and rejected otherwise.
 - Group related operations into multi-step scenario workflows — for example create a resource, read it, update it, and delete it. A workflow may also be a single step when an operation stands alone.
+- Prefer grouping operations that share a tag into the same workflow, and when scenarios are equally likely, follow the order in which operations appear in the description.
 - Design at most ${maxWorkflows} workflow(s); this limit is programmatically checked. Prefer covering every operation from the baseline in at least one workflow; when the limit does not allow that, choose the operations that form the most likely real-world scenarios.
 - When the API has authentication or token-issuing operations, run them first and pass their result to the steps that need it.
 - When a step registers or configures an OAuth2 client, request every grant type the security scheme's flows declare (for example both authorization_code and client_credentials), so the example works with any declared flow.

From 265457364434b524f799e9b7002b80a6d40a7dd4 Mon Sep 17 00:00:00 2001
From: DmitryAnansky <dmytro@redocly.com>
Date: Thu, 27 Aug 2026 12:55:52 +0300
Subject: [PATCH 3/6] chore: remove comments

---
 .../cli/src/commands/generate-arazzo/ai/generate-workflows.ts   | 2 --
 packages/cli/src/commands/generate-arazzo/index.ts              | 1 -
 2 files changed, 3 deletions(-)

diff --git a/packages/cli/src/commands/generate-arazzo/ai/generate-workflows.ts b/packages/cli/src/commands/generate-arazzo/ai/generate-workflows.ts
index de14b9d1cd..5359e7e4f7 100644
--- a/packages/cli/src/commands/generate-arazzo/ai/generate-workflows.ts
+++ b/packages/cli/src/commands/generate-arazzo/ai/generate-workflows.ts
@@ -17,9 +17,7 @@ export interface GenerateWorkflowsOptions {
   provider: AiProvider;
   /** The mechanically generated Arazzo description the AI redesigns. */
   baseline: TestDescription;
-  /** The bundled OpenAPI description, sent to the AI as context. */
   description: unknown;
-  /** The most workflows the AI may design; more get the answer rejected. */
   maxWorkflows: number;
 }
 
diff --git a/packages/cli/src/commands/generate-arazzo/index.ts b/packages/cli/src/commands/generate-arazzo/index.ts
index d23ad587f2..9e59872ecd 100644
--- a/packages/cli/src/commands/generate-arazzo/index.ts
+++ b/packages/cli/src/commands/generate-arazzo/index.ts
@@ -59,7 +59,6 @@ function collectWorkflowInputNames(document: unknown): string[] {
   return [...names];
 }
 
-/** A ready-to-run `respect` command with a placeholder for every input. */
 export function buildRespectHint(resultYaml: string, outputFile: string): string {
   const inputNames = collectWorkflowInputNames(parseYaml(resultYaml));
   const inputFlags = inputNames

From 40baaebdb8792bc64968503610c87de8601a7890 Mon Sep 17 00:00:00 2001
From: DmitryAnansky <dmytro@redocly.com>
Date: Thu, 27 Aug 2026 17:29:50 +0300
Subject: [PATCH 4/6] fix: oversized-spec log claims a send

---
 .../generate-arazzo/__tests__/generate-workflows.test.ts   | 3 +++
 .../src/commands/generate-arazzo/ai/generate-workflows.ts  | 7 +++----
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/packages/cli/src/commands/generate-arazzo/__tests__/generate-workflows.test.ts b/packages/cli/src/commands/generate-arazzo/__tests__/generate-workflows.test.ts
index 22a1fc9b46..79bccacb41 100644
--- a/packages/cli/src/commands/generate-arazzo/__tests__/generate-workflows.test.ts
+++ b/packages/cli/src/commands/generate-arazzo/__tests__/generate-workflows.test.ts
@@ -137,6 +137,9 @@ describe('generateWorkflowsWithAi', () => {
       })
     ).rejects.toThrow('the OpenAPI description is too large to send to the AI provider');
     expect(runProvider).not.toHaveBeenCalled();
+    expect(logger.info).not.toHaveBeenCalledWith(
+      expect.stringContaining('without description and example fields')
+    );
   });
 
   it('strips Markdown code fences before parsing', async () => {
diff --git a/packages/cli/src/commands/generate-arazzo/ai/generate-workflows.ts b/packages/cli/src/commands/generate-arazzo/ai/generate-workflows.ts
index 5359e7e4f7..37a6dbea82 100644
--- a/packages/cli/src/commands/generate-arazzo/ai/generate-workflows.ts
+++ b/packages/cli/src/commands/generate-arazzo/ai/generate-workflows.ts
@@ -172,15 +172,14 @@ export async function generateWorkflowsWithAi(
       baseline: options.baseline,
       maxWorkflows: options.maxWorkflows,
     }));
+    if (system.length + user.length > MAX_PROMPT_CHARS) {
+      throw new Error('the OpenAPI description is too large to send to the AI provider');
+    }
     logger.info(
       'The OpenAPI description is large; sending it to the AI provider without description and example fields.\n'
     );
   }
 
-  if (system.length + user.length > MAX_PROMPT_CHARS) {
-    throw new Error('the OpenAPI description is too large to send to the AI provider');
-  }
-
   const spinner = new Spinner();
   spinner.start('Waiting for the AI-designed workflows');
   let text: string;

From 13f984e2f6d127e33ce7595d5491ef1bd58c7fc1 Mon Sep 17 00:00:00 2001
From: DmitryAnansky <dmytro@redocly.com>
Date: Thu, 27 Aug 2026 18:25:44 +0300
Subject: [PATCH 5/6] fix: respect rejecting x-security HTTP schemes written
 with non-lowercase casing

---
 .../flow-runner/validate-x-security-parameters.test.ts    | 8 ++++++++
 .../src/modules/context-parser/get-security-parameters.ts | 4 ++--
 .../modules/flow-runner/validate-x-security-parameters.ts | 3 ++-
 packages/respect-core/src/utils/api-fetcher.ts            | 2 +-
 4 files changed, 13 insertions(+), 4 deletions(-)

diff --git a/packages/respect-core/src/modules/__tests__/flow-runner/validate-x-security-parameters.test.ts b/packages/respect-core/src/modules/__tests__/flow-runner/validate-x-security-parameters.test.ts
index 62e3591a96..208e6a6dcd 100644
--- a/packages/respect-core/src/modules/__tests__/flow-runner/validate-x-security-parameters.test.ts
+++ b/packages/respect-core/src/modules/__tests__/flow-runner/validate-x-security-parameters.test.ts
@@ -27,6 +27,14 @@ describe('validateXSecurityParameters', () => {
     expect(result).toEqual({ scheme, values });
   });
 
+  it('should validate an HTTP scheme regardless of its casing', () => {
+    const scheme = { type: 'http', scheme: 'Basic' } as Oas3SecurityScheme;
+    const values = { username: 'user', password: 'password' };
+
+    const result = validateXSecurityParameters({ scheme, values });
+    expect(result).toEqual({ scheme, values });
+  });
+
   it('should throw for missing username in basic scheme', () => {
     const scheme: BasicAuth = { type: 'http', scheme: 'basic' };
     const values = { username: 'user' };
diff --git a/packages/respect-core/src/modules/context-parser/get-security-parameters.ts b/packages/respect-core/src/modules/context-parser/get-security-parameters.ts
index 7cadcee328..775ed89e26 100644
--- a/packages/respect-core/src/modules/context-parser/get-security-parameters.ts
+++ b/packages/respect-core/src/modules/context-parser/get-security-parameters.ts
@@ -87,11 +87,11 @@ function isApiKeyAuth(
 function isBasicAuth(
   security: ResolvedSecurity
 ): security is Extract<ResolvedSecurity, { scheme: BasicAuth }> {
-  return security.scheme.type === 'http' && security.scheme.scheme === 'basic';
+  return security.scheme.type === 'http' && security.scheme.scheme?.toLowerCase() === 'basic';
 }
 
 function isBearerAuth(
   security: ResolvedSecurity
 ): security is Extract<ResolvedSecurity, { scheme: BearerAuth }> {
-  return security.scheme.type === 'http' && security.scheme.scheme === 'bearer';
+  return security.scheme.type === 'http' && security.scheme.scheme?.toLowerCase() === 'bearer';
 }
diff --git a/packages/respect-core/src/modules/flow-runner/validate-x-security-parameters.ts b/packages/respect-core/src/modules/flow-runner/validate-x-security-parameters.ts
index b6a4b16f58..d8a9191e73 100644
--- a/packages/respect-core/src/modules/flow-runner/validate-x-security-parameters.ts
+++ b/packages/respect-core/src/modules/flow-runner/validate-x-security-parameters.ts
@@ -20,7 +20,8 @@ export function validateXSecurityParameters({
   scheme: Oas3SecurityScheme;
   values: Record<string, string>;
 }): ResolvedSecurity {
-  const authType = scheme.type === 'http' ? scheme.scheme : scheme.type;
+  // RFC 7235 HTTP authentication scheme names are case-insensitive.
+  const authType = scheme.type === 'http' ? scheme.scheme?.toLowerCase() : scheme.type;
   const requiredKeys = REQUIRED_VALUES_BY_AUTH_TYPE[authType as AuthType];
 
   if (!requiredKeys) {
diff --git a/packages/respect-core/src/utils/api-fetcher.ts b/packages/respect-core/src/utils/api-fetcher.ts
index 94020ae89b..ee47ca8eb1 100644
--- a/packages/respect-core/src/utils/api-fetcher.ts
+++ b/packages/respect-core/src/utils/api-fetcher.ts
@@ -313,7 +313,7 @@ export class ApiFetcher implements IFetcher {
           operation: openapiOperation,
         });
 
-        return scheme?.type === 'http' && scheme?.scheme === 'digest';
+        return scheme?.type === 'http' && scheme?.scheme?.toLowerCase() === 'digest';
       });
 
     if (lastDigestSecurityScheme) {

From 24e1f7a62602b83a019cea771121baf55d7b4c96 Mon Sep 17 00:00:00 2001
From: DmitryAnansky <dmytro@redocly.com>
Date: Thu, 27 Aug 2026 18:37:45 +0300
Subject: [PATCH 6/6] fix: x-security-scheme-required-values case-insensitive
 schemes

---
 .changeset/respect-scheme-case.md             |  7 ++++
 .../x-security-scheme-required-values.test.ts | 38 +++++++++++++++++++
 .../x-security-scheme-required-values.ts      |  5 ++-
 3 files changed, 49 insertions(+), 1 deletion(-)
 create mode 100644 .changeset/respect-scheme-case.md

diff --git a/.changeset/respect-scheme-case.md b/.changeset/respect-scheme-case.md
new file mode 100644
index 0000000000..6c046a26b2
--- /dev/null
+++ b/.changeset/respect-scheme-case.md
@@ -0,0 +1,7 @@
+---
+'@redocly/cli': patch
+'@redocly/respect-core': patch
+'@redocly/openapi-core': patch
+---
+
+Fixed `respect` and the `x-security-scheme-required-values` rule rejecting `x-security` HTTP schemes written with non-lowercase casing (such as `Basic`, `Bearer`, or `Digest`) — RFC 7235 scheme names are case-insensitive.
diff --git a/packages/core/src/rules/arazzo/__tests__/x-security-scheme-required-values.test.ts b/packages/core/src/rules/arazzo/__tests__/x-security-scheme-required-values.test.ts
index d2df5d0a2d..0e61700ba4 100644
--- a/packages/core/src/rules/arazzo/__tests__/x-security-scheme-required-values.test.ts
+++ b/packages/core/src/rules/arazzo/__tests__/x-security-scheme-required-values.test.ts
@@ -113,6 +113,44 @@ describe('Arazzo x-security-scheme-required-values', () => {
     `);
   });
 
+  it('should accept an HTTP scheme regardless of its casing', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        arazzo: '1.0.1'
+        info:
+          title: Cool API
+          version: 1.0.0
+        sourceDescriptions:
+          - name: museum-api
+            type: openapi
+            url: openapi.yaml
+        workflows:
+          - workflowId: get-museum-hours
+            steps:
+              - stepId: step-with-openapi-operation
+                operationId: museum-api.getMuseumHours
+                x-security:
+                  - scheme:
+                      type: http
+                      scheme: Basic
+                    values:
+                      username: todd@example.com
+                      password: 123456
+      `,
+      'arazzo.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await createConfig({
+        rules: { 'x-security-scheme-required-values': 'error' },
+      }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`[]`);
+  });
+
   it('should report when required values are missing for Bearer Auth x-security schema', async () => {
     const document = parseYamlToDocument(
       outdent`
diff --git a/packages/core/src/rules/respect/x-security-scheme-required-values.ts b/packages/core/src/rules/respect/x-security-scheme-required-values.ts
index 8df40ab8d9..fc5f507302 100644
--- a/packages/core/src/rules/respect/x-security-scheme-required-values.ts
+++ b/packages/core/src/rules/respect/x-security-scheme-required-values.ts
@@ -32,6 +32,9 @@ function validateSecuritySchemas(
     const { scheme, values } = securitySchema;
     // TODO: Struct rule does not check before this point, so we need to check it here. Investigate if we can move this check to the Struct rule.
     const authType = scheme?.type === 'http' ? scheme.scheme : scheme?.type;
+    // RFC 7235 HTTP authentication scheme names are case-insensitive; the
+    // reported messages keep the scheme as written.
+    const normalizedAuthType = scheme?.type === 'http' ? authType?.toLowerCase() : authType;
 
     if (authType === 'mutualTLS') {
       logger.warn(
@@ -40,7 +43,7 @@ function validateSecuritySchemas(
       continue;
     }
 
-    const requiredValues = REQUIRED_VALUES_BY_AUTH_TYPE[authType as AuthType];
+    const requiredValues = REQUIRED_VALUES_BY_AUTH_TYPE[normalizedAuthType as AuthType];
 
     if (requiredValues) {
       for (const requiredValue of requiredValues) {