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

​

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

​

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 and 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).
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 from its step 3, and submit the workspace (recipe review-and-submit). If the new version was never extracted, see problem new-version-not-extracted.
   • Restore a trashed File: penumbra files restore <file-id>. It does not wait for approval (card rule file.8). A purged File cannot be restored (card rule file.9).
   • Delete: penumbra graph delete <entity-id>. An API key or a connected agent waits for approval (card 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).

​

If it goes wrong

​

Worth offering

• For each entity on the list, offer one clear choice. Refresh it from a new edition (recipe new-edition), 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 · Passage and citation · Entity · Context · Workspace · Citations to confirm · Bring in a new edition of a document · Review a workspace and submit it · Entities still cite a replaced version · An entity rests on a trashed File · A new version was never extracted · No lookup finds the entities of one version · A change returned pending