Give a client a Brain and check what it answers

​

Outcome

A Brain names one published View as its content. The people, keys or agents that the person chose have access to that content and nothing else. You asked the acceptance questions with a key that is limited to the Brain. Each question the client must answer found passages inside the View. Each question the client must not answer found none.

​

Before you start

• Orient first (recipe orient). Managing a Brain needs a signed-in person who is an owner or admin. A key or a connected agent is refused with human_session_required (card rule brain.12). If that is you, give the person the commands and ask them to run them.
• Ask the person for the acceptance questions, in the client’s words. Ask for three to five that the client must be able to answer from the content. Ask for at least one that the client must not be able to answer, because its answer lives in a File outside the content.
• Know what the View includes. If there is no published View yet, make one first (recipe share-with-a-view, steps 1 to 6).
• Decide with the person whether the Brain has agents of its own. Without a Kit only the clients’ own agents, such as Claude, work in it (card rule brain.6).

​

Steps

1. Choose the Kit, if any.
   • CLI: penumbra kits show <kit-id>. Use a version that says “reads only” (card rule kit.10). The Kit must be shared with the project. A private Kit is refused with brain_kit_unavailable, and the CLI cannot share it (card rule kit.11). Ask a project owner or admin to share it in the App.
   • No Kit: leave out --kit-version.
2. Make the Brain.
   • CLI: penumbra brains create "<name>" --view <view-id> --purpose "<text>", with --kit-version <version-id> and --instructions-from <file> when there are agents. Expect applied: Brain created, the Brain ID, a content: line that names the View, an agents: line, and next steps for giving access. Nothing in the instructions may be confidential, because the client can read them (card rule brain.11).
   • MCP: none manages a Brain. Use the CLI.
3. Give the client access. Each one is limited to the Brain’s content.
   • A client who is already a member of the project: penumbra access attach <view-id> --member <subject-id>, then penumbra brains attach <brain-id> --member <subject-id> (card rule brain.3).
   • A new client: ask the person to open the Brain in the App under Brains and choose Give access.
   • An agent: penumbra kits connections create "<name>" --brain <brain-id>. Expect brain_kit_required if the Brain has no Kit.
   • A key for the client’s own code: penumbra keys create "<name>" --scope files.search --scope files.file.list --scope graph.read --scope graph.search --brain <brain-id>. Each of these makes the access and adds it to the Brain together (card rule brain.4).
4. Make the acceptance key. It is yours, not the client’s. A client’s access is never passed on (card rule credential.8).
   • CLI: penumbra keys create "<Brain name> acceptance" --scope files.search --scope files.file.list --scope graph.read --scope graph.search --brain <brain-id>.
   • Expect the key’s scopes, limited to View: <name> … read-only, a line that says it was added to the Brain, and the secret once. Store the secret in an environment variable for this step only. Do not write it in a file or in the chat (card rule credential.5).
5. Check that the key sees what the client sees.
   • CLI: PENUMBRA_TOKEN=<secret> penumbra access me. Expect You read only the View <name>, a version: line and a graph: line. If it says that you read the whole project, stop. The key is not limited, and no answer below means anything (problem what-can-this-credential-see).
6. Ask each acceptance question with the key.
   • CLI: PENUMBRA_TOKEN=<secret> penumbra files search "<words of the question>" --mode lexical. Expect, for a question the client must answer, one or more results that each name a File, a version and a passage location. Read the passages. They must support the expected answer.
   • Expect, for a question the client must not answer, No passages match.
   • For each outside question, run the same search with your own credential. It must find the passage there. Then the empty answer proves the limit, and not a bad question.
   • Search by meaning (--mode hybrid) finds more. Ask the questions again in that mode when the project has it ready. A warning that meaning search is unavailable means the run was by words (card rule search.2).
   • MCP: the client’s agent asks with omnisearch and read. An agent in the Brain’s Kit uses the tools that the Kit has.
7. Read the activity.
   • CLI: penumbra brains receipts <brain-id>. Expect one row for each search you made, with the access it came through and how many results it returned. It does not show what you asked (card rule brain.14).
8. Decide with the person what happens to the acceptance key.
   • Keep it to ask the questions again after a Shape change or a new publish of the View. Or end it: penumbra keys revoke <credential-id> --yes. After the revoke, the key is refused with authentication_invalid.

​

Check

• PENUMBRA_TOKEN=<secret> penumbra access me names the Brain’s View.
• Every question the client must answer returned results, and each result is a passage of a File inside the View.
• Every outside question returned No passages match with the key, and found its passage with your own credential.
• penumbra brains show <brain-id> lists each access you gave, and none you did not give.
• penumbra brains receipts <brain-id> lists your searches.

​

If it goes wrong

​

Worth offering

• Offer to ask the acceptance questions again after every Shape change, new publish of the View, or new File in an included collection.
• Offer to write the questions down in a File of the project, with the answer each should give. The next run then starts from the same list.
• Offer to give the client’s agents instructions that say what the Brain is for and which questions it answers well (card rule brain.11).

​

Report

Name the Brain, its View and what the View includes, in the person’s words. List who has access and how. Give each acceptance question, the result, and whether the passages support the expected answer. Say that the outside questions found nothing with the limited key and something with your own credential. Say what the person must still do in the App, such as sending an invitation, and what waits for approval. State which checks you did not run, such as a Kit that is not yet shared.

​

Keep going

Brain · View · Kit · Credential · Collection · Share part of a project with a View · Something outside the View reads as not found · Approval · Answer from the project’s documents, with citations