feat: add experimental tree command with agent index

.changeset/calm-maps-appear.md

@@ -0,0 +1,6 @@
+---
+'@redocly/cli': minor
+'@redocly/openapi-core': patch
+---
+
+Added an experimental `generate-map` command that writes a compressed plain-text map of an OpenAPI description — one line per operation with its auth, required fields, and source coordinates — for LLM agents to search locally instead of re-reading the description.

.changeset/tree-command.md

@@ -0,0 +1,6 @@
+---
+'@redocly/openapi-core': minor
+'@redocly/cli': minor
+---
+
+Added an experimental `tree` command that prints an API description as a navigable index of its operations, components, and files, with a `--format=ai` output for agents.

AGENTS.md

@@ -80,6 +80,7 @@ Key directories:
 - `src/bundle/` — Bundling logic that resolves `$ref` across multiple files.
 - `src/resolve.ts` — Document resolution for multi-file specs (local and remote).
 - `src/types/` — TypeScript type definitions for OAS2, OAS3, AsyncAPI, Arazzo.
+- `src/api-graph/` — The index the `tree` command reads: the node graph, its selectors, and the views built from it.
 
 ### `packages/cli` (@redocly/cli)
 
@@ -110,6 +111,24 @@ The root `npm run compile` runs both steps: tsc for core/respect-core, then the
 
 The published CLI package ships from a staged `.publish/` directory (created by `packages/cli/scripts/prepare-publish-dir.mjs`) with a hand-crafted `package.json` that has zero runtime dependencies — everything is bundled.
 
+## Explore an API description with `tree`
+
+API descriptions are often too large to read directly — the OpenAPI descriptions used in this repository's benchmarks run to millions of tokens.
+Use [`tree`](./docs/@v2/commands/tree.md) to walk one in bounded steps instead of reading or grepping the file:
+
+```bash
+redocly tree <file> --format=ai                                                  # overview: tags, webhooks, component sections
+redocly tree <file> --find "<task words>" --format=ai                            # locate candidate operations/components
+redocly tree <file> --pointer='<ptr>' --format=ai                                # already hold a $ref/lint pointer: jump straight to its location and usage
+redocly tree <file> --path=<path> --operation=<method> --with-deps --format=ai   # one operation with its full $ref closure, as schema signatures
+redocly tree <file> --tag=<tag> --format=ai                                      # a whole area's operations, only when browsing is genuinely needed
+```
+
+`--format=ai` is the agent format: plain text, one line per listing entry, and schema signatures instead of raw YAML in a `--with-deps` closure.
+`--find` ranks operations and components by how many search terms hit their path, id, name, summary, or description, so step 2 usually narrows a whole API down to a few candidates in one call; anything a card's closure lists under `deeper` is one `--component`/`--name` call away.
+Every result carries the defining `file` and `start_line`/`end_line`, so any answer can be checked against the source it came from.
+Each view also ends with a `next:` line naming the flags that continue from it, so these five commands are enough — reading the full [command reference](./docs/@v2/commands/tree.md) costs more tokens than the exploration it saves.
+
 ## Respect the architecture: Walker, Visitors, Nodes
 
 Linting in `packages/core` rests on three concepts: the **Walker** traverses the parsed API description and resolves `$ref`s, **Visitors** are objects keyed by **Node** type, and the Walker calls each visitor's `enter` / `leave` / `skip` hooks as it reaches a node.

docs/@v2/commands/generate-map.md

@@ -0,0 +1,224 @@
+# `generate-map`
+
+## Introduction
+
+The `generate-map` command turns an API description into a single plain-text map for LLM agents:
+one line per operation carrying the auth it requires, the request fields it needs, what to carry
+from its response, and the file and line range that defines it.
+Above the operations sit a security section and a table of contents whose line ranges point back
+into the map itself.
+
+An agent greps the map or reads one section of it and has the answer locally — no CLI at use time,
+no network, and no re-reading of the description.
+Generate it once, commit it next to the description, and regenerate it when the description changes.
+
+Use `generate-map` to:
+
+- Give an agent runtime a self-sufficient index of an API it can search with ordinary file tools.
+- Keep the answer to "what does this call need" in one line instead of a `$ref` chase.
+- Ship an index alongside a published description, the way a repository ships a README.
+
+Generation is deterministic: no AI calls, no API keys, no timestamps.
+The same description always produces byte-identical output, so the artifact diffs cleanly in git.
+
+It is experimental and supports OpenAPI 2.0 and 3.x.
+AsyncAPI and Arazzo descriptions are rejected — they have no operations to map.
+
+For interactive exploration instead — impact analysis, `$ref` closures, search — use the
+[`tree` command](./tree.md); `generate-map` is its precomputed, CLI-free counterpart.
+
+## Usage
+
+```bash
+redocly generate-map <api>
+redocly generate-map <api> -o <file>
+redocly generate-map <api> --config=<path>
+```
+
+## Options
+
+| Option        | Type    | Description                                                                                                      |
+| ------------- | ------- | ---------------------------------------------------------------------------------------------------------------- |
+| api           | string  | OpenAPI description file path (or alias from `redocly.yaml` `apis:`).                                            |
+| --output, -o  | string  | Output file path. Defaults to `<name>.map.txt` next to the description. Required when the description is remote. |
+| --config      | string  | Path to the configuration file. Defaults to `redocly.yaml` in the working directory.                             |
+| --lint-config | string  | Severity level for the configuration file. **Possible values:** `warn`, `error`, `off`. Default value is `warn`. |
+| --help        | boolean | Display help.                                                                                                    |
+| --version     | boolean | Display version number.                                                                                          |
+
+## Examples
+
+### Generate a map
+
+```bash
+redocly generate-map cafe.yaml
+```
+
+```text
+Map written to cafe.map.txt. 12 operations, 3 KB.
+```
+
+The whole artifact for the [Cafe demo description](https://github.com/Redocly/redocly-cli/blob/main/resources/cafe.yaml):
+
+<!-- markdownlint-disable MD013 -->
+
+```text
+# Redocly Cafe · oas3_2 · 12 operations · generated by @redocly/cli from cafe.yaml — do not edit; regenerate after editing the spec
+# one line per operation: METHOD /path · operationId — summary · auth: scheme (scopes) · body: required* fields · params: required query/header · 2xx→{what to carry} · src: file Lstart-end
+# find your operation: grep this file by task words, or read the toc and sed its line range
+servers: https://api.cafe.redocly.com
+
+== security
+OAuth2: oauth2 · token from https://api.cafe.redocly.com/oauth2/token
+ApiKey: apiKey in header X-API-Key
+
+== toc
+Authorization (1) L17-18 — Create a client to demo the API.
+Products (4) L20-24 — Operations related to products.
+Orders (6) L26-32 — Order management operations.
+Statistics (1) L34-35 — Statistics operations.
+
+== operations
+## Authorization
+POST /oauth2/register · registerOAuth2Client — Create OAuth2 client · auth: none · body: name*, redirectUris:[any], scopes:[any], grantTypes:[any] · 201→{clientId, clientSecret, clientIdIssuedAt, clientSecretExpiresAt} · src: cafe.yaml L604-661
+
+## Products
+GET /menu · listMenuItems — List all menu items · auth: none · 200→{object, page, items} · src: cafe.yaml L32-111
+POST /menu · createMenuItem — Create menu item · auth: OAuth2 (menu:write) · body: multipart/form-data · 201 · src: cafe.yaml L113-173
+DELETE /menu/{menuItemId} · deleteMenuItem — Delete a menu item · auth: OAuth2 (menu:write) · 204 · src: cafe.yaml L178-198
+GET /menu-item-images/{menuItemId} · getMenuItemPhoto — Retrieve a menu item photo · auth: none · 200 · src: cafe.yaml L203-226
+
+## Orders
+GET /orders · listOrders — List all orders · auth: OAuth2 (orders:read) · 200→{object, page, items, items[].id} · src: cafe.yaml L229-314
+POST /orders · createOrder — Create order · auth: OAuth2 (orders:write) · body: customerName*, orderItems*:[{menuItemId*, quantity*}], id, object, status, totalPrice:int, createdAt, updatedAt · 201→{id, customerName, orderItems, orderItems[].menuItemId} · src: cafe.yaml L316-372
+GET /orders/{orderId} · getOrderById — Retrieve an order · auth: OAuth2 (orders:read) · 200→{id, customerName, orderItems, orderItems[].menuItemId} · src: cafe.yaml L375-416
+DELETE /orders/{orderId} · deleteOrder — Delete an order · auth: OAuth2 (orders:write) · 204 · src: cafe.yaml L478-502
+PATCH /orders/{orderId} · updateOrder — Partially update an order · auth: OAuth2 (orders:write) · body: status*→OrderStatus · 200→{id, customerName, orderItems, orderItems[].menuItemId} · src: cafe.yaml L418-476
+GET /order-items · listOrderItems — List all order items with menu item details · auth: OAuth2 (orders:read) · 200→{[].menuItemId} · src: cafe.yaml L505-546
+
+## Statistics
+GET /revenue · getRevenue — Get revenue statistics · auth: ApiKey (header X-API-Key) | OAuth2 (revenue:read) · 200→{revenue, averageOrderAmount, totalOrders, placedOrders} · src: cafe.yaml L549-601
+
+== webhooks
+POST webhook order-notification · orderNotificationWebhook — Order notification webhook · auth: none · body: orderId*, orderStatus*→OrderStatus, timestamp* · 200 · src: cafe.yaml L665-683
+```
+
+<!-- markdownlint-enable MD013 -->
+
+### Sections
+
+The map has four parts, in this order:
+
+- **Header** — three comment lines: what this API is and where the map came from, the row legend,
+  and how to search the file.
+  The header names the source description, because line numbers in `src:` go stale as soon as it is edited.
+- **`servers:`** — the servers the API declares at its root.
+- **`== security`** — one line per scheme the description defines, with what it asks the caller to
+  send: `apiKey in header X-API-Key`, `http bearer`, or an OAuth2 scheme with its token endpoint.
+  A description that declares no scheme says so explicitly, because an empty section reads as
+  "this API needs no auth" when it means "this document never states how its calls authenticate".
+- **`== toc`** — one line per tag with its operation count and the line range **into this map file**.
+  Those ranges are computed as the map is written and cannot go stale.
+- **`== operations`** and **`== webhooks`** — the rows themselves, grouped by tag in the order the
+  description declares them.
+
+### Row grammar
+
+`METHOD /path · operationId — summary · auth: … · body: … · params: … · CODE→{…} · flags · src: file Lstart-end`
+
+Every segment is omitted when it has nothing to say:
+
+| Segment      | What it carries                                                                                                                                                                                                                                                                                                                                                                  |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `auth:`      | The requirement the operation effectively has: its own, or the root one it inherits when it declares none. An `apiKey` scheme carries where the key goes (`ApiKey (header X-API-Key)`) so the row stands alone; an OAuth2 scheme carries its scopes. `\|` separates alternatives, `+` schemes that apply together. An operation that declares `security: []` reads `auth: none`. |
+| `body:`      | Top-level fields of the request schema: required first with `*`, compact types (`int`, `[str]`), enum values inline for required fields, one level into arrays of objects (`orderItems*:[{menuItemId*, quantity*}]`), capped at ten fields. A non-JSON body names its content type instead: `body: multipart/form-data`.                                                         |
+| `params:`    | Required query and header parameters. Path parameters are already visible in the path template.                                                                                                                                                                                                                                                                                  |
+| `CODE→{…}`   | The lowest success code and the fields worth carrying into the next call: the response's required top-level fields plus id-like fields at any depth as dotted paths (`orderItems[].menuItemId`), capped at four. When the operation overrides the server, its host follows: `⇒ uploads.github.com`. A response with no body renders as the bare code.                            |
+| `deprecated` | Present when the operation is deprecated.                                                                                                                                                                                                                                                                                                                                        |
+| `src:`       | The file that defines the operation and its line range, for checking any row against its source.                                                                                                                                                                                                                                                                                 |
+
+An operation with several tags appears once, under its first tag.
+Operations without tags group under `untagged`.
+
+### Multi-file descriptions
+
+A map of a multi-file description is one file all the same; each row's `src:` names the file that
+defines that operation:
+
+<!-- markdownlint-disable MD013 -->
+
+```bash
+redocly generate-map cafe-split/cafe.yaml
+```
+
+```text
+## Authorization
+POST /oauth2/register · registerOAuth2Client — Create OAuth2 client · auth: none · body: name*, redirectUris:[any], scopes:[any], grantTypes:[any] · 201→{clientId, clientSecret, clientIdIssuedAt, clientSecretExpiresAt} · src: cafe-split/paths/oauth2_register.yaml L2-57
+
+## Products
+```
+
+<!-- markdownlint-enable MD013 -->
+
+### Choose where the map goes
+
+```bash
+redocly generate-map cafe.yaml -o docs/cafe-index.txt
+```
+
+`--output` is required for a remote description, which has no local directory to write beside:
+
+```bash
+redocly generate-map https://example.com/openapi.yaml -o api.map.txt
+```
+
+## How agents use it
+
+Point the agent at the file and let it search with the tools it already has.
+Two access patterns cover almost everything.
+
+**Grep by task words.** The summary on each row is the lexical surface:
+
+```bash
+grep -i "order" cafe.map.txt
+```
+
+**Read the toc, then one section.** The toc's ranges address the map itself, so a large map is
+read in bounded slices instead of whole:
+
+```bash
+sed -n '26,32p' cafe.map.txt
+```
+
+<!-- markdownlint-disable MD013 -->
+
+```text
+## Orders
+GET /orders · listOrders — List all orders · auth: OAuth2 (orders:read) · 200→{object, page, items, items[].id} · src: cafe.yaml L229-314
+POST /orders · createOrder — Create order · auth: OAuth2 (orders:write) · body: customerName*, orderItems*:[{menuItemId*, quantity*}], id, object, status, totalPrice:int, createdAt, updatedAt · 201→{id, customerName, orderItems, orderItems[].menuItemId} · src: cafe.yaml L316-372
+GET /orders/{orderId} · getOrderById — Retrieve an order · auth: OAuth2 (orders:read) · 200→{id, customerName, orderItems, orderItems[].menuItemId} · src: cafe.yaml L375-416
+```
+
+<!-- markdownlint-enable MD013 -->
+
+When a row is not enough, `src:` opens the source at the right lines — a bounded read instead of
+opening the whole description.
+
+Tell the agent both patterns in the prompt.
+In the benchmark, the same map produced very different costs depending on whether the prompt said
+"start here" or "grep it, or read its toc and sed a range": the second wording kept a small model
+inside a few kilobytes where the first let it read a 166 KB map in chunks.
+
+For what this saves — 240 agent runs across eight description-task pairs, measured against both
+reading the description directly and exploring it with `tree` — see
+[Where the index pays](../guides/tree-agent-index-benchmark.md).
+
+## Keep the map fresh
+
+The map is generated, not maintained: the header says so, and every `src:` line range points into
+a description that may have moved on.
+Regenerate it whenever the description changes — in CI next to linting, or in a pre-commit hook:
+
+```bash
+redocly generate-map openapi.yaml && git add openapi.map.txt
+```

docs/@v2/commands/index.md

@@ -19,6 +19,7 @@ API management commands:
 - [`score`](score.md) Score an API for integration simplicity and AI agent readiness.
 - [`split`](split.md) Split API description into a multi-file structure.
 - [`stats`](stats.md) Gather statistics for a document.
+- [`tree`](tree.md) Display the structure of an API description as a tree.
 
 Linting commands: