<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.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.Setting it up
Register a GitHub App in 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: writedoes 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.