> ## 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.

# Synopsis

> "Penumbra's short account of what one File version is (its kind, subject, parties, period and status), written automatically from the file itself. Use it to decide which Files to open; cite passages, not the synopsis. It changes when a new version is ready. It is not the File's description, which the project sets and reviews (organizer or person)."

Concept · files

> **Use when**
>
> You must choose which Files to open from a search or a list, before you read or cite any of them.

> **Looking for something else?**
>
> The File's description, which the project sets and reviews (card [File](https://docs.pnbr.io/concepts/file.md)). The text you cite (card [Passage and citation](https://docs.pnbr.io/concepts/passage.md)). Finding Files by their content (card [Search](https://docs.pnbr.io/concepts/search.md)).

## For

A synopsis is a short account of one File version. It says what the File is:
its kind, its subject, the parties it names, the period it covers and its
status. Penumbra writes it from the file itself, once for each version. No
person or agent writes or edits it.

An agent that searches a project often gets more Files than it can open. The
synopsis is how it chooses. It reads one short account for each File, opens the
few that matter, and cites passages from them (card [Passage and citation](https://docs.pnbr.io/concepts/passage.md)). A synopsis tells
you where to look. It does not say what the File says.

A new version has its own synopsis. The File shows the synopsis of its current
version, so it changes when a new version is ready (card [File](https://docs.pnbr.io/concepts/file.md)). A File can also
have no synopsis yet, because Penumbra writes it after the version is stored.

The synopsis is not the File's description. The project sets and reviews the
description, in its own words. The synopsis is automatic and unreviewed. One
never replaces the other.

## Use when

* A search returns many Files and you must decide which to open.
* You list the Files of a collection and need to know what each one is.
* You tell a person what a File is without reading all of it.

## Not this

* What the File is called or how the project describes it: read the File
  (card [File](https://docs.pnbr.io/concepts/file.md)).
* The exact words that support a claim: use a passage and its citation
  (card [Passage and citation](https://docs.pnbr.io/concepts/passage.md)).
* Finding Files by what they say: use search (card [Search](https://docs.pnbr.io/concepts/search.md)).

## Rules

1. `synopsis.1` A synopsis belongs to one File version. Penumbra writes it
   automatically. **Enforced:** nobody can set or edit one. A new version gets its
   own, and the File shows the synopsis of its current version.
2. `synopsis.2` A File can have no synopsis, and the result says why. A synopsis
   is "not written yet", "being written", "could not be written", or "not
   written for this type of file". **Your job:** read a missing synopsis as
   unknown. It says nothing about the File. Open the File to learn what it holds.
3. `synopsis.3` Cite passages, not the synopsis. **Your job:** use a synopsis to
   choose Files, then read and cite their passages (card [Passage and citation](https://docs.pnbr.io/concepts/passage.md)). A synopsis is
   an automatic account. It is not the text of the File.
4. `synopsis.4` The synopsis is not the description. **Enforced:** they are two
   separate fields of a File, and writing a synopsis never changes the
   description. **Your job:** read the description as the project's own words
   and the synopsis as Penumbra's.
5. `synopsis.5` Search can return a synopsis with each File. **Your job:** ask for
   Files, not passages, when you must choose. Use `--results files` in
   `penumbra search`, or `results:'files'` in the MCP tool `omnisearch` and in
   `penumbra.search`. Add `--no-synopsis`, or `synopsis:false`, to leave the
   synopses out. The MCP tools `browse_files` and `file_gallery` show it too.

## Failure signs

* A File shows no synopsis: rule [synopsis.2](https://docs.pnbr.io/concepts/synopsis.md#rule-synopsis-2).
* You are about to cite a synopsis as a source: rule [synopsis.3](https://docs.pnbr.io/concepts/synopsis.md#rule-synopsis-3).
* A person asks why a synopsis differs from the description: rule [synopsis.4](https://docs.pnbr.io/concepts/synopsis.md#rule-synopsis-4).
* A search shows passages and you need to choose among Files: rule [synopsis.5](https://docs.pnbr.io/concepts/synopsis.md#rule-synopsis-5).

## Doors

| Door | Call |
| - | - |
| CLI | `penumbra search` with `--results files` |
| MCP (default) | `omnisearch` with `results:'files'` returns one row per File with its synopsis. `browse_files` and `file_gallery` rows carry it. `read` opens the File. |
| execute | `penumbra.search` with `results:'files'` is the same search as `omnisearch`. |
| SDK | `project.files.resolve` and `project.files.queryLibrary` return each File with its [synopsis](https://docs.pnbr.io/concepts/synopsis.md). `toSearchFileRows` builds the search rows. |

## Keep going

[File](https://docs.pnbr.io/concepts/file.md) · [Search](https://docs.pnbr.io/concepts/search.md) · [Passage and citation](https://docs.pnbr.io/concepts/passage.md)

Penumbra Grammar 0.6.26


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