Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
comments docs (#3482)
shagun-singh-inkeep7e30c53c3b1f
diff --git a/docs/content/features/comments.mdx b/docs/content/features/comments.mdxnew file mode 100644index 000000000..87c71dd35--- /dev/null+++ b/docs/content/features/comments.mdx@@ -0,0 +1,63 @@+---+title: Comments+icon: LuMessageSquare+description: Mark up a document with review notes, then hand the batch to an agent to act on.+---++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).++## 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++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.++++## 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.++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.++## When the commented text changes++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.++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.++## How agents see comments++Two ways, and you only drive one of them:++- **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.++## Where comments are stored++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).++<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.+</Callout>++## See also++- [Editor](/docs/features/editor) — the selection toolbar, the Properties panel, and the rest of the editing surface.+- [Agent activity](/docs/features/agent-activity) — reviewing what the agent changed after it acts on your comments.diff --git a/docs/content/features/editor.mdx b/docs/content/features/editor.mdxindex 247cb1f7a..e08f2b312 100644--- a/docs/content/features/editor.mdx+++ b/docs/content/features/editor.mdx@@ -42,9 +42,9 @@ An `html preview` code fence renders its contents live in a sandboxed iframe ins`Cmd+U`, or the Underline button in the selection bubble menu, underlines the selection. Markdown has no underline syntax of its own, so it saves as inline HTML: `<u>underlined</u>`. `<ins>…</ins>` — what Joplin and Logseq write — is read as underline too, whether it arrives on the clipboard or is already sitting in a file you open, and each file keeps the spelling it arrived with instead of being rewritten under you. Both underline in OpenKnowledge and in any renderer that passes inline HTML through. GitHub is the exception worth knowing: it renders `<ins>` underlined but strips `<u>` back to plain text, so the words survive and the underline doesn't.-### Comments+### Markdown Comments-Notes to yourself and to your agents that stay in the file and out of what a reader sees. OpenKnowledge reads two syntaxes. There's no button or shortcut for either — you type them, inline inside a paragraph or as a standalone block spanning several lines:+Notes that stay in the file and out of what a reader sees. (For review comments attached to a passage from outside the file, and sent to an agent as a batch, see [Comments](/docs/features/comments).) OpenKnowledge reads two syntaxes. There's no button or shortcut for either — you type them, inline inside a paragraph or as a standalone block spanning several lines:| Syntax | Hidden from readers in || --- | --- |@@ -98,11 +98,7 @@ The composer stays out of the way where it doesn't belong: it's hidden inside an### From a text selection-Select text in the WYSIWYG editor and the selection bubble menu shows an **Ask AI** button (Sparkles icon) alongside the formatting controls. Clicking it — or pressing `Cmd+Shift+I` (macOS only; that chord is the DevTools shortcut elsewhere) — opens and focuses the bottom Ask AI composer with the selected passage pinned as a removable context pill, so the exact text rides along as context. Type your instruction, pick an agent, and send. While the docked terminal is open, the button sends the selection into the active shell session instead. (Selecting an image or other non-text node doesn't show the affordance.)--### From a code block--Hovering a code block reveals a toolbar above it with its own **Ask AI** button (Sparkles icon). Clicking it sends the whole fenced block — info string and body — into the docked terminal's active shell session; with no terminal open, it opens and focuses the bottom Ask AI composer.+Select text in the WYSIWYG editor and the selection bubble menu shows a **Comment** button (Sparkles icon) alongside the formatting controls. Clicking it — or pressing `Cmd+Shift+M` — opens a composer on the selection. What you write there is a [comment](/docs/features/comments): it goes into the project's comment queue rather than to an agent, and you hand a batch of comments over as a separate, deliberate step from the **Comments** tab.## Terminal@@ -255,6 +251,8 @@ Keyboard shortcuts (use `Ctrl` on Windows / Linux in place of `Cmd`, unless the| `Cmd+Shift+J` | Open an additional terminal tab (macOS desktop app). With text selected, stages the passage into the new tab's AI CLI input. || `Cmd+P` | Open the [command palette](#command-palette) from anywhere — unlike `Cmd+K`, it opens the palette even while text is selected in the visual editor. || `Cmd+L` | Open and focus the [Ask AI](#ask-ai) composer (desktop app). |+| `Cmd+Shift+M` | [Comment](/docs/features/comments) on the selected text (visual editor). |+| `Cmd+Shift+Enter` | Send the checked comments the open **Comments** tab is showing to an agent. Does nothing while that tab is closed. || `Cmd+F` | Find in the visual editor. || `Cmd+Option+F` | Find and replace (`Ctrl+H` on Windows / Linux). || `Cmd+G` / `Shift+Cmd+G` | Next / previous find match. |diff --git a/docs/content/features/meta.json b/docs/content/features/meta.jsonindex f84c518cf..e89fd6ae5 100644--- a/docs/content/features/meta.json+++ b/docs/content/features/meta.json@@ -3,6 +3,7 @@"icon": "LuSparkles","pages": ["editor",+ "comments","assets-and-embeds","ignore-patterns","timeline-and-recovery",diff --git a/docs/content/reference/mcp.mdx b/docs/content/reference/mcp.mdxindex e41730c91..3c867b3b2 100644--- a/docs/content/reference/mcp.mdx+++ b/docs/content/reference/mcp.mdx@@ -16,7 +16,7 @@ To point an MCP client at this server, locally or over a tunnel from another mac| Tool | Purpose || --- | --- |-| `exec` | Read-only shell (`cat`, `ls`, `grep`, `find`, `head`, `tail`, `wc`, `sort`, `uniq`, `cut`); reads return frontmatter, backlinks, and recent history. When the [frontmatter schemas](/docs/advanced/content-rules/frontmatter) plugin is on, doc and folder entries also carry `schemas: …` naming the JSON Schema files that govern them — the contract to read before writing. Fs-direct; works without the server. |+| `exec` | Read-only shell (`cat`, `ls`, `grep`, `find`, `head`, `tail`, `wc`, `sort`, `uniq`, `cut`); reads return frontmatter, backlinks, recent history, and any unresolved [comments](/docs/features/comments) left on the doc. When the [frontmatter schemas](/docs/advanced/content-rules/frontmatter) plugin is on, doc and folder entries also carry `schemas: …` naming the JSON Schema files that govern them — the contract to read before writing. Fs-direct; works without the server. || `search` | Ranked workspace search (title boost + body BM25 + recency; same engine the cmd-K palette uses). `intent: "omnibar"` narrows to fast title/path matching (`full_text`, the default, includes the body); `scopes` filters hit kinds; `limit` caps rows (default 20, max 100). When [semantic search](/docs/reference/configuration#semantic-search) is enabled, an embeddings signal is additionally fused into `full_text` ranking (opt-in, content egress) — pass `semantic: false` to force pure-lexical. Right after boot, an empty result set with `ready: false` means the index is still building — retry after a couple of seconds rather than treating it as no matches. || `links` | Wiki-link graph. `kind` selects: `backlinks`, `forward`, `dead`, `orphans`, `hubs`, or `suggest`. Accepts an array (e.g. `["dead", "orphans", "hubs"]`) to fetch several views in one call; each view nests under its own key in the response || `lint` | Report content-rule problems (markdownlint style rules + frontmatter schema validation) for one `document` or a whole-project audit (`path` scopes it); each finding carries `source`/`code`/`message`/`range`/`severity`, audit capped at 10 files × 10 diagnostics with accurate totals; configuration problems (e.g. a broken schema file) ride a separate `warnings` channel. Pass `fix: true` with `document` to auto-fix fixable rules in place — the fix lands through the collaborative document (attributed, live preview), not a shell edit; the rest need `edit`/`write`. Example output: [content rules overview](/docs/advanced/content-rules/overview#ai-agents) |diff --git a/docs/content/reference/what-open-knowledge-writes.mdx b/docs/content/reference/what-open-knowledge-writes.mdxindex 8bd28dee8..393ce9f81 100644--- a/docs/content/reference/what-open-knowledge-writes.mdx+++ b/docs/content/reference/what-open-knowledge-writes.mdx@@ -113,6 +113,7 @@ The app runs a collaboration server for the open project. It writes runtime stat| `.ok/local/logs/server-*.jsonl` | Local server logs, rotated at ~25 MB | In-project, gitignored || `.ok/local/cache/<branch>/backlinks.json` | Backlink-graph cache | In-project, gitignored || `.ok/local/installed-skills.json` | Per-project skill-install markers (which editors each skill is projected into) | In-project, gitignored |+| `.ok/local/comments/` | [Comments](/docs/features/comments) left on documents, one JSON file each — the note, the passage it quotes, and whether it has been sent | In-project, gitignored || `.ok/worktrees/<branch>/` | Git worktree checkout created when you open a branch in its own window (project switcher); the path is also added to `.git/info/exclude` | In-project, gitignored || `.git/ok/` — or `.git/worktrees/<name>/ok/` in a linked worktree, or the enclosing repo's `.git/ok-<slug>/` when your project is a subfolder of a larger repo | Shadow git repo holding per-writer work-in-progress refs; always inside a git admin dir, never in your content tree | In-project, gitignored (inside `.git/`) |@@ -227,6 +228,7 @@ On Windows, Claude Desktop and OpenCode configs live under `%APPDATA%\Claude\` a| `.ok/local/logs/server-*.jsonl` | Local server logs, rotated at ~25 MB | In-project, gitignored || `.ok/local/cache/<branch>/backlinks.json` | Backlink-graph cache | In-project, gitignored || `.ok/local/installed-skills.json` | Per-project skill-install markers (which editors each skill is projected into) | In-project, gitignored |+| `.ok/local/comments/` | [Comments](/docs/features/comments) left on documents, one JSON file each — the note, the passage it quotes, and whether it has been sent | In-project, gitignored || `.git/ok/` — or `.git/worktrees/<name>/ok/` in a linked worktree, or the enclosing repo's `.git/ok-<slug>/` when your project is a subfolder of a larger repo | Shadow git repo holding per-writer work-in-progress refs (powers the timeline); always inside a git admin dir, never in your content tree | In-project, gitignored (inside `.git/`) |Diagnostic logs and telemetry are **on by default but local-only** — credential-bearing attributes are redacted (`[REDACTED]`) before anything is written, the files rotate at the size caps above, and nothing leaves the machine until you explicitly run `ok diagnose bundle`. Turn the local sink off with `telemetry.localSink.enabled: false`; see [Configuration](./configuration.mdx).diff --git a/docs/public/screenshots/comments.png b/docs/public/screenshots/comments.pngnew file mode 100644index 000000000..babae9775Binary files /dev/null and b/docs/public/screenshots/comments.png differ