Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
docs: clean up the comments feature (#3549)
robert-inkeep854b0c45a1cd
diff --git a/docs/content/features/comments.mdx b/docs/content/features/comments.mdxindex 87c71dd35..bb191dfc3 100644--- a/docs/content/features/comments.mdx+++ b/docs/content/features/comments.mdx@@ -1,60 +1,51 @@---title: Commentsicon: LuMessageSquare-description: Mark up a document with review notes, then hand the batch to an agent to act on.+description: Annotate your knowledge base with comments and resolve them with your agent----Comments let you leave a note on any part of a document, then hand the batch of all your notes to an agent in one turn. The agent then addresses each comment.--For comments you want to keep *inside* the file — `<!-- … -->` or `%%…%%` — see [markdown comments](/docs/features/editor#markdown-comments).+<Callout type="info">+For comments you want to keep *inside* a markdown file using `<!-- … -->` or `%%…%%`, see [markdown comments](/docs/features/editor#markdown-comments).+</Callout>## Write a comment-Select text, a code block, or a diagram in the visual editor, then press `Cmd+Shift+M` or choose **Comment** — in the selection toolbar. Type your note and press Enter. The new comment is checked and added to the batch automatically.--Nothing is sent yet, so you can read through a whole project and leave all your notes instead of going back and forth with your agent one fix at a time.--## Review what is waiting+Select text, a code block, or a diagram, then press `Cmd+Shift+M` or click **Comment** in the selection toolbar.-Commented passages are highlighted in the document, with a marker in the right-hand margin; click either one to open the thread.+-The **Comments** tab in the document panel (`Cmd+Option+B`) lists them, with a **This doc** / **This project** switch. Each comment carries a checkbox saying whether it goes out in the next batch.+## Review and send-+Comments are highlighted in the document, and each open comment gets a <InlineIcon name="MessageSquare" /> marker in the right-hand margin. Click either one to open the comment in the document panel (`Cmd+Option+B`).-## Send comments to an agent+-Checked comments attach themselves to whatever you send next. A chip appears on the bottom **Ask AI** composer and on the composer in the right-side agent panel, so your next message carries the batch with it — and whatever you type becomes the instruction for it. The chip's ✕ takes the batch off that message without unchecking anything.+You can control which comments are sent to your agent by checking or unchecking them. Then click the send button or use `Cmd+Shift+Enter` while the Comments tab is open.-To send the batch on its own, press **Send to chat** in the Comments tab, or `Cmd+Shift+Enter` while that tab is open. On **This doc** that sends the open document's checked comments; on **This project**, all of them.--## Resolve, reopen, edit, delete--Sending a comment resolves it. If you are unhappy with the way the agent made edits or just want to reopen the comment, **Reopen** puts the comment back in the list and adds it to the next batch.--**Edit** revises the note — a comment can be rewritten, but a thread holds one comment rather than a back-and-forth, so an edit replaces what was there. **Delete** is the way out of a comment you decided against.+<Callout type="info">+If the text a comment points to is deleted or rewritten enough that OpenKnowledge can no longer find it, the comment becomes orphaned. The comment is still there, but it is no longer attached to live text in the document. If you send it to your agent, it includes the original quote for context. To reattach it, select the new text in your document and click **Re-place on selected text**.+</Callout>-## When the commented text changes+## Resolve and reopen-A comment remembers the *words* it was left on rather than a position in the file, so it stays with its passage as the document is edited around it — including edits an agent makes while working through your batch.+After comments are sent to an agent, they are marked as resolved. To see resolved comments again, use the **Show resolved** control in the Comments tab.-If the passage is deleted outright, the comment is marked orphaned: its card strikes through the old quote and offers **Re-place on selected text**, which re-attaches it wherever you select next.+-An orphaned comment still sends. The instruction tells the agent that the original text is gone and not to apply the note to some other occurrence — a comment the agent asks you about is better than one it silently applies in the wrong place.+If you are unhappy with the way the agent made edits, or just want to reopen a comment, **Reopen** puts it back in the unresolved state so you can send it to an agent again.-## How agents see comments+## Agent access to comments-Two ways, and you only drive one of them:+Agents can view unresolved comments when they read a file via MCP. Each comment includes the note along with the passage it refers to.-- **You send them.** The batch above.-- **They read them.** An agent working through the [MCP server](/docs/reference/mcp) sees unresolved comments on a document: a count when it lists files, and the notes themselves — with their quoted passages — when it reads one. An agent picking up a document can act on outstanding review notes without you sending anything.+When an agent lists files, it can also see how many unresolved comments each file has.-## Where comments are stored+## Comments are local-Comments live in `.ok/local/comments/`, one JSON file each, alongside the rest of your machine-local runtime state. See [what OpenKnowledge writes](/docs/reference/what-open-knowledge-writes).+Comments stay local to the machine that created them. They are not committed and not pushed, so they are not visible to your team members.<Callout type="info">-That directory is gitignored, so comments stay on the machine that wrote them. They are not committed and not pushed, and a teammate who clones the project sees none of them. Comments are notes to your own agent, not a review thread you share.+Comments are stored in `.ok/local/comments/`. Read more on [what OpenKnowledge writes to your system](/docs/reference/what-open-knowledge-writes).</Callout>## See alsodiff --git a/docs/public/screenshots/show-resolved-comments.png b/docs/public/screenshots/show-resolved-comments.pngnew file mode 100644index 000000000..66fc68d89Binary files /dev/null and b/docs/public/screenshots/show-resolved-comments.png differdiff --git a/docs/public/screenshots/write-comment.gif b/docs/public/screenshots/write-comment.gifnew file mode 100644index 000000000..cffc003e3Binary files /dev/null and b/docs/public/screenshots/write-comment.gif differdiff --git a/docs/src/mdx-components.tsx b/docs/src/mdx-components.tsxindex fe911a2af..7d5b45947 100644--- a/docs/src/mdx-components.tsx+++ b/docs/src/mdx-components.tsx@@ -4,6 +4,7 @@ import { ImageZoom } from 'fumadocs-ui/components/image-zoom';import { Step, Steps } from 'fumadocs-ui/components/steps';import { TypeTable } from 'fumadocs-ui/components/type-table';import defaultMdxComponents from 'fumadocs-ui/mdx';+import { icons } from 'lucide-react';import type { MDXComponents } from 'mdx/types';import { AgentIcons } from '@/components/agent-icons';import { ComponentPreview } from '@/components/component-preview';@@ -30,6 +31,17 @@ import { TabPreview, TabsPreview } from '@/components/previews/tabs-preview';import { Tab, Tabs } from '@/components/tabs';import { VerifyExec } from '@/components/verify-exec';+function InlineIcon({ name, label }: { name: keyof typeof icons; label?: string }) {+ const Icon = icons[name];+ return (+ <Icon+ aria-label={label}+ aria-hidden={label ? undefined : true}+ className="-mt-0.5 inline size-4 align-middle text-amber-500"+ />+ );+}+export function getMDXComponents(components?: MDXComponents): MDXComponents {return {...defaultMdxComponents,@@ -50,6 +62,7 @@ export function getMDXComponents(components?: MDXComponents): MDXComponents {HtmlPreview,Image: ImageZoom,ImgPreview,+ InlineIcon,LayerStack,MathPreview,McpInstall,