Rules for agents (read first)

• For a specific term you can name, use bounded grep -C "term" file | head first — it's leaner than ranked search.
• Use query when grep would FLOOD, or when you have no reliable exact term: a common/ambiguous term over a corpus too large to scan (grep returns dozens of matches to sift), OR you don't know the document's exact wording (grep may return zero hits, sending you into repeated synonym guessing). query ranks the best passages and returns a bounded top-k, so it keeps context small.
• Small -k (1-2) for a single fact; --language <lang> for non-English so inflected/umlaut forms match (German Antrag<->Anträge).
• Build an index (--emit-index) only for many queries over the same corpus.

Query a document

Ranked search over an already-extracted text or Markdown file. You give it a natural-language query; it returns the most relevant line windows (with line numbers), not the whole document. This is the "parse once, then query the file" pattern: convert a PDF a single time, then ask as many questions as you like against the cheap, local text.

This is built for agent economy. A converted document can be tens of thousands of lines and will blow out your context window if you read it back. Querying returns only the handful of passages that matter, with line numbers you can use for a precise follow-up read.

When to use this

• Use query when you have a converted file and a question — "what's the termination clause", "where are the FY24 revenue figures", "does this mention indemnification". It ranks every line and hands back the best windows.
• Use pdf-to-markdown / pdf-to-text first to produce the file. query does not parse PDFs; it searches their extracted text.
• Don't read the whole converted file into context to find one thing, and don't run grep after grep — that's what this replaces. One ranked query beats many exact-match passes when you don't know the document's exact wording.