# Documents

Have an agent write an RFC, a report or notes, refine it with it, and step through every version.

You will often want an agent to write down something you can review outside the codebase. For instance, you may want an agent to write an RFC first, so that you can review it and fix its approach.

Komrad supports this natively. Its _documents_ are markdown files that an agent writes, and each belongs to that agent’s task. Komrad stores each one in its database as one of the types you define. Komrad ships with one type, RFC. A type’s context tells agents how to write it. You add or edit types from the documents view, where the [menu](https://komrad.dev/latest/guides/navigation.md#the-menu) over a type defines a new one with [`c`](https://komrad.dev/latest/config.md#keybindings.document_types_menu.new) and edits it with [`e`](https://komrad.dev/latest/config.md#keybindings.document_types_menu.edit). Komrad versions these documents, so you can step through their history.

## Agent-authored documents

Agents write documents with komrad’s tools, so you ask for one in the prompt. Once the agent has written one, open its task’s [menu](https://komrad.dev/latest/guides/navigation.md#the-menu) with [`space`](https://komrad.dev/latest/config.md#keybindings.menu.open) and pick documents with [`D`](https://komrad.dev/latest/config.md#keybindings.menu.documents). The documents view opens on the task’s documents.

[Video: Starting a task in the neovim workflow with a brief to write an RFC called truncate-rfc, then opening the task's documents once its agent has written it.](https://komrad.dev/media/documents-ask.mp4)

Other agents can read a document too. You can, for instance, have an orchestrator write an RFC and have another agent implement it.

Once the document says what you want, tell the agent to build it. It already has the document, so the prompt can be as short as “carry out truncate-rfc”. The document stays with the task, so later you can read it beside the diff and check that what was built is what you agreed on.

## Editing a document

Open the menu on a document with [`space`](https://komrad.dev/latest/config.md#keybindings.menu.open) and pick edit with [`e`](https://komrad.dev/latest/config.md#keybindings.document_menu.edit) to open it in your editor. When you quit, what you wrote is saved as the next version.

[Video: Opening the truncate-rfc document in Neovim beside the list, adding a line about one more test case, and quitting to see the document drawn again with the new line.](https://komrad.dev/media/documents-edit.mp4)

Komrad mails the agent when you change its document, and the agent can see exactly what you changed.

You can also start a document yourself from the same menu with [`c`](https://komrad.dev/latest/config.md#keybindings.document_menu.new), such as a plan you wrote or notes the agent should keep in mind. The new document goes to the agent the filter names with `agent:`, and to that agent’s task. Komrad tells the agent it exists.

To delete a document, pick delete from the same menu with [`d`](https://komrad.dev/latest/config.md#keybindings.document_menu.delete) and confirm. Komrad deletes every version of it. To delete several documents together, choose them with [visual selection](https://komrad.dev/latest/guides/navigation.md#visual-selection) first and pick delete all from the menu.

## Stepping through versions

You can step back through a document’s versions. Each step shows what that version changed, who wrote it, and when. After a round or two you see the agent’s first proposal, your changes, and the agent’s answer.

[Video: Stepping back through the truncate-rfc document: the agent's revision, the person's edit before it, and the first draft, each drawn as a diff, then stepping forward to the document as it stands.](https://komrad.dev/media/documents-history.mp4)

## Filtering documents

Press `/` on the documents view to filter it. Plain words match the document’s name, and these qualifiers narrow it further.

| Qualifier | Keeps the documents |
| --- | --- |
| `agent:NAME` | written by an agent whose name contains NAME |
| `task:NAME` | on a task whose slug contains NAME |
| `workflow:NAME` | written by an agent in a workflow whose name contains NAME |
| `type:NAME` | of the type NAME |
| `since:WHEN` | changed at or after WHEN, such as `2d` or `2026-10-01` |
| `until:WHEN` | changed up to WHEN, a day counting in full |
| `says:TEXT` | whose text contains TEXT |

Quote a name that holds a space.
