# Searching from the command line

`docspack search` runs the same query an agent would, and prints the results. Use it to
check that a package is indexed, to see what an agent will receive, or to find something
yourself.

```bash
npx docspack search "webhook signature"
```

An answer can also carry a declaration read from an installed library, ahead of the prose,
when the question names something no documentation mentions. That path does not go through
the ranking described below — see
[answers from the installed build](10-answers-from-the-installed-build.md).

## How matching works

The index is a SQLite FTS5 table tokenized with `porter unicode61`. Porter stemming means a
search for `authentication` matches a chunk that only says `authenticate`, and `retries`
matches `retry`.

Both the chunk's text and its tags are indexed, so a manifest that tags a chunk with
`idempotency` makes that chunk findable even when the word never appears in the prose.
Results are ranked by BM25, which favours chunks where the query terms are frequent and
distinctive. Tags weigh three times as much as prose, so the chunk an author tagged for a
subject beats one that merely repeats the words.

Query text is tokenized and each term is quoted before it reaches SQLite. Punctuation in a
query is searched for literally instead of being interpreted as FTS syntax, so a query like
`auth AND (NOT "x")` returns results rather than a syntax error.

Terms of one or two characters are dropped, because a question is mostly `how`, `do`, `i`
and `in`, and every chunk containing one of those becomes a candidate. A query made only of
short terms keeps them all, so `docspack search "id db"` still searches.

## Narrowing and widening results

- `--package <text>` restricts results to packages whose name contains that text, for
  example `--package stripe`.
- `--limit <n>` changes how many chunks are returned. The default is 3. It works on `ask`
  and `preview` too, so an agent that gets three near-misses can ask again for more.
- `--max-tokens <n>` changes the token ceiling for the whole result set. The default is
  3,000. Also honoured by `ask` and `preview`.
- `--all` searches every version in the index instead of only the versions this project
  installed. Useful when comparing releases; not what an agent should see.

## Machine-readable output

Every command accepts `--json`, which prints the full result including chunk ids, token
counts, file paths and trust flags:

```bash
npx docspack search "retry policy" --json
```

## Exit codes

`ask` and `search` distinguish the two ways an answer can be empty, so a script does not
have to read the prose to tell them apart:

| Code | Meaning |
| ---- | ------- |
| 0 | Chunks were returned |
| 3 | Nothing matched, and a docs package is installed but not indexed — run `docspack sync` |
| 4 | Nothing matched, and everything installed is already indexed |
| 1 | The command failed |
| 2 | The command was used wrongly |

Code 3 is the first-run case. The answer says which package it is, because "you have not
indexed anything yet" and "the documentation does not cover this" are different problems and
only one of them is yours to fix.