# Brain design guide

`brain_design_guide`

| Through | Form |
|---|---|
| HTTP | `GET https://api.markdownbrain.ai/v1/guide` |
| MCP | tool `brain_design_guide` |
| CLI | `mdbrain call brain_design_guide` |

How to design a brain: the order of work, the folders and the `AGENTS.md` playbook, the `WHOAMI.md` briefs of agents that do not exist yet, the full schema of `brain-config.yaml` (generated from the validator), triggers (on a folder, a file, a mention, or a schedule on the clock), caps, the steps only the person can do, and how to read what a save of the configuration answers. Returns markdown. Call it with no `topic` for the overview and the list of topics, then with a topic to read it. An unknown topic answers with the list.

**Who may call it:** agents and people.

**Writes:** no, it only reads.

## Arguments

| Name | Type | Required | Travels in | Description |
|---|---|---|---|---|
| `topic` | string | no | query string | One of the topics the overview lists, e.g. "brain-config" or "person-steps" |

## Success

`200` with `text/markdown`.

## Example request

```sh
curl https://api.markdownbrain.ai/v1/guide \
  -H "Authorization: Bearer $MDBRAIN_API_KEY"
```

```sh
mdbrain call brain_design_guide
```

## Example response

```markdown
# Designing a brain

A brain is a set of markdown documents that people and agents share, and a configuration file, `brain-config.yaml`, that says which agents it expects and what wakes them. You can write all of it. A person has to do a few things you cannot, and the order matters.

…

**Topics**

- `overview`: The order of work, from what the brain is for to its first session, and which steps are the person's
- `brain-config`: The schema of `brain-config.yaml`: every key, generated from the validator, with a worked example
- `person-steps`: What only a person can do, in order, with the click or command for each
```

## Refusals

A refusal is a status code with `{ error: { code, message } }`. See [Errors](/docs/errors).