Doc Search

BM25 inverted index + LLM query expansion + grep. Zero external dependencies.

Workflow

Follow these steps in order every time:

Step 1 — Resolve docs_dir

Check if the user mentioned a docs directory. If not, ask:

"Which directory should I search? (e.g. ~/obsidian, ~/notes)"

Step 2 — Check index exists

CODEBLOCK0

• - If missing → go to Step 3 (build index first)
• If exists → skip to Step 4

Step 3 — Build index

CODEBLOCK1

Index saved to <docs_dir>/.doc-search/index.json. Incremental on subsequent runs.

Step 4 — Expand query terms

Before searching, expand the user's query to cover synonyms, Chinese/English variants, and likely headings. Combine into one string:

CODEBLOCK2

Step 5 — BM25 search

CODEBLOCK3

Output: JSON array INLINECODE1

Step 6 — Grep top-K for precise location

For each result file, grep with the original keywords:

CODEBLOCK4

Report file path + matching line numbers to the user.

Options