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

# Bring in a new edition of a document

> A newer edition replaced the old one in the same File, and the entities that cite the File agree with the new text.

Guide · files

> **Use when**
>
> A person gives you a newer or amended copy of a document the project has, or entities must change because their source document changed.

> **Looking for something else?**
>
> A different document with a similar name (recipe [Bring a set of documents into the project](https://docs.pnbr.io/guides/bring-in-a-corpus.md)).

## Outcome

The File has the new edition as its current version, with its source date.
Every entity that cited the File holds the new values, or a person decides
about it.

## Before you start

* Find the File and compare its text with the new copy. Confirm it is the
  same document.
  * CLI: `penumbra files find "<name>"`, then `penumbra files text <file>`.
  * MCP: `omnisearch` with the document's name, then `read_document` with its
    path.
* Note the current version ID (CLI: `penumbra files show <file>`).
* Read the new edition's own date. That is its source date.

## Steps

1. Make the new edition the File's current version. Never upload a second
   File (card rules [file.1](https://docs.pnbr.io/concepts/file.md#rule-file-1) and [file.3](https://docs.pnbr.io/concepts/file.md#rule-file-3)).
   * CLI: `penumbra files replace <file> <path> --expect <version-id> --source-date <date> --wait`
     (card rule [file.4](https://docs.pnbr.io/concepts/file.md#rule-file-4)).
   * MCP: `edit_document` changes a Markdown File in place, after
     `read_document`. It returns the new version ID. Penumbra has no MCP door
     that replaces other kinds of File; use the CLI.
   * Program: `penumbra.files.edit_document(...)`, after
     `penumbra.files.read_document(...)`.
2. Set the new version's source date, if step 1 did not.
   * CLI: `penumbra files source-date <file> <date>`.
   * MCP: `update_file` with the File's `path` and `source_date`. It sets the
     current version.
   * Program: `penumbra.files.organize_file({ref, source_date})` with the
     version ref from `penumbra.files.list_versions(...)`.
3. Penumbra does not update entities for you. Find every entity that cites the
   File (card rules [file.7](https://docs.pnbr.io/concepts/file.md#rule-file-7) and [passage.7](https://docs.pnbr.io/concepts/passage.md#rule-passage-7)).
   * CLI: `penumbra context explore --file-id <file-id> --json`.
   * MCP: no tool lists the entities that cite a File. Search for the
     document's subjects with `omnisearch`, then `read` each `entity:` ref. Its
     citations name the File and the version they cite.
4. Compare each entity's properties with the new text.
   * CLI: `penumbra context entity <entity-id>`.
   * MCP: `read` with `entity:<entity-id>`.
5. For each entity with a changed value, open one workspace for the edition
   and check the entity out.
   * CLI: `penumbra graph workspace open "<edition name>"`, then
     `penumbra graph workspace hydrate "<edition name>" --node <entity-id>`.
   * Program: `penumbra.workspaces.open({name})`, then
     `w.hydrate({nodes: ["<entity-id>"]})`.
6. Give the new values in a patch, with a citation of the new version (card
   rules [entity.2](https://docs.pnbr.io/concepts/entity.md#rule-entity-2) and [citations-to-confirm.11](https://docs.pnbr.io/concepts/citations-to-confirm.md#rule-citations-to-confirm-11)). A patch keeps the
   properties you leave out.
   * CLI: write the patch to a file and run
     `penumbra graph workspace modify "<edition name>" <file.json>`. Take the
     handle from `penumbra graph workspace show "<edition name>"`. The
     citation's digest is the new version's `content_digest` from
     `penumbra files versions <file>`. To cite the passage that holds the new
     value, add its passage ID as `chunk_id`. Take the passage ID from a search
     of the new version or from `penumbra files chunks` (card [passage](https://docs.pnbr.io/concepts/passage.md)).

     ```json theme={null}
     {
       "handle": "<handle>",
       "changes": {
         "patch": { "properties": { "annual_fee": "135,000 USD" } },
         "evidence": [
           {
             "file_id": "<file-id>",
             "version_id": "<new-version-id>",
             "content_digest": "<content_digest>",
             "chunk_id": "<passage-id>"
           }
         ]
       }
     }
     ```

   * MCP and Program: get a citation token with `read` on the new version and
     `quote` set to the exact new text. Then
     `w.modify({edit: [{handle, changes: {patch: {properties}, evidence: [{citation}]}}]})`.
7. Validate, then submit the revision you reviewed (card rules [workspace.3](https://docs.pnbr.io/concepts/workspace.md#rule-workspace-3)
   and [workspace.4](https://docs.pnbr.io/concepts/workspace.md#rule-workspace-4)). A submit by an API key or a connected agent can wait for
   approval (card rule [workspace.10](https://docs.pnbr.io/concepts/workspace.md#rule-workspace-10)).
   * CLI: `penumbra graph workspace submit "<edition name>" --revision <n>`.
   * Program: `w.validate()`, then `w.submitReviewed({expectedRevision})`. An
     outcome `pending` waits for approval.
8. Do not delete an entity because its old passage left search. Ask the person
   first.

## Check

* `penumbra files versions <file>` shows the new version as current, with its
  source date.
* Each entity from this File holds the new values, or waits in your submitted
  workspace, or you named it to the person.

## If it goes wrong

| You see | Read |
| - | - |
| Two Files now hold the two editions | problem [two-editions-two-files](https://docs.pnbr.io/troubleshooting/two-editions-two-files.md) |
| Entities still cite the old version | problem [entities-cite-replaced-version](https://docs.pnbr.io/troubleshooting/entities-cite-replaced-version.md) |
| The new version has no source date | problem [file-has-no-source-date](https://docs.pnbr.io/troubleshooting/file-has-no-source-date.md) |
| The submit returned `pending` | problem [change-waits-for-approval](https://docs.pnbr.io/troubleshooting/change-waits-for-approval.md) |
| The submit was refused as changed | problem [workspace-changed-since-you-read](https://docs.pnbr.io/troubleshooting/workspace-changed-since-you-read.md) |

## Worth offering

* Offer a list of what changed between the editions, term by term.
* Other entities can state an old value and cite a different File. Offer to
  search the Graph for the old values and check them.
* If the old edition stated something that the new one drops, say so, and offer
  to mark the entity for the person to decide.

## Report

Say what changed between the editions. List each entity you updated, with old
and new values, and what waits for approval. Name entities you left for the
person to decide.

## 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) · [Workspace](https://docs.pnbr.io/concepts/workspace.md) · [Approval](https://docs.pnbr.io/concepts/approval.md) · [Citations to confirm](https://docs.pnbr.io/concepts/citations-to-confirm.md) · [Entities still cite a replaced version](https://docs.pnbr.io/troubleshooting/entities-cite-replaced-version.md) · [A new edition is a separate File](https://docs.pnbr.io/troubleshooting/two-editions-two-files.md)

Penumbra Grammar 0.6.26


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