> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whyfile.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Querying the intent layer

> explain, list-intent, and why — the three read-only, LLM-free query commands.

## Querying the intent layer

Once a run has produced its outputs, three subcommands read them back: **read-only, LLM-free,
and free of charge** (no backend call, no cost). Each prints exactly one **JSON object on
stdout by default**; add `--format text` for a human-readable render instead. All three accept
`--graph PATH` (default `graphify-out/graph.json`, same as the pipeline; may be given before or
after the subcommand name) and exit `0` for a `status` of `ok`/`no_strong_match`, `2` for
`not_found`/`ambiguous`/`no_intent_layer` (see [Exit codes](cli-reference.md#exit-codes); full JSON
schemas are in [`AGENTS.md`](../../AGENTS.md)).

**`explain <node>`** resolves `<node>` (an exact node id, else a rapidfuzz match over node
labels) and explains it: for a **code/document node**, the intent node(s) that motivate it (the
intent-origin `rationale_for` edges pointing at it); for an **intent node**, its own
claim/rationale, the node(s) it explains, and its Pass-C relations (a supersession is surfaced
as `superseded_by` on the superseded node). Requires `graph.enriched.json`; returns
`status: "no_intent_layer"` (exit `2`) if it doesn't exist yet.

```bash theme={null}
whyfile explain AuthModule
whyfile explain i_d1 --format text
```

**`list-intent [--kind decision|mechanism|constraint|tradeoff] [--min-confidence F]`** returns the
intent inventory, optionally filtered by kind and/or a minimum `confidence_score`.

```bash theme={null}
whyfile list-intent --kind decision --min-confidence 0.8
```

**`why "<question>"`** ranks intent nodes against free text with rapidfuzz token matching and
returns the top `--top` (default `5`) by score (0-100); a top score below the cutoff (60) still
returns its results, just with `status: "no_strong_match"` so a caller can tell the match was
weak.

```console theme={null}
$ whyfile why "why does Pass A use a stronger model than the others" --top 2 --format text
Top 2 match(es) (no_strong_match):
   56  [tradeoff] Per-pass tiering protects Pass A quality — Running Opus on every pass was the
       cost bug; tiering lets cheaper models handle most passes, but Pass A is deliberately held
       on sonnet because its output quality matters enough to justify the higher tier.
   56  [decision] Per-pass model tiering — Passes B/C/D need less reasoning than A, so downgrading
       them to cheaper haiku captures most of the cost saving without hurting quality — but a
       user's explicit model choice still wins.
```

`list-intent` and `why` don't require `graph.enriched.json`; they fall back to the
`.whyfile.json` sidecar when it's the only artifact present. The pipeline itself is
unchanged: running `whyfile` with no subcommand still runs the extract/anchor/relate
run described above.