Where should the pages your agent writes go

Every day an agent writes something that is not code. A plan before the work, a handoff note after it, a decision record, a research summary, a checklist for a migration. A few weeks into working this way I had dozens of them, and they were in four places: a docs folder in each repo, the terminal scrollback, the chat history of whichever tool wrote them, and, for the ones I had really meant to keep, a Notion page I had pasted in by hand, like it was 2019.

This is about where they should go. Three kinds of home, what each is good at, and the rule I use now. I built the fourth section, so calibrate accordingly.

🗂️ The repository

docs/plans/, docs/decisions/, docs/handoff/. The agent writes a file, the file goes into the branch, and it is reviewed with the diff it explains.

This is the right home for anything a reviewer reads alongside code. The plan for a change belongs next to the change. A decision record about a schema belongs in the repo that has the schema. It is free, it is versioned, and it is already there, which is why most of my agent-written documents still live in one, and I am not going to pretend otherwise.

Where it stops: the reader without repository access. A client who wants to know what the next two weeks look like. A manager who asked for the write-up. A designer, a contractor on the other repo, your own future self on a phone in a queue. GitHub answers all of them with a sign-in page. And the documents that are not about one repository at all, the research summary and the weekly notes, have nowhere to sit, so they end up in whichever repo happened to be open at the time.

📓 A notes app or wiki the agent can write into

The obvious answer, and in 2026 the write path into most of them is good.

Notion takes Markdown through its API and runs an MCP server that any agent can connect to. Obsidian's vault is plain files, so any agent that can write a file can write a note. Confluence has