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

# Passage and citation

> A passage is a piece of the text of one File version. A citation names the exact version and text that support a claim.

Concept · files

> **Use when**
>
> You cite what supports an answer or an entity, or you reopen a passage that you found earlier.

> **Looking for something else?**
>
> A whole document (card [File](https://docs.pnbr.io/concepts/file.md)). Finding passages (card [Search](https://docs.pnbr.io/concepts/search.md)). Deciding what to do with citations after an edit (card [Citations to confirm](https://docs.pnbr.io/concepts/citations-to-confirm.md)).

## For

A passage is a piece of the text extracted from one File version. Search
returns passages. Each one has a passage ID and belongs to one version of one
File. An audio or video result has a moment ID instead, and the passage
commands do not take it.

A citation names a File, an exact version, and the passage or the exact text
range that supports a claim. An answer cites passages. An entity holds its
citations, so a person can ask where it came from and open the same text.

A citation stays on the version it names. A new edition of the File does not
move it. Cite the version you read, and the fact keeps its tie to its source.

## Use when

* You answer a question from Files and must show where each claim comes from.
* You stage an entity that a File supports.
* You hold a passage ID from an earlier search and must read it again.
* You must read the text around a passage before you rely on it.

## Not this

* The whole document, its versions or its pages: use card [File](https://docs.pnbr.io/concepts/file.md).
* Finding passages for a question: use card [Search](https://docs.pnbr.io/concepts/search.md).
* Answering a question about a citation that an edit left unsupported: use card
  citations-to-confirm.

## Rules

1. `passage.1` Reopen a passage by its ID. Run `penumbra files chunks` with the
   passage ID. **Enforced:** a passage of an older version, of a trashed File,
   or of a version still processing reads as not found, with exit code 3. The
   reply does not say why. **Your job:** add `--inactive` to read a passage of
   an older version. It never opens a trashed File's passages.
2. `passage.2` Cite the version you read. A citation carries the File ID, the
   version ID and that version's content digest. **Enforced:** a digest that
   does not belong to the version is refused with `evidence_digest_mismatch`. A
   File or version you cannot read is refused with `evidence_unavailable`. A
   citation can also carry the passage ID as `chunk_id`. A passage that is not
   in that File and version is refused.
3. `passage.3` To cite exact words, take a citation token from the MCP tool
   `read`. Give `read` the reference of a passage, a version or a File and the
   exact text, and it returns a token for that text. **Enforced:** a token
   whose text no longer matches the version is refused with
   `evidence_quote_mismatch`. **Your job:** pass the token unchanged. It stands
   alone, with an optional note.
4. `passage.4` A staged entity or relationship takes at most 32 citations. One
   citation covers at most 4,096 bytes of text, and a note holds at most 500
   characters. **Enforced:** a staging call over a limit is refused with
   `input_invalid`.
5. `passage.5` A File that Penumbra writes (card [file](https://docs.pnbr.io/concepts/file.md)) cannot be cited.
   **Enforced:** citing one is refused with `file_not_evidence`. **Your job:**
   cite the Files that it is written from.
6. `passage.6` Staging does not require a citation. **Your job:** cite every
   entity that a File supports. An entity with no citation has no source to open,
   and an edit to it queues no check of its sources (card [Citations to confirm](https://docs.pnbr.io/concepts/citations-to-confirm.md)).
7. `passage.7` A replace or a trash does not move, flag or remove a citation.
   **Your job:** after a new edition, find the entities that still cite the old
   version. Run `penumbra context explore --file-id` with the File ID, then
   decide which ones to refresh (recipe [new-edition](https://docs.pnbr.io/guides/new-edition.md)).
8. `passage.8` The entity read shows the citations of its current revision.
   **Your job:** read "more citations are not shown" as unknown. A citation
   whose File version you cannot read, or whose digest no longer matches, is
   withheld and only counted.
9. `passage.9` A passage is only a part of its version. **Your job:** read the
   text around it before you rely on it, with `penumbra files text`. The flags
   `--version`, `--start` and `--max-bytes` choose the version and the byte
   window. `--page <n>` reads one page instead.

## Failure signs

* A citation is refused with `evidence_quote_mismatch`: read the passage again
  and pass the new token (rule [passage.3](https://docs.pnbr.io/concepts/passage.md#rule-passage-3)).
* A passage ID reads as not found: rule [passage.1](https://docs.pnbr.io/concepts/passage.md#rule-passage-1).
* You do not know whether a text read reached the end of a File: its last line
  says `end of text`, or where it stopped (recipe [check-file-text](https://docs.pnbr.io/guides/check-file-text.md)).
* Entities cite a version that is no longer current: problem
  [entities-cite-replaced-version](https://docs.pnbr.io/troubleshooting/entities-cite-replaced-version.md).
* You need every entity that cites one version: problem [what-cites-this-version](https://docs.pnbr.io/troubleshooting/what-cites-this-version.md).
* An entity has no citation: rule [passage.6](https://docs.pnbr.io/concepts/passage.md#rule-passage-6).
* An answer needs a citation for each claim: recipe [answer-with-citations](https://docs.pnbr.io/guides/answer-with-citations.md).

## Doors

| Door | Call |
| - | - |
| CLI | `penumbra files chunks`, `penumbra files text`, `penumbra search`, `penumbra files search`, `penumbra context entity`, `penumbra context explore`, `penumbra graph workspace capture` |
| MCP (default) | `read` opens a passage, a version, a File or an entity and returns citation tokens. `omnisearch` returns the references. `open_file` shows the source to a person. |
| MCP (full catalog) | `resolve_file_chunks`, `read_file_text` and `capture`, with the default tools. `capture` takes the tokens from `read`. |
| MCP (Files Kits) | Reader has `resolve_file_chunks` and `read_file_text`. |
| SDK | `project.files.chunks.resolve`, `project.files.text.read` |

The default catalog reads a passage by its `chunk:` reference only while its
version is current. For an older version, read the `version:` reference with
the exact text, and cite that version.

The CLI prints no citation token. The help for the graph commands names two
forms for `penumbra graph workspace capture`. One is a token from the MCP tool
`read`. The other is the File ID, the version ID and the content digest, which
cite a whole version. Add the passage ID as `chunk_id` to that second form to
cite one passage without a token. Penumbra checks that the passage belongs to
that File and version. This form cites the passage. It does not cite exact words,
which need a token.

```json theme={null}
{
  "file_id": "<file-id>",
  "version_id": "<version-id>",
  "content_digest": "<content_digest>",
  "chunk_id": "<passage-id>"
}
```

A search result prints the File ID, the version ID and the passage ID
(rule [search.9](https://docs.pnbr.io/concepts/search.md#rule-search-9)). `penumbra files versions <file>` prints the content digest.

## 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) · [Search](https://docs.pnbr.io/concepts/search.md) · [Entity](https://docs.pnbr.io/concepts/entity.md) · [Workspace](https://docs.pnbr.io/concepts/workspace.md) · [Citations to confirm](https://docs.pnbr.io/concepts/citations-to-confirm.md) · [Answer from the project's documents, with citations](https://docs.pnbr.io/guides/answer-with-citations.md) · [Save facts a person tells you as entities](https://docs.pnbr.io/guides/capture-by-hand.md) · [Entities still cite a replaced version](https://docs.pnbr.io/troubleshooting/entities-cite-replaced-version.md)

Penumbra Grammar 0.6.26


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