How Blenau and GitHub stay in sync

Editing a repo-backed document writes to your repo. Every agent edit is a real commit on your synced branch — not a hidden draft. That’s the point: your knowledge stays in git, where you can diff it, review it, and revert it.

GitHub is authoritative

The Markdown files in your connected repos are the source of truth. Blenau builds a search index (sections + embeddings) on top of them. That index is a projection of your files — it exists to make your knowledge searchable, not to replace your repo.

What happens when an agent edits

1. The agent calls edit_section.
2. Blenau reconstructs the document and commits it to your repo — before it updates its own index. A failed commit never leaves a Blenau-only “ghost” doc.
3. Blenau re-indexes from the committed file.

So an agent edit is a commit you can see in your git history, attributable and reversible. There is no separate “Blenau copy” to drift — the commit is the change.

What happens when you push

A push to the synced branch re-indexes the file and overwrites any agent edits made to it since. GitHub wins. If agents have been writing, git pull before you push.

Recovering from a bad edit

Your git history is the undo button:

git log -- path/to/doc.md      # see every change, with author
git revert <sha>               # undo an edit; Blenau re-indexes on the next sync

Recommended setups

• Dedicated knowledge repo — cleanest; agent commits don’t mix with your code.
• Subdirectory of an existing repo — good when the docs live next to the code.
• Review gate — point Blenau at a branch that requires PRs if you want a human in the loop; agents commit to that branch and you merge.

See Limits & known behaviors for current branch handling.