Go from an empty workspace to your first documents

Hand this whole page to your agent. Copy it from your Blenau dashboard and it arrives with your workspace’s repos already in it; blenau playbooks install first-repo-first-document writes it straight into your agent’s instructions folder; or an agent connected over MCP can fetch it itself with get_playbook("first-repo-first-document").

Download the raw Markdown

Give this whole file to your agent. It covers the one stretch where a new Blenau workspace usually stalls: the credential works, the agent is connected, and the brain is still empty.

Your workspace’s own values are not filled in here. Copy this playbook from your Blenau dashboard (or blenau playbooks get <id>) and it arrives with your workspace slug and your connected repos already in it. Ask your agent to run list_repos first if you are working from this generic copy.

The model you are working inside

A document lives in a GitHub repo and is mirrored into a searchable index. GitHub holds the content; Blenau never flattens what you wrote.
Grouping is by path, not by folders-as-entities. A shared prefix is the folder. acme/handbook/onboarding.md sits “inside” acme/handbook/ because of its name and nothing else.
Every connected repo is mapped to a path prefix. A document whose path starts with that prefix is committed to that repo. That mapping is the whole routing rule.
Write scope is per-group and per-path. An agent can only connect a repo at a prefix inside its own allowed paths.

Step 1 — Decide the shape before creating anything

Ask the human these three questions and wait for answers. Guessing here is the one mistake that is expensive to undo, because moving a prefix later means moving every document under it.

What bodies of knowledge do you have? Runbooks, product manuals, sales material, internal policy. Each coherent body wants its own repo.
Do any of them have a different audience? This is the question people forget. Two topics that feel adjacent can have completely different access lists — and access in Blenau is granted per path prefix, so a body of knowledge that not everyone may read has to sit under its own prefix from day one. Retrofitting that means moving documents.
Who writes them? If two teams write into the same body, they will need a group with write access to that prefix.

Propose a layout back, in one table: repo → path prefix → what goes in it → who reads it. Get an explicit OK before creating anything.

One repo per body of knowledge. A single catch-all repo is tempting and it is a drawer: everything lands in it, nothing can be scoped separately, and splitting it later is a migration.

Step 2 — Connect the repo

connect_repo(repo, path_prefix, installation_id).

repo is org/name of a repo the Blenau GitHub App can already reach. If it cannot, the call fails with an actionable error — Blenau cannot grant its own App access, so installing or extending the App is a human step.
path_prefix is where this repo’s documents live in the brain, e.g. acme/handbook/. It must fall inside your allowed paths. A trailing / is added if you omit it.
An empty repo is fine. Connecting queues an initial sync; if the repo already has Markdown in it, it becomes searchable without any further call.

Confirm with list_repos before writing.

Step 3 — Put real knowledge in, in the right order

Start with what people ask each other most often, not with what is easiest to export. The brain earns its keep the first time somebody’s question is answered out of it.

Three ways in, in increasing order of effort:

crystallize_session — the cheapest first document. Point it at a piece of work you just finished and it writes up what was learned, with provenance. It is the natural way for an agent to leave behind what it discovered.
ingest_document(path, title, content, source_type, sources) — a document you already have. The path must start with a connected prefix.
A bulk migration of an existing manual or export — that has its own playbook, migrate-markdown-export. If you have hundreds of pages with images, use it instead of doing this by hand.

Always search before writing — search_knowledge on the topic first. A new file where one already exists fragments the knowledge and degrades every future search. If something close exists, edit it (edit_section, patch_section) rather than adding a second document about the same thing.

Record where it came from. Pass sources=[…] on every ingest: a URL, a ticket, a team. Provenance is what separates a brain from a folder — it is how the next reader knows whether to trust an answer, and how anyone audits it later. An unsourced document is not a smaller document, it is a weaker one.

Step 4 — Verify, do not assume

ingest_document returns status: "queued" and a task_id. The document is already saved — written and committed — but indexing runs in a background worker, so it becomes findable a few seconds later. Use ingest_status(task_id) only if your very next step depends on searching for it.
Read applied and content_advice in the response. They tell you whether the content landed intact and whether it declared its sources. They are advice, never a block.
list_documents should show everything as ready.
Then the real test: search_knowledge with a question a colleague would actually ask, and check that the answer comes back with the right document.

Step 5 — Make it somebody else’s brain too

A brain with one writer is a notes app. Two follow-ups worth doing in the same sitting:

Invite the people who write this knowledge, and put them in a group scoped to the prefix they own.
Run brain_health once there is content. It reports structural damage, missing provenance and drift between GitHub and the index, grouped by casuistry, with the procedure for each. Fresh content usually comes back clean — and knowing it is clean now is what makes a later finding meaningful.