Skip to main content
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). Finding passages (card Search). Deciding what to do with citations after an edit (card Citations to confirm).

​
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.
  • Finding passages for a question: use card Search.
  • 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) 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).
  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).
  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).
  • A passage ID reads as not found: 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).
  • Entities cite a version that is no longer current: problem entities-cite-replaced-version.
  • You need every entity that cites one version: problem what-cites-this-version.
  • An entity has no citation: rule passage.6.
  • An answer needs a citation for each claim: recipe answer-with-citations.

​
Doors

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.
A search result prints the File ID, the version ID and the passage ID (rule search.9). penumbra files versions <file> prints the content digest.

​
The CLI word

The CLI calls a passage a chunk.

​
HTTP reference

​
Keep going

File · Search · Entity · Workspace · Citations to confirm · Answer from the project’s documents, with citations · Save facts a person tells you as entities · Entities still cite a replaced version