# From an empty workspace to your first documents

**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.

1. **What bodies of knowledge do you have?** Runbooks, product manuals, sales
   material, internal policy. Each coherent body wants its own repo.
2. **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.
3. **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.