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

# Brain

> A Brain gives a client one View with agents, instructions and a page, and it lists who has access and what they did.

Concept · access

> **Use when**
>
> You give a client part of a project and need to manage its content, agents, access and activity in one place.

> **Looking for something else?**
>
> The limit alone, with no agents or access list (card [View](https://docs.pnbr.io/concepts/view.md)). Which credential you hold (card [Credential](https://docs.pnbr.io/concepts/credential.md)). A group of Files (card [Collection](https://docs.pnbr.io/concepts/collection.md)).

## For

A Brain is the handoff of part of a project. It has a name, a purpose and four
parts.

* **Content** is one published View. Everything with access to the Brain reads
  that View and nothing else.
* **Agents** is a read-only Kit version and the instructions for the firm's own
  agents. A Brain may have no Kit. Then only the clients' own agents, such as
  Claude, work in it.
* **Access** lists the clients, agents, API keys, invites and the page that
  reach the Content. Each one is an access.
* **Activity** lists each search and read made through them.

A Brain's **page** is a read-only web page at a web address. It shows the
Content in a browser. Anyone with the web address reads it, or only the people
on the page's list do. A **listed person** is an email or a domain on that list.
They prove the email with a code or with the web address in the email message.
They hold no account, no seat and no key, and they cannot invite anyone.

A Brain adds no permission. Each person, key or agent has its own limit to the
View, and no read asks the Brain. The Brain only names who the firm gave that
View to. Content stays current. A new publish of the View, and a new File in an
included collection, reach every access that follows the View automatically.
A page can show cached public content for up to 30 seconds (rule [brain.17](https://docs.pnbr.io/concepts/brain.md#rule-brain-17)).

## Use when

* You hand a client part of a project and want one place to see who has it.
* You add an agent or an API key for a client's content.
* You must end one person's access, or all access, to that content.
* The person asks what a client or an agent read.
* A client or a prospect must read part of the project in a browser, with no
  account (rules [brain.15](https://docs.pnbr.io/concepts/brain.md#rule-brain-15) to [brain.20](https://docs.pnbr.io/concepts/brain.md#rule-brain-20)).

## Not this

* A limit for one key with no list of who has it: use a View (card [View](https://docs.pnbr.io/concepts/view.md)).
* Which credential you hold and what it can do: use card [Credential](https://docs.pnbr.io/concepts/credential.md).
* Putting Files into groups: use a collection (card [Collection](https://docs.pnbr.io/concepts/collection.md)).

## Rules

1. `brain.1` A Brain always has one published View as its Content, and it
   cannot change. **Enforced:** `penumbra brains create` refuses a retired or
   unpublished View with `brain_view_unavailable`. `penumbra brains update` has
   no flag for the View, and the API refuses a View in an update with
   `request_invalid`. **Your job:** to change what clients read, edit and
   publish the View (card rule [view.1](https://docs.pnbr.io/concepts/view.md#rule-view-1)), or make a new Brain.

2. `brain.2` A Brain name is unique among the active Brains of the project.
   **Enforced:** a second Brain with the same name is refused with
   `brain_name_taken`. Spaces and letter case do not make a name different.

3. `brain.3` Access comes from the own limit of each person, key or agent to
   the View. **Enforced:**
   `penumbra brains attach` refuses a person, key or agent that is not
   limited to the Brain's View with `brain_door_view_mismatch`. **Your job:**
   limit it first with `penumbra access attach`, or create it for the Brain in
   one call (rule [brain.4](https://docs.pnbr.io/concepts/brain.md#rule-brain-4)).

4. `brain.4` Create new access for a Brain in one call. **Enforced:** a key
   for a Brain can only read, and a write scope is refused with
   `view_requires_read_only`. **Your job:** use
   `penumbra keys create "<name>" --scope files.search --brain <brain-id>` for
   a key, and `penumbra kits connections create "<name>" --brain <brain-id>`
   for an agent. Each creates the key or agent, limits it to the Content and
   adds it to the Brain, or creates nothing.

5. `brain.5` The Kit of a Brain can only read. **Enforced:** a Kit version
   with a permission outside the read set is refused with
   `brain_kit_not_read_only`. A Kit that is not active, not shared with the
   project, or not the version's own is refused with `brain_kit_unavailable`.
   The CLI has no command that shares a Kit with the project.

6. `brain.6` An agent's access needs the Brain's own Kit version. **Enforced:** a
   Brain with no Kit refuses an agent with `brain_kit_required`, and an agent
   on another Kit version is refused with `brain_door_kit_mismatch`. A newer
   Kit version on the Brain does not change agents that already exist.

7. `brain.7` An access belongs to one Brain. **Enforced:** an access open in
   another Brain on the same View is refused with `brain_door_in_other_brain`. A key
   that belongs to an agent is refused as an API key with
   `brain_door_kind_mismatch`.

8. `brain.8` A client's own agents are part of the client. **Enforced:**
   attaching one is refused with `brain_door_belongs_to_client`. They act as
   the client, follow the client's View, and appear under the client as
   "Also uses Claude". Their reads appear in Activity as the client.

9. `brain.9` Ending one access ends it for the whole project, not only for this
   Brain. **Enforced:**
   `penumbra brains remove-door` revokes the key or agent, removes the client
   from the project, or cancels the invite, and it asks to confirm. Without a
   terminal it needs `--yes` and otherwise exits with
   `confirmation_required`. **Your job:** tell the person that the client loses
   the whole project and not only this Brain. Nothing detaches an access and
   keeps it.

10. `brain.10` Retiring a Brain ends all of its access, all or nothing.
    **Enforced:** if any access cannot end, `penumbra brains retire` is refused
    with `brain_retire_refused`, nothing changes, and the answer names each
    one with the authority it needs. **Your job:** expect that the Files, the
    graph, the View and the Kit stay.

11. `brain.11` Instructions reach the Brain's agents, and the client can read
    them. **Your job:** never put anything in `--instructions` that a client
    must not see. **Enforced:** more than 8192 bytes is refused as invalid. A
    Brain counts bytes, so a character outside ASCII takes more than one. A Kit
    counts characters (card rule [kit.13](https://docs.pnbr.io/concepts/kit.md#rule-kit-13)).

12. `brain.12` Only a signed-in person who manages access can change or read
    a Brain. **Enforced:** a key or agent is refused with
    `human_session_required`, and any other person with `permission_denied`.
    An editor, or a key with `context.view.write`, can change a View but not
    a Brain.

13. `brain.13` An access shows a state only when it needs attention.
    **Your job:** read `penumbra brains show <brain-id>` for each of these.
    **Moved** means the person, key or agent now has another View or none, and
    its access follows that limit and not the Brain. **Closed** means the
    person, key or agent is gone. A pending invite waits for the client.

14. `brain.14` Activity shows each search and read, and not what was asked.
    **Your job:** do not promise the person that you can show a client's
    questions. A read receipt belongs to the Brain only while the access was in it.

15. `brain.15` A page is made by publishing and by nothing else. **Enforced:**
    publishing makes the page and its own limit to the View in one step. Any
    other change to that limit is refused with
    `brain_app_boundary_managed_by_publish`. **Your job:** tell the person that a
    page has no key to copy and no account to remove.

16. `brain.16` A page is open to anyone with its web address, or only to the
    people on its list. **Enforced:** a page for a list refuses a request with no
    open session of that page. An email that is not on the list gets the same
    answer as one that is, and no message. **Your job:** say which of the two the
    person chose. Say that anyone with the web address of a public page reads it.

17. `brain.17` Unpublishing, expiry, or retiring its Brain or View ends a page.
    **Enforced:** the next request reaching the runtime refuses its content,
    and existing sessions no longer admit reads. The answer is
    `brain_app_not_found`, like an unknown web address, or the owner's expiry
    message when one was set. Public content already cached may remain visible
    for up to 30 seconds; pages for a list are not cached. Publishing a View
    again does not bring the page back. **Your job:** publish the page again if
    it must return. It gets a new web address.

18. `brain.18` A page shows the Content and nothing more. **Enforced:** it reads
    through its own limit to the View. History, the ontology and extraction are
    refused, and a File outside the View reads as missing. Turning downloads off
    removes the Download action and blocks non-image originals. Image originals
    and derived previews remain readable. **Your job:** do not promise a visitor
    more than the Content, or promise that previews cannot be saved.

19. `brain.19` The plan limits how many pages are published. **Enforced:**
    publishing past the limit is refused with `plan_brain_app_limit`. Free has 1,
    Pro has 3 and Team has 10. **Your job:** offer to unpublish one page first.

20. `brain.20` A page for a list shows its owner who opened it. **Enforced:**
    Activity lists each person's email, first and last visit and the pages they
    read. It never holds what they searched for. **Your job:** do not promise a
    visitor that the owner cannot see that they opened the page.

## Failure signs

* A client reads more than the Brain's Content: an access is `moved`, or it
  was given full project access (rule [brain.13](https://docs.pnbr.io/concepts/brain.md#rule-brain-13)).
* A client reads nothing: the View was retired or has no published version
  (card rule [view.11](https://docs.pnbr.io/concepts/view.md#rule-view-11)).
* A client's agent cannot find something the person sees: problem
  [hidden-reads-as-missing](https://docs.pnbr.io/troubleshooting/hidden-reads-as-missing.md).
* A key or agent cannot be added: rules [brain.3](https://docs.pnbr.io/concepts/brain.md#rule-brain-3), [brain.6](https://docs.pnbr.io/concepts/brain.md#rule-brain-6) and [brain.7](https://docs.pnbr.io/concepts/brain.md#rule-brain-7).

## Doors

| Door | Call |
| - | - |
| CLI | `penumbra brains list`, `penumbra brains show`, `penumbra brains create`, `penumbra brains update`, `penumbra brains attach`, `penumbra brains remove-door`, `penumbra brains retire`, `penumbra brains receipts`, `penumbra brains page show`, `penumbra brains page publish`, `penumbra brains page update`, `penumbra brains page unpublish`, `penumbra brains page viewers list`, `penumbra brains page viewers set`, `penumbra brains page activity`, and `--brain` on `penumbra keys create` and `penumbra kits connections create` |
| MCP | `brain_page` reads, publishes, changes and unpublishes a Brain's page, for the person who approved the connection. Nothing else manages a Brain. Use the CLI. A Brain's instructions reach an agent on one of the Brain's connections, in the instructions of the MCP connection. |
| SDK | `brains` |

No CLI command invites a client. Ask the person to open the Brain in the App
under **Brains**, and choose **Give access**.

A signed-in person who manages access manages a page. Use the CLI
(`penumbra brains page show` and the commands beside it), the SDK or the platform
API. On MCP, `brain_page` is only on the connection of a person who is an owner or
admin of the project. A key, a Kit and a delegated agent do not have it. The project's approval floor holds publishing, opening the page
wider and unpublishing (card [approval](https://docs.pnbr.io/concepts/approval.md)). It does not list the people or show
who looked: use the CLI. Recipe [publish-a-brain-page](https://docs.pnbr.io/guides/publish-a-brain-page.md) says what to prepare.

## The CLI word

The CLI calls an access a door. The command is
`penumbra brains remove-door <brain-id> <door-id>`. Take `<door-id>` from the
row that `penumbra brains show` prints under `access`.

## HTTP reference

* [List brains](https://docs.pnbr.io/api/http-brains-list.md)
* [Create brain](https://docs.pnbr.io/api/http-brains-create.md)
* [Get brain](https://docs.pnbr.io/api/http-brains-get.md)
* [Update brain](https://docs.pnbr.io/api/http-brains-update.md)
* [Attach brain connection](https://docs.pnbr.io/api/http-brains-doors-attach.md)
* [Remove brain connection](https://docs.pnbr.io/api/http-brains-doors-remove.md)
* [List brain receipts](https://docs.pnbr.io/api/http-brains-receipts.md)
* [Retire brain](https://docs.pnbr.io/api/http-brains-retire.md)

## Keep going

[View](https://docs.pnbr.io/concepts/view.md) · [Credential](https://docs.pnbr.io/concepts/credential.md) · [Collection](https://docs.pnbr.io/concepts/collection.md) · [Approval](https://docs.pnbr.io/concepts/approval.md) · [Share part of a project with a View](https://docs.pnbr.io/guides/share-with-a-view.md) · [Give a client a Brain and check what it answers](https://docs.pnbr.io/guides/ship-a-brain.md) · [Publish a Brain as a page](https://docs.pnbr.io/guides/publish-a-brain-page.md) · [Something outside the View reads as not found](https://docs.pnbr.io/troubleshooting/hidden-reads-as-missing.md)

Penumbra Grammar 0.6.26


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