feat: add experimental tree command with agent index

.changeset/tree-command.md

@@ -0,0 +1,10 @@
+---
+'@redocly/openapi-core': minor
+'@redocly/cli': minor
+---
+
+Added the experimental `tree` command: it prints an overview of an API description as a tree — its servers, every tag and webhook down to their individual operations, and component sections — and lets you drill into one tag, path, webhook, operation, component, or file with `--tag`, `--path`, `--webhook`, `--operation`, `--component`/`--name`, and `--file`, with every result attributed to the file that defines it.
+`--paths`, `--operations`, and `--webhooks` list the whole API surface, each entry already carrying its own typed one-hop `refs` and `usedBy`; `--used-by` runs impact analysis (which operations and components depend on a selection, including everything a whole file defines); `--with-deps` appends an operation's or component's transitive `$ref` closure. An operation or component selection renders as a tree too — coordinates, then `refs`/`usedBy`/`deps` as branches — with no raw source in the terminal output.
+`--format=json` prints the same selection as machine-readable data — stable ids, JSON pointers, source files, line ranges, summaries, and (with `--with-deps`) raw source, all taken from the description itself; `--files` shows the file-level `$ref` graph, optionally filtered to one file's neighborhood with `--file`.
+`--format=ai` is the agent format: it trims listing views (`--tag`, `--path`/`--webhook`, `--operations`, `--webhooks`, `--component`, and a `--file` card's `defines`) to one compact entry per item (method, path, summary, line range), serializes every view without indentation, and turns a `--with-deps` closure into compact schema signatures — required fields, types, enums, and `$ref` targets — instead of raw YAML, with anything more than two `$ref` hops away listed as a bare id instead of a body; on a large listing the projection and indentation cuts together save over 90%, and a schema-heavy `--with-deps` closure can shrink by a similar margin.
+The underlying engines live in `@redocly/openapi-core`'s new `api-graph` module (`analyzeApi`, `buildOverview`, `buildOperationCard`, `buildUsedByReport`, `buildFileCard`).

AGENTS.md

@@ -106,6 +106,22 @@ 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> --tag=<tag> --format=ai                                      # one tag's operations
+redocly tree <file> --path=<path> --operation=<method> --with-deps --format=ai   # one operation with its full $ref closure, as schema signatures
+redocly tree <file> --component=<section> --name=<Name> --used-by --format=ai    # what breaks if this component changes
+```
+
+`--format=ai` is the agent format: projected listings, no indentation, and schema signatures instead of raw YAML in a `--with-deps` closure.
+`--used-by` returns the complete transitive dependency graph with a `via` chain per entry, so walking `$ref`s by hand is unnecessary.
+Every result carries the defining `file` and `start_line`/`end_line`, so any answer can be checked against the source it came from.
+
 ## 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/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:
 

docs/@v2/guides/index.md

@@ -97,6 +97,12 @@ Authenticate, handle errors, and compose middleware with a client from `generate
 Pre-configure publisher defaults and write custom client generators.
 {% /card %}
 
+{% card title="Agent context costs with tree"
+    to="./tree-agent-index-benchmark"
+  %}
+Measured token counts for exploring GitHub's 10.0 MB REST API description with `tree`, compared against reading the whole file and against searching it with `grep`.
+{% /card %}
+
 {% card title="Set up tab completion"
     to="./autocomplete"
   %}