Roam Research Docs · Help & user documentation

roam/agent guidelines

Guidelines for AI agents working on this graph, Roam's public help documentation. Real users read every word. Follow these for every read and write.

Work page by page. A human reviews everything: write, then let them edit and cull.
When rewriting an existing page, append new sections at the bottom and let the human delete the old content. Never delete or reword content you didn't write unless asked.
Re-read a page before editing it; it may have changed since you last saw it.
When replacing old content, every fact the old version conveyed must be either carried forward or deliberately dropped as wrong. Say which.
Verify every claim against the product's source code before writing it. Never document from memory, and never trust the old docs' claims without checking.
If you have access to the relemma codebase: the full audit and fix plan lives at generated-docs/help-graph-audit-2026-07.md. Read it before starting doc work, and check items off there as they land.

No "What is it?" section. The intro is 2-3 plain bullets directly under the page title (the title is the question). Then sections like How to use it and Good to know.
One idea per block. Separate blocks are good.
Steps: a title block with one action per child bullet. Never pack several actions into one block.
Group by topic: don't interleave two topics (e.g. browsing shortcuts vs changing them) in one run of bullets.
One home per fact: don't say the same thing twice in different phrasings.

Hotkeys: the command name as a bold parent block, with Mac: and PC: sub-bullets when the keys differ. When the keys are the same on both platforms, one block with the keys inline.
Syntax references (query clauses and similar): the syntax in code as the parent block, the explanation nested underneath.
Tips go in callouts: [[>]] [[!TIP]].
Keep example syntax inside backticks so [[links]] in examples don't create real pages. If a stray page gets created, delete it.
When an example needs an outline shape, write it as real nested blocks, with each example line's text in a code span.

Link mentions of other help pages, but don't over-link. No links on incidental words (Mac, PC), and avoid linking to empty pages.
Alias links so names read naturally, e.g. [TODO]([[TODO/DONE]]) renders as the command name while linking the right page.
Every new page ships with at least one natural inbound link. Nothing orphaned.
Prefer a plain [[Page Title]] link where the page comes up, reshaping the sentence to fit the title ("A Hosted Graph is synchronized…") over appending "see Hosted Graph" at the end. Use a markdown alias ([TODO]([[TODO/DONE]])) only when the visible text must differ from the page title, like command names.

Prefer live components over screenshots: a real {{[[table]]}} or {{[[query]]}} the reader can poke at beats an image. Tell public readers their edits aren't saved, so they can play freely.
For screenshots and GIFs, leave placeholder blocks for a human to record: 📷 **Screenshot:** __what it should show__. Use GIFs sparingly: at most one per page, only for genuinely multi-step interactions.
Reuse images and videos that already exist in this graph (Change Log entries are a good source). Put the file link or video component directly on the page.

Plain, simple language. Explain mechanisms so a non-programmer can follow: "nested blocks inherit references", not implementation jargon.
Skip implementation details that confuse more than they help (e.g. desktop-shell updates vs web-app updates).
No false, unverifiable, or aspirational claims. If the product can't do something, say so plainly.
Page titles match the product's own terminology.
No em-dashes (—). Use commas, colons, parentheses, a new sentence, or a separate block instead.