Search

docpack indexes a corpus at the section level — one entry per heading, plus one per named command snippet — so a search returns the specific part of a page that matches, not just the whole document. The same index and ranking power three surfaces: the docpack search command line verb, the search box in a built site, and the search_docs tool an agent calls over MCP.

docpack --root pack search "trust model"

See run docpack search for the full command and flag reference, and the MCP server for how search_docs returns the same hits to an agent.

1What gets indexed#

Every section of every page — the text under each heading — and every named command snippet get their own searchable entry. A command's copy-exact text is indexed too, so a query can match on the contents of a command, not only the prose around it. Each entry also carries its page's title, its computed freshness badge (see freshness and badges), and whether the page is quarantined.

2Trust-aware ranking#

A match is scored by where the term hit — a title match counts for more than a heading match, which counts for more than a match in the body text — and the result is then adjusted by how much the page can be trusted: a page badged "up to date" ranks higher than an otherwise-equal hit on a stale, failing, or quarantined page. Ranking favors trusted pages by design, so a stale result has to be a noticeably better match to outrank a fresh one, not a marginal one. Quarantined pages are excluded from results entirely unless you explicitly ask to include them — the same refusal behavior quarantine enforces everywhere else in docpack.

3A narrow query still finds something useful#

By default, every word in a query has to match somewhere for a section to be a hit, apart from filler words like "how" and "the", which are ignored unless the query is nothing but filler. But when that turns up nothing — the way a specific, natural-language phrase sometimes does — search doesn't just return an empty page. It falls back to ranking every section that matched at least one of your words, ordered by how many distinct words it matched. A narrow query that has no exact hit still surfaces the closest related pages instead of a dead end. Either way, one page can't fill the front of the list: after its two best sections, a page's other hits move to the end of the ranking instead of being dropped.

4Two transports, one result#

docpack search on the command line and the search_docs tool an agent calls over MCP return the same ranked hits, in the same shape — a title, the matched heading, an excerpt, the page's route, and its freshness badge — so a script or an agent parsing one sees exactly what a person sees typing into the site's search box.