Roam Research Docs · Help & user documentation

roam/agent guidelines

markdown version · view in Roam Research

• 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.

Process

• 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 ai_scratchpad/help-graph-audit-2026-07.md. Read it before starting doc work, and check items off there as they land.

Page structure

• 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.

Formatting patterns

• 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.
• When an example needs an outline shape, write it as real nested blocks, with each example line's text in a code span.

Links

• 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.

Media

• 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.

Language & accuracy

• 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.
• Tone: conversational and friendly. Write to "you", explain why things matter, keep the warmth.
• But don't polish every bullet to the same rhythm. It's fine for a bullet to state a fact plainly and stop.
• Explaining why is part of the job. Mechanisms, consequences, and non-obvious benefits belong in the docs ("sorting reorders the blocks for everyone" is exactly what to say). What to skip is restating a benefit the reader already got: "handy once the graphs pile up" adds nothing to "the search box filters your list".
• Watch for other AI habits: three-item lists everywhere, and a charming aside on every page. Ration personality to about one moment per page, and vary list lengths.
• No rhetorical-question asides ("Reading this on the help graph? Your edits aren't saved, so play freely."). Say it straight: "Edits here aren't saved."
• Friendly means relaxed and natural, not clever. Write full sentences with a subject, attach the reason to the fact with "so" or "because", and prefer an invitation over a bare command.
• The voice, by example. Three drafts of the same block:
  • Too AI: "Try it on a classic: Doug Engelbart's 1962 Augmenting Human Intellect, the paper that imagined tools like this one. Select some text and make a highlight. (Reading this on the help graph? Your edits aren't saved, so play freely.)" The tells: a setup colon, a winking appositive, a rhetorical-question aside.
  • Overcorrected: "Highlight something. Edits here aren't saved." Clipped imperatives read cold, even aggressive.
  • Right: "Try it on this copy of Doug Engelbart's 1962 paper, Augmenting Human Intellect. Highlights you make here aren't saved, so feel free to experiment." Plain sentences, the interesting fact stated rather than sold, and the warmth comes from a natural invitation.