> ## Documentation Index
> Fetch the complete documentation index at: https://craftspace.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Brain as Code

> A repository's own brain folder, synced with a space.

Context that describes a codebase belongs next to it. Brain as Code binds a repository to a space: the
folder tree in the repo **is** the page tree in the app.

```
brain/knowledge/
├── index.md                 the space's own front page
├── engineering/
│   ├── index.md             the page for "engineering"
│   └── coding-style.md      a child of that page
└── decisions/
    └── 000042-a-claim.md    one hard-to-reverse call
```

`<area>/index.md` is the page for that area, and a leaf file beside it is that page's child. Frontmatter
carries `title`, `icon` and, for decisions, `status`.

## Which direction writes go

A repo-backed page syncs **one way**, from the repo into the app. That is on purpose: a file rides a pull
request and gets reviewed, while a write straight from an agent lands on the default branch and skips
review.

<Note>
  In a repo that has a local `brain/` folder, an agent should write a markdown **file** rather than calling
  `upsert_page`. The file is the reviewable artifact. The MCP write is for repos that have no brain folder
  of their own.
</Note>

## Setting it up

Register a GitHub App in [server settings](/self-hosting/server-settings), install it on the account that
owns the repositories, then connect a repo from the app. Connecting opens a setup pull request rather than
committing to your default branch.

## Gotchas

* **The repo picker is keyed to one GitHub owner per organisation.** Disconnect the old owner's
  repositories before switching accounts.
* **Transferring a connected repo to another GitHub owner deletes its installation.** An installation is
  scoped to one account, so the repo leaving that account revokes it. The binding then goes stale
  silently: nothing errors, and the setup card stays green. Repointing is install on the new owner, then
  disconnect and re-add.
* **`contents: write` does not cover `.github/workflows/`.** That is a separate app permission, and
  granting it takes two steps: flip it on the app, then have each installing organisation accept the
  request. Nothing takes effect until that accept, and a run already in flight keeps its old token.