# mentu-navigator

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22016638.svg)](https://doi.org/10.5281/zenodo.22016638)

Read-only, provenance-first repository navigation for humans and AI agents.

Point it at a repository and ask a question. It returns ranked file-and-line
ranges to read, each carrying the reason it ranked, and it never writes to the
repository it reads. It is built for agents that must find the document that
answers a question in a documentation-heavy repository, without pulling the
whole thing into context, and for the people reviewing what those agents did.

**Scope.** The ranking default is measured on documentation: markdown corpora,
in pre-registered studies (see *Evidence*). It has not been measured on source
code, where published comparisons favour other locators (see *Scope of the
evidence*). The code-structure commands (`map`, `symbol`, `impact`) work on any
repository; their usefulness has not been measured.

`mentu-navigator` is the product name. `mentu-nav` is its short CLI.

## Install

Requires Node.js 20 or newer.

```sh
npm install -g mentu-navigator     # CLI: mentu-nav, MCP server: mentu-navigator-mcp
```

To run it without installing:

```sh
npx -p mentu-navigator mentu-nav "where is retry handled?"
```

The package name and the command name differ, so `npx mentu-navigator` on its
own cannot resolve a binary. Pass `-p` as above.

License: Apache-2.0. Telemetry is local-only JSONL under `~/.mentu/pd1/`
(spec: [docs/TELEMETRY-SPEC.md](docs/TELEMETRY-SPEC.md)); disable with
`MENTU_NAV_TELEMETRY=off`. Nothing ever leaves the machine.

## Where it sits in Mentu

`mentu-navigator` is the retrieval surface.
[`mentu-pdv`](https://github.com/mentu-ai/mentu-pdv) validates the frontmatter
schema this tool consumes and emits the demotion sets `locate` applies. The two
are designed as a pair, and the schema is published as a spec
([SPEC-frontmatter.md](https://github.com/mentu-ai/mentu-pdv/blob/main/SPEC-frontmatter.md)).

## Why it exists

Search tools find matching text. A repository navigator also preserves the
question's intent and returns the nearby contracts, tests, docs, Git lineage,
and risk surfaces needed to act safely.

The first release is intentionally deterministic:

- no embeddings;
- no background index;
- no writes to target repositories;
- on-demand, bounded frontmatter handles that route to documents but never
  replace reading them;
- bounded snippets with file-and-line provenance;
- known secret-bearing paths excluded before content reads.

## One-command start

```bash
cd /path/to/repository
mentu-nav
mentu-nav "where is DEMO-274 implemented and tested?"
```

Interactive terminals receive a concise human view. Pipes receive compact JSON;
`--json` requests the full envelope.
Agents should use `--agent` for a compact, token-efficient JSON contract:

```bash
mentu-nav --agent "where is DEMO-274 implemented and tested?"
```

The front door auto-routes to `map`, `query`, `handles`, `symbol`, or `impact`. Their
explicit commands remain available for scripts and advanced use.

For a docs-as-code network:

```bash
mentu-nav handles "catalog lineage"
```

This returns metadata pointers, typed relationships, and diagnostics. Every
pointer carries `requiresHydration: true`. `query` keeps these pointers separate
from source-body evidence so a summary cannot silently become an answer.

## Capabilities

| Capability | Question answered | Evidence |
|---|---|---|
| `map` | What is here? | files, languages, contracts, manifests, typed docs, Git state |
| `query` | Where is the relevant evidence? | ranked path/line/snippet hits and routing reason |
| `locate` | Which ranges should I read? | BM25-ranked hits with retriever attribution (evidence-backed default) |
| `read-range` | What does that range say? | heading-bounded slice, frontmatter returned separately |
| `handles` | Which docs and typed relationships may matter? | frontmatter pointers, relationship resolution, diagnostics; hydration required |
| `symbol` | What surrounds this symbol? | definitions, references, tests, docs, config |
| `impact` | What may this change affect? | Git range, tickets, contracts, tests, risk signals |

## Progressive disclosure: `locate` and `read-range`

`locate` is the agent surface. Its default arm is **ranked lexical retrieval
(BM25)**. That default was set by a pre-registered study, not by taste (see
*Evidence* below). Two legs exist:

- a **ranked lexical leg**: in-memory Okapi BM25 over the same file set the
  walker already produces, with vendored Snowball stemmers for Spanish and
  English, routed by each document's `lang` frontmatter tag (detected as a
  fallback, and the detection is logged, never written);
- an **exact leg**: the deterministic `query` pipeline, unchanged in semantics.

A fused arm (reciprocal rank fusion of the two legs) exists as a measurement
arm. It was the original default and was **retired from the default path by
its own pre-registered ablation rule** when the registered bake-off found it
trailing plain BM25 by 7.8 points of localization (see *Evidence*). Every hit
says which leg (or both) put it there.

```bash
mentu-nav locate "compaction policy" --k 8
mentu-nav read-range docs/adr/ADR-014-ledger-compaction.md 38 62 --widen 1
```

`locate` returns `{path, line, range, snippet, score, retriever, why}`. That
is a range to read, not an answer. `read-range` returns the slice; each `--widen`
step reaches ±20 lines further and stops at the enclosing heading boundary, and
frontmatter comes back in its own field so metadata cannot be mistaken for body
evidence. Handles remain the pointer layer, unchanged: every pointer still
carries `requiresHydration: true`.

### Pinned parameters

These are design parameters, not implementation details. Each is registered as
an ablation and measured there; changing one is a dated decision plus a
re-measurement.

| Parameter | Value | What it governs |
|---|---|---|
| `LOCATE_DEFAULT_K` | 8 | hits `locate` returns by default |
| `LOCATE_MAX_K` | 40 | ceiling on `k`, whatever a caller asks for |
| `SNIPPET_MAX_CHARS` | 240 | snippet length, whitespace-normalized to one line |
| `WIDEN_STEP_LINES` | 20 | one `read-range` widening step |
| `RRF_K` | 60 | reciprocal rank fusion constant |
| `DEMOTION_MULTIPLIER` | 0.5 | penalty applied to a demoted document |

The legacy `query` command keeps its own human-facing default of 40 results;
the pins above govern `locate`.

### Demotions

`--demotions <path>` reads a `pdv demotions` JSON file (resolved against the
repository root) and multiplies those documents' scores by 0.5. A demoted
document ranks lower and is **never removed**. An unavailable document is the
more expensive error. An unreadable or malformed demotion set is reported in the
envelope diagnostics rather than silently ignored.

### `--retriever` is for measurement

`--retriever=bm25|exact|fused` selects an arm (default `bm25`). It exists so a
registered bake-off's arms are produced by the shipped code path rather than by
a harness fork. That is exactly how the defaults here were decided. The flag
is not a tuning knob.

### Evidence

Every performance-relevant default in this tool traces to a registered,
mechanically adjudicated study, and every claim below carries its scope: one
141-document bilingual operational documentation corpus, a fresh 115-question
blind set, this tool's k=8 contract. The bake-off
([doi:10.5281/zenodo.21969901](https://doi.org/10.5281/zenodo.21969901),
companion to [doi:10.5281/zenodo.21960138](https://doi.org/10.5281/zenodo.21960138)):

- **BM25 located the gold document on 93.0% of questions vs hardened exact
  search's 71.3%** (McNemar p < 1e-5). That is why `bm25` is the default.
- **The fused arm trailed BM25-alone by 7.8 pp** (p = 0.0225), failing its
  frozen "fusion never costs localization" prediction; the pre-registered
  ablation rule retired it from the default path
  ([docs/build/D3-REVISION-2026-08-16.md](docs/build/D3-REVISION-2026-08-16.md)).
- An off-the-shelf SQLite FTS5 control (89.6%) was **not statistically
  distinguishable** from this implementation. BM25 as such carries the gain.
- Downstream answer accuracy moved +5.2 pp under the better locator, almost
  entirely through localization.

Nothing here claims generality beyond that corpus class; the study, corpus
manifest, question set, and adjudicator are public in the DOIs above for
re-running.

### Scope of the evidence

Every study behind these defaults used markdown documentation; none used source
code, and the difference matters. Finding the file to change from an issue
description is a lower-overlap task, and published comparisons rank BM25 below
embedding retrieval there. On SWE-bench Lite, BM25 placed a correct file among
its top five 61.7% of the time, against 84.7% for a code-embedding retriever
([Chen et al., *LocAgent*, Table 4](https://arxiv.org/abs/2503.09089)). So:

- for a question answered by a document (a runbook, an ADR, a specification),
  use `locate`, then read the range it returns;
- to find code from an issue or a behaviour description, prefer your harness's
  native search, or a code-aware locator, until a study on code exists;
- a pre-registered comparison of this tool inside a live agent, against the
  harness's native tools, is drafted with a code-localization stratum. It has
  not been run. When it has, this section will report its result either way.

What *is* additionally asserted by the test suite on every commit: the index writes
nothing to a target repository and lives in memory for the life of the process;
identical corpus and query produce byte-identical hit lists across runs and
index rebuilds; secret-bearing paths are excluded before tokenization, not
after; and a search pattern beginning with `-` is passed after a literal `--`
so it can never be parsed as an engine flag.

## MCP

`mentu-navigator-mcp` exposes:

- `navigator`: preferred compact, auto-routing entrypoint
- `locate`: BM25-ranked ranges, with `retriever` and `demotions`
- `read_range`: the disclosure step `locate` hands off to
- `navigator_map`
- `navigator_query`
- `navigator_handles`
- `navigator_symbol_context`
- `navigator_change_impact`

An MCP client configuration:

```json
{
  "mcpServers": {
    "mentu-navigator": {
      "command": "npx",
      "args": ["-y", "-p", "mentu-navigator", "mentu-navigator-mcp"]
    }
  }
}
```

or launch the installed binary `mentu-navigator-mcp` directly.

## Agent setup

```bash
mentu-nav setup --target all
mentu-nav doctor --human
```

Setup links the bundled skill into Codex and Claude without copying its logic.
It refuses to replace an existing path. Repository navigation itself remains
read-only.

## Adoption

The executable remains centralized. Repositories adopt only a short operating
contract; they do not copy the implementation. See [docs/adoption.md](docs/adoption.md).