Document

​

For

A document is a Markdown File that sits at a Workspace path, such as /notes/plan.md. You read its exact text, and you change it by exact text or by adding a block. You do not upload bytes. Each change is one new version of the same File. The older versions stay readable, and search reads the newest one. A Markdown File that someone uploaded is a document too, once it has a path. penumbra files place <file> <path> gives it one. After that you read and edit it by exact text, and each edit is a new version of the same File. Read a document before you change it. An edit applies to the version you read. If anyone changes the document after your read, Penumbra writes nothing, and you read again.

​

Use when

• The person asks you to write a note, a plan or a summary that lives in the project.
• You must change a few sentences of a document, or add a section to it.
• You need a document’s headings, not its body.

​

Not this

• The person gives you a newer copy as a file on disk: replace the File (card file, recipe new-edition).
• The File is kept current by a synced folder: change it in its folder (card source).
• A PDF, an image or a file that is not Markdown: use card file.

​

Rules

1. document.1 A document is reached by its Workspace path. Your job: use the path, which starts with /, with penumbra files read and the other document commands. A File with no path is refused with file_unplaced and exit code 3. Give it a path with penumbra files place <file> <path>.
2. document.2 A new document takes a new path. Enforced: a path that is in use is refused with path_conflict and exit code 3, and nothing is overwritten. Create one with penumbra files new /notes/plan.md --from <file.md>. On MCP, call create_markdown with the name, the folder and the whole text. Penumbra makes missing folders and adds .md.
3. document.3 Edit the version you read. Enforced: if the document changed after you read it, nothing is written. The CLI exits with document_changed and code 3. The MCP tool answers version_conflict. Your job: read the document again, and make the edit again. In the CLI, penumbra files edit --from and penumbra files insert need --expect <version>, the version you read. penumbra files read <file> prints it as version: after the text, and --json prints it as version_id. Without --expect the command is refused with expect_required and exit code 2.
4. document.4 On MCP, an edit replaces exact text. Your job: call read_document first, with the view content or blocks. Then call edit_document with old_text copied from that read, and the new_text. Give 1 to 50 edits in one call. Enforced: an edit whose text is not found, or that matches more than one place without replace_all, fails the whole call. Nothing is written.
5. document.5 An outline is not enough to edit. Your job: do not edit from read_document with the view outline, or from get_document_outline. They omit the body, and they do not allow an edit. Read the content of the part you change.
6. document.6 The CLI gives the whole new text, or a block to add, from a file. Your job: run penumbra files edit <file> --from <file.md> --expect <version> for the whole new text. Run penumbra files insert <file> --after "<heading>" --from <file.md> --expect <version> to add a block under a heading. Take <version> from penumbra files read <file> (rule document.3). List the headings with penumbra files outline <file>. Enforced: a heading that is missing or that two headings share is refused with heading_not_found or heading_ambiguous and exit code 2. Name a shared heading by its block id, from penumbra files outline <file> --json.
7. document.7 An edit that changes nothing writes nothing. Enforced: penumbra files edit with the text that the document has says “unchanged” and makes no version. Every real edit makes one new version, and one edit call is one version, even with many changes.
8. document.8 An edit does not move what the Graph knows. Your job: treat an edit of a document that entities cite like a new edition. Entities keep citing the version they came from (card rule passage.7), and no extraction runs (card rule file.7).
9. document.9 A document that a synced folder keeps current cannot be changed here. Enforced: the edit is refused with file_write_constrained (card rule source.1). Your job: change the document in its folder.
10. document.10 Pass the source date when you create a document and its text states a date. Your job: use --source-date on penumbra files new. On MCP, create_markdown takes source_date only when the connection holds the permission set_source_date (card rule file.5).

​

Failure signs

• An edit is refused as document_changed or version_conflict: rule document.3.
• A read or edit of a File says it has no Workspace path: rule document.1.
• A create is refused with path_conflict: rule document.2.
• The Graph still shows the old text after an edit: problem entities-cite-replaced-version and problem new-version-not-extracted.

​

Doors

penumbra files proposals create suggests an edit and does not change the document.

​

HTTP reference

• Create document
• Read document
• Replace document text
• Insert document blocks

​

Keep going

File · Synced folder · Passage and citation · Bring in a new edition of a document · Entities still cite a replaced version · A new version was never extracted