0.18.0 — retrieval you can measure, see into, and steer

What this release is about¶

Retrieval was a black box: you could not point it at your own corpus, could not see inside it, and could not improve it without editing the source. 0.18.0 opens all three — a model you can change (embed_model:), an instrument you can run (docir bench), a trace you can read (--explain) — and adds a way to hand docir a better question (context --also, query --expr).

Released 2026-08-25. The full text is in CHANGELOG.md and on the GitHub release; this document exists for the half neither of those can hold — the edges.

What an upgrader must do¶

Run docir self upgrade. No migrations, but the relation-kind registry gained a property, and the index records the schema it was built against — until each store reindexes, docir check reports six schema-drift findings, one per core kind. Peers in stores.yaml each need their own reindex, as always.

Nothing is rewritten and no flag is retired. embed_model: is absent from every existing schema, which means the default, so retrieval is byte-identical until you set it.

Why it is a graph and not a second changelog¶

A changelog is a list; this release was an argument, and the argument is in the decisions it links. Four of them record work that was built and thrown away — a reranker's successor, a query rewriter, a weighting scheme, a generative dependency — and those are the entries a later reader most needs, because they are the ones somebody will otherwise propose again.

Read the linked decisions rather than this document. It is an index.

What it cost to be sure¶

Every ranking change in 0.18.0 was measured before it shipped, and the instrument that measured them shipped in the same release. Two mechanisms were measured and rejected: pseudo-relevance feedback lost 0.13 recall@5, and cross-encoder reranking had already lost more in 0.15.

Three defects were found by using the features rather than by reading them — a documented mermaid bundle that no longer existed, three flags that reached no MCP tool, and a check that called a problem good news. adr-7d9fbbf976e8 is the rule that came out of that, and it is the one entry here that is about how the work is done rather than what it produced.