How do I search docs with compass?

How do I full-text search the documentation graph from the shell?

Run compass.sh search with a query. FTS5 ranks results across title, description, tags, content and outline path; results are deduplicated (one per doc) and capped at 5 by default.

1. Plain search (pretty output, default). Each hit is one block: type icon, title, description, and a ready-to-run yellow compass show <UUID> hint:

   ./projects/ores.compass/compass.sh search "service isolation"
   

2. Ask a question. Question-shaped queries ("How do I …?") run a title-scoped first pass — recipes are titled as the question they answer — and surface a 💬 answer extract from the recipe's * Answer section:

   ./projects/ores.compass/compass.sh search "How do I create a PR?"
   

3. Cap or widen the number of results with -l:

   ./projects/ores.compass/compass.sh search "currency" -l 10
   

4. Verbose output with -v: adds the file path, outline location, tags, and the matched snippet per hit:

   ./projects/ores.compass/compass.sh search "currency" -v
   

5. Machine-readable output with -f. line prints UUID "path" "match" (one per line, easy to pipe); json prints a structured array (uuid, path, title, olp, tags, snippet):

   ./projects/ores.compass/compass.sh search "nats" -f line
   ./projects/ores.compass/compass.sh search "nats" -f json
   

6. Scope by path with --under <path> (repeatable). Restricts results to docs below the given directory. Combine with --type to narrow further:

   # Full-text search across the product backlog captures only
   ./projects/ores.compass/compass.sh search "ores shell" \
     --under doc/agile/product_backlog --type capture
   
   # Backlog search for a feature idea (no grep needed)
   ./projects/ores.compass/compass.sh search "typesense" \
     --under doc/agile/product_backlog/inbox
   
   # All sprint-20 tasks mentioning codegen
   ./projects/ores.compass/compass.sh search "codegen" \
     --under doc/agile/versions/v0/sprint_20 --type task -l 10
   

The query supports FTS5 syntax (quoted phrases, AND=/=OR, * prefixes); a bare multi-word query is tokenised (punctuation safe) and OR'd with prefix matching.

projects/ores.compass/compass.sh search → src/compass.py, querying the compass_fts FTS5 table in .compass.db (built by compass index).

Manual smoke test. Read-only over .compass.db; if the index is empty or stale, re-run compass index (see the indexing recipe).

• How do I index notes for compass? — build the cache search reads.
• How do I find docs matching a pattern? — exact filter listing (compass list) when you know the type/tag/path.
• How do I see where we are? — current version / sprint / in-flight.