Skip to main content
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). A named group of Files (card Collection). A folder kept current from a source (card Synced folder).

​
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). 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). 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).

​
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). 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).
  • 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). 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).
  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), 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). 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). 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).

​
Failure signs

​
Doors

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

​
Keep going

Project · Document · Collection · Passage and citation · Search · Synced folder · Bring in a new edition of a document · A new edition is a separate File · Website · Save web pages or crawl a website into the project · The site’s rules keep a page out · A crawl keeps fewer pages than the site has · A long page keeps pictures for its top only · The project already holds the page