Where: faircode/SPEC.md:391 (the list_explainers MCP tool table row) vs. faircode/mcp_server.py:60-61,243,249 (EXPLAINERS_DIR, _load_explainers_metadata, and _list_explainers_impl's own docstring).
The gap: the table says list_explainers wraps assets/explainers-data.json, and the tool's own docstring says it "reads the same assets/explainers-data.json the website's index page does." The code actually reads faircode/_explainers/data.json - a package-internal generated mirror built by scripts/build_explainers.py, specifically because assets/ isn't a file pyproject.toml ships (issue #388).
Repro:
$ grep -n "EXPLAINERS_DIR\|EXPLAINERS_DATA_JSON" faircode/mcp_server.py
60:EXPLAINERS_DIR = Path(__file__).resolve().parent / "_explainers"
61:EXPLAINERS_DATA_JSON = EXPLAINERS_DIR / "data.json"
$ grep -n "assets/explainers-data.json" faircode/SPEC.md faircode/mcp_server.py
faircode/SPEC.md:391:| `list_explainers` | `assets/explainers-data.json` | ...
faircode/mcp_server.py:249: same assets/explainers-data.json the website's index page does, so it's
EXPLAINERS_DIR resolves to faircode/_explainers/, not assets/.
Why it matters: this is the exact same category of doc/code mismatch already fixed for get_benchmark_results in #434 - it contradicts the packaging story faircode/SPEC.md tells elsewhere (explaining why faircode/_explainers//faircode/_results_frozen/ exist as generated package-internal mirrors), giving a reader the wrong mental model of what a real pip install faircode[mcp] actually reads from.
Suggested fix: update the SPEC.md table cell to faircode/_explainers/data.json (mirrored from assets/explainers-data.json), and reword the docstring at mcp_server.py:249 to match.
Where:
faircode/SPEC.md:391(thelist_explainersMCP tool table row) vs.faircode/mcp_server.py:60-61,243,249(EXPLAINERS_DIR,_load_explainers_metadata, and_list_explainers_impl's own docstring).The gap: the table says
list_explainerswrapsassets/explainers-data.json, and the tool's own docstring says it "reads the sameassets/explainers-data.jsonthe website's index page does." The code actually readsfaircode/_explainers/data.json- a package-internal generated mirror built byscripts/build_explainers.py, specifically becauseassets/isn't a filepyproject.tomlships (issue #388).Repro:
EXPLAINERS_DIRresolves tofaircode/_explainers/, notassets/.Why it matters: this is the exact same category of doc/code mismatch already fixed for
get_benchmark_resultsin #434 - it contradicts the packaging storyfaircode/SPEC.mdtells elsewhere (explaining whyfaircode/_explainers//faircode/_results_frozen/exist as generated package-internal mirrors), giving a reader the wrong mental model of what a realpip install faircode[mcp]actually reads from.Suggested fix: update the SPEC.md table cell to
faircode/_explainers/data.json(mirrored fromassets/explainers-data.json), and reword the docstring atmcp_server.py:249to match.