Brain

​

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

​

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 to brain.20).

​

Not this

• A limit for one key with no list of who has it: use a View (card View).
• Which credential you hold and what it can do: use card Credential.
• Putting Files into groups: use a collection (card Collection).

​

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), 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).
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).
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).
• A client reads nothing: the View was retired or has no published version (card rule view.11).
• A client’s agent cannot find something the person sees: problem hidden-reads-as-missing.
• A key or agent cannot be added: rules brain.3, brain.6 and brain.7.

​

Doors

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). It does not list the people or show who looked: use the CLI. Recipe publish-a-brain-page 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
• Create brain
• Get brain
• Update brain
• Attach brain connection
• Remove brain connection
• List brain receipts
• Retire brain

​

Keep going

View · Credential · Collection · Approval · Share part of a project with a View · Give a client a Brain and check what it answers · Publish a Brain as a page · Something outside the View reads as not found