Skip to main content
Guide · files

Use when

A person gives you a folder or a set of documents to add to the project.

Looking for something else?

A newer copy of a document the project already has (recipe Bring in a new edition of a document). One document you write yourself (card Document). Pages of a website (recipe Save web pages or crawl a website into the project).

​
Outcome

Every document is one File with its source date, in one collection, and search finds it by its words.

​
Before you start

  • Run penumbra status. Confirm the project and that no limit it lists stops uploads or collections (card rule project.1).
  • Read each document’s own date: a date line, a signature date or a date in its name. That date is its source date, not today’s date.
  • Run penumbra files find "<name>" for each document. A document the project already has is a new edition, not a new File (recipe new-edition).

​
Steps

  1. Choose one collection name for the set. Create it with penumbra files collections create "<name>" (card rule collection.1). MCP: none in the default catalog; use the CLI.
  2. Upload each document on its own, with its source date: penumbra files upload <path> --to /<folder> --source-date <date> --wait. A folder upload sets no per-File date (card rules file.4 and file.11). Expect uploaded and a File ID for each.
  3. If an upload returns an existing File, the project already held those bytes. Do not upload it again (card rule file.6).
  4. Add each File to the collection: penumbra files collections add "<name>" <file> (card collection).
  5. Check readiness: penumbra files collections readiness "<name>". Wait until every File is searchable by words (card rule collection.3).

​
Check

  • penumbra files list --collection "<name>" lists every document once.
  • penumbra files versions <file> shows the source date you set, for each File.
  • penumbra files search "<a phrase from one document>" --mode lexical finds that document’s passage.

​
If it goes wrong

​
Worth offering

  • Offer to extract entities from the new collection with a Shape that fits the documents (recipe extract-files).
  • Offer to share the collection with a client through a View (recipe share-with-a-view).
  • If two documents are editions of one document, offer to keep them as one File (problem two-editions-two-files).

​
Report

Say how many documents arrived, the collection name, and each document’s source date. Name any document you did not add and why. Say whether every File is searchable yet.

​
Keep going

File · Collection · Search · Passage and citation · Project · Answer from the project’s documents, with citations