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

# File

> A File is one document the project keeps, with every version, and search and extraction read its current version.

Concept · files

> **Use when**
>
> You add, find, read, replace or remove a document, or bring in a web page. A person may also give you a newer copy of one.

> **Looking for something else?**
>
> A Markdown note you write and edit often (card [Document](https://docs.pnbr.io/concepts/document.md)). A named group of Files (card [Collection](https://docs.pnbr.io/concepts/collection.md)). A folder kept current from a source (card [Synced folder](https://docs.pnbr.io/concepts/source.md)).

## For

A File keeps one document and all of its versions. A new edition is a new
version of the same File, not a new File. The current version is the one that
search and extraction read. Older versions stay readable by their version ID.

Adding or replacing a File does not change the Graph. An entity cites the exact
version it was read from, so it keeps citing the old edition after a replace.
To bring the Graph up to date, find the entities that cite the File, extract
from the new version, and review the result (recipe [new-edition](https://docs.pnbr.io/guides/new-edition.md)).

Penumbra writes a few Files itself, from other information, and keeps them up
to date. These Files read like other Files. Penumbra refuses to extract from one
or cite one, with `file_not_evidence`. It refuses a direct edit with
`file_write_constrained`, the code that a synced File also gives (card
[source](https://docs.pnbr.io/concepts/source.md)). The refusal for a File that Penumbra writes says to suggest a change.

A File moves through three steps before you can use it. The version is stored,
then it is searchable by words, then it is searchable by meaning. Passages come
from the text of the current version (card [Passage and citation](https://docs.pnbr.io/concepts/passage.md)).

## Use when

* You bring a document into the project.
* You bring a web page, or the pages of a website, into the project.
* You need the text, the pages or the versions of a document.
* A person gives you a newer copy of a document the project already holds.
* You must set the date a document states about itself.
* You must trash a document or bring it back.

## Not this

* A note you write and edit as Markdown: use a document (card [Document](https://docs.pnbr.io/concepts/document.md)). An
  uploaded Markdown File is a document too, once it has a path
  (`penumbra files place <file> <path>`).
* A set of Files that belong together: use a collection (card [Collection](https://docs.pnbr.io/concepts/collection.md)).
* A folder kept current from a place outside the project: use a source (card
  source).

## Rules

1. `file.1` A newer copy of a document is a new version of the same File. Use
   `penumbra files replace`. It keeps the File ID, name, tags and collections.
   **Your job:** if you upload the copy as a new File, search returns both
   copies and nothing marks one as older.

2. `file.2` A File takes one new version at a time. **Enforced:** a replace is
   refused with `version_in_progress` while another version of that File is
   still processing. Wait for the first one, then replace again.

3. `file.3` Replace only the version you read. **Enforced when you ask:** pass
   `--expect` with that version ID to `penumbra files replace`, and a different
   current version is refused with `version_conflict`. Without it, the replace
   builds on whichever version is current when Penumbra admits it.

4. `file.4` The source date is the date the document states about itself, such
   as a filing, sent or report date. Each version has its own. A year, a month,
   a day or a full date-time is accepted. **Your job:** send `--source-date`
   with every upload and replace. A new version does not inherit the old date.
   Without a date, an entity extracted from that version has a source time with
   no date.

5. `file.5` Set or change a source date later with `penumbra files source-date`.
   It changes the current version unless you pass `--version`. On MCP, the tool
   `update_file` does the same when the connection holds the permission
   `set_source_date`. Without it, a source date is refused with `access_denied`. **Your job:** set the date before you extract.
   An extraction copies the source date when it starts, and a later change does
   not reach entities already saved.

6. `file.6` Uploading bytes that the project already holds returns the existing
   File. **Your job:** the name, tags and description you sent are ignored, and
   the File keeps the upload batch of its first upload (rule [file.13](https://docs.pnbr.io/concepts/file.md#rule-file-13)). Read the
   File with `penumbra files show` and set them if they matter.

7. `file.7` Uploading or replacing starts no extraction. **Your job:** the
   entities do not change when a new version arrives. Start an extraction on the
   new version when the Graph must follow (card [Extraction](https://docs.pnbr.io/concepts/extraction.md)).

8. `file.8` Trashing a File waits for approval when you act with an API key or
   as a connected agent. **Enforced:** the result is `pending` with an approval
   link, and nothing changes yet. Do not retry. Restore and move do not wait.

9. `file.9` Trash takes the File out of search. Restore brings the current
   version back. **Enforced:** after Penumbra purges the bytes, a restore is
   refused with `file_content_purged`. **Your job:** before you trash, list the
   entities that cite the File with `penumbra context explore --file-id`. Their
   citations stay on the trashed File.

10. `file.10` A CLI command that changes a File needs its exact name, its path
    or its ID. **Enforced:** a partial name is refused with `file_not_exact`, and
    a name that two Files share is refused with `file_ambiguous`. Neither
    command changes anything.

11. `file.11` A stored version is searchable by words before it is searchable by
    meaning. **Your job:** `--wait` on `penumbra files upload` or
    `penumbra files replace` returns when the version is searchable by words.
    Read the semantic status in `penumbra files inspect` before a meaning search.

12. `file.12` A File can carry a title: the clearer name a person or a naming
    convention gives it. Set it with `penumbra files title <file> <title>` and
    remove it with `--clear`. On MCP, the tool `update_file` sets it when the
    connection holds the permission `set_file_title`. **Enforced:** a title never
    changes the File's name or path, so a note's `[[link]]` to the File keeps
    resolving. It works on a File kept in sync with a folder (card [source](https://docs.pnbr.io/concepts/source.md)),
    where renaming the File with `penumbra files move` sets the title instead.
    Search and `[[links]]` find the File by its title. **Your job:** give a
    synced File its title here; its name stays the folder's.

13. `file.13` Files you upload together are one drop, and a drop is one upload
    batch with one optional note: why you share them. `penumbra files upload`
    makes a batch when you give it more than one file or `--note`. To make one on
    its own, run `penumbra files batches create`, then pass `--batch` to the
    upload. Penumbra reads the note when it suggests names, tags and collections
    for every File in the batch. **Enforced:** a note over 2,000 characters is
    refused, and so is a batch id that the project does not hold. **Your job:**
    write the note before you upload, because a batch never changes.

14. `file.14` A web page can be a File (card [website](https://docs.pnbr.io/concepts/website.md)). `penumbra web save <url>…`
    saves up to 50 public pages, and `penumbra web crawl <url>` saves the pages of
    a site into one collection. A page File keeps its web address, has searchable
    text and has pictures of the page. It sits in the Workspace under
    `/web/<host>/<path>/index`. Choose another folder with `--to`.
    **Enforced:** Penumbra refuses an address that is not public, with
    `url_not_allowed`, and a page that the site's rules keep out, with
    `url_blocked_by_robots`. It reports a page that the project already holds as
    `already_in_project` and does not capture it again, so no new version is
    made. Each captured page is charged, and a page that fails costs nothing.
    **Your job:** show the person the kept count and the estimate before a
    crawl. `penumbra web crawl --dry-run` prints them. A crawl of more than 100
    pages is refused with the same dry run (recipe [bring-in-a-website](https://docs.pnbr.io/guides/bring-in-a-website.md)).
    Keeping a captured page current from the web is not available.

15. `file.15` A captured page keeps pictures unless you pass `--pictures none`.
    `--pictures full` is the default and keeps the whole page, `--pictures
    viewport` keeps the first screen. **Enforced:** a page keeps at most 20
    pictures, from the top down, and a longer page warns `page_pictures_truncated`.
    The text of the whole page stays searchable. **Your job:** tell the person
    which pages lost their lower pictures (problem [page-pictures-truncated](https://docs.pnbr.io/troubleshooting/page-pictures-truncated.md)).

## Failure signs

* Search returns two passages that say different things about one fact: problem
  [two-editions-two-files](https://docs.pnbr.io/troubleshooting/two-editions-two-files.md).
* The Graph still shows the facts of the old edition: problem
  [new-version-not-extracted](https://docs.pnbr.io/troubleshooting/new-version-not-extracted.md).
* Entities cite a version that is no longer current: problem
  [entities-cite-replaced-version](https://docs.pnbr.io/troubleshooting/entities-cite-replaced-version.md).
* An entity's only citations point to a trashed File: problem
  [entity-rests-on-trashed-file](https://docs.pnbr.io/troubleshooting/entity-rests-on-trashed-file.md).
* A replace is refused with `version_conflict`: read the versions again with
  `penumbra files versions`, decide, and replace with the new version ID.
* A trash returns `pending` or exit code 4: problem [change-waits-for-approval](https://docs.pnbr.io/troubleshooting/change-waits-for-approval.md).
* A File has no source date: problem [file-has-no-source-date](https://docs.pnbr.io/troubleshooting/file-has-no-source-date.md).
* A new File is missing from a meaning search: problem
  [new-file-not-searchable-yet](https://docs.pnbr.io/troubleshooting/new-file-not-searchable-yet.md).
* An upload returned an old File and no new version: problem
  [same-bytes-no-new-version](https://docs.pnbr.io/troubleshooting/same-bytes-no-new-version.md).
* The text of a File lost its tables or headings: recipe [check-file-text](https://docs.pnbr.io/guides/check-file-text.md).
* A page is refused with `url_blocked_by_robots`: problem
  [page-blocked-by-robots](https://docs.pnbr.io/troubleshooting/page-blocked-by-robots.md).
* A crawl keeps far fewer pages than the site has: problem
  [crawl-found-fewer-pages](https://docs.pnbr.io/troubleshooting/crawl-found-fewer-pages.md).
* A page's pictures stop partway down: problem [page-pictures-truncated](https://docs.pnbr.io/troubleshooting/page-pictures-truncated.md).
* A save reports a page as already in the project: problem
  [page-already-in-project](https://docs.pnbr.io/troubleshooting/page-already-in-project.md).

## Doors

| Door | Call |
| - | - |
| CLI | `penumbra files upload`, `penumbra files batches create`, `penumbra files batches get`, `penumbra files replace`, `penumbra files versions`, `penumbra files text`, `penumbra files show`, `penumbra files inspect`, `penumbra files source-date`, `penumbra files trash`, `penumbra files restore`, `penumbra files wait`, `penumbra files find` |
| MCP (default) | `file_gallery` and `open_file` show Files, `read` opens a File or one exact version, and `update_file` sets the description, tags and source date. |
| MCP (full catalog) | `list_files`, `list_file_versions`, `read_file_text`, `trash_file`, `restore_file`, `move_file` and `update_file`. |
| MCP (Files Kits) | Reader has `list_file_versions` and `read_file_text`. Steward has `trash_file`, `restore_file`, `move_file` and `update_file`. Manager has all of them. |
| SDK | `project.files` |

No MCP tool uploads or replaces a File, and none brings in a web page. Use the
CLI, the SDK or HTTP. An agent connected only through MCP cannot put a new
edition into a File.

## HTTP reference

* [Create upload session](https://docs.pnbr.io/api/http-uploads-create.md)
* [Get upload session](https://docs.pnbr.io/api/http-uploads-get.md)
* [Add file](https://docs.pnbr.io/api/http-files-admit.md)
* [List files](https://docs.pnbr.io/api/http-files-list.md)
* [Resolve files](https://docs.pnbr.io/api/http-files-resolve.md)
* [Replace file](https://docs.pnbr.io/api/http-files-replace.md)
* [List file versions](https://docs.pnbr.io/api/http-versions-list.md)
* [Get file version](https://docs.pnbr.io/api/http-versions-get.md)
* [Get file processing status](https://docs.pnbr.io/api/http-files-processing.md)
* [Download file](https://docs.pnbr.io/api/http-files-download.md)
* [Get file text](https://docs.pnbr.io/api/http-files-text.md)
* [Get file pages](https://docs.pnbr.io/api/http-files-pages.md)
* [List file citations](https://docs.pnbr.io/api/http-files-citations.md)
* [Set file title](https://docs.pnbr.io/api/http-files-title.md)
* [Set file description](https://docs.pnbr.io/api/http-files-describe.md)
* [Set file tags](https://docs.pnbr.io/api/http-files-tags.md)
* [Set file source date](https://docs.pnbr.io/api/http-files-source-date.md)
* [Trash files](https://docs.pnbr.io/api/http-files-trash.md)
* [Restore files](https://docs.pnbr.io/api/http-files-restore.md)
* [Get file operation](https://docs.pnbr.io/api/http-operations-get.md)
* [Recover file request](https://docs.pnbr.io/api/http-requests-get.md)

## Keep going

[Project](https://docs.pnbr.io/concepts/project.md) · [Document](https://docs.pnbr.io/concepts/document.md) · [Collection](https://docs.pnbr.io/concepts/collection.md) · [Passage and citation](https://docs.pnbr.io/concepts/passage.md) · [Search](https://docs.pnbr.io/concepts/search.md) · [Synced folder](https://docs.pnbr.io/concepts/source.md) · [Bring in a new edition of a document](https://docs.pnbr.io/guides/new-edition.md) · [A new edition is a separate File](https://docs.pnbr.io/troubleshooting/two-editions-two-files.md) · [Website](https://docs.pnbr.io/concepts/website.md) · [Save web pages or crawl a website into the project](https://docs.pnbr.io/guides/bring-in-a-website.md) · [The site's rules keep a page out](https://docs.pnbr.io/troubleshooting/page-blocked-by-robots.md) · [A crawl keeps fewer pages than the site has](https://docs.pnbr.io/troubleshooting/crawl-found-fewer-pages.md) · [A long page keeps pictures for its top only](https://docs.pnbr.io/troubleshooting/page-pictures-truncated.md) · [The project already holds the page](https://docs.pnbr.io/troubleshooting/page-already-in-project.md)

Penumbra Grammar 0.6.26


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