From 528872cdceab5e2fa63fe484c122df59dbbdb272 Mon Sep 17 00:00:00 2001
From: Andrew Tatomyr <andrew.tatomyr@redocly.com>
Date: Tue, 7 Jul 2026 11:04:19 +0300
Subject: [PATCH 1/4] feat: add experimental map command

---
 docs/@v2/commands/map.md                      |  146 ++
 docs/@v2/v2.sidebars.yaml                     |    2 +
 .../0001-deterministic-api-map-generation.md  |   24 +
 packages/cli/src/commands/map/index.ts        |   51 +
 .../cli/src/commands/map/print-map/index.ts   |   16 +
 .../cli/src/commands/map/print-map/json.ts    |    5 +
 .../cli/src/commands/map/print-map/stylish.ts |   13 +
 packages/cli/src/index.ts                     |   30 +
 .../api-map/__tests__/build-api-map.test.ts   |  571 ++++++++
 .../multi-file/components/menu-item.yaml      |    2 +
 .../fixtures/multi-file/openapi.yaml          |   13 +
 .../fixtures/multi-file/paths/menu.yaml       |    2 +
 packages/core/src/api-map/async.ts            |   65 +
 packages/core/src/api-map/build-api-map.ts    |   89 ++
 packages/core/src/api-map/hooks.ts            |  117 ++
 packages/core/src/api-map/oas.ts              |   78 +
 packages/core/src/api-map/types.ts            |   19 +
 packages/core/src/index.ts                    |    2 +
 packages/core/src/visitors.ts                 |   32 +
 tests/e2e/map/map-async2-stylish/async.yaml   |  606 ++++++++
 tests/e2e/map/map-async2-stylish/snapshot.txt |   55 +
 .../e2e/map/map-async3-stylish/asyncapi3.yaml |   31 +
 tests/e2e/map/map-async3-stylish/snapshot.txt |   12 +
 .../map/map-json/components/menu-item.yaml    |    2 +
 tests/e2e/map/map-json/openapi.yaml           |   12 +
 tests/e2e/map/map-json/paths/menu.yaml        |    3 +
 tests/e2e/map/map-json/snapshot.txt           |   90 ++
 tests/e2e/map/map-stylish/cafe.yaml           | 1261 +++++++++++++++++
 tests/e2e/map/map-stylish/snapshot.txt        |   73 +
 tests/e2e/map/map.test.ts                     |   44 +
 vitest.config.ts                              |    2 +-
 31 files changed, 3467 insertions(+), 1 deletion(-)
 create mode 100644 docs/@v2/commands/map.md
 create mode 100644 docs/adr/0001-deterministic-api-map-generation.md
 create mode 100644 packages/cli/src/commands/map/index.ts
 create mode 100644 packages/cli/src/commands/map/print-map/index.ts
 create mode 100644 packages/cli/src/commands/map/print-map/json.ts
 create mode 100644 packages/cli/src/commands/map/print-map/stylish.ts
 create mode 100644 packages/core/src/api-map/__tests__/build-api-map.test.ts
 create mode 100644 packages/core/src/api-map/__tests__/fixtures/multi-file/components/menu-item.yaml
 create mode 100644 packages/core/src/api-map/__tests__/fixtures/multi-file/openapi.yaml
 create mode 100644 packages/core/src/api-map/__tests__/fixtures/multi-file/paths/menu.yaml
 create mode 100644 packages/core/src/api-map/async.ts
 create mode 100644 packages/core/src/api-map/build-api-map.ts
 create mode 100644 packages/core/src/api-map/hooks.ts
 create mode 100644 packages/core/src/api-map/oas.ts
 create mode 100644 packages/core/src/api-map/types.ts
 create mode 100644 tests/e2e/map/map-async2-stylish/async.yaml
 create mode 100644 tests/e2e/map/map-async2-stylish/snapshot.txt
 create mode 100644 tests/e2e/map/map-async3-stylish/asyncapi3.yaml
 create mode 100644 tests/e2e/map/map-async3-stylish/snapshot.txt
 create mode 100644 tests/e2e/map/map-json/components/menu-item.yaml
 create mode 100644 tests/e2e/map/map-json/openapi.yaml
 create mode 100644 tests/e2e/map/map-json/paths/menu.yaml
 create mode 100644 tests/e2e/map/map-json/snapshot.txt
 create mode 100644 tests/e2e/map/map-stylish/cafe.yaml
 create mode 100644 tests/e2e/map/map-stylish/snapshot.txt
 create mode 100644 tests/e2e/map/map.test.ts

diff --git a/docs/@v2/commands/map.md b/docs/@v2/commands/map.md
new file mode 100644
index 0000000000..90c9781935
--- /dev/null
+++ b/docs/@v2/commands/map.md
@@ -0,0 +1,146 @@
+# `map`
+
+## Introduction
+
+The `map` command generates a structural map of an API description:
+a hierarchical tree that mirrors the document, like a sitemap for API tooling and agents.
+Every node in the tree represents a retrievable section of the description — an operation, a channel, a named component, a webhook, a server, or a tag — and is addressed by a canonical JSON pointer.
+
+{% admonition type="warning" name="OpenAPI and AsyncAPI only" %}
+The `map` command is considered an experimental feature.
+This means it's still a work in progress and may go through major changes.
+
+It supports OpenAPI 2.0 through 3.2 and AsyncAPI 2.x and 3.0 descriptions.
+{% /admonition %}
+
+The API map is designed as a compact index that tools — including LLM-based agents — can navigate to decide which parts of an API description to retrieve,
+instead of processing the whole document.
+The tree structure and node summaries are extracted deterministically from the description itself; no external services are involved.
+
+Each node has the following fields:
+
+| Field   | Type   | Description                                                                                                                                                                              |
+| ------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| title   | string | Human-readable name: the API title, path, `operationId`, channel address, component name, tag name, or server URL.                                                                       |
+| kind    | string | Node type name from Redocly's internal type system, for example `Root`, `Info`, `Server`, `Tag`, `Paths`, `PathItem`, `Operation`, `Channel`, `Components`, `NamedSchemas`, or `Schema`. |
+| pointer | string | Canonical JSON pointer that identifies and addresses the node, for example `#/paths/~1menu/get`.                                                                                         |
+| summary | string | Optional. The node's `summary` field, or its `description` truncated at a word boundary (about 200 characters).                                                                          |
+| method  | string | Optional. HTTP method; present on OpenAPI `Operation` nodes only.                                                                                                                        |
+| path    | string | Optional. URL path; present on OpenAPI `Operation` nodes under `paths` only.                                                                                                             |
+| source  | object | Optional. Original `{ file, pointer }` location of the node; present when `--source-locations` is used.                                                                                  |
+| nodes   | array  | Child nodes.                                                                                                                                                                             |
+
+The tree stops at operations, channels, and named components;
+parameters, responses, messages payloads, and schema internals are the node's content, retrievable through its pointer.
+
+{% admonition type="info" name="Pointers are logical" %}
+Pointers address the logical document structure as authored.
+For multi-file descriptions, note that `redocly bundle` may store referenced components under different keys;
+use `--source-locations` when you need the exact file and location of each node.
+{% /admonition %}
+
+## Usage
+
+```bash
+redocly map <api>
+redocly map <api> [--format=<option>] [--source-locations] [--config=<path>]
+redocly map --version
+```
+
+## Options
+
+| Option             | Type    | Description                                                                                                                        |
+| ------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| api                | string  | **REQUIRED.** Path to the API description filename or alias that you want to generate the map for.                                 |
+| --config           | string  | Specify path to the [configuration file](../configuration/index.md).                                                               |
+| --format           | string  | Format for the output.<br />**Possible values:** `stylish`, `json`. Default value is `stylish`.                                    |
+| --help             | boolean | Show help.                                                                                                                         |
+| --lint-config      | string  | Specify the severity level for the configuration file. <br/> **Possible values:** `warn`, `error`, `off`. Default value is `warn`. |
+| --source-locations | boolean | Include the original source file and pointer for each node. Useful for multi-file descriptions.                                    |
+| --version          | boolean | Show version number.                                                                                                               |
+
+## Examples
+
+### Map an OpenAPI description (stylish, default format)
+
+The default output format prints an indented tree, one node per line, with the node title, kind, and pointer:
+
+```
+Redocly Cafe Root #/
+  Redocly Cafe Info #/info
+  paths Paths #/paths
+    /menu PathItem #/paths/~1menu
+      listMenuItems Operation #/paths/~1menu/get
+      createMenuItem Operation #/paths/~1menu/post
+  components Components #/components
+    schemas NamedSchemas #/components/schemas
+      MenuItem Schema #/components/schemas/MenuItem
+```
+
+### Map an AsyncAPI description
+
+AsyncAPI descriptions map to their own structure: channels, operations (AsyncAPI 3), and message components:
+
+```
+Account Service Root #/
+  Account Service Info #/info
+  channels NamedChannels #/channels
+    userSignedup Channel #/channels/userSignedup
+  components Components #/components
+    messages NamedMessages #/components/messages
+      UserSignedUp Message #/components/messages/UserSignedUp
+  operations NamedOperations #/operations
+    sendUserSignedup Operation #/operations/sendUserSignedup
+```
+
+### Generate a machine-readable map
+
+Use `--format=json` to get the map as a JSON tree, suitable for further processing:
+
+```bash
+redocly map openapi.yaml --format=json
+```
+
+```json
+{
+  "title": "Redocly Cafe",
+  "kind": "Root",
+  "pointer": "#/",
+  "nodes": [
+    {
+      "title": "listMenuItems",
+      "kind": "Operation",
+      "pointer": "#/paths/~1menu/get",
+      "summary": "List all menu items",
+      "method": "get",
+      "path": "/menu",
+      "nodes": []
+    }
+  ]
+}
+```
+
+### Include source locations
+
+For descriptions split across multiple files with `$ref`s,
+use `--source-locations` to add the original file and pointer to every node:
+
+```bash
+redocly map openapi.yaml --format=json --source-locations
+```
+
+```json
+{
+  "title": "/menu",
+  "kind": "PathItem",
+  "pointer": "#/paths/~1menu",
+  "source": {
+    "file": "paths/menu.yaml",
+    "pointer": "#/"
+  },
+  "nodes": []
+}
+```
+
+The `pointer` stays canonical to the logical document,
+while `source` tells you which file the node actually lives in.
diff --git a/docs/@v2/v2.sidebars.yaml b/docs/@v2/v2.sidebars.yaml
index 0c06ce6aab..1dce4c39a2 100644
--- a/docs/@v2/v2.sidebars.yaml
+++ b/docs/@v2/v2.sidebars.yaml
@@ -26,6 +26,8 @@
           page: commands/login.md
         - label: logout
           page: commands/logout.md
+        - label: map
+          page: commands/map.md
         - label: preview
           page: commands/preview.md
         - label: push
diff --git a/docs/adr/0001-deterministic-api-map-generation.md b/docs/adr/0001-deterministic-api-map-generation.md
new file mode 100644
index 0000000000..47d4ef45f3
--- /dev/null
+++ b/docs/adr/0001-deterministic-api-map-generation.md
@@ -0,0 +1,24 @@
+# Deterministic API map generation without bundling
+
+The `map` command produces a tree index that tools — including LLM-based agents — can navigate to retrieve relevant sections of an API description.
+It is named `map` (an API map, like a sitemap for agents) rather than `toc`:
+the artifact is a navigable index, and "table of contents" is book vocabulary that doesn't extrapolate to AsyncAPI or Arazzo.
+API descriptions already carry explicit structure and native `summary`/`description` fields,
+so map generation is fully deterministic: no LLM calls, no network, testable with snapshots.
+
+We walk the ORIGINAL resolved document (lint-style: `resolveDocument` + `walkDocument`), not the bundled one,
+even though `stats` bundles first.
+The bundler keeps no per-node map from bundled locations back to source files,
+while the walker's resolved locations give original `{file, pointer}` per node for free (exposed via `--source-locations`),
+and the canonical pointer is reconstructed from the walk key path.
+This also avoids bundle-time component renaming.
+
+The canonical JSON pointer IS the node id — no synthetic sequential ids,
+because pointers are stable across regenerations and double as the retrieval address.
+A node's `kind` is the internal node type name the walker reports (`PathItem`, `Operation`, `Channel`) —
+the type system is the single source of node names, per spec.
+
+## Consequences
+
+- The map's pointers address the logical document as authored; `bundle` output may store `$ref`ed components under different keys.
+- Adding a spec means adding a visitor to the spec-version switch in `packages/core/src/api-map/build-api-map.ts`, not redesigning.
diff --git a/packages/cli/src/commands/map/index.ts b/packages/cli/src/commands/map/index.ts
new file mode 100644
index 0000000000..cd510a3529
--- /dev/null
+++ b/packages/cli/src/commands/map/index.ts
@@ -0,0 +1,51 @@
+import {
+  BaseResolver,
+  buildApiMap,
+  detectSpec,
+  getMajorSpecVersion,
+  type Document,
+  type OutputFormat,
+} from '@redocly/openapi-core';
+
+import type { VerifyConfigOptions } from '../../types.js';
+import { exitWithError } from '../../utils/error.js';
+import { getFallbackApisOrExit } from '../../utils/miscellaneous.js';
+import type { CommandArgs } from '../../wrapper.js';
+import { printApiMap } from './print-map/index.js';
+
+const SUPPORTED_MAJOR_VERSIONS = ['oas2', 'oas3', 'async2', 'async3'];
+
+export type MapArgv = {
+  api?: string;
+  format: OutputFormat;
+  'source-locations'?: boolean;
+} & VerifyConfigOptions;
+
+export async function handleMap({ argv, config, collectSpecData }: CommandArgs<MapArgv>) {
+  const [{ path }] = await getFallbackApisOrExit(argv.api ? [argv.api] : [], config);
+  const externalRefResolver = new BaseResolver(config.resolve);
+  // resolveDocument returns a Document for a readable, parseable file; mirrors lint()
+  const document = (await externalRefResolver.resolveDocument(null, path, true)) as Document;
+  collectSpecData?.(document.parsed);
+
+  let major;
+  try {
+    major = getMajorSpecVersion(detectSpec(document.parsed));
+  } catch {
+    major = undefined;
+  }
+  if (!major || !SUPPORTED_MAJOR_VERSIONS.includes(major)) {
+    exitWithError(
+      'The `map` command supports OpenAPI and AsyncAPI descriptions only. Please provide an OpenAPI 2.0-3.2 or AsyncAPI 2.x-3.0 document.'
+    );
+  }
+
+  const apiMap = await buildApiMap({
+    document,
+    config,
+    externalRefResolver,
+    sourceLocations: argv['source-locations'],
+  });
+
+  printApiMap(apiMap, path, argv.format);
+}
diff --git a/packages/cli/src/commands/map/print-map/index.ts b/packages/cli/src/commands/map/print-map/index.ts
new file mode 100644
index 0000000000..82c5ba8abb
--- /dev/null
+++ b/packages/cli/src/commands/map/print-map/index.ts
@@ -0,0 +1,16 @@
+import { logger, type ApiMapNode } from '@redocly/openapi-core';
+import * as colors from 'colorette';
+
+import { printApiMapJson } from './json.js';
+import { printApiMapStylish } from './stylish.js';
+
+export function printApiMap(apiMap: ApiMapNode, api: string, format: string) {
+  switch (format) {
+    case 'json':
+      printApiMapJson(apiMap);
+      break;
+    default:
+      logger.info(`Document: ${colors.magenta(api)} map:\n\n`);
+      printApiMapStylish(apiMap);
+  }
+}
diff --git a/packages/cli/src/commands/map/print-map/json.ts b/packages/cli/src/commands/map/print-map/json.ts
new file mode 100644
index 0000000000..a1562bed50
--- /dev/null
+++ b/packages/cli/src/commands/map/print-map/json.ts
@@ -0,0 +1,5 @@
+import { logger, type ApiMapNode } from '@redocly/openapi-core';
+
+export function printApiMapJson(apiMap: ApiMapNode) {
+  logger.output(JSON.stringify(apiMap, null, 2));
+}
diff --git a/packages/cli/src/commands/map/print-map/stylish.ts b/packages/cli/src/commands/map/print-map/stylish.ts
new file mode 100644
index 0000000000..b9540cd125
--- /dev/null
+++ b/packages/cli/src/commands/map/print-map/stylish.ts
@@ -0,0 +1,13 @@
+import { logger, type ApiMapNode } from '@redocly/openapi-core';
+import * as colors from 'colorette';
+
+export function printApiMapStylish(node: ApiMapNode, depth = 0) {
+  const indent = '  '.repeat(depth);
+  const source = node.source ? colors.dim(` (${node.source.file}${node.source.pointer})`) : '';
+  logger.output(
+    `${indent}${node.title} ${colors.dim(node.kind)} ${colors.cyan(node.pointer)}${source}\n`
+  );
+  for (const child of node.nodes) {
+    printApiMapStylish(child, depth + 1);
+  }
+}
diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts
index abfb940d9c..3159d7d88d 100644
--- a/packages/cli/src/index.ts
+++ b/packages/cli/src/index.ts
@@ -22,6 +22,7 @@ import {
 } from './commands/generate-arazzo.js';
 import { handleJoin } from './commands/join/index.js';
 import { handleLint } from './commands/lint.js';
+import { handleMap } from './commands/map/index.js';
 import { PRODUCT_PLANS } from './commands/preview-project/constants.js';
 import { previewProject } from './commands/preview-project/index.js';
 import { handleRespect, type RespectArgv } from './commands/respect/index.js';
@@ -78,6 +79,35 @@ yargs(hideBin(process.argv))
       commandWrapper(handleStats)(argv);
     }
   )
+  .command(
+    'map [api]',
+    'Generate a structural map of an API description.',
+    (yargs) =>
+      yargs
+        .env('REDOCLY_CLI_MAP')
+        .positional('api', { type: 'string' })
+        .option({
+          config: { description: 'Path to the config file.', type: 'string' },
+          'lint-config': {
+            description: 'Severity level for config file linting.',
+            choices: ['warn', 'error', 'off'] as ReadonlyArray<RuleSeverity>,
+            default: 'warn' as RuleSeverity,
+          },
+          format: {
+            description: 'Use a specific output format.',
+            choices: ['stylish', 'json'] as ReadonlyArray<OutputFormat>,
+            default: 'stylish' as OutputFormat,
+          },
+          'source-locations': {
+            description: 'Include the original source file and pointer for each node.',
+            type: 'boolean',
+            default: false,
+          },
+        }),
+    (argv) => {
+      commandWrapper(handleMap)(argv);
+    }
+  )
   .command(
     'score [api]',
     'Score an API description for integration simplicity and agent readiness.',
diff --git a/packages/core/src/api-map/__tests__/build-api-map.test.ts b/packages/core/src/api-map/__tests__/build-api-map.test.ts
new file mode 100644
index 0000000000..46f1780d95
--- /dev/null
+++ b/packages/core/src/api-map/__tests__/build-api-map.test.ts
@@ -0,0 +1,571 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { outdent } from 'outdent';
+
+import { parseYamlToDocument } from '../../../__tests__/utils.js';
+import { createConfig } from '../../config/index.js';
+import { BaseResolver, type Document } from '../../resolve.js';
+import { buildApiMap } from '../build-api-map.js';
+import type { ApiMapNode } from '../types.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+describe('buildApiMap', () => {
+  it('builds an API map mirroring the structure of an OpenAPI 3.0 document', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        openapi: 3.0.0
+        info:
+          title: Redocly Cafe
+          version: 1.0.0
+          description: Manage the cafe menu and orders.
+        servers:
+          - url: https://api.cafe.redocly.com
+        tags:
+          - name: Products
+            description: Operations related to products
+        paths:
+          /menu:
+            get:
+              operationId: listMenuItems
+              summary: List all menu items
+            post:
+              description: Add a menu item.
+          /orders/{orderId}:
+            summary: Single order operations
+            get:
+              operationId: getOrderById
+        components:
+          schemas:
+            MenuItem:
+              description: A menu item.
+            Error: {}
+          parameters: {}
+        x-webhooks:
+          orderStatusChanged:
+            post:
+              operationId: orderStatusChangedWebhook
+      `,
+      'cafe.yaml'
+    );
+
+    const apiMap = await buildApiMap({ document, config: await createConfig({}) });
+
+    expect(apiMap).toEqual({
+      title: 'Redocly Cafe',
+      kind: 'Root',
+      pointer: '#/',
+      nodes: [
+        {
+          title: 'Redocly Cafe',
+          kind: 'Info',
+          pointer: '#/info',
+          summary: 'Manage the cafe menu and orders.',
+          nodes: [],
+        },
+        {
+          title: 'servers',
+          kind: 'ServerList',
+          pointer: '#/servers',
+          nodes: [
+            {
+              title: 'https://api.cafe.redocly.com',
+              kind: 'Server',
+              pointer: '#/servers/0',
+              nodes: [],
+            },
+          ],
+        },
+        {
+          title: 'tags',
+          kind: 'TagList',
+          pointer: '#/tags',
+          nodes: [
+            {
+              title: 'Products',
+              kind: 'Tag',
+              pointer: '#/tags/0',
+              summary: 'Operations related to products',
+              nodes: [],
+            },
+          ],
+        },
+        {
+          title: 'paths',
+          kind: 'Paths',
+          pointer: '#/paths',
+          nodes: [
+            {
+              title: '/menu',
+              kind: 'PathItem',
+              pointer: '#/paths/~1menu',
+              nodes: [
+                {
+                  title: 'listMenuItems',
+                  kind: 'Operation',
+                  pointer: '#/paths/~1menu/get',
+                  summary: 'List all menu items',
+                  method: 'get',
+                  path: '/menu',
+                  nodes: [],
+                },
+                {
+                  title: 'POST /menu',
+                  kind: 'Operation',
+                  pointer: '#/paths/~1menu/post',
+                  summary: 'Add a menu item.',
+                  method: 'post',
+                  path: '/menu',
+                  nodes: [],
+                },
+              ],
+            },
+            {
+              title: '/orders/{orderId}',
+              kind: 'PathItem',
+              pointer: '#/paths/~1orders~1{orderId}',
+              summary: 'Single order operations',
+              nodes: [
+                {
+                  title: 'getOrderById',
+                  kind: 'Operation',
+                  pointer: '#/paths/~1orders~1{orderId}/get',
+                  method: 'get',
+                  path: '/orders/{orderId}',
+                  nodes: [],
+                },
+              ],
+            },
+          ],
+        },
+        {
+          title: 'components',
+          kind: 'Components',
+          pointer: '#/components',
+          nodes: [
+            {
+              title: 'schemas',
+              kind: 'NamedSchemas',
+              pointer: '#/components/schemas',
+              nodes: [
+                {
+                  title: 'MenuItem',
+                  kind: 'Schema',
+                  pointer: '#/components/schemas/MenuItem',
+                  summary: 'A menu item.',
+                  nodes: [],
+                },
+                {
+                  title: 'Error',
+                  kind: 'Schema',
+                  pointer: '#/components/schemas/Error',
+                  nodes: [],
+                },
+              ],
+            },
+          ],
+        },
+        {
+          title: 'x-webhooks',
+          kind: 'WebhooksMap',
+          pointer: '#/x-webhooks',
+          nodes: [
+            {
+              title: 'orderStatusChanged',
+              kind: 'PathItem',
+              pointer: '#/x-webhooks/orderStatusChanged',
+              nodes: [
+                {
+                  title: 'orderStatusChangedWebhook',
+                  kind: 'Operation',
+                  pointer: '#/x-webhooks/orderStatusChanged/post',
+                  method: 'post',
+                  nodes: [],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    });
+  });
+
+  it('truncates long descriptions at a word boundary', async () => {
+    const description = 'word '.repeat(50).trim();
+    const document = parseYamlToDocument(
+      outdent`
+        openapi: 3.0.0
+        info:
+          title: Redocly Cafe
+          version: 1.0.0
+        paths:
+          /menu:
+            get:
+              operationId: listMenuItems
+              description: ${description}
+      `,
+      'cafe.yaml'
+    );
+
+    const apiMap = await buildApiMap({ document, config: await createConfig({}) });
+    const operation = apiMap.nodes.find((n) => n.title === 'paths')!.nodes[0].nodes[0];
+
+    expect(operation.summary).toBeDefined();
+    expect(operation.summary!.length).toBeLessThanOrEqual(203);
+    expect(operation.summary!.endsWith('...')).toBe(true);
+    const words = operation.summary!.slice(0, -3).trim().split(' ');
+    expect(words.every((word) => word === 'word')).toBe(true);
+  });
+
+  it('handles OpenAPI 3.1 webhooks and pathItems and excludes $defs', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        openapi: 3.1.0
+        info:
+          title: Redocly Cafe
+          version: 1.0.0
+        webhooks:
+          newOrder:
+            post:
+              operationId: onNewOrder
+        components:
+          pathItems:
+            OrderPath:
+              get:
+                operationId: sharedGet
+          schemas:
+            Order:
+              $defs:
+                Status:
+                  type: string
+      `,
+      'cafe.yaml'
+    );
+
+    const apiMap = await buildApiMap({ document, config: await createConfig({}) });
+    const webhooks = apiMap.nodes.find((n) => n.title === 'webhooks');
+    const components = apiMap.nodes.find((n) => n.title === 'components');
+
+    expect(webhooks).toEqual({
+      title: 'webhooks',
+      kind: 'WebhooksMap',
+      pointer: '#/webhooks',
+      nodes: [
+        {
+          title: 'newOrder',
+          kind: 'PathItem',
+          pointer: '#/webhooks/newOrder',
+          nodes: [
+            {
+              title: 'onNewOrder',
+              kind: 'Operation',
+              pointer: '#/webhooks/newOrder/post',
+              method: 'post',
+              nodes: [],
+            },
+          ],
+        },
+      ],
+    });
+    expect(components).toEqual({
+      title: 'components',
+      kind: 'Components',
+      pointer: '#/components',
+      nodes: [
+        {
+          title: 'schemas',
+          kind: 'NamedSchemas',
+          pointer: '#/components/schemas',
+          nodes: [
+            {
+              title: 'Order',
+              kind: 'Schema',
+              pointer: '#/components/schemas/Order',
+              nodes: [],
+            },
+          ],
+        },
+        {
+          title: 'pathItems',
+          kind: 'NamedPathItems',
+          pointer: '#/components/pathItems',
+          nodes: [
+            {
+              title: 'OrderPath',
+              kind: 'PathItem',
+              pointer: '#/components/pathItems/OrderPath',
+              nodes: [],
+            },
+          ],
+        },
+      ],
+    });
+  });
+
+  it('builds an API map for an OpenAPI 2.0 document', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        swagger: '2.0'
+        info:
+          title: Legacy Cafe API
+          version: '1.0'
+        paths:
+          /orders:
+            get:
+              operationId: listOrders
+        definitions:
+          Order:
+            description: A customer order.
+        parameters:
+          limitParam:
+            name: limit
+            in: query
+        responses:
+          NotFound:
+            description: Not found
+        securityDefinitions:
+          api_key:
+            type: apiKey
+            name: key
+            in: header
+      `,
+      'cafe.yaml'
+    );
+
+    const apiMap = await buildApiMap({ document, config: await createConfig({}) });
+
+    expect(apiMap).toEqual({
+      title: 'Legacy Cafe API',
+      kind: 'Root',
+      pointer: '#/',
+      nodes: [
+        {
+          title: 'Legacy Cafe API',
+          kind: 'Info',
+          pointer: '#/info',
+          nodes: [],
+        },
+        {
+          title: 'paths',
+          kind: 'Paths',
+          pointer: '#/paths',
+          nodes: [
+            {
+              title: '/orders',
+              kind: 'PathItem',
+              pointer: '#/paths/~1orders',
+              nodes: [
+                {
+                  title: 'listOrders',
+                  kind: 'Operation',
+                  pointer: '#/paths/~1orders/get',
+                  method: 'get',
+                  path: '/orders',
+                  nodes: [],
+                },
+              ],
+            },
+          ],
+        },
+        {
+          title: 'definitions',
+          kind: 'NamedSchemas',
+          pointer: '#/definitions',
+          nodes: [
+            {
+              title: 'Order',
+              kind: 'Schema',
+              pointer: '#/definitions/Order',
+              summary: 'A customer order.',
+              nodes: [],
+            },
+          ],
+        },
+        {
+          title: 'parameters',
+          kind: 'NamedParameters',
+          pointer: '#/parameters',
+          nodes: [
+            {
+              title: 'limitParam',
+              kind: 'Parameter',
+              pointer: '#/parameters/limitParam',
+              nodes: [],
+            },
+          ],
+        },
+        {
+          title: 'responses',
+          kind: 'NamedResponses',
+          pointer: '#/responses',
+          nodes: [
+            {
+              title: 'NotFound',
+              kind: 'Response',
+              pointer: '#/responses/NotFound',
+              summary: 'Not found',
+              nodes: [],
+            },
+          ],
+        },
+        {
+          title: 'securityDefinitions',
+          kind: 'NamedSecuritySchemes',
+          pointer: '#/securityDefinitions',
+          nodes: [
+            {
+              title: 'api_key',
+              kind: 'SecurityScheme',
+              pointer: '#/securityDefinitions/api_key',
+              nodes: [],
+            },
+          ],
+        },
+      ],
+    });
+  });
+
+  it('keeps canonical pointers across files and adds source locations when enabled', async () => {
+    const fixturesDir = path.join(__dirname, 'fixtures/multi-file');
+    const externalRefResolver = new BaseResolver();
+    const document = (await externalRefResolver.resolveDocument(
+      null,
+      path.join(fixturesDir, 'openapi.yaml'),
+      true
+    )) as Document;
+
+    const apiMap = await buildApiMap({
+      document,
+      config: await createConfig({}),
+      externalRefResolver,
+      sourceLocations: true,
+    });
+
+    const relativizeSources = (node: ApiMapNode) => {
+      if (node.source) {
+        node.source = { ...node.source, file: path.relative(fixturesDir, node.source.file) };
+      }
+      node.nodes.forEach(relativizeSources);
+    };
+    relativizeSources(apiMap);
+
+    const paths = apiMap.nodes.find((n) => n.title === 'paths')!;
+    expect(paths.nodes).toEqual([
+      {
+        title: '/menu',
+        kind: 'PathItem',
+        pointer: '#/paths/~1menu',
+        source: { file: 'paths/menu.yaml', pointer: '#/' },
+        nodes: [
+          {
+            title: 'listMenuItems',
+            kind: 'Operation',
+            pointer: '#/paths/~1menu/get',
+            method: 'get',
+            path: '/menu',
+            source: { file: 'paths/menu.yaml', pointer: '#/get' },
+            nodes: [],
+          },
+        ],
+      },
+      {
+        title: '/menu-archive',
+        kind: 'PathItem',
+        pointer: '#/paths/~1menu-archive',
+        source: { file: 'paths/menu.yaml', pointer: '#/' },
+        nodes: [
+          {
+            title: 'listMenuItems',
+            kind: 'Operation',
+            pointer: '#/paths/~1menu-archive/get',
+            method: 'get',
+            path: '/menu-archive',
+            source: { file: 'paths/menu.yaml', pointer: '#/get' },
+            nodes: [],
+          },
+        ],
+      },
+    ]);
+
+    const schemas = apiMap.nodes.find((n) => n.title === 'components')!.nodes[0];
+    expect(schemas.nodes).toEqual([
+      {
+        title: 'MenuItem',
+        kind: 'Schema',
+        pointer: '#/components/schemas/MenuItem',
+        summary: 'A menu item.',
+        source: { file: 'components/menu-item.yaml', pointer: '#/' },
+        nodes: [],
+      },
+    ]);
+  });
+
+  it('excludes callback path items and nested schemas', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        openapi: 3.0.0
+        info:
+          title: Redocly Cafe
+          version: 1.0.0
+        paths:
+          /orders:
+            post:
+              operationId: createOrder
+              callbacks:
+                onStatusChange:
+                  '{$request.body#/callbackUrl}':
+                    post:
+                      operationId: statusChangeCallback
+              requestBody:
+                content:
+                  application/json:
+                    schema:
+                      type: object
+                      properties:
+                        nested:
+                          type: object
+      `,
+      'cafe.yaml'
+    );
+
+    const apiMap = await buildApiMap({ document, config: await createConfig({}) });
+    const paths = apiMap.nodes.find((n) => n.title === 'paths')!;
+
+    expect(paths.nodes).toEqual([
+      {
+        title: '/orders',
+        kind: 'PathItem',
+        pointer: '#/paths/~1orders',
+        nodes: [
+          {
+            title: 'createOrder',
+            kind: 'Operation',
+            pointer: '#/paths/~1orders/post',
+            method: 'post',
+            path: '/orders',
+            nodes: [],
+          },
+        ],
+      },
+    ]);
+    expect(JSON.stringify(apiMap)).not.toContain('statusChangeCallback');
+  });
+
+  it('throws for unsupported spec versions', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        arazzo: 1.0.1
+        info:
+          title: Cafe Workflows
+          version: 1.0.0
+        sourceDescriptions: []
+        workflows: []
+      `,
+      'cafe-workflows.yaml'
+    );
+
+    await expect(buildApiMap({ document, config: await createConfig({}) })).rejects.toThrow(
+      'Unsupported spec version'
+    );
+  });
+});
diff --git a/packages/core/src/api-map/__tests__/fixtures/multi-file/components/menu-item.yaml b/packages/core/src/api-map/__tests__/fixtures/multi-file/components/menu-item.yaml
new file mode 100644
index 0000000000..5bb358faf8
--- /dev/null
+++ b/packages/core/src/api-map/__tests__/fixtures/multi-file/components/menu-item.yaml
@@ -0,0 +1,2 @@
+type: object
+description: A menu item.
diff --git a/packages/core/src/api-map/__tests__/fixtures/multi-file/openapi.yaml b/packages/core/src/api-map/__tests__/fixtures/multi-file/openapi.yaml
new file mode 100644
index 0000000000..05aa4ba70c
--- /dev/null
+++ b/packages/core/src/api-map/__tests__/fixtures/multi-file/openapi.yaml
@@ -0,0 +1,13 @@
+openapi: 3.0.0
+info:
+  title: Redocly Cafe
+  version: 1.0.0
+paths:
+  /menu:
+    $ref: ./paths/menu.yaml
+  /menu-archive:
+    $ref: ./paths/menu.yaml
+components:
+  schemas:
+    MenuItem:
+      $ref: ./components/menu-item.yaml
diff --git a/packages/core/src/api-map/__tests__/fixtures/multi-file/paths/menu.yaml b/packages/core/src/api-map/__tests__/fixtures/multi-file/paths/menu.yaml
new file mode 100644
index 0000000000..33236c260c
--- /dev/null
+++ b/packages/core/src/api-map/__tests__/fixtures/multi-file/paths/menu.yaml
@@ -0,0 +1,2 @@
+get:
+  operationId: listMenuItems
diff --git a/packages/core/src/api-map/async.ts b/packages/core/src/api-map/async.ts
new file mode 100644
index 0000000000..bddab94c5b
--- /dev/null
+++ b/packages/core/src/api-map/async.ts
@@ -0,0 +1,65 @@
+import type { Async2Visitor, Async3Visitor } from '../visitors.js';
+import { createApiMapHooks } from './hooks.js';
+import type { ApiMapNode, ApiMapOptions } from './types.js';
+
+export function ApiMapAsync2(root: ApiMapNode, opts: ApiMapOptions): Async2Visitor {
+  const { rootHooks, sectionHooks, containerHooks, operationHooks, leafHooks } = createApiMapHooks(
+    root,
+    opts
+  );
+
+  return {
+    Root: rootHooks,
+    Info: leafHooks('title'),
+    ServerMap: {
+      ...sectionHooks('Root'),
+      Server: leafHooks(),
+    },
+    TagList: {
+      ...sectionHooks('Root'),
+      Tag: leafHooks('name'),
+    },
+    ChannelMap: {
+      ...sectionHooks('Root'),
+      Channel: {
+        ...containerHooks,
+        Operation: operationHooks({}),
+      },
+    },
+    Components: {
+      ...sectionHooks('Root'),
+      NamedSchemas: { ...sectionHooks('Components'), Schema: leafHooks() },
+      NamedMessages: { ...sectionHooks('Components'), Message: leafHooks('title') },
+      NamedParameters: { ...sectionHooks('Components'), Parameter: leafHooks() },
+      NamedSecuritySchemes: { ...sectionHooks('Components'), SecurityScheme: leafHooks() },
+    },
+  };
+}
+
+export function ApiMapAsync3(root: ApiMapNode, opts: ApiMapOptions): Async3Visitor {
+  const { rootHooks, sectionHooks, leafHooks } = createApiMapHooks(root, opts);
+
+  return {
+    Root: rootHooks,
+    Info: leafHooks('title'),
+    ServerMap: {
+      ...sectionHooks('Root'),
+      Server: leafHooks(),
+    },
+    NamedChannels: {
+      ...sectionHooks('Root'),
+      Channel: leafHooks('title'),
+    },
+    NamedOperations: {
+      ...sectionHooks('Root'),
+      Operation: leafHooks('title'),
+    },
+    Components: {
+      ...sectionHooks('Root'),
+      NamedSchemas: { ...sectionHooks('Components'), Schema: leafHooks() },
+      NamedMessages: { ...sectionHooks('Components'), Message: leafHooks('title') },
+      NamedParameters: { ...sectionHooks('Components'), Parameter: leafHooks() },
+      NamedSecuritySchemes: { ...sectionHooks('Components'), SecurityScheme: leafHooks() },
+    },
+  };
+}
diff --git a/packages/core/src/api-map/build-api-map.ts b/packages/core/src/api-map/build-api-map.ts
new file mode 100644
index 0000000000..0a6a4498ae
--- /dev/null
+++ b/packages/core/src/api-map/build-api-map.ts
@@ -0,0 +1,89 @@
+import type { Config } from '../config/index.js';
+import { detectSpec } from '../detect-spec.js';
+import { getTypes } from '../oas-types.js';
+import { BaseResolver, resolveDocument, type Document } from '../resolve.js';
+import { normalizeTypes } from '../types/index.js';
+import {
+  normalizeVisitors,
+  type Async2Visitor,
+  type Async3Visitor,
+  type NestedVisitObject,
+  type Oas2Visitor,
+  type Oas3Visitor,
+} from '../visitors.js';
+import { walkDocument, type WalkContext } from '../walk.js';
+import { ApiMapAsync2, ApiMapAsync3 } from './async.js';
+import { ApiMapOAS2, ApiMapOAS3 } from './oas.js';
+import type { ApiMapNode } from './types.js';
+
+export async function buildApiMap({
+  document,
+  config,
+  externalRefResolver = new BaseResolver(config.resolve),
+  sourceLocations = false,
+}: {
+  document: Document;
+  config: Config;
+  externalRefResolver?: BaseResolver;
+  sourceLocations?: boolean;
+}): Promise<ApiMapNode> {
+  const specVersion = detectSpec(document.parsed);
+  const root: ApiMapNode = {
+    title: 'API',
+    kind: 'Root',
+    pointer: '#/',
+    ...(sourceLocations && { source: { file: document.source.absoluteRef, pointer: '#/' } }),
+    nodes: [],
+  };
+
+  let visitor: NestedVisitObject<
+    unknown,
+    Oas3Visitor | Oas2Visitor | Async2Visitor | Async3Visitor
+  >;
+  switch (specVersion) {
+    case 'oas2':
+      visitor = ApiMapOAS2(root, { sourceLocations });
+      break;
+    case 'oas3_0':
+    case 'oas3_1':
+    case 'oas3_2':
+      visitor = ApiMapOAS3(root, { sourceLocations });
+      break;
+    case 'async2':
+      visitor = ApiMapAsync2(root, { sourceLocations });
+      break;
+    case 'async3':
+      visitor = ApiMapAsync3(root, { sourceLocations });
+      break;
+    default:
+      throw new Error(`Unsupported spec version for API map generation: ${specVersion}`);
+  }
+
+  const types = normalizeTypes(config.extendTypes(getTypes(specVersion), specVersion), config);
+
+  const resolvedRefMap = await resolveDocument({
+    rootDocument: document,
+    rootType: types.Root,
+    externalRefResolver,
+  });
+
+  const ctx: WalkContext = {
+    problems: [],
+    specVersion,
+    config,
+    visitorsData: {},
+  };
+
+  walkDocument({
+    document,
+    rootType: types.Root,
+    normalizedVisitors: normalizeVisitors(
+      [{ severity: 'warn', ruleId: 'api-map', visitor }],
+      types
+    ),
+    resolvedRefMap,
+    ctx,
+  });
+
+  return root;
+}
diff --git a/packages/core/src/api-map/hooks.ts b/packages/core/src/api-map/hooks.ts
new file mode 100644
index 0000000000..77ff54465c
--- /dev/null
+++ b/packages/core/src/api-map/hooks.ts
@@ -0,0 +1,117 @@
+import { escapePointerFragment } from '../ref-utils.js';
+import { isPlainObject } from '../utils/is-plain-object.js';
+import type { UserContext } from '../walk.js';
+import type { ApiMapNode, ApiMapOptions } from './types.js';
+
+const SUMMARY_MAX_LENGTH = 200;
+
+export function getStringProp(node: unknown, key: string): string | undefined {
+  if (!isPlainObject(node)) return undefined;
+  const value = node[key];
+  return typeof value === 'string' && value ? value : undefined;
+}
+
+function makeSummary(node: unknown): string | undefined {
+  const summary = getStringProp(node, 'summary');
+  if (summary) return summary;
+  const description = getStringProp(node, 'description');
+  if (!description) return undefined;
+  if (description.length <= SUMMARY_MAX_LENGTH) return description;
+  return description.slice(0, SUMMARY_MAX_LENGTH).replace(/\s+\S*$/, '') + '...';
+}
+
+export function createApiMapHooks(root: ApiMapNode, opts: ApiMapOptions) {
+  const stack: { obj: unknown; node: ApiMapNode }[] = [];
+  const top = () => stack[stack.length - 1];
+  const isDirectChild = (ctx: UserContext) => stack.length > 0 && ctx.parent === top().obj;
+
+  function addNode(
+    init: Pick<ApiMapNode, 'title' | 'summary' | 'method' | 'path'>,
+    ctx: UserContext
+  ): ApiMapNode {
+    const parentNode = top().node;
+    const fragment = escapePointerFragment(String(ctx.key));
+    const node: ApiMapNode = {
+      title: init.title,
+      kind: ctx.type.name,
+      pointer: parentNode.pointer === '#/' ? `#/${fragment}` : `${parentNode.pointer}/${fragment}`,
+      ...(init.summary && { summary: init.summary }),
+      ...(init.method && { method: init.method }),
+      ...(init.path && { path: init.path }),
+      ...(opts.sourceLocations && {
+        source: { file: ctx.location.source.absoluteRef, pointer: ctx.location.pointer },
+      }),
+      nodes: [],
+    };
+    parentNode.nodes.push(node);
+    return node;
+  }
+
+  const rootHooks = {
+    enter(node: unknown) {
+      root.title = getStringProp(isPlainObject(node) ? node.info : undefined, 'title') ?? 'API';
+      stack.push({ obj: node, node: root });
+    },
+  };
+
+  function sectionHooks(parentTypeName: string) {
+    return {
+      enter(node: unknown, ctx: UserContext) {
+        if (!isDirectChild(ctx) || top().node.kind !== parentTypeName) return;
+        const section = addNode({ title: String(ctx.key) }, ctx);
+        stack.push({ obj: node, node: section });
+      },
+      leave(node: unknown) {
+        if (top()?.obj !== node) return;
+        const { node: section } = stack.pop()!;
+        if (section.nodes.length === 0) {
+          const siblings = top().node.nodes;
+          siblings.splice(siblings.indexOf(section), 1);
+        }
+      },
+    };
+  }
+
+  const containerHooks = {
+    enter(node: unknown, ctx: UserContext) {
+      if (!isDirectChild(ctx)) return;
+      const container = addNode({ title: String(ctx.key), summary: makeSummary(node) }, ctx);
+      stack.push({ obj: node, node: container });
+    },
+    leave(node: unknown) {
+      if (top()?.obj === node) stack.pop();
+    },
+  };
+
+  function operationHooks(fields: { method?: boolean; path?: boolean }) {
+    return {
+      enter(operation: unknown, ctx: UserContext) {
+        if (!isDirectChild(ctx)) return;
+        const parentNode = top().node;
+        const key = String(ctx.key);
+        addNode(
+          {
+            title:
+              getStringProp(operation, 'operationId') ?? `${key.toUpperCase()} ${parentNode.title}`,
+            summary: makeSummary(operation),
+            method: fields.method ? key : undefined,
+            path: fields.path ? parentNode.title : undefined,
+          },
+          ctx
+        );
+      },
+    };
+  }
+
+  function leafHooks(titleProp?: string) {
+    return {
+      enter(node: unknown, ctx: UserContext) {
+        if (!isDirectChild(ctx)) return;
+        const title = titleProp && getStringProp(node, titleProp);
+        addNode({ title: title || String(ctx.key), summary: makeSummary(node) }, ctx);
+      },
+    };
+  }
+
+  return { rootHooks, sectionHooks, containerHooks, operationHooks, leafHooks };
+}
diff --git a/packages/core/src/api-map/oas.ts b/packages/core/src/api-map/oas.ts
new file mode 100644
index 0000000000..f6d674f3ae
--- /dev/null
+++ b/packages/core/src/api-map/oas.ts
@@ -0,0 +1,78 @@
+import type { Oas2Visitor, Oas3Visitor } from '../visitors.js';
+import { createApiMapHooks } from './hooks.js';
+import type { ApiMapNode, ApiMapOptions } from './types.js';
+
+export function ApiMapOAS3(root: ApiMapNode, opts: ApiMapOptions): Oas3Visitor {
+  const { rootHooks, sectionHooks, containerHooks, operationHooks, leafHooks } = createApiMapHooks(
+    root,
+    opts
+  );
+
+  return {
+    Root: rootHooks,
+    Info: leafHooks('title'),
+    ServerList: {
+      ...sectionHooks('Root'),
+      Server: leafHooks('url'),
+    },
+    TagList: {
+      ...sectionHooks('Root'),
+      Tag: leafHooks('name'),
+    },
+    Paths: {
+      ...sectionHooks('Root'),
+      PathItem: {
+        ...containerHooks,
+        Operation: operationHooks({ method: true, path: true }),
+      },
+    },
+    WebhooksMap: {
+      ...sectionHooks('Root'),
+      PathItem: {
+        ...containerHooks,
+        Operation: operationHooks({ method: true }),
+      },
+    },
+    Components: {
+      ...sectionHooks('Root'),
+      NamedSchemas: { ...sectionHooks('Components'), Schema: leafHooks() },
+      NamedResponses: { ...sectionHooks('Components'), Response: leafHooks() },
+      NamedParameters: { ...sectionHooks('Components'), Parameter: leafHooks() },
+      NamedExamples: { ...sectionHooks('Components'), Example: leafHooks() },
+      NamedRequestBodies: { ...sectionHooks('Components'), RequestBody: leafHooks() },
+      NamedHeaders: { ...sectionHooks('Components'), Header: leafHooks() },
+      NamedSecuritySchemes: { ...sectionHooks('Components'), SecurityScheme: leafHooks() },
+      NamedLinks: { ...sectionHooks('Components'), Link: leafHooks() },
+      NamedCallbacks: { ...sectionHooks('Components'), Callback: leafHooks() },
+      NamedPathItems: { ...sectionHooks('Components'), PathItem: containerHooks },
+      NamedMediaTypes: { ...sectionHooks('Components'), MediaTypesMap: leafHooks() },
+    },
+  };
+}
+
+export function ApiMapOAS2(root: ApiMapNode, opts: ApiMapOptions): Oas2Visitor {
+  const { rootHooks, sectionHooks, containerHooks, operationHooks, leafHooks } = createApiMapHooks(
+    root,
+    opts
+  );
+
+  return {
+    Root: rootHooks,
+    Info: leafHooks('title'),
+    TagList: {
+      ...sectionHooks('Root'),
+      Tag: leafHooks('name'),
+    },
+    Paths: {
+      ...sectionHooks('Root'),
+      PathItem: {
+        ...containerHooks,
+        Operation: operationHooks({ method: true, path: true }),
+      },
+    },
+    NamedSchemas: { ...sectionHooks('Root'), Schema: leafHooks() },
+    NamedParameters: { ...sectionHooks('Root'), Parameter: leafHooks() },
+    NamedResponses: { ...sectionHooks('Root'), Response: leafHooks() },
+    NamedSecuritySchemes: { ...sectionHooks('Root'), SecurityScheme: leafHooks() },
+  };
+}
diff --git a/packages/core/src/api-map/types.ts b/packages/core/src/api-map/types.ts
new file mode 100644
index 0000000000..318b1661d2
--- /dev/null
+++ b/packages/core/src/api-map/types.ts
@@ -0,0 +1,19 @@
+export type ApiMapNodeSource = {
+  file: string;
+  pointer: string;
+};
+
+export type ApiMapNode = {
+  title: string;
+  kind: string;
+  pointer: string;
+  summary?: string;
+  method?: string;
+  path?: string;
+  source?: ApiMapNodeSource;
+  nodes: ApiMapNode[];
+};
+
+export type ApiMapOptions = {
+  sourceLocations?: boolean;
+};
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 401bc33d5a..4b23f96536 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -123,6 +123,8 @@ export {
 export { lint, lint as validate, lintDocument, lintFromString, lintConfig } from './lint.js';
 export { lintEntityFile, lintEntityWithScorecardLevel, lintSchema } from './lint-entity.js';
 export { bundle, bundleFromString, type BundleResult } from './bundle/bundle.js';
+export { buildApiMap } from './api-map/build-api-map.js';
+export type { ApiMapNode, ApiMapNodeSource } from './api-map/types.js';
 export { bundleDocument, type ComponentNamesStrategy } from './bundle/bundle-document.js';
 export { mapTypeToComponent } from './bundle/bundle-visitor.js';
 export { type Assertions, type Assertion } from './rules/common/assertions/index.js';
diff --git a/packages/core/src/visitors.ts b/packages/core/src/visitors.ts
index 5bb36b70a0..2b9f58c95a 100644
--- a/packages/core/src/visitors.ts
+++ b/packages/core/src/visitors.ts
@@ -218,6 +218,7 @@ type Oas3FlatVisitor = {
   NamedSecuritySchemes?: VisitFunctionOrObject<Record<string, Oas3SecurityScheme>>;
   NamedLinks?: VisitFunctionOrObject<Record<string, Oas3Link>>;
   NamedCallbacks?: VisitFunctionOrObject<Record<string, Oas3Callback<Oas3Schema | Oas3_1Schema>>>;
+  NamedPathItems?: VisitFunctionOrObject<Record<string, Oas3PathItem<Oas3Schema | Oas3_1Schema>>>;
   NamedMediaTypes?: VisitFunctionOrObject<Record<string, Oas3MediaType<Oas3Schema | Oas3_1Schema>>>;
 
   ImplicitFlow?: VisitFunctionOrObject<NonNullable<OAuth2Auth['flows']['implicit']>>;
@@ -262,11 +263,42 @@ type Oas2FlatVisitor = {
 type Async2FlatVisitor = {
   Root?: VisitFunctionOrObject<Async2Definition>;
   Schema?: VisitFunctionOrObject<Oas3_1Schema>;
+  Info?: VisitFunctionOrObject<any>;
+  ServerMap?: VisitFunctionOrObject<Record<string, any>>;
+  Server?: VisitFunctionOrObject<any>;
+  TagList?: VisitFunctionOrObject<any[]>;
+  Tag?: VisitFunctionOrObject<any>;
+  ChannelMap?: VisitFunctionOrObject<Record<string, any>>;
+  Channel?: VisitFunctionOrObject<any>;
+  Operation?: VisitFunctionOrObject<any>;
+  Components?: VisitFunctionOrObject<any>;
+  NamedSchemas?: VisitFunctionOrObject<Record<string, Oas3_1Schema>>;
+  NamedMessages?: VisitFunctionOrObject<Record<string, any>>;
+  Message?: VisitFunctionOrObject<any>;
+  NamedParameters?: VisitFunctionOrObject<Record<string, any>>;
+  Parameter?: VisitFunctionOrObject<any>;
+  NamedSecuritySchemes?: VisitFunctionOrObject<Record<string, any>>;
+  SecurityScheme?: VisitFunctionOrObject<any>;
 };
 
 type Async3FlatVisitor = {
   Root?: VisitFunctionOrObject<Async3Definition>;
   Schema?: VisitFunctionOrObject<Oas3_1Schema>;
+  Info?: VisitFunctionOrObject<any>;
+  ServerMap?: VisitFunctionOrObject<Record<string, any>>;
+  Server?: VisitFunctionOrObject<any>;
+  NamedChannels?: VisitFunctionOrObject<Record<string, any>>;
+  Channel?: VisitFunctionOrObject<any>;
+  NamedOperations?: VisitFunctionOrObject<Record<string, any>>;
+  Operation?: VisitFunctionOrObject<any>;
+  Components?: VisitFunctionOrObject<any>;
+  NamedSchemas?: VisitFunctionOrObject<Record<string, Oas3_1Schema>>;
+  NamedMessages?: VisitFunctionOrObject<Record<string, any>>;
+  Message?: VisitFunctionOrObject<any>;
+  NamedParameters?: VisitFunctionOrObject<Record<string, any>>;
+  Parameter?: VisitFunctionOrObject<any>;
+  NamedSecuritySchemes?: VisitFunctionOrObject<Record<string, any>>;
+  SecurityScheme?: VisitFunctionOrObject<any>;
 };
 
 type ArazzoFlatVisitor = {
diff --git a/tests/e2e/map/map-async2-stylish/async.yaml b/tests/e2e/map/map-async2-stylish/async.yaml
new file mode 100644
index 0000000000..41f5a20326
--- /dev/null
+++ b/tests/e2e/map/map-async2-stylish/async.yaml
@@ -0,0 +1,606 @@
+asyncapi: '2.6.0'
+id: 'urn:com:smartylighting:streetlights:server'
+info:
+  title: Streetlights API
+  version: '1.0.0'
+  description: |
+    The Smartylighting Streetlights API allows you to remotely manage the city lights.
+
+    ### Check out its awesome features:
+
+    * Turn a specific streetlight on/off 🌃
+    * Dim a specific streetlight 😎
+    * Receive real-time information about environmental lighting conditions 📈
+
+  termsOfService: http://asyncapi.org/terms/
+  contact:
+    name: API Support
+    url: http://www.asyncapi.org/support
+    email: support@asyncapi.org
+  license:
+    name: Apache 2.0
+    url: http://www.apache.org/licenses/LICENSE-2.0.html
+tags:
+  - name: root-tag1
+    externalDocs:
+      description: External docs description 1
+      url: https://www.asyncapi.com/
+  - name: root-tag2
+    description: Description 2
+    externalDocs:
+      url: 'https://www.asyncapi.com/'
+  - name: root-tag3
+  - name: root-tag4
+    description: Description 4
+  - name: root-tag5
+    externalDocs:
+      url: 'https://www.asyncapi.com/'
+externalDocs:
+  description: Find more info here
+  url: https://example.com
+defaultContentType: application/json
+
+servers:
+  production:
+    url: api.streetlights.smartylighting.com:{port}
+    protocol: mqtt
+    description: |
+      Private server that requires authorization.
+      Once the socket is open you can subscribe to private-data channels by sending an authenticated subscribe request message.
+
+      The API client must request an authentication "token" via the following REST API endpoint "GetWebSocketsToken" to connect to WebSockets Private endpoints. For more details read https://support.kraken.com/hc/en-us/articles/360034437672-How-to-retrieve-a-WebSocket-authentication-token-Example-code-in-Python-3
+
+      The resulting token must be provided in the "token" field of any new private WebSocket feed subscription:
+      ```json
+      {
+        "event": "subscribe",
+        "subscription":
+        {
+          "name": "ownTrades",
+          "token": "WW91ciBhdXRoZW50aWNhdGlvbiB0b2tlbiBnb2VzIGhlcmUu"
+        }
+      }
+      ```
+
+      ```elixir
+      defmodule Hello do
+        def world do
+          IO.puts("hello")
+        end
+      end
+      ```
+    variables:
+      port:
+        description: Secure connection (TLS) is available through port 8883.
+        default: '1883'
+        enum:
+          - '1883'
+          - '8883'
+    tags:
+      - name: 'env:production'
+    security:
+      - apiKey: []
+      - supportedOauthFlows:
+          - streetlights:on
+          - streetlights:off
+          - streetlights:dim
+      - openIdConnectWellKnown: []
+  dummy-mqtt:
+    url: mqtt://localhost
+    protocol: mqtt
+    description: |
+      Private server
+
+      ```csharp
+      using System;
+
+      namespace HelloWorld
+      {
+        class Program
+        {
+          static void Main(string[] args)
+          {
+            Console.WriteLine("Hello World!");
+          }
+        }
+      }
+      ```
+    bindings:
+      mqtt:
+        clientId: guest
+        cleanSession: false
+        keepAlive: 60
+        bindingVersion: 0.1.0
+        lastWill:
+          topic: smartylighting/streetlights/1/0/lastwill
+          qos: 1
+          message: so long and thanks for all the fish
+          retain: false
+  dummy-amqp:
+    url: amqp://localhost:{port}
+    protocol: amqp
+    description: dummy AMQP broker
+    protocolVersion: '0.9.1'
+    variables:
+      port:
+        enum:
+          - '15672'
+          - '5672'
+  dommy-kafka:
+    url: http://localhost:{port}
+    protocol: kafka
+    description: dummy Kafka broker
+    variables:
+      port:
+        default: '9092'
+
+channels:
+  smartylighting/streetlights/1/0/event/{streetlightId}/lighting/measured:
+    x-security:
+      $ref: '#/components/securitySchemes/supportedOauthFlows/flows/clientCredentials'
+    description: The topic on which measured values may be produced and consumed.
+    parameters:
+      streetlightId:
+        $ref: '#/components/parameters/streetlightId'
+    servers:
+      - production
+      - dommy-kafka
+    subscribe:
+      summary: Receive information about environmental lighting conditions of a particular streetlight.
+      operationId: receiveLightMeasurement
+      externalDocs:
+        description: Find more info here
+        url: https://example.com
+      traits:
+        - $ref: '#/components/operationTraits/kafka'
+      message:
+        $ref: '#/components/messages/lightMeasured'
+      bindings:
+        mqtt:
+          qos: 1
+          bindingVersion: 0.1.0
+        http:
+          type: request
+          method: GET
+          query:
+            type: object
+            required:
+              - companyId
+            properties:
+              companyId:
+                type: number
+                minimum: 1
+                description: The Id of the company.
+            additionalProperties: false
+
+  smartylighting/streetlights/1/0/action/{streetlightId}/turn/on/:
+    parameters:
+      streetlightId:
+        $ref: '#/components/parameters/streetlightId'
+    servers:
+      - production
+      - dummy-amqp
+    publish:
+      operationId: turnOn
+      security:
+        - supportedOauthFlows:
+            - streetlights:on
+      externalDocs:
+        description: Find more info here
+        url: https://example.com
+      traits:
+        - $ref: '#/components/operationTraits/kafka'
+      message:
+        $ref: '#/components/messages/turnOnOff'
+
+  smartylighting/streetlights/1/0/action/{streetlightId}/turn/off:
+    parameters:
+      streetlightId:
+        $ref: '#/components/parameters/streetlightId'
+    publish:
+      traits:
+        - $ref: '#/components/operationTraits/kafka'
+      message:
+        $ref: '#/components/messages/turnOnOff'
+
+  smartylighting/streetlights/1/0/action/{streetlightId}/dim:
+    parameters:
+      streetlightId:
+        $ref: '#/components/parameters/streetlightId'
+    servers:
+      - production
+      - dummy-amqp
+    publish:
+      operationId: dimLight
+      traits:
+        - $ref: '#/components/operationTraits/kafka'
+      message:
+        $ref: '#/components/messages/dimLight'
+
+components:
+  messages:
+    lightMeasured:
+      messageId: lightMeasured Message ID
+      name: lightMeasured
+      title: Light measured
+      summary: Inform about environmental lighting conditions for a particular streetlight.
+      contentType: application/json
+      correlationId:
+        $ref: '#/components/correlationIds/sentAtCorrelator'
+      externalDocs:
+        url: 'https://www.asyncapi.com/'
+      traits:
+        - $ref: '#/components/messageTraits/commonHeaders'
+      payload:
+        $ref: '#/components/schemas/lightMeasuredPayload'
+      bindings:
+        mqtt:
+          bindingVersion: 0.1.0
+      examples:
+        - headers:
+            my-app-header: 12
+          payload:
+            lumens: 1
+            sentAt: '2020-01-31T13:24:53Z'
+        - headers:
+            my-app-header: 13
+        - payload:
+            lumens: 3
+            sentAt: '2020-10-31T13:24:53Z'
+      x-schema-extensions-as-object:
+        type: object
+        properties:
+          prop1:
+            type: string
+          prop2:
+            type: integer
+            minimum: 0
+      x-schema-extensions-as-primitive: dummy
+      x-schema-extensions-as-array:
+        - 'item1'
+        - 'item2'
+    LwM2mOjbects:
+      payload:
+        type: object
+        properties:
+          objectLinks:
+            type: string
+        example:
+          objectLinks: 'lwm2m=1.1, </0/0>, </1/1>;ssid=1, </2>, </3/0>'
+    turnOnOff:
+      # name: turnOnOff
+      title: Turn on/off
+      summary: Command a particular streetlight to turn the lights on or off.
+      payload:
+        $ref: '#/components/schemas/turnOnOffPayload'
+      headers:
+        type: object
+        properties:
+          $ref: '#/components/schemas/streamHeaders'
+    dimLight:
+      name: dimLight
+      title: Dim light
+      summary: Command a particular streetlight to dim the lights.
+      correlationId:
+        $ref: '#/components/correlationIds/sentAtCorrelator'
+      externalDocs:
+        url: 'https://www.asyncapi.com/'
+      tags:
+        - name: oparation-tag1
+          externalDocs:
+            description: External docs description 1
+            url: https://www.asyncapi.com/
+        - name: oparation-tag2
+          description: Description 2
+          externalDocs:
+            url: 'https://www.asyncapi.com/'
+        - name: oparation-tag3
+        - name: oparation-tag4
+          description: Description 4
+        - name: oparation-tag5
+          externalDocs:
+            url: 'https://www.asyncapi.com/'
+      traits:
+        - $ref: '#/components/messageTraits/commonHeaders'
+      payload:
+        $ref: '#/components/schemas/dimLightPayload'
+
+  schemas:
+    lightMeasuredPayload:
+      type: object
+      properties:
+        lumens:
+          type: integer
+          description: Light intensity measured in lumens.
+          writeOnly: true
+          oneOf:
+            - minimum: 0
+              maximum: 5
+            - minimum: 10
+              maximum: 20
+          externalDocs:
+            url: 'https://www.asyncapi.com/'
+        sentAt:
+          $ref: '#/components/schemas/sentAt'
+        ifElseThen:
+          type: integer
+          minimum: 1
+          maximum: 1000
+          if:
+            minimum: 100
+          then:
+            multipleOf: 100
+          else:
+            if:
+              minimum: 10
+            then:
+              multipleOf: 10
+        dependencies:
+          $ref: '#/components/schemas/dependenciesObject'
+        anySchema: true
+        cannotBeDefined: false
+        restrictedAny:
+          minimum: 1
+          maximum: 1000
+      required:
+        - lumens
+      x-schema-extensions-as-object:
+        type: object
+        properties:
+          prop1:
+            type: string
+          prop2:
+            type: integer
+            minimum: 0
+      x-schema-extensions-as-primitive: dummy
+      x-schema-extensions-as-array:
+        - 'item1'
+        - 'item2'
+    turnOnOffPayload:
+      type: object
+      properties:
+        command:
+          type: string
+          enum:
+            - on
+            - off
+          description: Whether to turn on or off the light.
+        sentAt:
+          $ref: '#/components/schemas/sentAt'
+        arrayRank:
+          $ref: '#/components/schemas/arrayRank'
+      additionalProperties:
+        type: string
+
+    dimLightPayload:
+      type: object
+      properties:
+        percentage:
+          type: integer
+          description: Percentage to which the light should be dimmed to.
+          minimum: 0
+          maximum: 100
+          readOnly: true
+        sentAt:
+          $ref: '#/components/schemas/sentAt'
+        key:
+          type: integer
+          not:
+            minimum: 3
+      patternProperties:
+        ^S_:
+          type: string
+        ^I_:
+          type: integer
+      additionalProperties: false
+    sentAt:
+      type: string
+      format: date-time
+      description: Date and time when the message was sent.
+    union:
+      type: [string, number]
+    objectWithKey:
+      type: object
+      propertyNames:
+        format: email
+      properties:
+        key:
+          type: string
+    objectWithKey2:
+      type: object
+      properties:
+        key2:
+          type: string
+          format: time
+    oneOfSchema:
+      oneOf:
+        - $ref: '#/components/schemas/objectWithKey'
+        - $ref: '#/components/schemas/objectWithKey2'
+    anyOfSchema:
+      anyOf:
+        - $ref: '#/components/schemas/objectWithKey'
+        - $ref: '#/components/schemas/objectWithKey2'
+    allOfSchema:
+      allOf:
+        - $ref: '#/components/schemas/objectWithKey'
+        - $ref: '#/components/schemas/objectWithKey2'
+    arrayContains:
+      type: array
+      contains:
+        type: integer
+    dependenciesObject:
+      type: object
+      properties:
+        name:
+          type: string
+        credit_card:
+          type: integer
+        billing_address:
+          type: string
+        schema_dependency:
+          type: string
+      required:
+        - name
+      dependencies:
+        credit_card:
+          properties:
+            billing_address:
+              type: string
+            billing_address2:
+              type: string
+          required:
+            - billing_address
+          dependencies:
+            billing_address2:
+              properties:
+                billing_address3:
+                  type: string
+              required:
+                - billing_address3
+
+    subscriptionStatus:
+      type: object
+      oneOf:
+        - properties:
+            channelID:
+              type: integer
+              description: ChannelID on successful subscription, applicable to public messages only.
+            channelName:
+              type: string
+              description: Channel Name on successful subscription. For payloads 'ohlc' and 'book', respective interval or depth will be added as suffix.
+        - properties:
+            errorMessage:
+              type: string
+      properties:
+        event:
+          type: string
+          const: subscriptionStatus
+        subscription:
+          type: object
+          properties:
+            depth:
+              type: string
+            interval:
+              type: string
+          required:
+            - name
+      required:
+        - event
+
+    arrayRank:
+      type: object
+      properties:
+        valueRank:
+          $ref: '#/components/schemas/arrayValueRank'
+        arrayDimensions:
+          $ref: '#/components/schemas/arrayArrayDimensions'
+
+    arrayValueRank:
+      description: >
+        This Attribute indicates whether the val Attribute of the datapoint is an
+        array and how many dimensions the array has.
+      type: integer
+      default: -1
+      examples:
+        - 2
+      oneOf:
+        - const: -1
+          description: 'Scalar: The value is not an array.'
+        - const: 0
+          description: 'OneOrMoreDimensions: The value is an array with one or more dimensions.'
+        - const: 1
+          description: 'OneDimension: The value is an array with one dimension.'
+        - const: 2
+          description: 'The value is an array with two dimensions.'
+
+    arrayArrayDimensions:
+      type: array
+      items:
+        type: integer
+        minimum: 0
+      examples:
+        - [3, 5]
+
+    streamHeaders:
+      Etag:
+        type: string
+        description: |
+          The RFC7232 ETag header field in a response provides the current entity-
+          tag for the selected resource. An entity-tag is an opaque identifier for
+          different versions of a resource over time, regardless whether multiple
+          versions are valid at the same time. An entity-tag consists of an opaque
+          quoted string, possibly prefixed by a weakness indicator.
+        example: 411a
+      Cache-Control:
+        description: The Cache-Control HTTP header holds directives (instructions) for caching in request.
+        type: string
+        example: no-cache, no-store, must-revalidate
+
+  securitySchemes:
+    apiKey:
+      type: apiKey
+      in: user
+      description: Provide your API key as the user and leave the password empty.
+    supportedOauthFlows:
+      type: oauth2
+      description: Flows to support OAuth 2.0
+      flows:
+        implicit:
+          authorizationUrl: 'https://authserver.example/auth'
+          scopes:
+            'streetlights:on': Ability to switch lights on
+            'streetlights:off': Ability to switch lights off
+            'streetlights:dim': Ability to dim the lights
+        password:
+          tokenUrl: 'https://authserver.example/token'
+          scopes:
+            'streetlights:on': Ability to switch lights on
+            'streetlights:off': Ability to switch lights off
+            'streetlights:dim': Ability to dim the lights
+        clientCredentials:
+          tokenUrl: 'https://authserver.example/token'
+          scopes:
+            'streetlights:on': Ability to switch lights on
+            'streetlights:off': Ability to switch lights off
+            'streetlights:dim': Ability to dim the lights
+        authorizationCode:
+          authorizationUrl: 'https://authserver.example/auth'
+          tokenUrl: 'https://authserver.example/token'
+          refreshUrl: 'https://authserver.example/refresh'
+          scopes:
+            'streetlights:on': Ability to switch lights on
+            'streetlights:off': Ability to switch lights off
+            'streetlights:dim': Ability to dim the lights
+    openIdConnectWellKnown:
+      type: openIdConnect
+      openIdConnectUrl: 'https://authserver.example/.well-known'
+
+  parameters:
+    streetlightId:
+      description: The ID of the streetlight.
+      schema:
+        type: string
+      location: '$message.payload#/user/id'
+
+  correlationIds:
+    sentAtCorrelator:
+      description: Data from message payload used as correlation ID
+      location: $message.payload#/sentAt
+
+  messageTraits:
+    commonHeaders:
+      headers:
+        type: object
+        properties:
+          my-app-header:
+            type: integer
+            minimum: 0
+            maximum: 100
+        required:
+          - my-app-header
+
+  operationTraits:
+    kafka:
+      bindings:
+        kafka:
+          clientId: my-app-id
diff --git a/tests/e2e/map/map-async2-stylish/snapshot.txt b/tests/e2e/map/map-async2-stylish/snapshot.txt
new file mode 100644
index 0000000000..643f127586
--- /dev/null
+++ b/tests/e2e/map/map-async2-stylish/snapshot.txt
@@ -0,0 +1,55 @@
+Streetlights API Root #/
+  Streetlights API Info #/info
+  servers ServerMap #/servers
+    production Server #/servers/production
+    dummy-mqtt Server #/servers/dummy-mqtt
+    dummy-amqp Server #/servers/dummy-amqp
+    dommy-kafka Server #/servers/dommy-kafka
+  channels ChannelMap #/channels
+    smartylighting/streetlights/1/0/event/{streetlightId}/lighting/measured Channel #/channels/smartylighting~1streetlights~11~10~1event~1{streetlightId}~1lighting~1measured
+      receiveLightMeasurement Operation #/channels/smartylighting~1streetlights~11~10~1event~1{streetlightId}~1lighting~1measured/subscribe
+    smartylighting/streetlights/1/0/action/{streetlightId}/turn/on/ Channel #/channels/smartylighting~1streetlights~11~10~1action~1{streetlightId}~1turn~1on~1
+      turnOn Operation #/channels/smartylighting~1streetlights~11~10~1action~1{streetlightId}~1turn~1on~1/publish
+    smartylighting/streetlights/1/0/action/{streetlightId}/turn/off Channel #/channels/smartylighting~1streetlights~11~10~1action~1{streetlightId}~1turn~1off
+      PUBLISH smartylighting/streetlights/1/0/action/{streetlightId}/turn/off Operation #/channels/smartylighting~1streetlights~11~10~1action~1{streetlightId}~1turn~1off/publish
+    smartylighting/streetlights/1/0/action/{streetlightId}/dim Channel #/channels/smartylighting~1streetlights~11~10~1action~1{streetlightId}~1dim
+      dimLight Operation #/channels/smartylighting~1streetlights~11~10~1action~1{streetlightId}~1dim/publish
+  components Components #/components
+    messages NamedMessages #/components/messages
+      Light measured Message #/components/messages/lightMeasured
+      LwM2mOjbects Message #/components/messages/LwM2mOjbects
+      Turn on/off Message #/components/messages/turnOnOff
+      Dim light Message #/components/messages/dimLight
+    parameters NamedParameters #/components/parameters
+      streetlightId Parameter #/components/parameters/streetlightId
+    schemas NamedSchemas #/components/schemas
+      lightMeasuredPayload Schema #/components/schemas/lightMeasuredPayload
+      turnOnOffPayload Schema #/components/schemas/turnOnOffPayload
+      dimLightPayload Schema #/components/schemas/dimLightPayload
+      sentAt Schema #/components/schemas/sentAt
+      union Schema #/components/schemas/union
+      objectWithKey Schema #/components/schemas/objectWithKey
+      objectWithKey2 Schema #/components/schemas/objectWithKey2
+      oneOfSchema Schema #/components/schemas/oneOfSchema
+      anyOfSchema Schema #/components/schemas/anyOfSchema
+      allOfSchema Schema #/components/schemas/allOfSchema
+      arrayContains Schema #/components/schemas/arrayContains
+      dependenciesObject Schema #/components/schemas/dependenciesObject
+      subscriptionStatus Schema #/components/schemas/subscriptionStatus
+      arrayRank Schema #/components/schemas/arrayRank
+      arrayValueRank Schema #/components/schemas/arrayValueRank
+      arrayArrayDimensions Schema #/components/schemas/arrayArrayDimensions
+      streamHeaders Schema #/components/schemas/streamHeaders
+    securitySchemes NamedSecuritySchemes #/components/securitySchemes
+      apiKey SecurityScheme #/components/securitySchemes/apiKey
+      supportedOauthFlows SecurityScheme #/components/securitySchemes/supportedOauthFlows
+      openIdConnectWellKnown SecurityScheme #/components/securitySchemes/openIdConnectWellKnown
+  tags TagList #/tags
+    root-tag1 Tag #/tags/0
+    root-tag2 Tag #/tags/1
+    root-tag3 Tag #/tags/2
+    root-tag4 Tag #/tags/3
+    root-tag5 Tag #/tags/4
+
+Document: async.yaml map:
+
diff --git a/tests/e2e/map/map-async3-stylish/asyncapi3.yaml b/tests/e2e/map/map-async3-stylish/asyncapi3.yaml
new file mode 100644
index 0000000000..e5bde335ef
--- /dev/null
+++ b/tests/e2e/map/map-async3-stylish/asyncapi3.yaml
@@ -0,0 +1,31 @@
+asyncapi: 3.0.0
+info:
+  title: Account Service
+  version: 1.0.0
+  description: This service is in charge of processing user signups
+channels:
+  userSignedup:
+    address: user/signedup/
+    messages:
+      UserSignedUp:
+        $ref: '#/components/messages/UserSignedUp'
+operations:
+  sendUserSignedup:
+    action: send
+    channel:
+      $ref: '#/channels/userSignedup'
+    messages:
+      - $ref: '#/channels/userSignedup/messages/UserSignedUp'
+components:
+  messages:
+    UserSignedUp:
+      payload:
+        type: object
+        properties:
+          displayName:
+            type: string
+            description: Name of the user
+          email:
+            type: string
+            format: email
+            description: Email of the user
diff --git a/tests/e2e/map/map-async3-stylish/snapshot.txt b/tests/e2e/map/map-async3-stylish/snapshot.txt
new file mode 100644
index 0000000000..6d0489241a
--- /dev/null
+++ b/tests/e2e/map/map-async3-stylish/snapshot.txt
@@ -0,0 +1,12 @@
+Account Service Root #/
+  Account Service Info #/info
+  channels NamedChannels #/channels
+    userSignedup Channel #/channels/userSignedup
+  components Components #/components
+    messages NamedMessages #/components/messages
+      UserSignedUp Message #/components/messages/UserSignedUp
+  operations NamedOperations #/operations
+    sendUserSignedup Operation #/operations/sendUserSignedup
+
+Document: asyncapi3.yaml map:
+
diff --git a/tests/e2e/map/map-json/components/menu-item.yaml b/tests/e2e/map/map-json/components/menu-item.yaml
new file mode 100644
index 0000000000..5bb358faf8
--- /dev/null
+++ b/tests/e2e/map/map-json/components/menu-item.yaml
@@ -0,0 +1,2 @@
+type: object
+description: A menu item.
diff --git a/tests/e2e/map/map-json/openapi.yaml b/tests/e2e/map/map-json/openapi.yaml
new file mode 100644
index 0000000000..bfb55fab81
--- /dev/null
+++ b/tests/e2e/map/map-json/openapi.yaml
@@ -0,0 +1,12 @@
+openapi: 3.0.0
+info:
+  title: Redocly Cafe
+  version: 1.0.0
+  description: A small multi-file cafe API used to test TOC generation.
+paths:
+  /menu:
+    $ref: ./paths/menu.yaml
+components:
+  schemas:
+    MenuItem:
+      $ref: ./components/menu-item.yaml
diff --git a/tests/e2e/map/map-json/paths/menu.yaml b/tests/e2e/map/map-json/paths/menu.yaml
new file mode 100644
index 0000000000..d14afe468d
--- /dev/null
+++ b/tests/e2e/map/map-json/paths/menu.yaml
@@ -0,0 +1,3 @@
+get:
+  operationId: listMenuItems
+  summary: List all menu items
diff --git a/tests/e2e/map/map-json/snapshot.txt b/tests/e2e/map/map-json/snapshot.txt
new file mode 100644
index 0000000000..7f2c6cc6d7
--- /dev/null
+++ b/tests/e2e/map/map-json/snapshot.txt
@@ -0,0 +1,90 @@
+{
+  "title": "Redocly Cafe",
+  "kind": "Root",
+  "pointer": "#/",
+  "source": {
+    "file": "./tests/e2e/map/map-json/openapi.yaml",
+    "pointer": "#/"
+  },
+  "nodes": [
+    {
+      "title": "Redocly Cafe",
+      "kind": "Info",
+      "pointer": "#/info",
+      "summary": "A small multi-file cafe API used to test TOC generation.",
+      "source": {
+        "file": "./tests/e2e/map/map-json/openapi.yaml",
+        "pointer": "#/info"
+      },
+      "nodes": []
+    },
+    {
+      "title": "paths",
+      "kind": "Paths",
+      "pointer": "#/paths",
+      "source": {
+        "file": "./tests/e2e/map/map-json/openapi.yaml",
+        "pointer": "#/paths"
+      },
+      "nodes": [
+        {
+          "title": "/menu",
+          "kind": "PathItem",
+          "pointer": "#/paths/~1menu",
+          "source": {
+            "file": "./tests/e2e/map/map-json/paths/menu.yaml",
+            "pointer": "#/"
+          },
+          "nodes": [
+            {
+              "title": "listMenuItems",
+              "kind": "Operation",
+              "pointer": "#/paths/~1menu/get",
+              "summary": "List all menu items",
+              "method": "get",
+              "path": "/menu",
+              "source": {
+                "file": "./tests/e2e/map/map-json/paths/menu.yaml",
+                "pointer": "#/get"
+              },
+              "nodes": []
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "title": "components",
+      "kind": "Components",
+      "pointer": "#/components",
+      "source": {
+        "file": "./tests/e2e/map/map-json/openapi.yaml",
+        "pointer": "#/components"
+      },
+      "nodes": [
+        {
+          "title": "schemas",
+          "kind": "NamedSchemas",
+          "pointer": "#/components/schemas",
+          "source": {
+            "file": "./tests/e2e/map/map-json/openapi.yaml",
+            "pointer": "#/components/schemas"
+          },
+          "nodes": [
+            {
+              "title": "MenuItem",
+              "kind": "Schema",
+              "pointer": "#/components/schemas/MenuItem",
+              "summary": "A menu item.",
+              "source": {
+                "file": "./tests/e2e/map/map-json/components/menu-item.yaml",
+                "pointer": "#/"
+              },
+              "nodes": []
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
diff --git a/tests/e2e/map/map-stylish/cafe.yaml b/tests/e2e/map/map-stylish/cafe.yaml
new file mode 100644
index 0000000000..c7102cc8a2
--- /dev/null
+++ b/tests/e2e/map/map-stylish/cafe.yaml
@@ -0,0 +1,1261 @@
+openapi: 3.2.0
+info:
+  title: Redocly Cafe
+  description: >
+    Demo API for cafe operators (not customers) to manage menus, orders, and
+    revenue.
+
+    Create API credentials and try it yourself in a realistic OpenAPI workflow.
+  version: 1.0.0
+  contact:
+    email: team@redocly.com
+    url: https://redocly.com/contact-us/
+  license:
+    name: MIT
+    url: https://opensource.org/licenses/MIT
+  termsOfService: https://redocly.com/subscription-agreement
+servers:
+  - url: https://api.cafe.redocly.com
+    description: Live server.
+tags:
+  - name: Authorization
+    description: Create a client to demo the API.
+  - name: Products
+    description: Operations related to products.
+  - name: Orders
+    description: Order management operations.
+  - name: Statistics
+    description: Statistics operations.
+paths:
+  /menu:
+    get:
+      tags:
+        - Products
+      summary: List all menu items
+      description: >-
+        Retrieve a collection of menu items with optional filtering and
+        pagination.
+      operationId: listMenuItems
+      security: []
+      parameters:
+        - $ref: '#/components/parameters/After'
+        - $ref: '#/components/parameters/Before'
+        - $ref: '#/components/parameters/Sort'
+        - $ref: '#/components/parameters/Filter'
+        - $ref: '#/components/parameters/Search'
+        - $ref: '#/components/parameters/Limit'
+      responses:
+        '200':
+          description: Successful operation.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MenuItemList'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+    post:
+      tags:
+        - Products
+      summary: Create menu item
+      description: Create a new menu item.
+      operationId: createMenuItem
+      security:
+        - OAuth2:
+            - menu:write
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              $ref: '#/components/schemas/MenuItem'
+            examples:
+              Beverage:
+                summary: Create a beverage
+                value:
+                  name: Cappuccino
+                  price: 4500
+                  category: beverage
+                  volume: 250
+                  containsCaffeine: true
+                  photoTextDescription: A hot cappuccino in a white ceramic cup.
+              Dessert:
+                summary: Create a dessert
+                value:
+                  name: Chocolate-Brownie
+                  price: 3500
+                  category: dessert
+                  calories: 420
+                  photoTextDescription: A rich chocolate brownie square dusted with cocoa.
+      responses:
+        '201':
+          description: Menu item created successfully.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MenuItem'
+              examples:
+                MenuItemResponse:
+                  value:
+                    id: prd_01khr487f7qm7p44xn427m43vb
+                    object: menuItem
+                    name: coffee
+                    price: 4000
+                    category: beverage
+                    createdAt: '2026-02-18T10:20:38.228Z'
+                    updatedAt: '2026-02-18T10:20:38.228Z'
+                    volume: 600
+                    containsCaffeine: false
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '409':
+          $ref: '#/components/responses/Conflict'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+  /menu/{menuItemId}:
+    parameters:
+      - $ref: '#/components/parameters/MenuItemId'
+    delete:
+      tags:
+        - Products
+      summary: Delete a menu item
+      description: Delete an existing menu item.
+      operationId: deleteMenuItem
+      security:
+        - OAuth2:
+            - menu:write
+      responses:
+        '204':
+          description: Menu item deleted successfully.
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+  /menu-item-images/{menuItemId}:
+    parameters:
+      - $ref: '#/components/parameters/MenuItemId'
+    get:
+      operationId: getMenuItemPhoto
+      summary: Retrieve a menu item photo
+      description: Retrieve the product photo image for a specific menu item.
+      security: []
+      tags:
+        - Products
+      parameters:
+        - $ref: '#/components/parameters/PhotoSize'
+      responses:
+        '200':
+          description: Menu item photo retrieved successfully.
+          content:
+            image/png:
+              schema:
+                type: string
+                format: binary
+            text/plain:
+              schema:
+                description: Alternative image text.
+                type: string
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+  /orders:
+    get:
+      tags:
+        - Orders
+      summary: List all orders
+      description: Retrieve a collection of orders with optional filtering and pagination.
+      operationId: listOrders
+      security:
+        - OAuth2:
+            - orders:read
+      parameters:
+        - $ref: '#/components/parameters/Filter'
+        - $ref: '#/components/parameters/Sort'
+        - $ref: '#/components/parameters/Limit'
+        - $ref: '#/components/parameters/After'
+        - $ref: '#/components/parameters/Before'
+        - $ref: '#/components/parameters/Search'
+      responses:
+        '200':
+          description: Successful operation.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OrderList'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+    post:
+      tags:
+        - Orders
+      summary: Create order
+      description: >
+        Create a new order.
+
+        Order items cannot be changed - if they need to be updated, the order
+        should be canceled and a new one placed.
+      operationId: createOrder
+      security:
+        - OAuth2:
+            - orders:write
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Order'
+            examples:
+              OrderRequest:
+                dataValue:
+                  customerName: Mary Ann
+                  orderItems:
+                    - menuItemId: prd_01h1s5z6vf2mm1mz3hevnn9va7
+                      quantity: 2
+                      comment: No sugar!
+                      discount: 0
+      responses:
+        '201':
+          description: Order placed successfully.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Order'
+              examples:
+                OrderResponse:
+                  dataValue:
+                    id: ord_01h1s5z6vf2mm1mz3hevnn9va7
+                    customerName: Mary Ann
+                    orderItems:
+                      - menuItemId: prd_01h1s5z6vf2mm1mz3hevnn9va7
+                        quantity: 2
+                        comment: No sugar!
+                        discount: 0
+                    object: order
+                    status: placed
+                    totalPrice: 200
+                    createdAt: '2026-08-24T14:15:22Z'
+                    updatedAt: '2026-08-24T14:15:22Z'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+  /orders/{orderId}:
+    get:
+      tags:
+        - Orders
+      summary: Retrieve an order
+      description: Retrieve a single order by its ID.
+      operationId: getOrderById
+      security:
+        - OAuth2:
+            - orders:read
+      parameters:
+        - $ref: '#/components/parameters/OrderId'
+      responses:
+        '200':
+          description: Successful operation.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Order'
+              examples:
+                OrderResponse:
+                  dataValue:
+                    id: ord_01h1s5z6vf2mm1mz3hevnn9va7
+                    customerName: Mary Ann
+                    orderItems:
+                      - menuItemId: prd_01h1s5z6vf2mm1mz3hevnn9va7
+                        quantity: 2
+                        comment: No sugar!
+                        discount: 0
+                    object: order
+                    status: placed
+                    totalPrice: 200
+                    createdAt: '2026-08-24T14:15:22Z'
+                    updatedAt: '2026-08-24T14:15:22Z'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+    patch:
+      tags:
+        - Orders
+      summary: Partially update an order
+      description: >
+        Update an existing order status.
+
+        Order items cannot be changed - if they need to be updated, the order
+        should be canceled and a new one placed.
+      operationId: updateOrder
+      security:
+        - OAuth2:
+            - orders:write
+      parameters:
+        - $ref: '#/components/parameters/OrderId'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              description: >
+                Partial order update using JSON Merge Patch - only include
+                fields to update.
+              properties:
+                status:
+                  $ref: '#/components/schemas/OrderStatus'
+              required:
+                - status
+      responses:
+        '200':
+          description: Order updated successfully.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Order'
+              examples:
+                OrderResponse:
+                  dataValue:
+                    id: ord_01h1s5z6vf2mm1mz3hevnn9va7
+                    customerName: Mary Ann
+                    orderItems:
+                      - menuItemId: prd_01h1s5z6vf2mm1mz3hevnn9va7
+                        quantity: 2
+                        comment: No sugar!
+                        discount: 0
+                    object: order
+                    status: completed
+                    totalPrice: 200
+                    createdAt: '2026-08-24T14:15:22Z'
+                    updatedAt: '2026-08-24T14:15:22Z'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+    delete:
+      tags:
+        - Orders
+      summary: Delete an order
+      description: >
+        Delete the order.
+
+        To keep the order history, the order should be canceled instead of
+        deleted.
+      operationId: deleteOrder
+      security:
+        - OAuth2:
+            - orders:write
+      parameters:
+        - $ref: '#/components/parameters/OrderId'
+      responses:
+        '204':
+          description: Order deleted successfully.
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+  /order-items:
+    get:
+      tags:
+        - Orders
+      summary: List all order items with menu item details
+      description: |
+        Returns an array of order items for a specific order.
+        Use the `filter` parameter to filter by order ID.
+      operationId: listOrderItems
+      security:
+        - OAuth2:
+            - orders:read
+      parameters:
+        - $ref: '#/components/parameters/Filter'
+          required: true
+      responses:
+        '200':
+          description: Successful operation.
+          content:
+            application/json:
+              schema:
+                type: array
+                description: List of menu items that are part of the order.
+                items:
+                  $ref: '#/components/schemas/OrderItem'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+  /revenue:
+    get:
+      tags:
+        - Statistics
+      summary: Get revenue statistics
+      description: >
+        Retrieve revenue statistics for a configurable date range.
+
+        Returns revenue, order counts, average order amount, and other useful
+        statistics.
+      operationId: getRevenue
+      security:
+        - ApiKey: []
+        - OAuth2:
+            - revenue:read
+      parameters:
+        - name: startDate
+          in: query
+          required: false
+          description: >
+            Start date for the revenue calculation period (ISO 8601 datetime
+            format).
+
+            Defaults to 30 days ago if not provided.
+          schema:
+            type: string
+            format: date
+          example: '2026-01-01'
+        - name: endDate
+          in: query
+          required: false
+          description: >
+            End date for the revenue calculation period (ISO 8601 datetime
+            format).
+
+            Defaults to current time if not provided.
+          schema:
+            type: string
+            format: date
+          example: '2026-01-31'
+      responses:
+        '200':
+          description: Revenue statistics retrieved successfully.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RevenueStatistics'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+  /oauth2/register:
+    post:
+      tags:
+        - Authorization
+      summary: Create OAuth2 client
+      description: >
+        Register a new OAuth2 client for dynamic client registration.  This
+        endpoint implements the Dynamic Client Registration Protocol (RFC 7591),
+        using camelCase field names instead of the RFC's snake_case convention
+        (e.g., `redirectUris` instead of `redirect_uris`, `grantTypes` instead
+        of `grant_types`). The `name` field is required. Other fields are
+        optional. If not provided:
+
+        - `redirectUris` defaults to an empty array. Note: When using the
+        `authorization_code` grant type, 
+          `redirectUris` must be provided (per RFC 7591 Section 2).
+        - `scopes` defaults to all available scopes (menu:read, menu:write,
+        orders:read, orders:write) - `grantTypes` defaults to both supported
+        grant types (authorization_code, client_credentials)
+
+        Returns the registered client information per RFC 7591, including:
+
+        - `clientId` and `clientSecret` (must be stored securely) -
+        `clientIdIssuedAt` and `clientSecretExpiresAt` timestamps - All
+        registered client metadata (name, redirectUris, scopes, grantTypes)
+      operationId: registerOAuth2Client
+      security: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RegisterClientObject'
+            examples:
+              RegisterClientObject:
+                dataValue:
+                  name: auth
+                  redirectUris:
+                    - https://api.cafe.redocly.com/callback
+                  scopes:
+                    - menu:read
+                    - menu:write
+                    - orders:read
+                    - orders:write
+                    - revenue:read
+                  grantTypes:
+                    - client_credentials
+      responses:
+        '201':
+          description: OAuth2 client registered successfully.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OAuth2Client'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+webhooks:
+  order-notification:
+    post:
+      tags:
+        - Orders
+      operationId: orderNotificationWebhook
+      security: []
+      summary: Order notification webhook
+      description: Webhook triggered when a new order is placed.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/OrderNotification'
+      responses:
+        '200':
+          description: Webhook received successfully.
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+components:
+  securitySchemes:
+    OAuth2:
+      type: oauth2
+      description: OAuth2 authorization for API access.
+      flows:
+        authorizationCode:
+          authorizationUrl: https://api.cafe.redocly.com/oauth2/authorize
+          tokenUrl: https://api.cafe.redocly.com/oauth2/token
+          scopes:
+            menu:read: Read access to menu items and images
+            menu:write: Write access to menu items (create, delete)
+            orders:read: Read access to orders
+            orders:write: Write access to orders (create, update, delete)
+            revenue:read: Read access to revenue statistics
+        clientCredentials:
+          tokenUrl: https://api.cafe.redocly.com/oauth2/token
+          scopes:
+            menu:read: Read access to menu items and images
+            menu:write: Write access to menu items (create, delete)
+            orders:read: Read access to orders
+            orders:write: Write access to orders (create, update, delete)
+            revenue:read: Read access to revenue statistics
+    ApiKey:
+      type: apiKey
+      name: X-API-Key
+      in: header
+      description: API key for internal operations.
+  parameters:
+    After:
+      name: after
+      in: query
+      required: false
+      description: >-
+        Use the `endCursor` as a value for the `after` parameter to get the next
+        page.
+      schema:
+        type: string
+    Before:
+      name: before
+      in: query
+      required: false
+      description: >
+        Use the `startCursor` as a value for the `before` parameter to get the
+        next page.
+      schema:
+        type: string
+    Sort:
+      name: sort
+      description: |-
+        To sort by id in descending order use `-id`.
+        To sort by id in ascending order use `id`.
+      in: query
+      required: false
+      schema:
+        type: string
+    Filter:
+      name: filter
+      description: >-
+        Filters the collection items using space-separated `field:value` pairs.
+
+
+        **Format:** `field1:value1 field2:value2`
+
+
+        **Supported operators:**
+
+        - `field:value` - Exact match
+
+        - `field:value1,value2` - Match any of the comma-separated values (OR)
+
+        - Time ranges: Use `30d` (30 days), `7d` (7 days), `1h` (1 hour), etc.
+
+
+        **Examples:**
+
+        - `status:placed` - Filter by single status.
+
+        - `status:placed,completed` - Filter by multiple statuses.
+
+        - `createdAt:30d` - Filter orders created in the last 30 days.
+
+        - `orderId:ord_01h1s5z6vf2mm1mz3hevnn9va7` - Filter by specific order
+        ID.
+
+        - `status:placed createdAt:7d` - Combine multiple filters.
+      in: query
+      required: false
+      schema:
+        type: string
+    Search:
+      name: search
+      in: query
+      description: >-
+        Performs a case-insensitive text search across relevant fields in the
+        collection.
+
+
+        **Fields searched depend on the endpoint:**
+
+        - **Menu items:** `name`, `photoTextDescription`
+
+        - **Orders:** `customerName`, `id`
+
+
+        Returns items where any of the searchable fields contain the search term
+        as a substring.
+      required: false
+      schema:
+        type: string
+    Limit:
+      name: limit
+      description: >
+        Use to return a number of results per page.
+
+        If there is more data, use in combination with `after` to page through
+        the data.
+      in: query
+      required: false
+      schema:
+        type: integer
+        minimum: 1
+        maximum: 100
+        default: 10
+      example: 10
+    MenuItemId:
+      name: menuItemId
+      in: path
+      description: ID of the menu item to retrieve.
+      required: true
+      schema:
+        type: string
+        pattern: ^prd_[0-9abcdefghjkmnpqrstvwxyz]{26}$
+    PhotoSize:
+      name: photoSize
+      in: query
+      description: Photo size to retrieve.
+      required: false
+      schema:
+        type: string
+        enum:
+          - thumbnail
+          - medium
+          - large
+        default: medium
+    OrderId:
+      name: orderId
+      in: path
+      description: ID of the order to retrieve.
+      required: true
+      schema:
+        type: string
+        pattern: ^ord_[0-9abcdefghjkmnpqrstvwxyz]{26}$
+      example: ord_01h1s5z6vf2mm1mz3hevnn9va7
+  schemas:
+    Page:
+      type: object
+      properties:
+        endCursor:
+          type:
+            - string
+            - 'null'
+          description: |-
+            Use with the `after` query parameter to load the next page of data.
+            When `null`, there is no data.
+            The cursor is opaque and internal structure is subject to change.
+        startCursor:
+          type:
+            - string
+            - 'null'
+          description: >-
+            Use with the `before` query parameter to load the previous page of
+            data.
+
+            When `null`, there is no data.
+
+            The cursor is opaque and internal structure is subject to change.
+        hasNextPage:
+          type: boolean
+          description: Indicates if there is a next page with items.
+        hasPrevPage:
+          type: boolean
+          description: Indicates if there is a previous page with items.
+        limit:
+          type: integer
+          minimum: 1
+          maximum: 100
+          default: 10
+          description: Value showing how many items are in the page limit.
+        total:
+          type: integer
+          description: Count of items across all pages.
+          minimum: 0
+      required:
+        - endCursor
+        - startCursor
+        - hasNextPage
+        - hasPrevPage
+        - limit
+        - total
+    MenuBaseItem:
+      type: object
+      properties:
+        createdAt:
+          description: Created date.
+          type: string
+          format: date-time
+          readOnly: true
+        updatedAt:
+          description: Updated date.
+          type: string
+          format: date-time
+          readOnly: true
+        id:
+          description: Menu item ID. Unique identifier prefixed with `prd_`.
+          type: string
+          readOnly: true
+          pattern: ^prd_[0-9abcdefghjkmnpqrstvwxyz]{26}$
+          example: prd_01h1s5z6vf2mm1mz3hevnn9va7
+        object:
+          description: Entity name.
+          type: string
+          const: menuItem
+          readOnly: true
+        name:
+          description: Menu item name.
+          type: string
+          minLength: 1
+          maxLength: 50
+        price:
+          description: Price in cents.
+          type: integer
+          minimum: 0
+        photo:
+          writeOnly: true
+          type:
+            - string
+            - 'null'
+          format: binary
+          description: Photo of the menu item. Must be a PNG image and less than 1MB.
+        photoUrl:
+          readOnly: true
+          type: string
+          format: uri
+          description: Photo URL of the menu item.
+        photoTextDescription:
+          type:
+            - string
+            - 'null'
+      required:
+        - id
+        - name
+        - price
+        - createdAt
+        - updatedAt
+        - object
+    Beverage:
+      allOf:
+        - type: object
+          properties:
+            category:
+              description: Menu item category.
+              type: string
+              const: beverage
+            volume:
+              type: number
+              description: Size of the beverage in milliliters.
+              exclusiveMinimum: 0
+            containsCaffeine:
+              type: boolean
+              description: Indicates if the beverage contains caffeine.
+          required:
+            - category
+            - volume
+            - containsCaffeine
+        - $ref: '#/components/schemas/MenuBaseItem'
+    Dessert:
+      allOf:
+        - type: object
+          properties:
+            category:
+              description: Menu item category.
+              type: string
+              const: dessert
+            calories:
+              type: number
+              exclusiveMinimum: 0
+              description: Amount of calories.
+          required:
+            - category
+            - calories
+        - $ref: '#/components/schemas/MenuBaseItem'
+    MenuItem:
+      discriminator:
+        propertyName: category
+        mapping:
+          beverage: '#/components/schemas/Beverage'
+          dessert: '#/components/schemas/Dessert'
+      oneOf:
+        - $ref: '#/components/schemas/Beverage'
+        - $ref: '#/components/schemas/Dessert'
+      required:
+        - category
+    MenuItemList:
+      type: object
+      properties:
+        object:
+          type: string
+          const: list
+          description: Entity name.
+        page:
+          $ref: '#/components/schemas/Page'
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/MenuItem'
+      required:
+        - object
+        - page
+        - items
+    Error:
+      type: object
+      properties:
+        type:
+          type: string
+          format: uri-reference
+          description: URI reference that identifies the problem type.
+          default: about:blank
+        title:
+          type: string
+          description: Short summary of the problem type.
+        status:
+          type: integer
+          format: int32
+          description: >
+            HTTP status code generated by the origin server for this occurrence
+            of the problem.
+          minimum: 100
+          exclusiveMaximum: 600
+        instance:
+          type: string
+          format: uri-reference
+          description: >
+            URI reference that identifies the specific occurrence of the
+            problem, e.g. by adding a fragment identifier or sub-path to the
+            problem type.
+
+            May be used to locate the root of this problem in the source code.
+          example: /some/uri-reference#specific-occurrence-context
+        details:
+          description: Additional error details.
+          type: object
+          additionalProperties: true
+      required:
+        - type
+        - title
+        - status
+    OrderStatus:
+      type: string
+      description: Order status.
+      enum:
+        - placed
+        - preparing
+        - completed
+        - canceled
+    Order:
+      type: object
+      title: Order
+      properties:
+        id:
+          description: Order ID. Unique identifier prefixed with `ord_`.
+          type: string
+          format: ulid
+          readOnly: true
+          pattern: ^ord_[0-9abcdefghjkmnpqrstvwxyz]{26}$
+          example: ord_01h1s5z6vf2mm1mz3hevnn9va7
+        object:
+          description: Entity name.
+          type: string
+          const: order
+          readOnly: true
+        customerName:
+          description: >
+            Name of the customer who placed the order.
+
+            Must start and end with a letter, and can contain letters, spaces,
+            hyphens, and apostrophes (e.g., "John Doe", "Mary-Jane", "O'Brien").
+          type: string
+          pattern: ^[A-Za-z]+(?:[\s'-][A-Za-z]+)*$
+          minLength: 1
+          maxLength: 100
+        status:
+          allOf:
+            - $ref: '#/components/schemas/OrderStatus'
+          readOnly: true
+        totalPrice:
+          description: Total order price in cents.
+          type: integer
+          minimum: 0
+          readOnly: true
+        createdAt:
+          description: Created date.
+          type: string
+          format: date-time
+          readOnly: true
+        updatedAt:
+          description: Updated date.
+          type: string
+          format: date-time
+          readOnly: true
+        orderItems:
+          type: array
+          description: List of items to include in the order.
+          minItems: 1
+          items:
+            type: object
+            properties:
+              menuItemId:
+                type: string
+                format: ulid
+                description: ID of the menu item to add to the order.
+              quantity:
+                type: integer
+                minimum: 1
+                description: Quantity of the menu item.
+              discount:
+                type: integer
+                minimum: 0
+                description: Discount amount in cents (absolute value).
+                default: 0
+              comment:
+                type: string
+                maxLength: 500
+                description: Optional comment for the order item (e.g., "No sugar").
+            required:
+              - menuItemId
+              - quantity
+      required:
+        - customerName
+        - orderItems
+    OrderList:
+      type: object
+      properties:
+        object:
+          type: string
+          const: list
+          description: Entity name.
+        page:
+          $ref: '#/components/schemas/Page'
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/Order'
+      required:
+        - object
+        - page
+        - items
+    OrderItem:
+      type: object
+      properties:
+        menuItemId:
+          type: string
+          description: ID of the menu item to add to the order.
+          writeOnly: true
+        menuItem:
+          allOf:
+            - $ref: '#/components/schemas/MenuItem'
+          description: Menu item that is part of the order.
+          readOnly: true
+        quantity:
+          type: integer
+          minimum: 1
+          description: Quantity of the menu item.
+        discount:
+          type: integer
+          minimum: 0
+          description: Discount amount in cents (absolute value).
+          default: 0
+        comment:
+          type: string
+          maxLength: 500
+          description: Optional comment for the order item (e.g., "No sugar").
+      required:
+        - menuItemId
+        - quantity
+    RevenueStatistics:
+      type: object
+      description: Revenue statistics for a given date range.
+      properties:
+        revenue:
+          type: number
+          format: float
+          description: Total revenue in cents from completed orders.
+          minimum: 0
+        averageOrderAmount:
+          type: number
+          format: float
+          description: >-
+            Average order amount in cents (calculated from completed orders
+            only).
+          minimum: 0
+        totalOrders:
+          type: integer
+          description: Total number of orders (all statuses) in the date range.
+          minimum: 0
+        placedOrders:
+          type: integer
+          description: Number of placed orders.
+          minimum: 0
+        preparingOrders:
+          type: integer
+          description: Number of preparing orders.
+          minimum: 0
+        completedOrders:
+          type: integer
+          description: Number of completed orders.
+          minimum: 0
+        canceledOrders:
+          type: integer
+          description: Number of canceled orders.
+          minimum: 0
+        startDate:
+          type: string
+          format: date
+          description: Start date of the revenue calculation period.
+        endDate:
+          type: string
+          format: date
+          description: End date of the revenue calculation period.
+      required:
+        - revenue
+        - averageOrderAmount
+        - totalOrders
+        - placedOrders
+        - preparingOrders
+        - completedOrders
+        - canceledOrders
+        - startDate
+        - endDate
+    RegisterClientObject:
+      type: object
+      properties:
+        name:
+          type: string
+          description: Client name.
+        redirectUris:
+          type: array
+          items:
+            type: string
+            format: uri
+          description: List of redirect URIs (optional, defaults to empty array).
+        scopes:
+          type: array
+          items:
+            type: string
+            enum:
+              - menu:read
+              - menu:write
+              - orders:read
+              - orders:write
+              - revenue:read
+          description: List of scopes.
+        grantTypes:
+          type: array
+          items:
+            type: string
+            enum:
+              - authorization_code
+              - client_credentials
+          description: List of grant types.
+      required:
+        - name
+    OAuth2Client:
+      type: object
+      description: >-
+        OAuth2 client registration response. Per RFC 7591, includes the client
+        identifier, secret, timestamps, and all registered client metadata.
+      properties:
+        clientId:
+          type: string
+          description: Client identifier issued by the authorization server.
+        clientSecret:
+          type: string
+          description: Client secret issued by the authorization server.
+        clientIdIssuedAt:
+          type: integer
+          format: int64
+          description: >-
+            Time when the client_id is issued, represented as seconds since
+            epoch (RFC7591).
+        clientSecretExpiresAt:
+          type: integer
+          format: int64
+          description: >-
+            Time at which the client_secret expires, represented as seconds
+            since epoch. 0 indicates the secret does not expire (RFC 7591).
+        name:
+          type: string
+          description: Client name (registered metadata).
+        redirectUris:
+          type: array
+          items:
+            type: string
+            format: uri
+          description: List of redirect URIs (registered metadata).
+        registrationClientUri:
+          type: string
+          format: uri
+          description: >-
+            URL of the client configuration endpoint for managing this client
+            registration (RFC 7592).
+        registrationAccessToken:
+          type: string
+          description: >-
+            Access token to be used at the client configuration endpoint for
+            managing this client registration (RFC 7592).
+        scopes:
+          type: array
+          items:
+            type: string
+            enum:
+              - menu:read
+              - menu:write
+              - orders:read
+              - orders:write
+              - revenue:read
+          description: List of scopes (registered metadata).
+        grantTypes:
+          type: array
+          items:
+            type: string
+            enum:
+              - authorization_code
+              - client_credentials
+          description: List of grant types (registered metadata).
+      required:
+        - clientId
+        - clientSecret
+        - clientIdIssuedAt
+        - clientSecretExpiresAt
+        - registrationClientUri
+        - registrationAccessToken
+    OrderNotification:
+      type: object
+      required:
+        - orderId
+        - orderStatus
+        - timestamp
+      properties:
+        orderId:
+          type: string
+          description: Unique order identifier.
+        orderStatus:
+          $ref: '#/components/schemas/OrderStatus'
+        timestamp:
+          type: string
+          format: date-time
+          description: When the event occurred.
+  responses:
+    BadRequest:
+      description: Bad request - invalid input parameters.
+      content:
+        application/problem+json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    InternalServerError:
+      description: Internal server error.
+      content:
+        application/problem+json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    Unauthorized:
+      description: Unauthorized - authorization required.
+      content:
+        application/problem+json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    Forbidden:
+      description: Forbidden - insufficient permissions.
+      content:
+        application/problem+json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    Conflict:
+      description: Conflict - entity already exists.
+      content:
+        application/problem+json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    NotFound:
+      description: Resource not found.
+      content:
+        application/problem+json:
+          schema:
+            $ref: '#/components/schemas/Error'
diff --git a/tests/e2e/map/map-stylish/snapshot.txt b/tests/e2e/map/map-stylish/snapshot.txt
new file mode 100644
index 0000000000..03967ebf43
--- /dev/null
+++ b/tests/e2e/map/map-stylish/snapshot.txt
@@ -0,0 +1,73 @@
+Redocly Cafe Root #/
+  Redocly Cafe Info #/info
+  servers ServerList #/servers
+    https://api.cafe.redocly.com Server #/servers/0
+  tags TagList #/tags
+    Authorization Tag #/tags/0
+    Products Tag #/tags/1
+    Orders Tag #/tags/2
+    Statistics Tag #/tags/3
+  paths Paths #/paths
+    /menu PathItem #/paths/~1menu
+      listMenuItems Operation #/paths/~1menu/get
+      createMenuItem Operation #/paths/~1menu/post
+    /menu/{menuItemId} PathItem #/paths/~1menu~1{menuItemId}
+      deleteMenuItem Operation #/paths/~1menu~1{menuItemId}/delete
+    /menu-item-images/{menuItemId} PathItem #/paths/~1menu-item-images~1{menuItemId}
+      getMenuItemPhoto Operation #/paths/~1menu-item-images~1{menuItemId}/get
+    /orders PathItem #/paths/~1orders
+      listOrders Operation #/paths/~1orders/get
+      createOrder Operation #/paths/~1orders/post
+    /orders/{orderId} PathItem #/paths/~1orders~1{orderId}
+      getOrderById Operation #/paths/~1orders~1{orderId}/get
+      deleteOrder Operation #/paths/~1orders~1{orderId}/delete
+      updateOrder Operation #/paths/~1orders~1{orderId}/patch
+    /order-items PathItem #/paths/~1order-items
+      listOrderItems Operation #/paths/~1order-items/get
+    /revenue PathItem #/paths/~1revenue
+      getRevenue Operation #/paths/~1revenue/get
+    /oauth2/register PathItem #/paths/~1oauth2~1register
+      registerOAuth2Client Operation #/paths/~1oauth2~1register/post
+  webhooks WebhooksMap #/webhooks
+    order-notification PathItem #/webhooks/order-notification
+      orderNotificationWebhook Operation #/webhooks/order-notification/post
+  components Components #/components
+    parameters NamedParameters #/components/parameters
+      After Parameter #/components/parameters/After
+      Before Parameter #/components/parameters/Before
+      Sort Parameter #/components/parameters/Sort
+      Filter Parameter #/components/parameters/Filter
+      Search Parameter #/components/parameters/Search
+      Limit Parameter #/components/parameters/Limit
+      MenuItemId Parameter #/components/parameters/MenuItemId
+      PhotoSize Parameter #/components/parameters/PhotoSize
+      OrderId Parameter #/components/parameters/OrderId
+    schemas NamedSchemas #/components/schemas
+      Page Schema #/components/schemas/Page
+      MenuBaseItem Schema #/components/schemas/MenuBaseItem
+      Beverage Schema #/components/schemas/Beverage
+      Dessert Schema #/components/schemas/Dessert
+      MenuItem Schema #/components/schemas/MenuItem
+      MenuItemList Schema #/components/schemas/MenuItemList
+      Error Schema #/components/schemas/Error
+      OrderStatus Schema #/components/schemas/OrderStatus
+      Order Schema #/components/schemas/Order
+      OrderList Schema #/components/schemas/OrderList
+      OrderItem Schema #/components/schemas/OrderItem
+      RevenueStatistics Schema #/components/schemas/RevenueStatistics
+      RegisterClientObject Schema #/components/schemas/RegisterClientObject
+      OAuth2Client Schema #/components/schemas/OAuth2Client
+      OrderNotification Schema #/components/schemas/OrderNotification
+    responses NamedResponses #/components/responses
+      BadRequest Response #/components/responses/BadRequest
+      InternalServerError Response #/components/responses/InternalServerError
+      Unauthorized Response #/components/responses/Unauthorized
+      Forbidden Response #/components/responses/Forbidden
+      Conflict Response #/components/responses/Conflict
+      NotFound Response #/components/responses/NotFound
+    securitySchemes NamedSecuritySchemes #/components/securitySchemes
+      OAuth2 SecurityScheme #/components/securitySchemes/OAuth2
+      ApiKey SecurityScheme #/components/securitySchemes/ApiKey
+
+Document: cafe.yaml map:
+
diff --git a/tests/e2e/map/map.test.ts b/tests/e2e/map/map.test.ts
new file mode 100644
index 0000000000..9b246a720a
--- /dev/null
+++ b/tests/e2e/map/map.test.ts
@@ -0,0 +1,44 @@
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { getCommandOutput, getParams, cleanupOutput } from '../helpers.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const indexEntryPoint = join(process.cwd(), 'packages/cli/lib/index.js');
+
+describe('map', () => {
+  const folderPath = __dirname;
+
+  test('map should produce correct output (stylish format)', async () => {
+    const testPath = join(folderPath, 'map-stylish');
+    const args = getParams(indexEntryPoint, ['map', 'cafe.yaml']);
+    const result = getCommandOutput(args, { testPath });
+    await expect(cleanupOutput(result)).toMatchFileSnapshot(join(testPath, 'snapshot.txt'));
+  });
+
+  test('map should produce correct JSON output with source locations', async () => {
+    const testPath = join(folderPath, 'map-json');
+    const args = getParams(indexEntryPoint, [
+      'map',
+      'openapi.yaml',
+      '--format=json',
+      '--source-locations',
+    ]);
+    const result = getCommandOutput(args, { testPath });
+    await expect(cleanupOutput(result)).toMatchFileSnapshot(join(testPath, 'snapshot.txt'));
+  });
+
+  test('map should support AsyncAPI 2.x (stylish format)', async () => {
+    const testPath = join(folderPath, 'map-async2-stylish');
+    const args = getParams(indexEntryPoint, ['map', 'async.yaml']);
+    const result = getCommandOutput(args, { testPath });
+    await expect(cleanupOutput(result)).toMatchFileSnapshot(join(testPath, 'snapshot.txt'));
+  });
+
+  test('map should support AsyncAPI 3.0 (stylish format)', async () => {
+    const testPath = join(folderPath, 'map-async3-stylish');
+    const args = getParams(indexEntryPoint, ['map', 'asyncapi3.yaml']);
+    const result = getCommandOutput(args, { testPath });
+    await expect(cleanupOutput(result)).toMatchFileSnapshot(join(testPath, 'snapshot.txt'));
+  });
+});
diff --git a/vitest.config.ts b/vitest.config.ts
index f3f67f308c..8451a21595 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -22,7 +22,7 @@ const configExtension: { [key: string]: ViteUserConfig } = {
         thresholds: {
           lines: 81,
           functions: 84,
-          statements: 81,
+          statements: 80,
           branches: 73,
         },
       },

From c839cc444ed7f2c590a7827c4e93d50cd45589d7 Mon Sep 17 00:00:00 2001
From: Andrew Tatomyr <andrew.tatomyr@redocly.com>
Date: Tue, 7 Jul 2026 11:44:21 +0300
Subject: [PATCH 2/4] add locations and pointer

---
 docs/@v2/commands/map.md                      | 34 ++++++++++--
 docs/adr/0002-pointer-retrieval-keeps-refs.md | 16 ++++++
 packages/cli/src/commands/map/index.ts        | 22 ++++++++
 .../cli/src/commands/map/print-map/stylish.ts |  4 +-
 packages/cli/src/index.ts                     |  4 ++
 .../api-map/__tests__/build-api-map.test.ts   | 10 ++--
 packages/core/src/api-map/build-api-map.ts    |  4 +-
 packages/core/src/api-map/hooks.ts            | 19 +++++--
 packages/core/src/api-map/resolve-pointer.ts  | 55 +++++++++++++++++++
 packages/core/src/api-map/types.ts            |  2 +
 packages/core/src/index.ts                    |  1 +
 tests/e2e/map/map-json/openapi.yaml           |  2 +-
 tests/e2e/map/map-json/snapshot.txt           | 34 +++++++++---
 .../map/map-pointer/components/menu-item.yaml |  2 +
 tests/e2e/map/map-pointer/openapi.yaml        | 12 ++++
 tests/e2e/map/map-pointer/paths/menu.yaml     |  3 +
 .../map/map-pointer/snapshot-not-found.txt    |  3 +
 tests/e2e/map/map-pointer/snapshot.txt        |  4 ++
 tests/e2e/map/map.test.ts                     | 16 ++++++
 19 files changed, 221 insertions(+), 26 deletions(-)
 create mode 100644 docs/adr/0002-pointer-retrieval-keeps-refs.md
 create mode 100644 packages/core/src/api-map/resolve-pointer.ts
 create mode 100644 tests/e2e/map/map-pointer/components/menu-item.yaml
 create mode 100644 tests/e2e/map/map-pointer/openapi.yaml
 create mode 100644 tests/e2e/map/map-pointer/paths/menu.yaml
 create mode 100644 tests/e2e/map/map-pointer/snapshot-not-found.txt
 create mode 100644 tests/e2e/map/map-pointer/snapshot.txt

diff --git a/docs/@v2/commands/map.md b/docs/@v2/commands/map.md
index 90c9781935..5118e6a222 100644
--- a/docs/@v2/commands/map.md
+++ b/docs/@v2/commands/map.md
@@ -27,7 +27,7 @@ Each node has the following fields:
 | summary | string | Optional. The node's `summary` field, or its `description` truncated at a word boundary (about 200 characters).                                                                          |
 | method  | string | Optional. HTTP method; present on OpenAPI `Operation` nodes only.                                                                                                                        |
 | path    | string | Optional. URL path; present on OpenAPI `Operation` nodes under `paths` only.                                                                                                             |
-| source  | object | Optional. Original `{ file, pointer }` location of the node; present when `--source-locations` is used.                                                                                  |
+| source  | object | Optional. Original `{ file, pointer, startLine, endLine }` location of the node; present when `--source-locations` is used.                                                              |
 | nodes   | array  | Child nodes.                                                                                                                                                                             |
 
 The tree stops at operations, channels, and named components;
@@ -44,6 +44,7 @@ use `--source-locations` when you need the exact file and location of each node.
 ```bash
 redocly map <api>
 redocly map <api> [--format=<option>] [--source-locations] [--config=<path>]
+redocly map <api> --pointer=<json-pointer>
 redocly map --version
 ```
 
@@ -56,7 +57,8 @@ redocly map --version
 | --format           | string  | Format for the output.<br />**Possible values:** `stylish`, `json`. Default value is `stylish`.                                    |
 | --help             | boolean | Show help.                                                                                                                         |
 | --lint-config      | string  | Specify the severity level for the configuration file. <br/> **Possible values:** `warn`, `error`, `off`. Default value is `warn`. |
-| --source-locations | boolean | Include the original source file and pointer for each node. Useful for multi-file descriptions.                                    |
+| --pointer          | string  | Print the content at the given JSON pointer instead of the map. YAML by default; JSON with `--format=json`.                        |
+| --source-locations | boolean | Include the original source file, pointer, and line range for each node. Useful for multi-file descriptions.                       |
 | --version          | boolean | Show version number.                                                                                                               |
 
 ## Examples
@@ -136,11 +138,35 @@ redocly map openapi.yaml --format=json --source-locations
   "pointer": "#/paths/~1menu",
   "source": {
     "file": "paths/menu.yaml",
-    "pointer": "#/"
+    "pointer": "#/",
+    "startLine": 1,
+    "endLine": 3
   },
   "nodes": []
 }
 ```
 
 The `pointer` stays canonical to the logical document,
-while `source` tells you which file the node actually lives in.
+while `source` tells you which file and lines the node actually lives in —
+so any tool that can read a file range can retrieve the node's content.
+
+### Retrieve the content of a node
+
+Use `--pointer` with a canonical pointer from the map to print that node's content
+instead of the map itself:
+
+```bash
+redocly map openapi.yaml --pointer=#/paths/~1menu
+```
+
+```yaml
+get:
+  operationId: listMenuItems
+  summary: List all menu items
+```
+
+The node itself is resolved (a path item referenced from another file prints that file's content),
+and `$ref`s inside the printed content are kept as-is —
+follow them with further `--pointer` calls.
+Any pointer into the logical document works, including paths deeper than the map's nodes,
+for example `--pointer=#/paths/~1menu/get/summary`.
diff --git a/docs/adr/0002-pointer-retrieval-keeps-refs.md b/docs/adr/0002-pointer-retrieval-keeps-refs.md
new file mode 100644
index 0000000000..1bf3bbe64f
--- /dev/null
+++ b/docs/adr/0002-pointer-retrieval-keeps-refs.md
@@ -0,0 +1,16 @@
+# Pointer retrieval keeps `$ref`s intact
+
+`redocly map --pointer=<json-pointer>` closes the retrieval half of the map's index-navigate-retrieve loop:
+it prints the logical content at any canonical pointer, resolving the addressed node itself
+(a path item that is a file `$ref` prints the target file's content)
+but leaving `$ref`s inside the printed content untouched.
+
+We chose not to inline the subtree:
+inlining duplicates shared schemas across fetches, needs cycle guards for recursive schemas,
+and can silently explode output size.
+Keeping refs is honest and cycle-proof — the consumer follows them with further `--pointer` calls,
+guided by the map.
+
+Source locations additionally carry `startLine`/`endLine`
+(computed from the same YAML AST positions the lint codeframes use),
+so consumers with plain file tools can retrieve node content without any JSON-pointer tooling.
diff --git a/packages/cli/src/commands/map/index.ts b/packages/cli/src/commands/map/index.ts
index cd510a3529..ce1b1a2af9 100644
--- a/packages/cli/src/commands/map/index.ts
+++ b/packages/cli/src/commands/map/index.ts
@@ -3,6 +3,9 @@ import {
   buildApiMap,
   detectSpec,
   getMajorSpecVersion,
+  logger,
+  resolveApiMapPointer,
+  stringifyYaml,
   type Document,
   type OutputFormat,
 } from '@redocly/openapi-core';
@@ -19,6 +22,7 @@ export type MapArgv = {
   api?: string;
   format: OutputFormat;
   'source-locations'?: boolean;
+  pointer?: string;
 } & VerifyConfigOptions;
 
 export async function handleMap({ argv, config, collectSpecData }: CommandArgs<MapArgv>) {
@@ -40,6 +44,24 @@ export async function handleMap({ argv, config, collectSpecData }: CommandArgs<M
     );
   }
 
+  if (argv.pointer) {
+    const content = await resolveApiMapPointer({
+      document,
+      config,
+      externalRefResolver,
+      pointer: argv.pointer,
+    });
+    if (content === undefined) {
+      exitWithError(
+        `No content found at pointer ${argv.pointer}. Run the command without --pointer to see the available nodes.`
+      );
+    }
+    logger.output(
+      argv.format === 'json' ? JSON.stringify(content, null, 2) : stringifyYaml(content)
+    );
+    return;
+  }
+
   const apiMap = await buildApiMap({
     document,
     config,
diff --git a/packages/cli/src/commands/map/print-map/stylish.ts b/packages/cli/src/commands/map/print-map/stylish.ts
index b9540cd125..f60b88513d 100644
--- a/packages/cli/src/commands/map/print-map/stylish.ts
+++ b/packages/cli/src/commands/map/print-map/stylish.ts
@@ -3,7 +3,9 @@ import * as colors from 'colorette';
 
 export function printApiMapStylish(node: ApiMapNode, depth = 0) {
   const indent = '  '.repeat(depth);
-  const source = node.source ? colors.dim(` (${node.source.file}${node.source.pointer})`) : '';
+  const source = node.source
+    ? colors.dim(` (${node.source.file}:${node.source.startLine}-${node.source.endLine})`)
+    : '';
   logger.output(
     `${indent}${node.title} ${colors.dim(node.kind)} ${colors.cyan(node.pointer)}${source}\n`
   );
diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts
index 3159d7d88d..6c5a7c37f6 100644
--- a/packages/cli/src/index.ts
+++ b/packages/cli/src/index.ts
@@ -103,6 +103,10 @@ yargs(hideBin(process.argv))
             type: 'boolean',
             default: false,
           },
+          pointer: {
+            description: 'Print the content at the given JSON pointer instead of the map.',
+            type: 'string',
+          },
         }),
     (argv) => {
       commandWrapper(handleMap)(argv);
diff --git a/packages/core/src/api-map/__tests__/build-api-map.test.ts b/packages/core/src/api-map/__tests__/build-api-map.test.ts
index 46f1780d95..0053d88792 100644
--- a/packages/core/src/api-map/__tests__/build-api-map.test.ts
+++ b/packages/core/src/api-map/__tests__/build-api-map.test.ts
@@ -455,7 +455,7 @@ describe('buildApiMap', () => {
         title: '/menu',
         kind: 'PathItem',
         pointer: '#/paths/~1menu',
-        source: { file: 'paths/menu.yaml', pointer: '#/' },
+        source: { file: 'paths/menu.yaml', pointer: '#/', startLine: 1, endLine: 2 },
         nodes: [
           {
             title: 'listMenuItems',
@@ -463,7 +463,7 @@ describe('buildApiMap', () => {
             pointer: '#/paths/~1menu/get',
             method: 'get',
             path: '/menu',
-            source: { file: 'paths/menu.yaml', pointer: '#/get' },
+            source: { file: 'paths/menu.yaml', pointer: '#/get', startLine: 2, endLine: 2 },
             nodes: [],
           },
         ],
@@ -472,7 +472,7 @@ describe('buildApiMap', () => {
         title: '/menu-archive',
         kind: 'PathItem',
         pointer: '#/paths/~1menu-archive',
-        source: { file: 'paths/menu.yaml', pointer: '#/' },
+        source: { file: 'paths/menu.yaml', pointer: '#/', startLine: 1, endLine: 2 },
         nodes: [
           {
             title: 'listMenuItems',
@@ -480,7 +480,7 @@ describe('buildApiMap', () => {
             pointer: '#/paths/~1menu-archive/get',
             method: 'get',
             path: '/menu-archive',
-            source: { file: 'paths/menu.yaml', pointer: '#/get' },
+            source: { file: 'paths/menu.yaml', pointer: '#/get', startLine: 2, endLine: 2 },
             nodes: [],
           },
         ],
@@ -494,7 +494,7 @@ describe('buildApiMap', () => {
         kind: 'Schema',
         pointer: '#/components/schemas/MenuItem',
         summary: 'A menu item.',
-        source: { file: 'components/menu-item.yaml', pointer: '#/' },
+        source: { file: 'components/menu-item.yaml', pointer: '#/', startLine: 1, endLine: 2 },
         nodes: [],
       },
     ]);
diff --git a/packages/core/src/api-map/build-api-map.ts b/packages/core/src/api-map/build-api-map.ts
index 0a6a4498ae..45bac3cec5 100644
--- a/packages/core/src/api-map/build-api-map.ts
+++ b/packages/core/src/api-map/build-api-map.ts
@@ -1,6 +1,7 @@
 import type { Config } from '../config/index.js';
 import { detectSpec } from '../detect-spec.js';
 import { getTypes } from '../oas-types.js';
+import { Location } from '../ref-utils.js';
 import { BaseResolver, resolveDocument, type Document } from '../resolve.js';
 import { normalizeTypes } from '../types/index.js';
 import {
@@ -13,6 +14,7 @@ import {
 } from '../visitors.js';
 import { walkDocument, type WalkContext } from '../walk.js';
 import { ApiMapAsync2, ApiMapAsync3 } from './async.js';
+import { makeSourceLocation } from './hooks.js';
 import { ApiMapOAS2, ApiMapOAS3 } from './oas.js';
 import type { ApiMapNode } from './types.js';
 
@@ -32,7 +34,7 @@ export async function buildApiMap({
     title: 'API',
     kind: 'Root',
     pointer: '#/',
-    ...(sourceLocations && { source: { file: document.source.absoluteRef, pointer: '#/' } }),
+    ...(sourceLocations && { source: makeSourceLocation(new Location(document.source, '#/')) }),
     nodes: [],
   };
 
diff --git a/packages/core/src/api-map/hooks.ts b/packages/core/src/api-map/hooks.ts
index 77ff54465c..637a25fb51 100644
--- a/packages/core/src/api-map/hooks.ts
+++ b/packages/core/src/api-map/hooks.ts
@@ -1,7 +1,18 @@
-import { escapePointerFragment } from '../ref-utils.js';
+import { getLineColLocation } from '../format/codeframes.js';
+import { escapePointerFragment, type Location } from '../ref-utils.js';
 import { isPlainObject } from '../utils/is-plain-object.js';
 import type { UserContext } from '../walk.js';
-import type { ApiMapNode, ApiMapOptions } from './types.js';
+import type { ApiMapNode, ApiMapNodeSource, ApiMapOptions } from './types.js';
+
+export function makeSourceLocation(location: Location): ApiMapNodeSource {
+  const { start, end } = getLineColLocation(location);
+  return {
+    file: location.source.absoluteRef,
+    pointer: location.pointer,
+    startLine: start?.line ?? 1,
+    endLine: end?.line ?? start?.line ?? 1,
+  };
+}
 
 const SUMMARY_MAX_LENGTH = 200;
 
@@ -38,9 +49,7 @@ export function createApiMapHooks(root: ApiMapNode, opts: ApiMapOptions) {
       ...(init.summary && { summary: init.summary }),
       ...(init.method && { method: init.method }),
       ...(init.path && { path: init.path }),
-      ...(opts.sourceLocations && {
-        source: { file: ctx.location.source.absoluteRef, pointer: ctx.location.pointer },
-      }),
+      ...(opts.sourceLocations && { source: makeSourceLocation(ctx.location) }),
       nodes: [],
     };
     parentNode.nodes.push(node);
diff --git a/packages/core/src/api-map/resolve-pointer.ts b/packages/core/src/api-map/resolve-pointer.ts
new file mode 100644
index 0000000000..da4431749d
--- /dev/null
+++ b/packages/core/src/api-map/resolve-pointer.ts
@@ -0,0 +1,55 @@
+import type { Config } from '../config/index.js';
+import { detectSpec } from '../detect-spec.js';
+import { getTypes } from '../oas-types.js';
+import { isRef, parsePointer } from '../ref-utils.js';
+import { BaseResolver, resolveDocument, type Document } from '../resolve.js';
+import { normalizeTypes } from '../types/index.js';
+import { isPlainObject } from '../utils/is-plain-object.js';
+import { makeRefId } from '../utils/make-ref-id.js';
+
+export async function resolveApiMapPointer({
+  document,
+  config,
+  externalRefResolver = new BaseResolver(config.resolve),
+  pointer,
+}: {
+  document: Document;
+  config: Config;
+  externalRefResolver?: BaseResolver;
+  pointer: string;
+}): Promise<unknown> {
+  const specVersion = detectSpec(document.parsed);
+  const types = normalizeTypes(config.extendTypes(getTypes(specVersion), specVersion), config);
+  const resolvedRefMap = await resolveDocument({
+    rootDocument: document,
+    rootType: types.Root,
+    externalRefResolver,
+  });
+
+  let current: unknown = document.parsed;
+  let fromFile = document.source.absoluteRef;
+
+  const followRefs = () => {
+    while (isRef(current)) {
+      const resolvedRef = resolvedRefMap.get(makeRefId(fromFile, current.$ref));
+      if (!resolvedRef?.resolved) return false;
+      current = resolvedRef.node;
+      fromFile = resolvedRef.document.source.absoluteRef;
+    }
+    return true;
+  };
+
+  for (const segment of parsePointer(pointer.replace(/^#\//, ''))) {
+    if (!followRefs()) return undefined;
+    if (Array.isArray(current)) {
+      current = current[Number(segment)];
+    } else if (isPlainObject(current)) {
+      current = current[segment];
+    } else {
+      return undefined;
+    }
+    if (current === undefined) return undefined;
+  }
+
+  return followRefs() ? current : undefined;
+}
diff --git a/packages/core/src/api-map/types.ts b/packages/core/src/api-map/types.ts
index 318b1661d2..93cf071c38 100644
--- a/packages/core/src/api-map/types.ts
+++ b/packages/core/src/api-map/types.ts
@@ -1,6 +1,8 @@
 export type ApiMapNodeSource = {
   file: string;
   pointer: string;
+  startLine: number;
+  endLine: number;
 };
 
 export type ApiMapNode = {
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 4b23f96536..a698b18bed 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -124,6 +124,7 @@ export { lint, lint as validate, lintDocument, lintFromString, lintConfig } from
 export { lintEntityFile, lintEntityWithScorecardLevel, lintSchema } from './lint-entity.js';
 export { bundle, bundleFromString, type BundleResult } from './bundle/bundle.js';
 export { buildApiMap } from './api-map/build-api-map.js';
+export { resolveApiMapPointer } from './api-map/resolve-pointer.js';
 export type { ApiMapNode, ApiMapNodeSource } from './api-map/types.js';
 export { bundleDocument, type ComponentNamesStrategy } from './bundle/bundle-document.js';
 export { mapTypeToComponent } from './bundle/bundle-visitor.js';
diff --git a/tests/e2e/map/map-json/openapi.yaml b/tests/e2e/map/map-json/openapi.yaml
index bfb55fab81..36c88ec911 100644
--- a/tests/e2e/map/map-json/openapi.yaml
+++ b/tests/e2e/map/map-json/openapi.yaml
@@ -2,7 +2,7 @@ openapi: 3.0.0
 info:
   title: Redocly Cafe
   version: 1.0.0
-  description: A small multi-file cafe API used to test TOC generation.
+  description: A small multi-file cafe API used to test API map generation.
 paths:
   /menu:
     $ref: ./paths/menu.yaml
diff --git a/tests/e2e/map/map-json/snapshot.txt b/tests/e2e/map/map-json/snapshot.txt
index 7f2c6cc6d7..cdf3abe958 100644
--- a/tests/e2e/map/map-json/snapshot.txt
+++ b/tests/e2e/map/map-json/snapshot.txt
@@ -4,17 +4,21 @@
   "pointer": "#/",
   "source": {
     "file": "./tests/e2e/map/map-json/openapi.yaml",
-    "pointer": "#/"
+    "pointer": "#/",
+    "startLine": 1,
+    "endLine": 12
   },
   "nodes": [
     {
       "title": "Redocly Cafe",
       "kind": "Info",
       "pointer": "#/info",
-      "summary": "A small multi-file cafe API used to test TOC generation.",
+      "summary": "A small multi-file cafe API used to test API map generation.",
       "source": {
         "file": "./tests/e2e/map/map-json/openapi.yaml",
-        "pointer": "#/info"
+        "pointer": "#/info",
+        "startLine": 3,
+        "endLine": 5
       },
       "nodes": []
     },
@@ -24,7 +28,9 @@
       "pointer": "#/paths",
       "source": {
         "file": "./tests/e2e/map/map-json/openapi.yaml",
-        "pointer": "#/paths"
+        "pointer": "#/paths",
+        "startLine": 7,
+        "endLine": 8
       },
       "nodes": [
         {
@@ -33,7 +39,9 @@
           "pointer": "#/paths/~1menu",
           "source": {
             "file": "./tests/e2e/map/map-json/paths/menu.yaml",
-            "pointer": "#/"
+            "pointer": "#/",
+            "startLine": 1,
+            "endLine": 3
           },
           "nodes": [
             {
@@ -45,7 +53,9 @@
               "path": "/menu",
               "source": {
                 "file": "./tests/e2e/map/map-json/paths/menu.yaml",
-                "pointer": "#/get"
+                "pointer": "#/get",
+                "startLine": 2,
+                "endLine": 3
               },
               "nodes": []
             }
@@ -59,7 +69,9 @@
       "pointer": "#/components",
       "source": {
         "file": "./tests/e2e/map/map-json/openapi.yaml",
-        "pointer": "#/components"
+        "pointer": "#/components",
+        "startLine": 10,
+        "endLine": 12
       },
       "nodes": [
         {
@@ -68,7 +80,9 @@
           "pointer": "#/components/schemas",
           "source": {
             "file": "./tests/e2e/map/map-json/openapi.yaml",
-            "pointer": "#/components/schemas"
+            "pointer": "#/components/schemas",
+            "startLine": 11,
+            "endLine": 12
           },
           "nodes": [
             {
@@ -78,7 +92,9 @@
               "summary": "A menu item.",
               "source": {
                 "file": "./tests/e2e/map/map-json/components/menu-item.yaml",
-                "pointer": "#/"
+                "pointer": "#/",
+                "startLine": 1,
+                "endLine": 2
               },
               "nodes": []
             }
diff --git a/tests/e2e/map/map-pointer/components/menu-item.yaml b/tests/e2e/map/map-pointer/components/menu-item.yaml
new file mode 100644
index 0000000000..5bb358faf8
--- /dev/null
+++ b/tests/e2e/map/map-pointer/components/menu-item.yaml
@@ -0,0 +1,2 @@
+type: object
+description: A menu item.
diff --git a/tests/e2e/map/map-pointer/openapi.yaml b/tests/e2e/map/map-pointer/openapi.yaml
new file mode 100644
index 0000000000..36c88ec911
--- /dev/null
+++ b/tests/e2e/map/map-pointer/openapi.yaml
@@ -0,0 +1,12 @@
+openapi: 3.0.0
+info:
+  title: Redocly Cafe
+  version: 1.0.0
+  description: A small multi-file cafe API used to test API map generation.
+paths:
+  /menu:
+    $ref: ./paths/menu.yaml
+components:
+  schemas:
+    MenuItem:
+      $ref: ./components/menu-item.yaml
diff --git a/tests/e2e/map/map-pointer/paths/menu.yaml b/tests/e2e/map/map-pointer/paths/menu.yaml
new file mode 100644
index 0000000000..d14afe468d
--- /dev/null
+++ b/tests/e2e/map/map-pointer/paths/menu.yaml
@@ -0,0 +1,3 @@
+get:
+  operationId: listMenuItems
+  summary: List all menu items
diff --git a/tests/e2e/map/map-pointer/snapshot-not-found.txt b/tests/e2e/map/map-pointer/snapshot-not-found.txt
new file mode 100644
index 0000000000..447156baab
--- /dev/null
+++ b/tests/e2e/map/map-pointer/snapshot-not-found.txt
@@ -0,0 +1,3 @@
+
+No content found at pointer #/paths/~1nope. Run the command without --pointer to see the available nodes.
+
diff --git a/tests/e2e/map/map-pointer/snapshot.txt b/tests/e2e/map/map-pointer/snapshot.txt
new file mode 100644
index 0000000000..ebd9bbc682
--- /dev/null
+++ b/tests/e2e/map/map-pointer/snapshot.txt
@@ -0,0 +1,4 @@
+get:
+  operationId: listMenuItems
+  summary: List all menu items
+
diff --git a/tests/e2e/map/map.test.ts b/tests/e2e/map/map.test.ts
index 9b246a720a..8c49c757d3 100644
--- a/tests/e2e/map/map.test.ts
+++ b/tests/e2e/map/map.test.ts
@@ -28,6 +28,22 @@ describe('map', () => {
     await expect(cleanupOutput(result)).toMatchFileSnapshot(join(testPath, 'snapshot.txt'));
   });
 
+  test('map should retrieve the content at a pointer', async () => {
+    const testPath = join(folderPath, 'map-pointer');
+    const args = getParams(indexEntryPoint, ['map', 'openapi.yaml', '--pointer=#/paths/~1menu']);
+    const result = getCommandOutput(args, { testPath });
+    await expect(cleanupOutput(result)).toMatchFileSnapshot(join(testPath, 'snapshot.txt'));
+  });
+
+  test('map should report an error for an unknown pointer', async () => {
+    const testPath = join(folderPath, 'map-pointer');
+    const args = getParams(indexEntryPoint, ['map', 'openapi.yaml', '--pointer=#/paths/~1nope']);
+    const result = getCommandOutput(args, { testPath });
+    await expect(cleanupOutput(result)).toMatchFileSnapshot(
+      join(testPath, 'snapshot-not-found.txt')
+    );
+  });
+
   test('map should support AsyncAPI 2.x (stylish format)', async () => {
     const testPath = join(folderPath, 'map-async2-stylish');
     const args = getParams(indexEntryPoint, ['map', 'async.yaml']);

From 87b1e62eb9267bf1f760ea51fffafa2f9199c346 Mon Sep 17 00:00:00 2001
From: Andrew Tatomyr <andrew.tatomyr@redocly.com>
Date: Tue, 7 Jul 2026 14:52:56 +0300
Subject: [PATCH 3/4] add line:col position

---
 docs/@v2/commands/map.md                      |  12 +-
 .../cli/src/commands/map/print-map/stylish.ts |   4 +-
 .../api-map/__tests__/build-api-map.test.ts   |  45 ++++++-
 packages/core/src/api-map/hooks.ts            |   2 +
 packages/core/src/api-map/types.ts            |   2 +
 tests/e2e/map/map-json-file/cafe.json         |   8 ++
 tests/e2e/map/map-json-file/snapshot.txt      | 120 ++++++++++++++++++
 tests/e2e/map/map-json/snapshot.txt           |  32 +++--
 tests/e2e/map/map.test.ts                     |  12 ++
 9 files changed, 219 insertions(+), 18 deletions(-)
 create mode 100644 tests/e2e/map/map-json-file/cafe.json
 create mode 100644 tests/e2e/map/map-json-file/snapshot.txt

diff --git a/docs/@v2/commands/map.md b/docs/@v2/commands/map.md
index 5118e6a222..4ad89ab4e1 100644
--- a/docs/@v2/commands/map.md
+++ b/docs/@v2/commands/map.md
@@ -27,7 +27,7 @@ Each node has the following fields:
 | summary | string | Optional. The node's `summary` field, or its `description` truncated at a word boundary (about 200 characters).                                                                          |
 | method  | string | Optional. HTTP method; present on OpenAPI `Operation` nodes only.                                                                                                                        |
 | path    | string | Optional. URL path; present on OpenAPI `Operation` nodes under `paths` only.                                                                                                             |
-| source  | object | Optional. Original `{ file, pointer, startLine, endLine }` location of the node; present when `--source-locations` is used.                                                              |
+| source  | object | Optional. Original `{ file, pointer, startLine, startCol, endLine, endCol }` location of the node; present when `--source-locations` is used.                                            |
 | nodes   | array  | Child nodes.                                                                                                                                                                             |
 
 The tree stops at operations, channels, and named components;
@@ -58,7 +58,7 @@ redocly map --version
 | --help             | boolean | Show help.                                                                                                                         |
 | --lint-config      | string  | Specify the severity level for the configuration file. <br/> **Possible values:** `warn`, `error`, `off`. Default value is `warn`. |
 | --pointer          | string  | Print the content at the given JSON pointer instead of the map. YAML by default; JSON with `--format=json`.                        |
-| --source-locations | boolean | Include the original source file, pointer, and line range for each node. Useful for multi-file descriptions.                       |
+| --source-locations | boolean | Include the original source file, pointer, and line/column range for each node. Useful for multi-file descriptions.                |
 | --version          | boolean | Show version number.                                                                                                               |
 
 ## Examples
@@ -140,15 +140,19 @@ redocly map openapi.yaml --format=json --source-locations
     "file": "paths/menu.yaml",
     "pointer": "#/",
     "startLine": 1,
-    "endLine": 3
+    "startCol": 1,
+    "endLine": 3,
+    "endCol": 24
   },
   "nodes": []
 }
 ```
 
 The `pointer` stays canonical to the logical document,
-while `source` tells you which file and lines the node actually lives in —
+while `source` tells you exactly where the node lives —
 so any tool that can read a file range can retrieve the node's content.
+Column boundaries make the location universal across formats:
+for a JSON description on a single line, the columns give the exact span of each node.
 
 ### Retrieve the content of a node
 
diff --git a/packages/cli/src/commands/map/print-map/stylish.ts b/packages/cli/src/commands/map/print-map/stylish.ts
index f60b88513d..9b2171d33c 100644
--- a/packages/cli/src/commands/map/print-map/stylish.ts
+++ b/packages/cli/src/commands/map/print-map/stylish.ts
@@ -4,7 +4,9 @@ import * as colors from 'colorette';
 export function printApiMapStylish(node: ApiMapNode, depth = 0) {
   const indent = '  '.repeat(depth);
   const source = node.source
-    ? colors.dim(` (${node.source.file}:${node.source.startLine}-${node.source.endLine})`)
+    ? colors.dim(
+        ` (${node.source.file}:${node.source.startLine}:${node.source.startCol}-${node.source.endLine}:${node.source.endCol})`
+      )
     : '';
   logger.output(
     `${indent}${node.title} ${colors.dim(node.kind)} ${colors.cyan(node.pointer)}${source}\n`
diff --git a/packages/core/src/api-map/__tests__/build-api-map.test.ts b/packages/core/src/api-map/__tests__/build-api-map.test.ts
index 0053d88792..2d8a114031 100644
--- a/packages/core/src/api-map/__tests__/build-api-map.test.ts
+++ b/packages/core/src/api-map/__tests__/build-api-map.test.ts
@@ -455,7 +455,14 @@ describe('buildApiMap', () => {
         title: '/menu',
         kind: 'PathItem',
         pointer: '#/paths/~1menu',
-        source: { file: 'paths/menu.yaml', pointer: '#/', startLine: 1, endLine: 2 },
+        source: {
+          file: 'paths/menu.yaml',
+          pointer: '#/',
+          startLine: 1,
+          startCol: 1,
+          endLine: 2,
+          endCol: 30,
+        },
         nodes: [
           {
             title: 'listMenuItems',
@@ -463,7 +470,14 @@ describe('buildApiMap', () => {
             pointer: '#/paths/~1menu/get',
             method: 'get',
             path: '/menu',
-            source: { file: 'paths/menu.yaml', pointer: '#/get', startLine: 2, endLine: 2 },
+            source: {
+              file: 'paths/menu.yaml',
+              pointer: '#/get',
+              startLine: 2,
+              startCol: 3,
+              endLine: 2,
+              endCol: 29,
+            },
             nodes: [],
           },
         ],
@@ -472,7 +486,14 @@ describe('buildApiMap', () => {
         title: '/menu-archive',
         kind: 'PathItem',
         pointer: '#/paths/~1menu-archive',
-        source: { file: 'paths/menu.yaml', pointer: '#/', startLine: 1, endLine: 2 },
+        source: {
+          file: 'paths/menu.yaml',
+          pointer: '#/',
+          startLine: 1,
+          startCol: 1,
+          endLine: 2,
+          endCol: 30,
+        },
         nodes: [
           {
             title: 'listMenuItems',
@@ -480,7 +501,14 @@ describe('buildApiMap', () => {
             pointer: '#/paths/~1menu-archive/get',
             method: 'get',
             path: '/menu-archive',
-            source: { file: 'paths/menu.yaml', pointer: '#/get', startLine: 2, endLine: 2 },
+            source: {
+              file: 'paths/menu.yaml',
+              pointer: '#/get',
+              startLine: 2,
+              startCol: 3,
+              endLine: 2,
+              endCol: 29,
+            },
             nodes: [],
           },
         ],
@@ -494,7 +522,14 @@ describe('buildApiMap', () => {
         kind: 'Schema',
         pointer: '#/components/schemas/MenuItem',
         summary: 'A menu item.',
-        source: { file: 'components/menu-item.yaml', pointer: '#/', startLine: 1, endLine: 2 },
+        source: {
+          file: 'components/menu-item.yaml',
+          pointer: '#/',
+          startLine: 1,
+          startCol: 1,
+          endLine: 2,
+          endCol: 27,
+        },
         nodes: [],
       },
     ]);
diff --git a/packages/core/src/api-map/hooks.ts b/packages/core/src/api-map/hooks.ts
index 637a25fb51..5e2e2f2d69 100644
--- a/packages/core/src/api-map/hooks.ts
+++ b/packages/core/src/api-map/hooks.ts
@@ -10,7 +10,9 @@ export function makeSourceLocation(location: Location): ApiMapNodeSource {
     file: location.source.absoluteRef,
     pointer: location.pointer,
     startLine: start?.line ?? 1,
+    startCol: start?.col ?? 1,
     endLine: end?.line ?? start?.line ?? 1,
+    endCol: end?.col ?? start?.col ?? 1,
   };
 }
 
diff --git a/packages/core/src/api-map/types.ts b/packages/core/src/api-map/types.ts
index 93cf071c38..49618031d6 100644
--- a/packages/core/src/api-map/types.ts
+++ b/packages/core/src/api-map/types.ts
@@ -2,7 +2,9 @@ export type ApiMapNodeSource = {
   file: string;
   pointer: string;
   startLine: number;
+  startCol: number;
   endLine: number;
+  endCol: number;
 };
 
 export type ApiMapNode = {
diff --git a/tests/e2e/map/map-json-file/cafe.json b/tests/e2e/map/map-json-file/cafe.json
new file mode 100644
index 0000000000..8a0ac5b2d7
--- /dev/null
+++ b/tests/e2e/map/map-json-file/cafe.json
@@ -0,0 +1,8 @@
+{
+  "openapi": "3.0.0",
+  "info": { "title": "Redocly Cafe", "version": "1.0.0" },
+  "paths": {
+    "/menu": { "get": { "operationId": "listMenuItems", "summary": "List all menu items" } }
+  },
+  "components": { "schemas": { "MenuItem": { "type": "object" } } }
+}
diff --git a/tests/e2e/map/map-json-file/snapshot.txt b/tests/e2e/map/map-json-file/snapshot.txt
new file mode 100644
index 0000000000..39a6e02bdc
--- /dev/null
+++ b/tests/e2e/map/map-json-file/snapshot.txt
@@ -0,0 +1,120 @@
+{
+  "title": "Redocly Cafe",
+  "kind": "Root",
+  "pointer": "#/",
+  "source": {
+    "file": "./tests/e2e/map/map-json-file/cafe.json",
+    "pointer": "#/",
+    "startLine": 1,
+    "startCol": 1,
+    "endLine": 1,
+    "endCol": 216
+  },
+  "nodes": [
+    {
+      "title": "Redocly Cafe",
+      "kind": "Info",
+      "pointer": "#/info",
+      "source": {
+        "file": "./tests/e2e/map/map-json-file/cafe.json",
+        "pointer": "#/info",
+        "startLine": 1,
+        "startCol": 27,
+        "endLine": 1,
+        "endCol": 69
+      },
+      "nodes": []
+    },
+    {
+      "title": "paths",
+      "kind": "Paths",
+      "pointer": "#/paths",
+      "source": {
+        "file": "./tests/e2e/map/map-json-file/cafe.json",
+        "pointer": "#/paths",
+        "startLine": 1,
+        "startCol": 78,
+        "endLine": 1,
+        "endCol": 159
+      },
+      "nodes": [
+        {
+          "title": "/menu",
+          "kind": "PathItem",
+          "pointer": "#/paths/~1menu",
+          "source": {
+            "file": "./tests/e2e/map/map-json-file/cafe.json",
+            "pointer": "#/paths/~1menu",
+            "startLine": 1,
+            "startCol": 87,
+            "endLine": 1,
+            "endCol": 158
+          },
+          "nodes": [
+            {
+              "title": "listMenuItems",
+              "kind": "Operation",
+              "pointer": "#/paths/~1menu/get",
+              "summary": "List all menu items",
+              "method": "get",
+              "path": "/menu",
+              "source": {
+                "file": "./tests/e2e/map/map-json-file/cafe.json",
+                "pointer": "#/paths/~1menu/get",
+                "startLine": 1,
+                "startCol": 94,
+                "endLine": 1,
+                "endCol": 157
+              },
+              "nodes": []
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "title": "components",
+      "kind": "Components",
+      "pointer": "#/components",
+      "source": {
+        "file": "./tests/e2e/map/map-json-file/cafe.json",
+        "pointer": "#/components",
+        "startLine": 1,
+        "startCol": 173,
+        "endLine": 1,
+        "endCol": 215
+      },
+      "nodes": [
+        {
+          "title": "schemas",
+          "kind": "NamedSchemas",
+          "pointer": "#/components/schemas",
+          "source": {
+            "file": "./tests/e2e/map/map-json-file/cafe.json",
+            "pointer": "#/components/schemas",
+            "startLine": 1,
+            "startCol": 184,
+            "endLine": 1,
+            "endCol": 214
+          },
+          "nodes": [
+            {
+              "title": "MenuItem",
+              "kind": "Schema",
+              "pointer": "#/components/schemas/MenuItem",
+              "source": {
+                "file": "./tests/e2e/map/map-json-file/cafe.json",
+                "pointer": "#/components/schemas/MenuItem",
+                "startLine": 1,
+                "startCol": 196,
+                "endLine": 1,
+                "endCol": 213
+              },
+              "nodes": []
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
diff --git a/tests/e2e/map/map-json/snapshot.txt b/tests/e2e/map/map-json/snapshot.txt
index cdf3abe958..5414e061ad 100644
--- a/tests/e2e/map/map-json/snapshot.txt
+++ b/tests/e2e/map/map-json/snapshot.txt
@@ -6,7 +6,9 @@
     "file": "./tests/e2e/map/map-json/openapi.yaml",
     "pointer": "#/",
     "startLine": 1,
-    "endLine": 12
+    "startCol": 1,
+    "endLine": 12,
+    "endCol": 41
   },
   "nodes": [
     {
@@ -18,7 +20,9 @@
         "file": "./tests/e2e/map/map-json/openapi.yaml",
         "pointer": "#/info",
         "startLine": 3,
-        "endLine": 5
+        "startCol": 3,
+        "endLine": 5,
+        "endCol": 76
       },
       "nodes": []
     },
@@ -30,7 +34,9 @@
         "file": "./tests/e2e/map/map-json/openapi.yaml",
         "pointer": "#/paths",
         "startLine": 7,
-        "endLine": 8
+        "startCol": 3,
+        "endLine": 8,
+        "endCol": 28
       },
       "nodes": [
         {
@@ -41,7 +47,9 @@
             "file": "./tests/e2e/map/map-json/paths/menu.yaml",
             "pointer": "#/",
             "startLine": 1,
-            "endLine": 3
+            "startCol": 1,
+            "endLine": 3,
+            "endCol": 32
           },
           "nodes": [
             {
@@ -55,7 +63,9 @@
                 "file": "./tests/e2e/map/map-json/paths/menu.yaml",
                 "pointer": "#/get",
                 "startLine": 2,
-                "endLine": 3
+                "startCol": 3,
+                "endLine": 3,
+                "endCol": 31
               },
               "nodes": []
             }
@@ -71,7 +81,9 @@
         "file": "./tests/e2e/map/map-json/openapi.yaml",
         "pointer": "#/components",
         "startLine": 10,
-        "endLine": 12
+        "startCol": 3,
+        "endLine": 12,
+        "endCol": 40
       },
       "nodes": [
         {
@@ -82,7 +94,9 @@
             "file": "./tests/e2e/map/map-json/openapi.yaml",
             "pointer": "#/components/schemas",
             "startLine": 11,
-            "endLine": 12
+            "startCol": 5,
+            "endLine": 12,
+            "endCol": 40
           },
           "nodes": [
             {
@@ -94,7 +108,9 @@
                 "file": "./tests/e2e/map/map-json/components/menu-item.yaml",
                 "pointer": "#/",
                 "startLine": 1,
-                "endLine": 2
+                "startCol": 1,
+                "endLine": 2,
+                "endCol": 27
               },
               "nodes": []
             }
diff --git a/tests/e2e/map/map.test.ts b/tests/e2e/map/map.test.ts
index 8c49c757d3..a9a5725265 100644
--- a/tests/e2e/map/map.test.ts
+++ b/tests/e2e/map/map.test.ts
@@ -28,6 +28,18 @@ describe('map', () => {
     await expect(cleanupOutput(result)).toMatchFileSnapshot(join(testPath, 'snapshot.txt'));
   });
 
+  test('map should produce column-precise locations for a JSON description', async () => {
+    const testPath = join(folderPath, 'map-json-file');
+    const args = getParams(indexEntryPoint, [
+      'map',
+      'cafe.json',
+      '--format=json',
+      '--source-locations',
+    ]);
+    const result = getCommandOutput(args, { testPath });
+    await expect(cleanupOutput(result)).toMatchFileSnapshot(join(testPath, 'snapshot.txt'));
+  });
+
   test('map should retrieve the content at a pointer', async () => {
     const testPath = join(folderPath, 'map-pointer');
     const args = getParams(indexEntryPoint, ['map', 'openapi.yaml', '--pointer=#/paths/~1menu']);

From 9138ebbe4ccbca8a63b289c1f6b930632e8e32cf Mon Sep 17 00:00:00 2001
From: Andrew Tatomyr <andrew.tatomyr@redocly.com>
Date: Tue, 7 Jul 2026 17:39:22 +0300
Subject: [PATCH 4/4] add with-ai, ai-provider, and ai-model to refine the
 output node summaries

---
 docs/@v2/commands/map.md                      |  44 ++++--
 .../0001-deterministic-api-map-generation.md  |   5 +
 packages/cli/src/commands/map/ai/prompt.ts    |  29 ++++
 packages/cli/src/commands/map/ai/providers.ts | 142 ++++++++++++++++++
 packages/cli/src/commands/map/ai/refine.ts    |  65 ++++++++
 packages/cli/src/commands/map/index.ts        |  24 +++
 packages/cli/src/index.ts                     |  18 ++-
 .../api-map/__tests__/build-api-map.test.ts   | 109 ++++++++++++++
 packages/core/src/api-map/async.ts            |  19 ++-
 packages/core/src/api-map/derive-summary.ts   |  93 ++++++++++++
 packages/core/src/api-map/hooks.ts            |  14 +-
 packages/core/src/api-map/oas.ts              |  14 +-
 tests/e2e/map/map-ai/bin-ok/claude            |   7 +
 tests/e2e/map/map-ai/openapi.yaml             |  20 +++
 tests/e2e/map/map-ai/snapshot-fallback.txt    |  58 +++++++
 tests/e2e/map/map-ai/snapshot.txt             |  58 +++++++
 tests/e2e/map/map-json-file/snapshot.txt      |  61 ++++----
 tests/e2e/map/map.test.ts                     |  39 ++++-
 18 files changed, 761 insertions(+), 58 deletions(-)
 create mode 100644 packages/cli/src/commands/map/ai/prompt.ts
 create mode 100644 packages/cli/src/commands/map/ai/providers.ts
 create mode 100644 packages/cli/src/commands/map/ai/refine.ts
 create mode 100644 packages/core/src/api-map/derive-summary.ts
 create mode 100755 tests/e2e/map/map-ai/bin-ok/claude
 create mode 100644 tests/e2e/map/map-ai/openapi.yaml
 create mode 100644 tests/e2e/map/map-ai/snapshot-fallback.txt
 create mode 100644 tests/e2e/map/map-ai/snapshot.txt

diff --git a/docs/@v2/commands/map.md b/docs/@v2/commands/map.md
index 4ad89ab4e1..1c836f4f8c 100644
--- a/docs/@v2/commands/map.md
+++ b/docs/@v2/commands/map.md
@@ -15,20 +15,21 @@ It supports OpenAPI 2.0 through 3.2 and AsyncAPI 2.x and 3.0 descriptions.
 
 The API map is designed as a compact index that tools — including LLM-based agents — can navigate to decide which parts of an API description to retrieve,
 instead of processing the whole document.
-The tree structure and node summaries are extracted deterministically from the description itself; no external services are involved.
+The tree structure and node summaries are extracted deterministically from the description itself;
+no external services are involved unless you opt into [AI refinement](#ai-providers) with `--with-ai`.
 
 Each node has the following fields:
 
-| Field   | Type   | Description                                                                                                                                                                              |
-| ------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| title   | string | Human-readable name: the API title, path, `operationId`, channel address, component name, tag name, or server URL.                                                                       |
-| kind    | string | Node type name from Redocly's internal type system, for example `Root`, `Info`, `Server`, `Tag`, `Paths`, `PathItem`, `Operation`, `Channel`, `Components`, `NamedSchemas`, or `Schema`. |
-| pointer | string | Canonical JSON pointer that identifies and addresses the node, for example `#/paths/~1menu/get`.                                                                                         |
-| summary | string | Optional. The node's `summary` field, or its `description` truncated at a word boundary (about 200 characters).                                                                          |
-| method  | string | Optional. HTTP method; present on OpenAPI `Operation` nodes only.                                                                                                                        |
-| path    | string | Optional. URL path; present on OpenAPI `Operation` nodes under `paths` only.                                                                                                             |
-| source  | object | Optional. Original `{ file, pointer, startLine, startCol, endLine, endCol }` location of the node; present when `--source-locations` is used.                                            |
-| nodes   | array  | Child nodes.                                                                                                                                                                             |
+| Field   | Type   | Description                                                                                                                                                                                                                                                                                                       |
+| ------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| title   | string | Human-readable name: the API title, path, `operationId`, channel address, component name, tag name, or server URL.                                                                                                                                                                                                |
+| kind    | string | Node type name from Redocly's internal type system, for example `Root`, `Info`, `Server`, `Tag`, `Paths`, `PathItem`, `Operation`, `Channel`, `Components`, `NamedSchemas`, or `Schema`.                                                                                                                          |
+| pointer | string | Canonical JSON pointer that identifies and addresses the node, for example `#/paths/~1menu/get`.                                                                                                                                                                                                                  |
+| summary | string | Optional. The node's `summary` field, its `description` truncated at a word boundary (about 200 characters), or a summary derived from the node's structure when neither is present — for example `Returns 200 (MenuItemList). Parameters: limit, sort.` for an operation, or `object: name, price` for a schema. |
+| method  | string | Optional. HTTP method; present on OpenAPI `Operation` nodes only.                                                                                                                                                                                                                                                 |
+| path    | string | Optional. URL path; present on OpenAPI `Operation` nodes under `paths` only.                                                                                                                                                                                                                                      |
+| source  | object | Optional. Original `{ file, pointer, startLine, startCol, endLine, endCol }` location of the node; present when `--source-locations` is used.                                                                                                                                                                     |
+| nodes   | array  | Child nodes.                                                                                                                                                                                                                                                                                                      |
 
 The tree stops at operations, channels, and named components;
 parameters, responses, messages payloads, and schema internals are the node's content, retrievable through its pointer.
@@ -45,6 +46,7 @@ use `--source-locations` when you need the exact file and location of each node.
 redocly map <api>
 redocly map <api> [--format=<option>] [--source-locations] [--config=<path>]
 redocly map <api> --pointer=<json-pointer>
+redocly map <api> --with-ai [--ai-provider=<provider>] [--ai-model=<model>]
 redocly map --version
 ```
 
@@ -53,6 +55,8 @@ redocly map --version
 | Option             | Type    | Description                                                                                                                        |
 | ------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------- |
 | api                | string  | **REQUIRED.** Path to the API description filename or alias that you want to generate the map for.                                 |
+| --ai-model         | string  | Model passed to the selected AI provider (provider-specific default applies).                                                      |
+| --ai-provider      | string  | AI provider used with `--with-ai`.<br />**Possible values:** `openai`, `claude`, `codex`. Default value is `claude`.               |
 | --config           | string  | Specify path to the [configuration file](../configuration/index.md).                                                               |
 | --format           | string  | Format for the output.<br />**Possible values:** `stylish`, `json`. Default value is `stylish`.                                    |
 | --help             | boolean | Show help.                                                                                                                         |
@@ -60,6 +64,7 @@ redocly map --version
 | --pointer          | string  | Print the content at the given JSON pointer instead of the map. YAML by default; JSON with `--format=json`.                        |
 | --source-locations | boolean | Include the original source file, pointer, and line/column range for each node. Useful for multi-file descriptions.                |
 | --version          | boolean | Show version number.                                                                                                               |
+| --with-ai          | boolean | Refine node summaries with an AI provider. See [AI providers](#ai-providers).                                                      |
 
 ## Examples
 
@@ -154,6 +159,23 @@ so any tool that can read a file range can retrieve the node's content.
 Column boundaries make the location universal across formats:
 for a JSON description on a single line, the columns give the exact span of each node.
 
+## AI providers
+
+By default the map is fully deterministic.
+With `--with-ai`, node summaries that are missing or mechanically derived are refined by an AI provider:
+
+```bash
+redocly map openapi.yaml --with-ai --ai-provider=claude
+```
+
+The provider receives the map and the API description,
+and returns improved summaries for individual nodes; the tree structure is never changed by the provider.
+`openai` calls an OpenAI-compatible endpoint configured with `OPENAI_ENDPOINT` and `OPENAI_API_KEY`;
+`claude` and `codex` run the respective CLI, which must be installed and authenticated.
+If refinement fails for any reason, the command falls back to the deterministic map.
+
+Currently available AI models for Claude are: `claude-fable-5`, `claude-opus-4-8`, `claude-opus-4-7`, `claude-opus-4-6`, `claude-sonnet-5`, `claude-sonnet-4-6`, `claude-haiku-4-5`.
+
 ### Retrieve the content of a node
 
 Use `--pointer` with a canonical pointer from the map to print that node's content
diff --git a/docs/adr/0001-deterministic-api-map-generation.md b/docs/adr/0001-deterministic-api-map-generation.md
index 47d4ef45f3..eb73b6178e 100644
--- a/docs/adr/0001-deterministic-api-map-generation.md
+++ b/docs/adr/0001-deterministic-api-map-generation.md
@@ -18,6 +18,11 @@ because pointers are stable across regenerations and double as the retrieval add
 A node's `kind` is the internal node type name the walker reports (`PathItem`, `Operation`, `Channel`) —
 the type system is the single source of node names, per spec.
 
+## Update: opt-in AI refinement
+
+`--with-ai` (with `--ai-provider`/`--ai-model`) later added an opt-in enrichment step that asks an AI provider for improved node summaries.
+It does not change this decision: the default path stays fully deterministic, the provider can only contribute summary strings merged by pointer (never structure), and any failure falls back to the deterministic map.
+
 ## Consequences
 
 - The map's pointers address the logical document as authored; `bundle` output may store `$ref`ed components under different keys.
diff --git a/packages/cli/src/commands/map/ai/prompt.ts b/packages/cli/src/commands/map/ai/prompt.ts
new file mode 100644
index 0000000000..1c5768b847
--- /dev/null
+++ b/packages/cli/src/commands/map/ai/prompt.ts
@@ -0,0 +1,29 @@
+import type { ApiMapNode } from '@redocly/openapi-core';
+
+const SYSTEM_INSTRUCTIONS = `You are an expert API technical writer. You are given:
+1. An API map: a JSON tree index of an API description. Each node has "title", "kind", a canonical JSON "pointer", an optional "summary", and child "nodes". Some summaries are missing or were derived mechanically from structure.
+2. The API description the map was generated from.
+
+Write concise, useful summaries (plain text, at most 200 characters each) for map nodes whose current summary is missing, mechanical, or unhelpful. Base every summary strictly on the API description; do not invent behavior.
+
+Output ONLY a JSON object mapping node "pointer" values to their improved summary strings. Do not wrap it in Markdown code fences. Do not add any commentary before or after the JSON.`;
+
+export interface BuildPromptOptions {
+  apiMap: ApiMapNode;
+  description: string;
+}
+
+export function buildSummariesPrompt(options: BuildPromptOptions): {
+  system: string;
+  user: string;
+} {
+  const user = [
+    '## API map',
+    JSON.stringify(options.apiMap, null, 2),
+    '',
+    '## API description',
+    options.description,
+  ].join('\n');
+
+  return { system: SYSTEM_INSTRUCTIONS, user };
+}
diff --git a/packages/cli/src/commands/map/ai/providers.ts b/packages/cli/src/commands/map/ai/providers.ts
new file mode 100644
index 0000000000..579521b6aa
--- /dev/null
+++ b/packages/cli/src/commands/map/ai/providers.ts
@@ -0,0 +1,142 @@
+import { spawn } from 'node:child_process';
+
+export type AiProvider = 'openai' | 'claude' | 'codex';
+
+export interface ProviderRequest {
+  system: string;
+  user: string;
+  model?: string;
+}
+
+export interface ProviderResult {
+  text: string;
+}
+
+function runCommand(
+  command: string,
+  args: string[],
+  stdin: string
+): Promise<{ stdout: string; stderr: string; code: number | null }> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { stdio: ['pipe', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout.on('data', (chunk: Buffer) => {
+      stdout += chunk.toString();
+    });
+    child.stderr.on('data', (chunk: Buffer) => {
+      stderr += chunk.toString();
+    });
+    child.on('error', (error: NodeJS.ErrnoException) => {
+      if (error.code === 'ENOENT') {
+        reject(new Error(`Could not find the "${command}" CLI on PATH. Is it installed?`));
+        return;
+      }
+      reject(error);
+    });
+    child.on('close', (code) => {
+      resolve({ stdout, stderr, code });
+    });
+
+    child.stdin.end(stdin);
+  });
+}
+
+interface OpenAiChatResponse {
+  choices?: { message?: { content?: string } }[];
+  error?: { message?: string };
+}
+
+async function runOpenAi(request: ProviderRequest): Promise<ProviderResult> {
+  const endpoint = process.env.OPENAI_ENDPOINT;
+  const apiKey = process.env.OPENAI_API_KEY;
+  if (!endpoint) {
+    throw new Error('Set OPENAI_ENDPOINT to the base URL of an OpenAI-compatible API.');
+  }
+  if (!apiKey) {
+    throw new Error('Set OPENAI_API_KEY with a token for the configured OpenAI-compatible API.');
+  }
+
+  const model = request.model ?? process.env.OPENAI_MODEL ?? 'gpt-4o';
+  const url = `${endpoint.replace(/\/+$/, '')}/chat/completions`;
+
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${apiKey}`,
+    },
+    body: JSON.stringify({
+      model,
+      messages: [
+        { role: 'system', content: request.system },
+        { role: 'user', content: request.user },
+      ],
+      temperature: 0,
+    }),
+  });
+
+  const payload = (await response.json()) as OpenAiChatResponse;
+  if (!response.ok) {
+    throw new Error(
+      `OpenAI-compatible endpoint returned ${response.status}: ${
+        payload.error?.message ?? response.statusText
+      }`
+    );
+  }
+
+  const text = payload.choices?.[0]?.message?.content;
+  if (!text) {
+    throw new Error('OpenAI-compatible endpoint returned an empty completion.');
+  }
+  return { text };
+}
+
+async function runClaude(request: ProviderRequest): Promise<ProviderResult> {
+  const args = ['-p', '--output-format', 'text', '--append-system-prompt', request.system];
+  if (request.model) {
+    args.push('--model', request.model);
+  }
+  const { stdout, stderr, code } = await runCommand('claude', args, request.user);
+  if (code !== 0) {
+    throw new Error(`claude CLI exited with code ${code}: ${stderr.trim()}`);
+  }
+  if (!stdout.trim()) {
+    throw new Error('claude CLI returned no output.');
+  }
+  return { text: stdout };
+}
+
+async function runCodex(request: ProviderRequest): Promise<ProviderResult> {
+  const args = ['exec'];
+  if (request.model) {
+    args.push('--model', request.model);
+  }
+  args.push('-');
+  const prompt = `${request.system}\n\n${request.user}`;
+  const { stdout, stderr, code } = await runCommand('codex', args, prompt);
+  if (code !== 0) {
+    throw new Error(`codex CLI exited with code ${code}: ${stderr.trim()}`);
+  }
+  if (!stdout.trim()) {
+    throw new Error('codex CLI returned no output.');
+  }
+  return { text: stdout };
+}
+
+export async function runProvider(
+  provider: AiProvider,
+  request: ProviderRequest
+): Promise<ProviderResult> {
+  switch (provider) {
+    case 'openai':
+      return runOpenAi(request);
+    case 'claude':
+      return runClaude(request);
+    case 'codex':
+      return runCodex(request);
+    default:
+      throw new Error(`Unknown AI provider: ${provider}`);
+  }
+}
diff --git a/packages/cli/src/commands/map/ai/refine.ts b/packages/cli/src/commands/map/ai/refine.ts
new file mode 100644
index 0000000000..2901a0e41e
--- /dev/null
+++ b/packages/cli/src/commands/map/ai/refine.ts
@@ -0,0 +1,65 @@
+import { isPlainObject, type ApiMapNode } from '@redocly/openapi-core';
+
+import { buildSummariesPrompt } from './prompt.js';
+import { type AiProvider, runProvider } from './providers.js';
+
+export interface RefineOptions {
+  provider: AiProvider;
+  model?: string;
+  apiMap: ApiMapNode;
+  description: string;
+}
+
+/** 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;
+}
+
+export async function refineSummariesWithAi(options: RefineOptions): Promise<number> {
+  const { system, user } = buildSummariesPrompt({
+    apiMap: options.apiMap,
+    description: options.description,
+  });
+
+  const { text } = await runProvider(options.provider, { system, user, model: options.model });
+
+  const cleaned = stripCodeFences(text);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(cleaned);
+  } catch (error) {
+    throw new Error(
+      `The ${options.provider} provider did not return valid JSON: ${
+        error instanceof Error ? error.message : String(error)
+      }`
+    );
+  }
+  if (!isPlainObject(parsed)) {
+    throw new Error(
+      `The ${options.provider} provider returned content that is not a pointer-to-summary JSON object.`
+    );
+  }
+
+  const summaries = new Map(
+    Object.entries(parsed).filter(
+      (entry): entry is [string, string] =>
+        entry[0].startsWith('#/') && typeof entry[1] === 'string' && entry[1].length > 0
+    )
+  );
+  return applySummaries(options.apiMap, summaries);
+}
+
+function applySummaries(node: ApiMapNode, summaries: Map<string, string>): number {
+  let applied = 0;
+  const summary = summaries.get(node.pointer);
+  if (summary) {
+    node.summary = summary;
+    applied++;
+  }
+  for (const child of node.nodes) {
+    applied += applySummaries(child, summaries);
+  }
+  return applied;
+}
diff --git a/packages/cli/src/commands/map/index.ts b/packages/cli/src/commands/map/index.ts
index ce1b1a2af9..7e5eedd8dd 100644
--- a/packages/cli/src/commands/map/index.ts
+++ b/packages/cli/src/commands/map/index.ts
@@ -14,6 +14,8 @@ import type { VerifyConfigOptions } from '../../types.js';
 import { exitWithError } from '../../utils/error.js';
 import { getFallbackApisOrExit } from '../../utils/miscellaneous.js';
 import type { CommandArgs } from '../../wrapper.js';
+import { type AiProvider } from './ai/providers.js';
+import { refineSummariesWithAi } from './ai/refine.js';
 import { printApiMap } from './print-map/index.js';
 
 const SUPPORTED_MAJOR_VERSIONS = ['oas2', 'oas3', 'async2', 'async3'];
@@ -23,6 +25,9 @@ export type MapArgv = {
   format: OutputFormat;
   'source-locations'?: boolean;
   pointer?: string;
+  'with-ai'?: boolean;
+  'ai-provider': AiProvider;
+  'ai-model'?: string;
 } & VerifyConfigOptions;
 
 export async function handleMap({ argv, config, collectSpecData }: CommandArgs<MapArgv>) {
@@ -69,5 +74,24 @@ export async function handleMap({ argv, config, collectSpecData }: CommandArgs<M
     sourceLocations: argv['source-locations'],
   });
 
+  if (argv['with-ai']) {
+    const provider = argv['ai-provider'];
+    try {
+      const applied = await refineSummariesWithAi({
+        provider,
+        model: argv['ai-model'],
+        apiMap,
+        description: document.source.body,
+      });
+      logger.info(`AI refinement complete (${provider}): ${applied} summaries updated.\n`);
+    } catch (error) {
+      logger.info(
+        `AI refinement failed, falling back to the deterministic map: ${
+          error instanceof Error ? error.message : String(error)
+        }\n`
+      );
+    }
+  }
+
   printApiMap(apiMap, path, argv.format);
 }
diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts
index 6c5a7c37f6..19f673e330 100644
--- a/packages/cli/src/index.ts
+++ b/packages/cli/src/index.ts
@@ -22,7 +22,7 @@ import {
 } from './commands/generate-arazzo.js';
 import { handleJoin } from './commands/join/index.js';
 import { handleLint } from './commands/lint.js';
-import { handleMap } from './commands/map/index.js';
+import { handleMap, type MapArgv } from './commands/map/index.js';
 import { PRODUCT_PLANS } from './commands/preview-project/constants.js';
 import { previewProject } from './commands/preview-project/index.js';
 import { handleRespect, type RespectArgv } from './commands/respect/index.js';
@@ -107,6 +107,22 @@ yargs(hideBin(process.argv))
             description: 'Print the content at the given JSON pointer instead of the map.',
             type: 'string',
           },
+          'with-ai': {
+            description: 'Refine node summaries with an AI provider.',
+            type: 'boolean',
+            default: false,
+          },
+          'ai-provider': {
+            description:
+              'AI provider used with --with-ai. "openai" calls an OpenAI-compatible endpoint (OPENAI_ENDPOINT/OPENAI_API_KEY); "claude" and "codex" run the respective CLI.',
+            choices: ['openai', 'claude', 'codex'] as ReadonlyArray<MapArgv['ai-provider']>,
+            default: 'claude' as MapArgv['ai-provider'],
+          },
+          'ai-model': {
+            description:
+              'Model passed to the selected AI provider (provider-specific default applies).',
+            type: 'string',
+          },
         }),
     (argv) => {
       commandWrapper(handleMap)(argv);
diff --git a/packages/core/src/api-map/__tests__/build-api-map.test.ts b/packages/core/src/api-map/__tests__/build-api-map.test.ts
index 2d8a114031..8b0cff7a86 100644
--- a/packages/core/src/api-map/__tests__/build-api-map.test.ts
+++ b/packages/core/src/api-map/__tests__/build-api-map.test.ts
@@ -586,6 +586,115 @@ describe('buildApiMap', () => {
     expect(JSON.stringify(apiMap)).not.toContain('statusChangeCallback');
   });
 
+  it('derives summaries from structure when descriptions are missing', async () => {
+    const oasDocument = parseYamlToDocument(
+      outdent`
+        openapi: 3.0.0
+        info:
+          title: Redocly Cafe
+          version: 1.0.0
+        paths:
+          /menu:
+            get:
+              operationId: listMenuItems
+              parameters:
+                - name: limit
+                  in: query
+                - $ref: '#/components/parameters/Sort'
+              responses:
+                '200':
+                  content:
+                    application/json:
+                      schema:
+                        $ref: '#/components/schemas/MenuItemList'
+                '404': {}
+        components:
+          parameters:
+            Sort:
+              name: sort
+              in: query
+          schemas:
+            MenuItemList:
+              type: array
+              items:
+                $ref: '#/components/schemas/MenuItem'
+            MenuItem:
+              type: object
+              properties:
+                name:
+                  type: string
+                price:
+                  type: number
+      `,
+      'cafe.yaml'
+    );
+
+    const oasMap = await buildApiMap({ document: oasDocument, config: await createConfig({}) });
+    const operation = oasMap.nodes.find((n) => n.title === 'paths')!.nodes[0].nodes[0];
+    const schemas = oasMap.nodes
+      .find((n) => n.title === 'components')!
+      .nodes.find((n) => n.title === 'schemas')!;
+
+    expect(operation.summary).toBe('Returns 200 (MenuItemList), 404. Parameters: limit, Sort.');
+    expect(schemas.nodes.find((n) => n.title === 'MenuItemList')!.summary).toBe(
+      'array of MenuItem'
+    );
+    expect(schemas.nodes.find((n) => n.title === 'MenuItem')!.summary).toBe('object: name, price');
+
+    const async2Document = parseYamlToDocument(
+      outdent`
+        asyncapi: 2.6.0
+        info:
+          title: Cafe Events
+          version: 1.0.0
+        channels:
+          orders/created:
+            subscribe:
+              operationId: onOrderCreated
+              message:
+                $ref: '#/components/messages/OrderCreated'
+        components:
+          messages:
+            OrderCreated:
+              payload:
+                type: object
+      `,
+      'cafe-events.yaml'
+    );
+
+    const async2Map = await buildApiMap({
+      document: async2Document,
+      config: await createConfig({}),
+    });
+    const async2Operation = async2Map.nodes.find((n) => n.title === 'channels')!.nodes[0].nodes[0];
+    expect(async2Operation.summary).toBe('message: OrderCreated');
+
+    const async3Document = parseYamlToDocument(
+      outdent`
+        asyncapi: 3.0.0
+        info:
+          title: Cafe Events
+          version: 1.0.0
+        channels:
+          ordersCreated:
+            address: orders/created
+        operations:
+          sendOrderCreated:
+            action: send
+            channel:
+              $ref: '#/channels/ordersCreated'
+      `,
+      'cafe-events.yaml'
+    );
+
+    const async3Map = await buildApiMap({
+      document: async3Document,
+      config: await createConfig({}),
+    });
+    const async3Operation = async3Map.nodes.find((n) => n.title === 'operations')!.nodes[0];
+    expect(async3Operation.summary).toBe('send to ordersCreated');
+  });
+
   it('throws for unsupported spec versions', async () => {
     const document = parseYamlToDocument(
       outdent`
diff --git a/packages/core/src/api-map/async.ts b/packages/core/src/api-map/async.ts
index bddab94c5b..23bcd72726 100644
--- a/packages/core/src/api-map/async.ts
+++ b/packages/core/src/api-map/async.ts
@@ -1,4 +1,9 @@
 import type { Async2Visitor, Async3Visitor } from '../visitors.js';
+import {
+  deriveAsync2OperationSummary,
+  deriveAsync3OperationSummary,
+  deriveSchemaSummary,
+} from './derive-summary.js';
 import { createApiMapHooks } from './hooks.js';
 import type { ApiMapNode, ApiMapOptions } from './types.js';
 
@@ -23,12 +28,15 @@ export function ApiMapAsync2(root: ApiMapNode, opts: ApiMapOptions): Async2Visit
       ...sectionHooks('Root'),
       Channel: {
         ...containerHooks,
-        Operation: operationHooks({}),
+        Operation: operationHooks({}, deriveAsync2OperationSummary),
       },
     },
     Components: {
       ...sectionHooks('Root'),
-      NamedSchemas: { ...sectionHooks('Components'), Schema: leafHooks() },
+      NamedSchemas: {
+        ...sectionHooks('Components'),
+        Schema: leafHooks(undefined, deriveSchemaSummary),
+      },
       NamedMessages: { ...sectionHooks('Components'), Message: leafHooks('title') },
       NamedParameters: { ...sectionHooks('Components'), Parameter: leafHooks() },
       NamedSecuritySchemes: { ...sectionHooks('Components'), SecurityScheme: leafHooks() },
@@ -52,11 +60,14 @@ export function ApiMapAsync3(root: ApiMapNode, opts: ApiMapOptions): Async3Visit
     },
     NamedOperations: {
       ...sectionHooks('Root'),
-      Operation: leafHooks('title'),
+      Operation: leafHooks('title', deriveAsync3OperationSummary),
     },
     Components: {
       ...sectionHooks('Root'),
-      NamedSchemas: { ...sectionHooks('Components'), Schema: leafHooks() },
+      NamedSchemas: {
+        ...sectionHooks('Components'),
+        Schema: leafHooks(undefined, deriveSchemaSummary),
+      },
       NamedMessages: { ...sectionHooks('Components'), Message: leafHooks('title') },
       NamedParameters: { ...sectionHooks('Components'), Parameter: leafHooks() },
       NamedSecuritySchemes: { ...sectionHooks('Components'), SecurityScheme: leafHooks() },
diff --git a/packages/core/src/api-map/derive-summary.ts b/packages/core/src/api-map/derive-summary.ts
new file mode 100644
index 0000000000..97a1c1a85b
--- /dev/null
+++ b/packages/core/src/api-map/derive-summary.ts
@@ -0,0 +1,93 @@
+import { pointerBaseName } from '../ref-utils.js';
+import { isPlainObject } from '../utils/is-plain-object.js';
+
+const MAX_PROPERTY_NAMES = 8;
+
+function refBaseName(node: unknown): string | undefined {
+  return isPlainObject(node) && typeof node.$ref === 'string'
+    ? pointerBaseName(node.$ref)
+    : undefined;
+}
+
+function responseSchemaName(response: unknown): string | undefined {
+  if (!isPlainObject(response)) return undefined;
+  // OAS2 responses hold the schema directly; OAS3 nests it under content/<media-type>
+  const mediaTypes = isPlainObject(response.content) ? Object.values(response.content) : [response];
+  for (const mediaType of mediaTypes) {
+    if (!isPlainObject(mediaType)) continue;
+    const name = refBaseName(mediaType.schema);
+    if (name) return name;
+  }
+  return undefined;
+}
+
+export function deriveOperationSummary(operation: unknown): string | undefined {
+  if (!isPlainObject(operation)) return undefined;
+  const parts: string[] = [];
+
+  if (isPlainObject(operation.responses)) {
+    const codes = Object.keys(operation.responses);
+    if (codes.length > 0) {
+      const primary = codes.find((code) => code.startsWith('2')) ?? codes[0];
+      const schemaName = responseSchemaName(operation.responses[primary]);
+      const described = codes.map((code) =>
+        code === primary && schemaName ? `${code} (${schemaName})` : code
+      );
+      parts.push(`Returns ${described.join(', ')}.`);
+    }
+  }
+
+  if (Array.isArray(operation.parameters) && operation.parameters.length > 0) {
+    const names = operation.parameters
+      .map((parameter) =>
+        isPlainObject(parameter) && typeof parameter.name === 'string'
+          ? parameter.name
+          : refBaseName(parameter)
+      )
+      .filter(Boolean);
+    if (names.length > 0) {
+      parts.push(`Parameters: ${names.join(', ')}.`);
+    }
+  }
+
+  return parts.length > 0 ? parts.join(' ') : undefined;
+}
+
+export function deriveSchemaSummary(schema: unknown): string | undefined {
+  if (!isPlainObject(schema)) return undefined;
+  if (schema.type === 'array' || isPlainObject(schema.items)) {
+    const items = refBaseName(schema.items) ?? getType(schema.items);
+    return items ? `array of ${items}` : 'array';
+  }
+  if (schema.type === 'object' || isPlainObject(schema.properties)) {
+    const names = isPlainObject(schema.properties) ? Object.keys(schema.properties) : [];
+    if (names.length === 0) return 'object';
+    const shown = names.slice(0, MAX_PROPERTY_NAMES);
+    if (names.length > MAX_PROPERTY_NAMES) shown.push('…');
+    return `object: ${shown.join(', ')}`;
+  }
+  return undefined;
+}
+
+function getType(node: unknown): string | undefined {
+  return isPlainObject(node) && typeof node.type === 'string' ? node.type : undefined;
+}
+
+export function deriveAsync2OperationSummary(operation: unknown): string | undefined {
+  if (!isPlainObject(operation)) return undefined;
+  const message = operation.message;
+  const name =
+    refBaseName(message) ??
+    (isPlainObject(message)
+      ? (typeof message.name === 'string' && message.name) ||
+        (typeof message.title === 'string' && message.title) ||
+        undefined
+      : undefined);
+  return name ? `message: ${name}` : undefined;
+}
+
+export function deriveAsync3OperationSummary(operation: unknown): string | undefined {
+  if (!isPlainObject(operation) || typeof operation.action !== 'string') return undefined;
+  const channel = refBaseName(operation.channel);
+  return channel ? `${operation.action} to ${channel}` : operation.action;
+}
diff --git a/packages/core/src/api-map/hooks.ts b/packages/core/src/api-map/hooks.ts
index 5e2e2f2d69..95424d2118 100644
--- a/packages/core/src/api-map/hooks.ts
+++ b/packages/core/src/api-map/hooks.ts
@@ -24,11 +24,13 @@ export function getStringProp(node: unknown, key: string): string | undefined {
   return typeof value === 'string' && value ? value : undefined;
 }
 
-function makeSummary(node: unknown): string | undefined {
+export type SummaryDeriver = (node: unknown) => string | undefined;
+
+function makeSummary(node: unknown, derive?: SummaryDeriver): string | undefined {
   const summary = getStringProp(node, 'summary');
   if (summary) return summary;
   const description = getStringProp(node, 'description');
-  if (!description) return undefined;
+  if (!description) return derive?.(node);
   if (description.length <= SUMMARY_MAX_LENGTH) return description;
   return description.slice(0, SUMMARY_MAX_LENGTH).replace(/\s+\S*$/, '') + '...';
 }
@@ -94,7 +96,7 @@ export function createApiMapHooks(root: ApiMapNode, opts: ApiMapOptions) {
     },
   };
 
-  function operationHooks(fields: { method?: boolean; path?: boolean }) {
+  function operationHooks(fields: { method?: boolean; path?: boolean }, derive?: SummaryDeriver) {
     return {
       enter(operation: unknown, ctx: UserContext) {
         if (!isDirectChild(ctx)) return;
@@ -104,7 +106,7 @@ export function createApiMapHooks(root: ApiMapNode, opts: ApiMapOptions) {
           {
             title:
               getStringProp(operation, 'operationId') ?? `${key.toUpperCase()} ${parentNode.title}`,
-            summary: makeSummary(operation),
+            summary: makeSummary(operation, derive),
             method: fields.method ? key : undefined,
             path: fields.path ? parentNode.title : undefined,
           },
@@ -114,12 +116,12 @@ export function createApiMapHooks(root: ApiMapNode, opts: ApiMapOptions) {
     };
   }
 
-  function leafHooks(titleProp?: string) {
+  function leafHooks(titleProp?: string, derive?: SummaryDeriver) {
     return {
       enter(node: unknown, ctx: UserContext) {
         if (!isDirectChild(ctx)) return;
         const title = titleProp && getStringProp(node, titleProp);
-        addNode({ title: title || String(ctx.key), summary: makeSummary(node) }, ctx);
+        addNode({ title: title || String(ctx.key), summary: makeSummary(node, derive) }, ctx);
       },
     };
   }
diff --git a/packages/core/src/api-map/oas.ts b/packages/core/src/api-map/oas.ts
index f6d674f3ae..56fae5c50e 100644
--- a/packages/core/src/api-map/oas.ts
+++ b/packages/core/src/api-map/oas.ts
@@ -1,4 +1,5 @@
 import type { Oas2Visitor, Oas3Visitor } from '../visitors.js';
+import { deriveOperationSummary, deriveSchemaSummary } from './derive-summary.js';
 import { createApiMapHooks } from './hooks.js';
 import type { ApiMapNode, ApiMapOptions } from './types.js';
 
@@ -23,19 +24,22 @@ export function ApiMapOAS3(root: ApiMapNode, opts: ApiMapOptions): Oas3Visitor {
       ...sectionHooks('Root'),
       PathItem: {
         ...containerHooks,
-        Operation: operationHooks({ method: true, path: true }),
+        Operation: operationHooks({ method: true, path: true }, deriveOperationSummary),
       },
     },
     WebhooksMap: {
       ...sectionHooks('Root'),
       PathItem: {
         ...containerHooks,
-        Operation: operationHooks({ method: true }),
+        Operation: operationHooks({ method: true }, deriveOperationSummary),
       },
     },
     Components: {
       ...sectionHooks('Root'),
-      NamedSchemas: { ...sectionHooks('Components'), Schema: leafHooks() },
+      NamedSchemas: {
+        ...sectionHooks('Components'),
+        Schema: leafHooks(undefined, deriveSchemaSummary),
+      },
       NamedResponses: { ...sectionHooks('Components'), Response: leafHooks() },
       NamedParameters: { ...sectionHooks('Components'), Parameter: leafHooks() },
       NamedExamples: { ...sectionHooks('Components'), Example: leafHooks() },
@@ -67,10 +71,10 @@ export function ApiMapOAS2(root: ApiMapNode, opts: ApiMapOptions): Oas2Visitor {
       ...sectionHooks('Root'),
       PathItem: {
         ...containerHooks,
-        Operation: operationHooks({ method: true, path: true }),
+        Operation: operationHooks({ method: true, path: true }, deriveOperationSummary),
       },
     },
-    NamedSchemas: { ...sectionHooks('Root'), Schema: leafHooks() },
+    NamedSchemas: { ...sectionHooks('Root'), Schema: leafHooks(undefined, deriveSchemaSummary) },
     NamedParameters: { ...sectionHooks('Root'), Parameter: leafHooks() },
     NamedResponses: { ...sectionHooks('Root'), Response: leafHooks() },
     NamedSecuritySchemes: { ...sectionHooks('Root'), SecurityScheme: leafHooks() },
diff --git a/tests/e2e/map/map-ai/bin-ok/claude b/tests/e2e/map/map-ai/bin-ok/claude
new file mode 100755
index 0000000000..a71d493c55
--- /dev/null
+++ b/tests/e2e/map/map-ai/bin-ok/claude
@@ -0,0 +1,7 @@
+#!/bin/sh
+# Stub of the "claude" CLI: consume the prompt from stdin and return a fixed
+# pointer-to-summary JSON object, wrapped in code fences like a chatty model would.
+cat > /dev/null
+echo '```json'
+echo '{"#/paths/~1menu/get": "Lists every item currently on the cafe menu.", "#/components/schemas/MenuItemList": "Paginated collection of menu items."}'
+echo '```'
diff --git a/tests/e2e/map/map-ai/openapi.yaml b/tests/e2e/map/map-ai/openapi.yaml
new file mode 100644
index 0000000000..fac4a6e4f3
--- /dev/null
+++ b/tests/e2e/map/map-ai/openapi.yaml
@@ -0,0 +1,20 @@
+openapi: 3.0.0
+info:
+  title: Redocly Cafe
+  version: 1.0.0
+paths:
+  /menu:
+    get:
+      operationId: listMenuItems
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MenuItemList'
+components:
+  schemas:
+    MenuItemList:
+      type: array
+      items:
+        type: object
diff --git a/tests/e2e/map/map-ai/snapshot-fallback.txt b/tests/e2e/map/map-ai/snapshot-fallback.txt
new file mode 100644
index 0000000000..ab79671e8d
--- /dev/null
+++ b/tests/e2e/map/map-ai/snapshot-fallback.txt
@@ -0,0 +1,58 @@
+{
+  "title": "Redocly Cafe",
+  "kind": "Root",
+  "pointer": "#/",
+  "nodes": [
+    {
+      "title": "Redocly Cafe",
+      "kind": "Info",
+      "pointer": "#/info",
+      "nodes": []
+    },
+    {
+      "title": "paths",
+      "kind": "Paths",
+      "pointer": "#/paths",
+      "nodes": [
+        {
+          "title": "/menu",
+          "kind": "PathItem",
+          "pointer": "#/paths/~1menu",
+          "nodes": [
+            {
+              "title": "listMenuItems",
+              "kind": "Operation",
+              "pointer": "#/paths/~1menu/get",
+              "summary": "Returns 200 (MenuItemList).",
+              "method": "get",
+              "path": "/menu",
+              "nodes": []
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "title": "components",
+      "kind": "Components",
+      "pointer": "#/components",
+      "nodes": [
+        {
+          "title": "schemas",
+          "kind": "NamedSchemas",
+          "pointer": "#/components/schemas",
+          "nodes": [
+            {
+              "title": "MenuItemList",
+              "kind": "Schema",
+              "pointer": "#/components/schemas/MenuItemList",
+              "summary": "array of object",
+              "nodes": []
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
+AI refinement failed, falling back to the deterministic map: Could not find the "claude" CLI on PATH. Is it installed?
diff --git a/tests/e2e/map/map-ai/snapshot.txt b/tests/e2e/map/map-ai/snapshot.txt
new file mode 100644
index 0000000000..88e8c432f6
--- /dev/null
+++ b/tests/e2e/map/map-ai/snapshot.txt
@@ -0,0 +1,58 @@
+{
+  "title": "Redocly Cafe",
+  "kind": "Root",
+  "pointer": "#/",
+  "nodes": [
+    {
+      "title": "Redocly Cafe",
+      "kind": "Info",
+      "pointer": "#/info",
+      "nodes": []
+    },
+    {
+      "title": "paths",
+      "kind": "Paths",
+      "pointer": "#/paths",
+      "nodes": [
+        {
+          "title": "/menu",
+          "kind": "PathItem",
+          "pointer": "#/paths/~1menu",
+          "nodes": [
+            {
+              "title": "listMenuItems",
+              "kind": "Operation",
+              "pointer": "#/paths/~1menu/get",
+              "summary": "Lists every item currently on the cafe menu.",
+              "method": "get",
+              "path": "/menu",
+              "nodes": []
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "title": "components",
+      "kind": "Components",
+      "pointer": "#/components",
+      "nodes": [
+        {
+          "title": "schemas",
+          "kind": "NamedSchemas",
+          "pointer": "#/components/schemas",
+          "nodes": [
+            {
+              "title": "MenuItemList",
+              "kind": "Schema",
+              "pointer": "#/components/schemas/MenuItemList",
+              "summary": "Paginated collection of menu items.",
+              "nodes": []
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
+AI refinement complete (claude): 2 summaries updated.
diff --git a/tests/e2e/map/map-json-file/snapshot.txt b/tests/e2e/map/map-json-file/snapshot.txt
index 39a6e02bdc..c418411366 100644
--- a/tests/e2e/map/map-json-file/snapshot.txt
+++ b/tests/e2e/map/map-json-file/snapshot.txt
@@ -7,8 +7,8 @@
     "pointer": "#/",
     "startLine": 1,
     "startCol": 1,
-    "endLine": 1,
-    "endCol": 216
+    "endLine": 8,
+    "endCol": 3
   },
   "nodes": [
     {
@@ -18,10 +18,10 @@
       "source": {
         "file": "./tests/e2e/map/map-json-file/cafe.json",
         "pointer": "#/info",
-        "startLine": 1,
-        "startCol": 27,
-        "endLine": 1,
-        "endCol": 69
+        "startLine": 3,
+        "startCol": 11,
+        "endLine": 3,
+        "endCol": 58
       },
       "nodes": []
     },
@@ -32,10 +32,10 @@
       "source": {
         "file": "./tests/e2e/map/map-json-file/cafe.json",
         "pointer": "#/paths",
-        "startLine": 1,
-        "startCol": 78,
-        "endLine": 1,
-        "endCol": 159
+        "startLine": 4,
+        "startCol": 12,
+        "endLine": 6,
+        "endCol": 4
       },
       "nodes": [
         {
@@ -45,10 +45,10 @@
           "source": {
             "file": "./tests/e2e/map/map-json-file/cafe.json",
             "pointer": "#/paths/~1menu",
-            "startLine": 1,
-            "startCol": 87,
-            "endLine": 1,
-            "endCol": 158
+            "startLine": 5,
+            "startCol": 14,
+            "endLine": 5,
+            "endCol": 93
           },
           "nodes": [
             {
@@ -61,10 +61,10 @@
               "source": {
                 "file": "./tests/e2e/map/map-json-file/cafe.json",
                 "pointer": "#/paths/~1menu/get",
-                "startLine": 1,
-                "startCol": 94,
-                "endLine": 1,
-                "endCol": 157
+                "startLine": 5,
+                "startCol": 23,
+                "endLine": 5,
+                "endCol": 91
               },
               "nodes": []
             }
@@ -79,10 +79,10 @@
       "source": {
         "file": "./tests/e2e/map/map-json-file/cafe.json",
         "pointer": "#/components",
-        "startLine": 1,
-        "startCol": 173,
-        "endLine": 1,
-        "endCol": 215
+        "startLine": 7,
+        "startCol": 17,
+        "endLine": 7,
+        "endCol": 68
       },
       "nodes": [
         {
@@ -92,23 +92,24 @@
           "source": {
             "file": "./tests/e2e/map/map-json-file/cafe.json",
             "pointer": "#/components/schemas",
-            "startLine": 1,
-            "startCol": 184,
-            "endLine": 1,
-            "endCol": 214
+            "startLine": 7,
+            "startCol": 30,
+            "endLine": 7,
+            "endCol": 66
           },
           "nodes": [
             {
               "title": "MenuItem",
               "kind": "Schema",
               "pointer": "#/components/schemas/MenuItem",
+              "summary": "object",
               "source": {
                 "file": "./tests/e2e/map/map-json-file/cafe.json",
                 "pointer": "#/components/schemas/MenuItem",
-                "startLine": 1,
-                "startCol": 196,
-                "endLine": 1,
-                "endCol": 213
+                "startLine": 7,
+                "startCol": 44,
+                "endLine": 7,
+                "endCol": 64
               },
               "nodes": []
             }
diff --git a/tests/e2e/map/map.test.ts b/tests/e2e/map/map.test.ts
index a9a5725265..478e5ee315 100644
--- a/tests/e2e/map/map.test.ts
+++ b/tests/e2e/map/map.test.ts
@@ -1,4 +1,4 @@
-import { join, dirname } from 'node:path';
+import { join, dirname, delimiter } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { getCommandOutput, getParams, cleanupOutput } from '../helpers.js';
@@ -56,6 +56,43 @@ describe('map', () => {
     );
   });
 
+  test('map should refine summaries with a stubbed AI provider', async () => {
+    const testPath = join(folderPath, 'map-ai');
+    const args = getParams(indexEntryPoint, [
+      'map',
+      'openapi.yaml',
+      '--format=json',
+      '--with-ai',
+      '--ai-provider=claude',
+    ]);
+    // Prepend the stub bin directory to PATH so the spawned "claude" CLI
+    // resolves to the fixture stub instead of a real installation.
+    const result = getCommandOutput(args, {
+      testPath,
+      env: { PATH: `${join(testPath, 'bin-ok')}${delimiter}${process.env.PATH}` },
+    });
+    await expect(cleanupOutput(result)).toMatchFileSnapshot(join(testPath, 'snapshot.txt'));
+  });
+
+  test('map should fall back to the deterministic map when the AI provider is unavailable', async () => {
+    const testPath = join(folderPath, 'map-ai');
+    const args = getParams(indexEntryPoint, [
+      'map',
+      'openapi.yaml',
+      '--format=json',
+      '--with-ai',
+      '--ai-provider=claude',
+    ]);
+    // Restrict PATH to the node binary directory so "claude" cannot resolve.
+    const result = getCommandOutput(args, {
+      testPath,
+      env: { PATH: dirname(process.execPath) },
+    });
+    await expect(cleanupOutput(result)).toMatchFileSnapshot(
+      join(testPath, 'snapshot-fallback.txt')
+    );
+  });
+
   test('map should support AsyncAPI 2.x (stylish format)', async () => {
     const testPath = join(folderPath, 'map-async2-stylish');
     const args = getParams(indexEntryPoint, ['map', 'async.yaml']);