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

# Citations to confirm

> After you edit an entity, each citation that may no longer support it waits for one answer: keep, change back, or true before the edit.

Concept · graph

> **Use when**
>
> You edited an entity that has citations, or the person asks what still waits to be confirmed.

> **Looking for something else?**
>
> Citing a passage when you stage an entity (card [Passage and citation](https://docs.pnbr.io/concepts/passage.md)). Finding entities that cite an old edition of a File (recipe [Find entities that rest on an old version or a trashed File](https://docs.pnbr.io/guides/find-stale-entities.md)).

## For

A citation belongs to one revision of an entity. An edit gives the entity a new
revision, and that revision starts with no citations of its own. Penumbra then
checks each citation of the earlier revision against the edit. A citation that
still holds moves to the new revision. A citation that may not hold waits for
an answer, and it stays off the new revision until someone answers.

Each waiting citation asks one question: does this text still support the
entity? The answers are keep, change back, and true before the edit. Nothing
deletes a citation or a File.

This queue is where edits meet sources. A passage supports an entity through
its citation (card [Passage and citation](https://docs.pnbr.io/concepts/passage.md)). An edit to the entity, directly or in a workspace
(card [Entity](https://docs.pnbr.io/concepts/entity.md), card [Workspace](https://docs.pnbr.io/concepts/workspace.md)), may leave that support in doubt. The queue
keeps the entity honest about what it still stands on.

## Use when

* You updated or restored an entity, and it had citations.
* You submitted a workspace that changed entities you checked out.
* The person asks what still waits to be confirmed.
* An entity shows fewer citations than it had before your edit.

## Not this

* You stage a new entity and cite a passage for it: use card [Passage and citation](https://docs.pnbr.io/concepts/passage.md).
* You need every entity that rests on an old edition of a File: use recipe
  [find-stale-entities](https://docs.pnbr.io/guides/find-stale-entities.md).

## Rules

1. `citations-to-confirm.1` An edit of an entity or relationship that had
   citations queues a check of them. An update, a restore and a workspace
   submit of checked-out items all do. A delete queues one that Penumbra then
   skips. A first write queues none. **Your job:** after such an edit, look for
   waiting citations. `penumbra attention` counts the sources to confirm, and
   `penumbra evidence list` shows them.

2. `citations-to-confirm.2` A citation that waits is not on the new revision.
   Only citations that still hold are carried over. **Your job:** do not read a
   shorter list of citations as a lost source. On MCP, the entity read counts
   the waiting ones and lists them apart.

3. `citations-to-confirm.3` When Penumbra cannot check a citation, it marks the
   citation unchecked, and it waits like any other. **Your job:** compare the
   cited text with the edit yourself before you answer.

4. `citations-to-confirm.4` Read each item before you answer it. **Your job:**
   run `penumbra evidence list`. Each item shows the entity, what changed, who
   edited it and when. It also shows the cited text and its File, why it was
   flagged, and the open answers. Add `--resolved` for answered items, and
   `--limit` or `--cursor` to page.

5. `citations-to-confirm.5` Three answers exist, one command each.
   `penumbra evidence keep` says the text still supports the entity as it is now.
   `penumbra evidence true-then` says it was true before the edit, so it stays with the earlier revision only.
   `penumbra evidence change-back` says the edit was wrong.
   **Your job:** open the entity and the File version, and compare before you answer.
   An answer takes effect at once and waits for no approval.

6. `citations-to-confirm.6` Change back is open only when the cited text states
   the earlier value of a field the edit changed. **Enforced:** otherwise the
   CLI refuses it with `evidence_review_change_back_unavailable`, and the MCP
   tool answers `change_back_unavailable`. If the entity changed again, the CLI
   refuses with `evidence_review_record_changed`, and the MCP tool answers
   `record_changed`. Nothing is applied. List again, then decide on the current
   entity.

7. `citations-to-confirm.7` A first answer stands. **Enforced:** answering a
   citation again returns the first answer, marked as answered earlier. A
   citation that needs no answer is refused with `not_flagged`.

8. `citations-to-confirm.8` One call answers up to 100 citations, and you name
   each verdict ID once. **Enforced:** the three answer commands refuse a longer
   list or a repeated ID with `invalid_arguments`.

9. `citations-to-confirm.9` Change back puts the earlier values back with an
   ordinary update made as you. It can settle more citations than you named.
   If the entity then equals the revision they were written for, the other
   waiting citations of that edit are settled the same way. **Your job:** read
   the full result before you list again.

10. `citations-to-confirm.10` Answering needs permission to change entities: an
    owner, admin or editor, or a key with `graph.lifecycle.apply`. A viewer
    can read the flags but not answer them. **Enforced:** a person limited to a
    View sees no queue. **Your job:** ask an owner or editor to answer when you
    cannot.

11. `citations-to-confirm.11` To cite the new value of an entity in a workspace,
    check the entity out and give the edit with its citations. **Your job:** the
    citations you give replace the pending list, and leaving them out makes no
    new claim. Earlier citations stay on the earlier revision (card [Entity](https://docs.pnbr.io/concepts/entity.md)).

12. `citations-to-confirm.12` A File that Penumbra writes (card [file](https://docs.pnbr.io/concepts/file.md)) cannot be
    cited. **Enforced:** keep and change back refuse a citation of such a File
    with `file_not_evidence`. **Your job:** answer with
    `penumbra evidence true-then` instead, or cite a File that was uploaded or
    synced (card [Passage and citation](https://docs.pnbr.io/concepts/passage.md)).

## Failure signs

* An edited entity shows fewer citations than before: rule
  [citations-to-confirm.2](https://docs.pnbr.io/concepts/citations-to-confirm.md#rule-citations-to-confirm-2).
* An answer is refused with `evidence_review_record_changed`: list again and
  decide on the current entity (rule [citations-to-confirm.6](https://docs.pnbr.io/concepts/citations-to-confirm.md#rule-citations-to-confirm-6)).
* Entities cite a version that a new edition replaced: problem
  [entities-cite-replaced-version](https://docs.pnbr.io/troubleshooting/entities-cite-replaced-version.md). Edits queue this check. A replace does not.
* You must find the entities that rest on an old edition: recipe
  [find-stale-entities](https://docs.pnbr.io/guides/find-stale-entities.md).

## Doors

| Door | Call |
| - | - |
| CLI | `penumbra evidence list`, `penumbra evidence keep`, `penumbra evidence change-back`, `penumbra evidence true-then`, `penumbra attention` |
| MCP (default) | `read` shows an entity's waiting citations and a count. The default catalog has no tool that answers them. |
| MCP (full catalog) | `evidence_review` lists the waiting citations and answers them, for a caller who may change entities. `read` shows the count on each entity. |
| MCP (Kits) | `evidence_review` in the full Kit and in any Kit that selects it. |
| SDK | `project.evidenceReviews` |

The default catalog may tell an editor to answer with `evidence_review`. Use the
CLI, the SDK or HTTP then, because that catalog does not list the tool.

## The CLI word

The CLI calls an entity a record and a citation a quote in `penumbra evidence list`.
The CLI calls an entity a node in `penumbra graph nodes`.

## Keep going

[Entity](https://docs.pnbr.io/concepts/entity.md) · [Passage and citation](https://docs.pnbr.io/concepts/passage.md) · [Workspace](https://docs.pnbr.io/concepts/workspace.md) · [File](https://docs.pnbr.io/concepts/file.md) · [Entities still cite a replaced version](https://docs.pnbr.io/troubleshooting/entities-cite-replaced-version.md) · [Find entities that rest on an old version or a trashed File](https://docs.pnbr.io/guides/find-stale-entities.md)

Penumbra Grammar 0.6.26


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