tero-explain

name	tero-explain
description	Get the EXPLAIN trace for a mycelium-tero query — why these sources, in what order: the candidate count, the ordering rule(s) applied, a per-hit reason, and any cross-reference edges that could not be resolved. The auditability view of the transparent memory API (DN-87 / E39-1).
when_to_use	Use when you need to audit or debug a retrieval — understand why a query returned what it did (or ranked one hit above another), or which cross-reference edges were unresolved — rather than just consuming the answer.
allowed-tools	Bash(curl:*), Read

/tero-explain — The EXPLAIN Trace for a Query

explain runs the same query as /tero-query but returns only the EXPLAIN trace — retrieval is never a black box (DN-87 §4). The trace is a pure function of the query and the (already-sorted) index: two runs produce byte-identical output (no clock, no rng).

Fields: query (the query as executed, including any depth clamp), candidates_scanned, candidates_matched (pre-cap total, so a truncated result set is visible — never silently), order_by (the ordering rule(s), outermost first), hits (per-result anchor + score + a why reason, in final order), and unresolved_edges (for cross_ref: depends_on/doc_refs edges considered but not resolvable within Layer 1 — recorded, never dropped, G2).

HTTP

curl -s -H 'Authorization: Bearer demo' 'http://127.0.0.1:8787/v1/explain?kind=text&value=eval%20gate'
curl -s -H 'Authorization: Bearer demo' 'http://127.0.0.1:8787/v1/explain?kind=cross_ref&start=M-1017&depth=2'

Envelope: {"kind":"explain","explain":{ "query":…, "candidates_scanned":…, "order_by":[…], "hits":[…], "unresolved_edges":[…] }}.

MCP

tools/call with { "name": "explain", "arguments": { "kind": "text", "value": "eval gate", "token": "demo" } }.

Honesty

The text ranking weighting is stated verbatim in order_by (id match ×4 + title ×3 + summary ×1 per matched term). A cross_ref walk is clamped to a hard depth cap; the clamp, if applied, is recorded in the query string (never silent). Unresolved api:/src: doc_refs and dangling depends_on ids are listed, not hidden — the trace is the honest account of what the engine did.