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

# Find entities that rest on an old version or a trashed File

> You have a list of entities whose only support is an old version or a trashed File, and the person decides about each.

Guide · graph

> **Use when**
>
> A person replaced or trashed Files and asks what the Graph still says from them, or you audit the Graph for entities with stale sources.

> **Looking for something else?**
>
> Bringing in a new edition and refreshing its entities (recipe [Bring in a new edition of a document](https://docs.pnbr.io/guides/new-edition.md)). Citations that wait for an answer after an edit (card [Citations to confirm](https://docs.pnbr.io/concepts/citations-to-confirm.md)).

## Outcome

You hold a list of entities whose citations all point to an older version of a
File, or to a trashed or purged File. For each entity, the person has decided:
keep it as it is, refresh it from current text, restore the File, or delete it.
You have changed nothing before the person decided.

## Before you start

1. Know your credential and project: `penumbra whoami`. Every step through the
   list is a read. The changes at the end can wait for approval when you use an
   API key or a connected agent (card rule [approval.1](https://docs.pnbr.io/concepts/approval.md#rule-approval-1)).
2. Choose the Files to check. Take the Files that the person names. Or take
   every trashed File, which step 1 lists. If the person names none, sweep the
   Graph as step 2 says.
3. No MCP tool lists the entities that cite a File. This recipe uses the CLI.
   The SDK and HTTP reach the same reads (card [context](https://docs.pnbr.io/concepts/context.md)).

## Steps

1. List the Files that are no longer live.
   * CLI: `penumbra files list --all --json`. Page with `--cursor`.
   * Expect: one row for each File with its `id`, `name` and `status`. A trashed
     File has the status `deleted`, and a purged File has `purged`. Note their IDs.
2. List the entities that cite the Files.
   * CLI: `penumbra context explore --file-id <file-id> --limit 200 --json`. Repeat
     `--file-id` for more Files. Add `--cursor <cursor>` while a `next:` line
     shows.
   * Sweep: when no File is named, run `penumbra context explore --json` and page
     through every entity. Each entity carries its `files` list.
   * Expect: `entities`, and for each entity a `files` list. An entry holds
     `file_id`, `version_id`, `content_digest` and `chunk_id`.
   * See card rules [context.2](https://docs.pnbr.io/concepts/context.md#rule-context-2) and [context.3](https://docs.pnbr.io/concepts/context.md#rule-context-3).
3. Read the state of each File that the lists cite.
   * A File from step 1 is trashed or purged.
   * For any other File: `penumbra files versions <file-id>`. Note the version
     ID on the `current:` line.
4. Mark each entity. Look at every entry of its `files` list.
   * An entry is old when its File is trashed or purged, or when its
     `version_id` is not the File's current version.
   * An entity is stale when every entry is old.
   * Set aside an entity that has one entry on a current version of a live File.
     It still has support.
   * Write the reason for each stale entity: `replaced by version <n>`,
     `trashed` or `purged`.
   * An entity that shows 32 entries may have more that the list does not
     show. Name it to the person as possibly incomplete (card rule [context.3](https://docs.pnbr.io/concepts/context.md#rule-context-3)).
5. Read each stale entity before you show it:
   `penumbra context entity <entity-id>`. MCP: `read` with `entity:<entity-id>`
   shows the same citations, and says how many it cannot open.
6. Give the person the list. Change nothing yet. For each entity give its name,
   its type, its main properties, the File and version it cites, and the reason.
   Offer the choices that fit: keep, refresh, restore the File, delete.
7. Carry out only the choices the person made.
   * Keep: do nothing, and note it in your report.
   * Refresh from current text: follow recipe [new-edition](https://docs.pnbr.io/guides/new-edition.md) from its step 3, and
     submit the workspace (recipe [review-and-submit](https://docs.pnbr.io/guides/review-and-submit.md)). If the new version was
     never extracted, see problem [new-version-not-extracted](https://docs.pnbr.io/troubleshooting/new-version-not-extracted.md).
   * Restore a trashed File: `penumbra files restore <file-id>`. It does not
     wait for approval (card rule [file.8](https://docs.pnbr.io/concepts/file.md#rule-file-8)). A purged File cannot be restored
     (card rule [file.9](https://docs.pnbr.io/concepts/file.md#rule-file-9)).
   * Delete: `penumbra graph delete <entity-id>`. An API key or a connected agent
     waits for approval (card rule [entity.4](https://docs.pnbr.io/concepts/entity.md#rule-entity-4)). Give the person the approval URL.

## Check

* Run steps 2, 3 and 4 again for the same Files. Each entity from your list is
  no longer stale, or the person chose to keep it.
* An entity that waits in a submitted workspace or for an approval is named to
  the person as still open.
* After a refresh, open the entity with `penumbra context entity <entity-id>`.
  A `from:` line must name the current version of a live File.
* Run `penumbra evidence list`. A refresh is an edit, so it can queue citations
  for an answer (card [citations-to-confirm](https://docs.pnbr.io/concepts/citations-to-confirm.md)).

## If it goes wrong

| You see | Read |
| - | - |
| An entity cites a replaced version | problem [entities-cite-replaced-version](https://docs.pnbr.io/troubleshooting/entities-cite-replaced-version.md) |
| An entity's sources are in a trashed File | problem [entity-rests-on-trashed-file](https://docs.pnbr.io/troubleshooting/entity-rests-on-trashed-file.md) |
| The new version has no extraction | problem [new-version-not-extracted](https://docs.pnbr.io/troubleshooting/new-version-not-extracted.md) |
| You need the entities of one exact version | problem [what-cites-this-version](https://docs.pnbr.io/troubleshooting/what-cites-this-version.md) |
| An entity you expect is missing from its File's list | card [citations-to-confirm](https://docs.pnbr.io/concepts/citations-to-confirm.md), rule [context.2](https://docs.pnbr.io/concepts/context.md#rule-context-2) |
| A restore is refused with `file_content_purged` | problem [entity-rests-on-trashed-file](https://docs.pnbr.io/troubleshooting/entity-rests-on-trashed-file.md) |
| A delete or a submit returns `pending` | problem [change-waits-for-approval](https://docs.pnbr.io/troubleshooting/change-waits-for-approval.md) |

## Worth offering

* For each entity on the list, offer one clear choice. Refresh it from a new
  edition (recipe [new-edition](https://docs.pnbr.io/guides/new-edition.md)), restore the File, keep it, or delete it.
* If the File went to the trash by mistake, offer to restore it while Penumbra
  still keeps it.

## Report

Say how many Files you checked and how many entities each one had. List the
stale entities with the reason for each, and the person's decision. Name what
waits for approval. Say what you did not check: relationships, entities whose
citations wait for an answer, and any entity that showed 32 entries.

## 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) · [Context](https://docs.pnbr.io/concepts/context.md) · [Workspace](https://docs.pnbr.io/concepts/workspace.md) · [Citations to confirm](https://docs.pnbr.io/concepts/citations-to-confirm.md) · [Bring in a new edition of a document](https://docs.pnbr.io/guides/new-edition.md) · [Review a workspace and submit it](https://docs.pnbr.io/guides/review-and-submit.md) · [Entities still cite a replaced version](https://docs.pnbr.io/troubleshooting/entities-cite-replaced-version.md) · [An entity rests on a trashed File](https://docs.pnbr.io/troubleshooting/entity-rests-on-trashed-file.md) · [A new version was never extracted](https://docs.pnbr.io/troubleshooting/new-version-not-extracted.md) · [No lookup finds the entities of one version](https://docs.pnbr.io/troubleshooting/what-cites-this-version.md) · [A change returned pending](https://docs.pnbr.io/troubleshooting/change-waits-for-approval.md)

Penumbra Grammar 0.6.26


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