> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pnbr.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Search

> Search finds the Files that match, or their passages, and entities in the Graph, and it reports how much it covered.

Concept · core

> **Use when**
>
> You look for what a project says or knows, before you read, cite, answer or extract.

> **Looking for something else?**
>
> A File by its name or ID (card [File](https://docs.pnbr.io/concepts/file.md)). Everything about one topic as a packet (card [Context](https://docs.pnbr.io/concepts/context.md)). Walking relationships from a known entity (card [Relationship](https://docs.pnbr.io/concepts/relationship.md)).

## For

Search reads two places. File search returns passages: pieces of the text
extracted from a File's current version. Each passage comes with the File, the
version and the passage ID. Graph search returns entities saved in the Graph,
with their type and ID.

Search is how a job moves from Files to answers. Search finds a passage, you
open and cite it, and an entity can then hold the fact with that citation.
Search the Graph before you extract or capture, so you reuse an entity that
already exists.

A result is either a passage or a File. Passages are the default. To choose
among many Files, ask for the Files that matched. Each File comes with its
synopsis (card [Synopsis](https://docs.pnbr.io/concepts/synopsis.md)), so you open the few that matter and cite their
passages. The steps are search, then open, then cite.

A new edition of a File takes over in search once its version is ready (card
file). Every File search reports the mode that ran and how much of the project
it covered. Read that report before you decide that something is not there.

## Use when

* You need passages to answer a question or to cite.
* You must choose which of many Files to open, before you read any of them.
* You look for an entity by name, description or property before you create one.
* You must tell the person what the project holds on a topic.
* A result says it ran in a different mode than you asked for.

## Not this

* A File by name when you know it: use `penumbra files find` (card [File](https://docs.pnbr.io/concepts/file.md)).
* All you know about one topic, bundled for an agent: use card [Context](https://docs.pnbr.io/concepts/context.md).
* Entities one relationship away from a known entity: use card [Relationship](https://docs.pnbr.io/concepts/relationship.md).

## Rules

1. `search.1` Choose the mode on purpose. Lexical mode matches words and works
   as soon as a version is searchable. Semantic mode matches meaning. Hybrid
   mode does both. **Your job:** the defaults differ by door.
   `penumbra files search` uses hybrid, and `penumbra graph search` uses lexical.
   The command `penumbra search` uses each side's own default, unless you pass
   `--mode`. The MCP tool `omnisearch` and the program method `penumbra.search`
   use hybrid for both. The MCP tool `file_gallery` starts in a text mode that
   does not use meaning.
2. `search.2` The result states the mode that ran. **Your job:** read it. A
   hybrid search runs as lexical, with a warning, in three cases. No version has
   finished embedding. Meaning search is unavailable. The query is too long for
   it. A semantic search with no embedded version returns nothing and warns. If
   meaning search is unavailable, it fails with `semantic_unavailable`.
3. `search.3` File search covers only the current version of each live File.
   **Enforced:** older versions, trashed Files and versions that are still
   processing never appear. While a new edition processes, search still returns
   the old edition.
4. `search.4` Meaning search trails word search. A version is searchable by
   words first and by meaning after embedding. **Your job:** when a new File is
   missing from a meaning search, run `penumbra files inspect` on it and read
   the lexical and semantic status. Search by words in the meantime.
5. `search.5` Filters narrow a File search: File IDs, collection IDs, tags and
   media types. **Enforced:** an unknown or trashed File ID, or a File or
   collection ID from another project, refuses the whole search with
   `search_filter_not_found`. It does not say which ID was wrong. Filters never
   narrow the Graph side.
6. `search.6` `penumbra search` runs the File search and the Graph search
   together. **Your job:** read each side's own mode and warnings. One side can
   fail while the other answers, and the command exits non-zero only when every
   side fails. The limit is per side, so the lists share no ranking. With
   `--results files`, the Files side also reads the Files that matched. If that
   read fails, the Files side fails.
7. `search.7` Graph search finds only entities that are in the Graph. Staged
   items in a workspace are not found. **Your job:** after a submit returns
   `applied`, an entity can still be missing for a moment, so search again or
   open it by ID.
8. `search.8` Search has no filter or order by source date, and a File row
   carries none. **Your job:** read the source date from the version listing
   with `penumbra files versions`, and order the results yourself.
9. `search.9` Every File result carries the File ID, the version ID and the
   passage ID. An audio or video result carries a moment ID in place of the
   passage ID. **Your job:** keep all three with each fact you use. A citation
   needs them, and the person can reopen the passage with them (card [Passage and citation](https://docs.pnbr.io/concepts/passage.md)).
10. `search.10` Zero results does not mean the project lacks the fact. Lexical
    mode needs every plain word to match, and quoted phrases and `or` work.
    **Your job:** try hybrid mode, a shorter query and the coverage report. A
    View can also hide items, which then look missing.
11. `search.11` Each door sets its own limits. **Enforced:** `penumbra search`
    takes a query of up to 8,192 characters and 1 to 50 results per side. Its
    entity side takes up to 512 characters: a longer query still searches
    passages, and the entity side fails with `invalid_input`. The
    MCP tool `omnisearch` and `penumbra.search` take a query of up to 2,048
    characters and 1 to 20 results per catalog. They take up to 100 collections
    and up to 20 tags, media types or File references. A request outside the
    limit is refused as invalid.
12. `search.12` Choose what one result is. **Enforced:** `results:'passages'` is
    the default and returns passages. `results:'files'` returns one row for each
    File that matched. A row has its name, type, tags, collections,
    best-matching page, whether it is searchable by words and meaning, and its
    synopsis (card [Synopsis](https://docs.pnbr.io/concepts/synopsis.md)). A row carries no source date yet. **Your job:** ask for Files when you must choose, then read the
    few that matter and cite their passages. The command is
    `penumbra search --results files`. `--no-synopsis` and `synopsis:false` leave
    the synopses out.
13. `search.13` The filters combine in one way. **Enforced:** a File must be in at
    least one of the collections you name. It must carry every tag you name. It
    must match one of the media types and be one of the File references. The
    tool `omnisearch` and `penumbra.search` refuse a filter when `catalogs` leaves
    out `files`. **Your job:** name collections by ID, and check them in
    `project_overview` first.
14. `search.14` A search can read one catalog or both. **Enforced:** `catalogs`
    takes `files`, `graph` or both. Without it, the search reads every catalog the
    connection can read. A catalog it cannot read is refused with
    `catalog_unavailable`. The command `penumbra search` uses `--only` for the same
    choice.

## Failure signs

* Search returns nothing for words you know are in a File: problem
  [search-returns-nothing](https://docs.pnbr.io/troubleshooting/search-returns-nothing.md).
* Search warns that meaning search is unavailable: rule [search.2](https://docs.pnbr.io/concepts/search.md#rule-search-2).
* A new File is missing from a meaning search: problem
  [new-file-not-searchable-yet](https://docs.pnbr.io/troubleshooting/new-file-not-searchable-yet.md).
* You must choose among many Files and have only passages: rule [search.12](https://docs.pnbr.io/concepts/search.md#rule-search-12)
  and card [synopsis](https://docs.pnbr.io/concepts/synopsis.md).
* A filter returns less than you expect: rule [search.13](https://docs.pnbr.io/concepts/search.md#rule-search-13).
* You need the newest of several dated facts: rule [search.8](https://docs.pnbr.io/concepts/search.md#rule-search-8).
* Search returns text from the old edition after a replace: rule [search.3](https://docs.pnbr.io/concepts/search.md#rule-search-3).
* Search returns two passages that disagree about one fact: problem
  [two-editions-two-files](https://docs.pnbr.io/troubleshooting/two-editions-two-files.md).

## Doors

| Door | Call |
| - | - |
| CLI | `penumbra search`, `penumbra files search`, `penumbra graph search`, `penumbra files find`, `penumbra files inspect` |
| MCP (default) | `omnisearch` searches Files and Graph together, as passages or as Files. `file_gallery` browses and searches visually. `read` opens a result by its reference. |
| MCP (full catalog) | `search_files`, `search_workspace` and `search_graph`, with the default tools. The tool `search_workspace` finds paths. |
| MCP (Files Kits) | `search_files` in every Files Kit, `search_workspace` in Reader and Manager, and `omnisearch` when the connection can also read the Graph. |
| MCP (Domain Mode) | `search_graph` in the Domain Mode Kit. |
| execute | `penumbra.search` is the same search as `omnisearch`, with the same input. `penumbra.files.search` is the native power method: moments, grouping, neighbors and rerank. |
| SDK | `project.files.search`, `project.graph.search`, and `toSearchFileRows` for the File rows |

The MCP tool `search_graph` defaults to lexical mode and takes 1 to 100 results.
The CLI command `penumbra graph search` takes the same range.

## The CLI word

The CLI calls a passage a chunk.

## HTTP reference

* [Search files](https://docs.pnbr.io/api/http-files-search.md)
* [Resolve citations](https://docs.pnbr.io/api/http-files-chunks.md)
* [Search graph](https://docs.pnbr.io/api/http-graph-search.md)
* [Get entity context](https://docs.pnbr.io/api/http-context-entity.md)
* [Explore context](https://docs.pnbr.io/api/http-context-explore.md)

## Keep going

[File](https://docs.pnbr.io/concepts/file.md) · [Passage and citation](https://docs.pnbr.io/concepts/passage.md) · [Entity](https://docs.pnbr.io/concepts/entity.md) · [Collection](https://docs.pnbr.io/concepts/collection.md) · [Synopsis](https://docs.pnbr.io/concepts/synopsis.md) · [Search returns nothing](https://docs.pnbr.io/troubleshooting/search-returns-nothing.md)

Penumbra Grammar 0.6.26


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.