Work with brains and blueprints

The job

Answer a question about one subject, such as the business or its website, from the brain that Sasha holds for that subject. Tell the person how complete that brain is, and which documents are still missing.

What a brain is

A brain is everything Sasha knows about one subject. It is a folder inside a project. The folder holds a brain.md card and a set of ordinary documents. The brain id is <project>/<folder>. A card at the root of a project is not a brain.
A blueprint is the plan for one kind of brain. It ships with Sasha and has a version, for example site@1. It lists every document that kind of brain should have. Each document has a ring, the Context Spine domains it covers (deepens, numbers 1 to 20), an out-of-date rule (outOfDateAfterDays) and one line on what it should contain (asks).
This release has two blueprints. business@1 is the Context Spine: twenty documents in five rings. site@1 describes one website and sits under a business brain.
The five rings are, in order: Public Context (stage Scope), Organisational Knowledge (Land), Proprietary Methodology (Expand), System Integration (Embed) and Flow (Flow). A brain's depth counts its documents in each ring by state.
The card names the blueprint and lists only the differences. add gives an extra document with an id, title, ring, deepens, outOfDateAfterDays, asks and a reason. drop removes a blueprint document, with a reason. A brain's documents are the blueprint's, minus drop, plus add.
A document's state is missing, filled, checked, declined or out of date. The state comes from the document's own frontmatter (checked, checkedBy, declined, summary), never from the card.
A card can name a parent brain, for example a site brain under its business brain. When a site brain has no document for a domain, the parent business brain may cover it. A parent that this connection cannot read is reported as no parent.
A brain in a member's own home has level tenant. A brain in a shared project has level sasha.

Prerequisites

The connection holds knowledge:read. Admin, staff and member connections can all hold it.
A member sees the brains in their own member home and in each shared project where they hold a grant. Admin and staff see the brains in every active shared project, but in no member home. See listBrains.
The brain tools only read. A brain document is an ordinary document: to change one, see Write a document in your member home.

Steps

The example question is: "What does the Northwind Advisory website say about discounts, and what is still missing from it?" The instance is your-sasha.example.com.

List the brains that this connection can see.

{}

{
  "brains": [
    {
      "id": "northwind-advisory/brains/business",
      "type": "business",
      "title": "Northwind Advisory",
      "blueprint": "business@1",
      "level": "sasha",
      "parent": null,
      "card": "northwind-advisory/brains/business/brain.md",
      "depth": [
        { "ring": "Public Context", "stage": "Scope", "documents": 4, "filled": 2, "checked": 1, "declined": 0, "outOfDate": 0, "missing": 2 }
      ]
    },
    {
      "id": "northwind-advisory/brains/website",
      "type": "site",
      "title": "Northwind Advisory website",
      "blueprint": "site@1",
      "level": "sasha",
      "parent": "northwind-advisory/brains/business",
      "card": "northwind-advisory/brains/website/brain.md",
      "depth": [
        { "ring": "Public Context", "stage": "Scope", "documents": 10, "filled": 2, "checked": 0, "declined": 0, "outOfDate": 0, "missing": 8 }
      ]
    }
  ],
  "truncated": false
}

This response shows only the first ring of each brain. Keep the id of the brain that matches the subject, here northwind-advisory/brains/website. An empty brains list means that no folder this person can read holds a brain.md card.

Learn what this kind of brain should hold. Use the blueprint value from step 1.
```
{ "type": "site@1" }
```
Each document in the result has its file, title, ring, deepens, outOfDateAfterDays and asks. Use asks to tell the person what a missing document should contain.
Open the brain's contents page.
```
{ "brain": "northwind-advisory/brains/website" }
```
documents gives each document with its state and a path. dropped gives the documents that the card drops, with the reason. For a missing document, parentCovers names the parent brain's filled or checked documents for the same domain. An empty parentCovers list means that the parent does not cover it either.
Search the brain and its parents for the subject.
```
{ "brain": "northwind-advisory/brains/website", "query": "discount", "includeParents": true }
```
searched lists the brains that the search covered, in order. Each result has the brain, the document title, the path, the line and a snippet. The search is a plain text match, not a semantic search.
Read the document before you state a fact. A snippet is one line. Pass the path as it is, with no project.
```
{ "path": "northwind-advisory/brains/website/offer.md" }
```
Give the answer with its source path. Then give the gaps: the documents with state missing, what each should contain (asks from step 2), and any parent document that covers the same domain (parentCovers from step 3). If a document from the site brain and a document from the parent brain say different things, tell the person, and give both paths.

Brains for the customers of a product

A product that runs one shared Sasha for many customer accounts can give each account its own brains:

Each customer account is one Sasha member. The member home is that account's folder, and the account's brains live inside it at level tenant.
The product calls Sasha with that member's own token. Each check is then the member's: the token reads that one home and the shared projects where the member holds a grant, and nothing else.
Another member's home reads as Not found. Admin and staff connections see no member home, so they cannot read a customer's brains over MCP.
Material that every customer may read, such as a product's house rules, goes in one shared project. Each member gets a read grant on it. A tenant brain can name a brain in that project as its parent.

What can go wrong

Error in getBrain: Not found or Error in searchBrain: Not found: there is no brain with this id that this person can read. The answer is the same whether the brain is hidden or does not exist. Use an id from listBrains.
Error in getBlueprint: Unknown blueprint. Call getBlueprint with no type for the list.: use a ref from getBlueprint with no arguments.
parent is null although the card names one: this person cannot read the parent brain, or it does not exist. searchBrain with includeParents then searches only the brain itself.
warnings and depth: null: the card names a blueprint that this release does not have. warnings also names add and drop entries that were skipped, and why.
truncated is true: listBrains returns at most 50 brains, and searchBrain at most 40 results. Name a project, or make the query narrower.
MCP error -32602: Tool listBrains not found: the connection does not hold knowledge:read. Read the permissions section of getDocs. Do not tell the person that Sasha has no brains.