> ## 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. # Document > A document is a Markdown File that you read at a Workspace path and change by exact text. Each change is a new version of the same File. Concept · documents > **Use when** > > You write a note, a brief or a summary in Markdown, or you change the text of a Markdown File that already has a path. > **Looking for something else?** > > A newer copy of a document that you have as a file on disk (card [file](https://docs.pnbr.io/concepts/file.md), recipe [new-edition](https://docs.pnbr.io/guides/new-edition.md)). A File that a synced folder keeps current (card [source](https://docs.pnbr.io/concepts/source.md)). A PDF or an image (card [file](https://docs.pnbr.io/concepts/file.md)). ## 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 ` 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](https://docs.pnbr.io/concepts/file.md), recipe [new-edition](https://docs.pnbr.io/guides/new-edition.md)). * The File is kept current by a synced folder: change it in its folder (card [source](https://docs.pnbr.io/concepts/source.md)). * A PDF, an image or a file that is not Markdown: use card [file](https://docs.pnbr.io/concepts/file.md). ## 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 `. 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 `. 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 `, the version you read. `penumbra files read ` 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 --from --expect ` for the whole new text. Run `penumbra files insert --after "" --from --expect ` to add a block under a heading. Take `` from `penumbra files read ` (rule [document.3](https://docs.pnbr.io/concepts/document.md#rule-document-3)). List the headings with `penumbra files outline `. **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 --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](https://docs.pnbr.io/concepts/passage.md#rule-passage-7)), and no extraction runs (card rule [file.7](https://docs.pnbr.io/concepts/file.md#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](https://docs.pnbr.io/concepts/source.md#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](https://docs.pnbr.io/concepts/file.md#rule-file-5)). ## Failure signs * An edit is refused as `document_changed` or `version_conflict`: rule [document.3](https://docs.pnbr.io/concepts/document.md#rule-document-3). * A read or edit of a File says it has no Workspace path: rule [document.1](https://docs.pnbr.io/concepts/document.md#rule-document-1). * A create is refused with `path_conflict`: rule [document.2](https://docs.pnbr.io/concepts/document.md#rule-document-2). * The Graph still shows the old text after an edit: problem [entities-cite-replaced-version](https://docs.pnbr.io/troubleshooting/entities-cite-replaced-version.md) and problem [new-version-not-extracted](https://docs.pnbr.io/troubleshooting/new-version-not-extracted.md). ## Doors | Door | Call | | - | - | | CLI | `penumbra files new`, `penumbra files read`, `penumbra files outline`, `penumbra files edit`, `penumbra files insert`, `penumbra files place` | | MCP (default) | `read_document`, `create_markdown`, `edit_document`, `get_operation` | | MCP (Files Kits) | `get_document_outline` and `insert_blocks` in the Files Kits that select them. The Files editor Kit also has the proposal tools, which suggest an edit without making it. | | SDK | `project.files` | `penumbra files proposals create` suggests an edit and does not change the document. ## HTTP reference * [Create document](https://docs.pnbr.io/api/http-documents-create.md) * [Read document](https://docs.pnbr.io/api/http-documents-read.md) * [Replace document text](https://docs.pnbr.io/api/http-documents-edit.md) * [Insert document blocks](https://docs.pnbr.io/api/http-documents-insert.md) ## Keep going [File](https://docs.pnbr.io/concepts/file.md) · [Synced folder](https://docs.pnbr.io/concepts/source.md) · [Passage and citation](https://docs.pnbr.io/concepts/passage.md) · [Bring in a new edition of a document](https://docs.pnbr.io/guides/new-edition.md) · [Entities still cite a replaced version](https://docs.pnbr.io/troubleshooting/entities-cite-replaced-version.md) · [A new version was never extracted](https://docs.pnbr.io/troubleshooting/new-version-not-extracted.md) Penumbra Grammar 0.6.26 This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.