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

# Collection

> A collection is a named group of Files that you search, extract from and share as one set, and its membership is read live.

Concept · files

> **Use when**
>
> You group Files for a job, check whether a group is ready, extract from a group, or choose what a View includes.

> **Looking for something else?**
>
> One document and its versions (card [File](https://docs.pnbr.io/concepts/file.md)). A folder kept current from a source (card [Synced folder](https://docs.pnbr.io/concepts/source.md)). The part of a project a person may see (card [View](https://docs.pnbr.io/concepts/view.md)).

## For

A collection is a name for a set of Files. A File can belong to several
collections, and joining one does not change the File, its path or its versions.
The collection holds the File itself, so a new edition of a member is still a
member.

Collections are how a job works on a corpus. You bring Files in, put them in a
collection, and check that the collection is ready. You then search inside it
and extract from it. A View can include the collection, and a Brain includes
that View, so the same collection decides what a client sees.

Membership is read when a command runs, not when you set it up. Adding a File
to a collection changes what every search, extraction scope and View on that
collection reads next.

## Use when

* You bring in a set of documents and must treat them as one corpus.
* You need to know whether every File in a group is searchable.
* You extract from many Files at once.
* You search inside one or more collections, with `penumbra search --collection`
  or with `collections` in the MCP tool `omnisearch` (card [Search](https://docs.pnbr.io/concepts/search.md)).
* You choose which Files a View, and so a Brain, includes.

## Not this

* One document and its versions: use card [File](https://docs.pnbr.io/concepts/file.md).
* A folder on a machine or in a drive that Penumbra keeps current: use a source
  (card [Synced folder](https://docs.pnbr.io/concepts/source.md)).
* What one person or agent may read: use a View (card [View](https://docs.pnbr.io/concepts/view.md)).

## Rules

1. `collection.1` A collection name is unique in the project, and case does not
   matter. **Enforced:** the CLI refuses a second collection with the same name
   with `collection_conflict`. Files commands and
   `penumbra search --collection` take a collection by ID or by name, an exact
   match first, then one that differs only in case. `penumbra graph extract`
   and `penumbra extractions plan` take the ID only.
2. `collection.2` Deleting a collection keeps its Files. **Enforced:**
   `penumbra files collections delete` is refused with `confirmation_required`
   unless you pass `--yes`. It also waits for approval when you act with an API
   key or as a connected agent. The result is `pending` with an approval link.
   **Your job:** do not retry. A deleted collection cannot be restored. A new
   collection has a new ID, so a View that named the old one does not include it.
3. `collection.3` Check readiness before you search a collection or extract from
   it. **Your job:** run `penumbra files collections readiness`. It splits the
   Files into four groups that add up to the File count: searchable, still
   processing, unreadable and without text. Search reads only the searchable
   ones. An extraction is refused with `source_unavailable` when a member has no
   readable current version.
4. `collection.4` Some searchable Files are not yet searchable by meaning.
   **Your job:** the readiness report counts them apart. Search them by words,
   or wait, before you rely on a meaning search of the collection.
5. `collection.5` An extraction from a collection reads each member's current
   version when it starts. **Enforced:** an empty collection is refused with
   `collection_empty`. A collection with more than 256 Files, or more text than
   one run reads, is refused with `collection_too_large`. No credit is held.
6. `collection.6` An admitted extraction keeps its Files and versions. **Your
   job:** a File you add or a version you replace after the start is not read by
   that run. Run `penumbra extractions plan` first to see the Files, versions
   and cost, because it changes nothing and charges nothing.
7. `collection.7` An API key, a connected agent or a Kit can start a collection
   extraction only when an owner or admin allows it. **Enforced:** while that
   setting is off, which is the default, the start is refused with
   `unattended_collection_extraction_off`. With it on, a run above the per-run
   cap is refused with `collection_run_over_cap`. Only a signed-in owner or
   admin can change the setting.
8. `collection.8` A pending approval of an extraction names the collection as it
   stood. **Enforced:** if a File joins or leaves, or a member gets a new
   version, before the owner approves, the approval is refused with
   `target_changed`. Start the extraction again.
9. `collection.9` A View that includes a collection shows its members as they
   are when someone reads. **Your job:** before you add a File to such a
   collection, decide that everyone limited to that View may read it. It
   appears at once, and removing the File hides it at once.
10. `collection.10` A collection that a source keeps current follows its folder.
    **Your job:** do not treat its membership as yours. Files that the person
    deletes from the folder leave the collection.
11. `collection.11` The collection list comes a page at a time. **Your job:**
    `penumbra files collections list` shows 50 by default and up to 200 with
    `--limit`, and prints `more: rerun with --cursor <cursor>` when more remain.
    On a managed connection, the MCP tool `list_collections` shows only the
    first 200 collections. Check a collection beyond that by its exact name,
    with `penumbra files suggest collections`.

## Failure signs

* An extraction is refused with `collection_too_large`: rule [collection.5](https://docs.pnbr.io/concepts/collection.md#rule-collection-5).
* An extraction finished in part, or you must know whether it read every File:
  problem [extraction-incomplete](https://docs.pnbr.io/troubleshooting/extraction-incomplete.md).
* Readiness lists unreadable Files, or their text lost layout: recipe
  [check-file-text](https://docs.pnbr.io/guides/check-file-text.md).
* A person limited to a View sees a File they should not: recipe
  [share-with-a-view](https://docs.pnbr.io/guides/share-with-a-view.md).
* A delete returns `pending` or exit code 4: problem [change-waits-for-approval](https://docs.pnbr.io/troubleshooting/change-waits-for-approval.md).
* Search inside a collection returns nothing for a new File: problem
  [new-file-not-searchable-yet](https://docs.pnbr.io/troubleshooting/new-file-not-searchable-yet.md).

## Doors

| Door | Call |
| - | - |
| CLI | `penumbra files collections list`, `penumbra files collections get`, `penumbra files collections files`, `penumbra files collections readiness`, `penumbra files collections create`, `penumbra files collections update`, `penumbra files collections delete`, `penumbra files collections add`, `penumbra files collections remove`, `penumbra files suggest collections`, `penumbra extractions plan`, `penumbra graph extract` |
| MCP (default) | `project_overview` lists collections, and `file_gallery` filters by one. `omnisearch` and `penumbra.search` search inside any of several. No default tool creates, renames or deletes a collection. An `execute` program can add a File to a collection or remove it. |
| MCP (full catalog) | `list_collections`, `create_collection`, `update_collection`, `delete_collection`, `list_collection_files` and `set_collection_membership`. The tool `extraction_start` takes a collection ID. |
| MCP (Files Kits) | Steward has `list_collections` and `set_collection_membership`. Manager has all six tools of the full catalog. |
| SDK | `project.files.collections` |

The default catalog has no tool that starts an extraction. The MCP tool
`extraction_start` does, in the full catalog and in a Kit that selects it.

The MCP tool `set_collection_membership` names a File by its path. A File with
no path cannot be added that way. Give it a path with `penumbra files place`,
or use the CLI command `penumbra files collections add`.

No MCP tool reports the readiness of a whole collection. The tool `list_files`
with the collection and the current version expanded shows each File's
processing. Use the CLI, the SDK or HTTP for the grouped report.

## The CLI word

The CLI calls a View a Context Slice.

## HTTP reference

* [List collections](https://docs.pnbr.io/api/http-collections-list.md)
* [Create collection](https://docs.pnbr.io/api/http-collections-create.md)
* [Get collection](https://docs.pnbr.io/api/http-collections-get.md)
* [Update collection](https://docs.pnbr.io/api/http-collections-update.md)
* [Delete collection](https://docs.pnbr.io/api/http-collections-delete.md)
* [Add file to collection](https://docs.pnbr.io/api/http-collections-add.md)
* [Remove file from collection](https://docs.pnbr.io/api/http-collections-remove.md)
* [Get collection readiness](https://docs.pnbr.io/api/http-collections-readiness.md)

## Keep going

[File](https://docs.pnbr.io/concepts/file.md) · [Search](https://docs.pnbr.io/concepts/search.md) · [Extraction](https://docs.pnbr.io/concepts/extraction.md) · [View](https://docs.pnbr.io/concepts/view.md) · [Brain](https://docs.pnbr.io/concepts/brain.md) · [Synced folder](https://docs.pnbr.io/concepts/source.md) · [Bring a set of documents into the project](https://docs.pnbr.io/guides/bring-in-a-corpus.md) · [An extraction did not read every File](https://docs.pnbr.io/troubleshooting/extraction-incomplete.md)

Penumbra Grammar 0.6.26


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