Bring in a new edition of a document

​

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 and file.3).
   • CLI: penumbra files replace <file> <path> --expect <version-id> --source-date <date> --wait (card 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 and 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 and 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).
     {
       "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 and workspace.4). A submit by an API key or a connected agent can wait for approval (card 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

​

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 · Passage and citation · Entity · Workspace · Approval · Citations to confirm · Entities still cite a replaced version · A new edition is a separate File