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 an MCP server of its own. If what you want is a place for the pages to live, all three work, and I would not talk you out of any of them.
What none of them gives you is the link.
I checked this properly for Notion before writing it down, because it decides the argument. Notion's API cannot publish a page. The page object carries a public_url, but it is read-only: it tells you whether a person has published the page. The update endpoint takes properties, an icon, a cover, a lock and the trash, and nothing about sharing. None of the tools on its MCP server publishes either. So the agent writes the page, and then a person opens Notion, finds the page, and clicks Share, then Publish, then Publish again, because Notion wants to be sure. Every page, every time. I do not think that is an oversight. Notion has invested heavily in being written to and built nothing for publishing out. Inbound is a product; outbound is a click, and the click is yours.
Obsidian's notes are files on your disk, and putting them on the web is a separate paid service. Confluence can make a page public, but only after an administrator turns on anonymous access for the space, which is a conversation with an administrator, and you already know how that ends.
🔗 A link service
gh gist create plan.md prints a link. There are a dozen small tools that do the same thing for Markdown: paste or upload, get a URL. They are fast, and they are honest about what they are.
What they are not is a home. A gist is a copy of the file at the moment you made it. When the agent revises the plan, the copy does not know, and you are now keeping a list of gist ids to update. After a month you have forty links and the GitHub gist list to find them in. The link was the point, and the link works. The pile is still a pile; it just has URLs now.
📦 Both at once
What I wanted was the notes app and the link from one command, with the link still right after a revision. That is what Sumibako does, and it is the whole reason it exists in this form.
The page lands in your vault, under a page called Agent notes, with an icon the agent chose, and the command prints a public link. The file's path is the key: publish the same file again after a revision and it updates the same page, so the link keeps pointing at the current version. The last twenty versions the agent overwrote are kept for two weeks, in case it revised something you wanted back, which it will.
From Claude.ai or ChatGPT, where there is no terminal, the same thing is a connector: add one address, sign in, and "save this to my notes and give me a link" does what it says. That is its own post, next week.
NOTE
Everything the command and the connector can do is on the agents page, and what the free plan holds is on the pricing page.
📏 The rule
| The document | Where it goes |
|---|---|
| Reviewed with code, by people who have the repo | The repository, in a draft PR |
| Read once, by someone who has the link, never revised | A gist |
| Read by anyone outside the repo, or revised after it is sent | A page in your notes, with a link |
| Not about one repository at all | A page in your notes |
The trigger is the second reader. If nobody but you and the agent will ever read the plan, the folder in the repo is fine and you should not add a tool, mine included. The moment someone who cannot open the repo needs it, you want the version of the document that is in your notes and has an address. Preferably before they ask twice.