--- title: "Answer questions about a docs folder" canonical: "https://xerj.org/answers/answer-questions-about-a-docs-folder-with-citations" updated: "2026-10-20" source: "content/answers/answer-questions-about-a-docs-folder-with-citations.md" --- # Answer questions about a docs folder, with a file to cite **Short answer** (updated 2026-10-20): Answer questions about a docs folder by indexing it with `xerj autoindex`, then running a phrase query. Each hit carries `ax_path`, so the agent can cite the file. On 2026-10-20 a phrase query for "what is in here" returned `WHY_XERJ.md` and took 1 ms. `xerj search` on the same words did not. **Key number:** A phrase query for "what is in here" returned WHY_XERJ.md and took 1 ms. (as of 2026-10-20; source: [benchmarks/agent-queries-2026-10-20/08-docs-phrase.json](https://github.com/xerj-org/xerj/blob/main/benchmarks/agent-queries-2026-10-20/08-docs-phrase.json)) **TL;DR** — Answer questions about a docs folder by indexing it with `xerj autoindex`, then running a phrase query. Each hit carries `ax_path`, so the agent can cite the file. On 2026-10-20 a phrase query for "what is in here" returned `WHY_XERJ.md` and took 1 ms. `xerj search` on the same words did not. ## Agent prompt ```text Read https://xerj.org/llms.txt. Start one local node, run xerj autoindex on the docs folder, then run xerj autoindex map and query the prose field it names. Cite ax_path for every passage you use. If xerj search returns code identifiers, say so and run a match_phrase on the prose field. ``` ## Commands ### Command 1 Note: Index the docs folder. The capture exited 3, which is completed-with-junk. ```sh xerj autoindex --url http://127.0.0.1:9217 --yes --no-graph --progress plain --disable-feedback /workspace/docs --prefix docs --state-dir /tmp/xerj-aq-2026-10-20/state-docs ``` ### Command 2 Note: Definition-first search. On this question it returned code lines, not the prose sentence. ```sh xerj search --url http://127.0.0.1:9217 --prefix docs -k 3 what is in here ``` ### Command 3 Note: Phrase query on the prose field. One hit, WHY_XERJ.md, took 1 ms. ```sh curl -s -XPOST http://127.0.0.1:9217/docs-docs/_search -H 'content-type: application/json' -d '{"size":3,"_source":["ax_path","title"],"query":{"match_phrase":{"body":"what is in here"}}}' ``` XERJ is a new way for AI to search for data. ## Index the folder The capture pointed `xerj autoindex` at this repo's `docs/` directory. It walked 294 files, skipped 10 by ignore rules, and committed 11 datasets and 9,940 records. Wall time was 14.3 s. Exit 3, `reason=completed-with-junk`: 3 files were junk, and the rest is searchable. Exit 3 is success. ```text xerj-done ok=true exit=3 reason=completed-with-junk wall=14.3s files=290 records=9940 generation=1 ``` `xerj autoindex map` names the real fields. On the markdown dataset the prose field was `body`. ## The code command missed the sentence ```sh xerj search --url http://127.0.0.1:9217 --prefix docs -k 3 "what is in here" ``` The command printed three passages, all code, all a variable named `here`. It said to cite `ax_path:line`. The capture file is 689 bytes. `rg -n` on `docs/**/*.md` printed one line, in `WHY_XERJ.md`, and that capture file is 270 bytes. For this question `rg` was shorter and it was the right line. ## Ask the prose field ```sh curl -s -XPOST http://127.0.0.1:9217/docs-docs/_search -H 'content-type: application/json' -d '{"size":3,"_source":["ax_path","title"],"query":{"match_phrase":{"body":"what is in here"}}}' ``` One hit. `ax_path` was `WHY_XERJ.md`. `took` was 1. The title on the hit was the file's first heading. The same response said the query scored `body` with BM25 and did not read the embedding. Ranking is lexical unless the node was started with `--embed-mode neural`. XERJ does not write the answer. It returns the passage and the path. The agent quotes the path. ## Measured on 2026-10-20 | Check | Result | |---|---| | `xerj autoindex` on `docs/` | Exit 3, 9,940 records, wall 14.3 s, 3 junk files | | `xerj search` "what is in here" | 3 code passages. Capture file 689 bytes | | `rg` the same words | 1 line in `WHY_XERJ.md`. Capture file 270 bytes | | `match_phrase` on `body` | 1 hit, `WHY_XERJ.md`, `took` 1 ms | One node, binary v1.0.0-rc.97. `rg` won this comparison on both bytes and the right line. ## When not to use XERJ If the question is one exact string in a handful of files, `rg` already returned it. Use the index when the folder is large enough that you want a ranked passage and a path, or when the next step is an agent call rather than a scroll. ## FAQ ### Answer questions about a docs folder? Index the folder, then run a phrase query on the prose field. Cite `ax_path`. The agent writes the answer. XERJ returns the passage. ### Local search for documentation with citations? The 2026-10-20 phrase query returned `WHY_XERJ.md` and took 1 ms. Nothing in that query left the machine. ### Search large roadmap and changelog files? They are markdown in the same folder. A hit carries `ax_path`. This capture's prose hit did not include a line number. ### Does xerj search answer a prose question? Not this one. `xerj search` returned three code passages about a variable named `here`. `rg` found the sentence in `WHY_XERJ.md`. ### Can I run xerj ask on the folder? No. `xerj ask` answers hub corpora. A folder you autoindexed is `xerj search`, `xerj def`, or a `_search` body. ## Evidence - autoindex of docs/ exited 3, wall 14.3 s, 9,940 records, 3 junk files. — `benchmarks/agent-queries-2026-10-20/02-autoindex-docs.txt` - xerj search wrote 689 bytes and rg wrote 270 bytes for the same words. — `benchmarks/agent-queries-2026-10-20/02-byte-compare.txt` - match_phrase on body took 1 ms and returned WHY_XERJ.md. — `benchmarks/agent-queries-2026-10-20/08-docs-phrase.json` ## Related - [I want to point something at a folder and then ask questions about what's in it. What should I use?](/answers/how-xerj-autoindexes-a-folder) - [I have a folder of PDFs, Word docs, and markdown. How do I search all of them at once?](/answers/search-file-contents-in-a-folder) - [How should an agent figure out what's in a messy data folder before searching?](/answers/catalog-files-with-autoindex-map)