Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
Correct OpenKnowledge docs against source and fix seeded pack copy (#2454)
Nick Gomez49dbb1206a4a
diff --git a/.changeset/pack-copy-and-cli-help-corrections.md b/.changeset/pack-copy-and-cli-help-corrections.mdnew file mode 100644index 000000000..b4199d8c0--- /dev/null+++ b/.changeset/pack-copy-and-cli-help-corrections.md@@ -0,0 +1,21 @@+---+'@inkeep/open-knowledge': patch+---++Correct user-facing copy that described behavior that doesn't exist, and finish+the Personal CRM rename in seeded content:++- The OKF pack's seeded skill no longer claims an "OKF export" normalizes+ `[[wiki-link]]` shorthand to standard links — no export feature exists;+ OpenKnowledge accepts the shorthand as a native superset and preserves it+ byte-for-byte.+- The `entity-vault` pack's seeded skill now titles itself **Personal CRM+ (GBrain-compatible)**, matching the starter-pack picker and the+ `ok seed` output. Applies to newly seeded projects; an existing project's+ skill is user-owned and left untouched.+- `ok seed --help` no longer promises a `--root` prompt on a TTY — omitting+ `--root` scaffolds at the project root (only the apply confirmation prompts).+- The template dialog's filename hint no longer says the filename "can't be+ changed later" (local templates are renamable from the edit dialog), and the+ description placeholder says "under the title", matching the field it sits+ beside.diff --git a/README.md b/README.mdindex 880679dfc..f1e988632 100644--- a/README.md+++ b/README.md@@ -22,7 +22,7 @@<a href="https://discord.com/invite/YujKpFN49">Discord</a></div>-</br>+<br/><imgsrc="assets/hero.webp"@@ -36,22 +36,22 @@Highlights:- Full true **WYSIWYG** so that editing markdown files feels like editing a Google Doc or Notion page.- **macOS app** and **web UI** with file navigator, search, tabs, graph wiki link viewer, and more.-- Collaborative **AI-editing** with **Claude, Codex, and Cursor desktop apps**. Can be used with any harness/agent via MCP/CLI, like OpenCode.+- Collaborative **AI-editing** with **Claude, Codex, Cursor, and OpenCode**. Can be used with any harness/agent via MCP/CLI.- Out-of-the-box **MCP**, **skills**, and **agentic search** for LLM Wikis, agent second brains, and knowledge graphs.- No-code **Team sharing** and **Auto-sync** powered by git/GitHub under the hood.- **Embeddable HTML** and rich components for writing engineering specs and visualized reports.-- A **built-in TUI** in the Desktop app and a Web UI for users who prefer terminals.+- A **built-in TUI** in the macOS app for users who prefer terminals.## Install**macOS:** download the desktop app — open the DMG, drag **OpenKnowledge** to **Applications**, and launch it. [Latest release](https://github.com/inkeep/open-knowledge/releases/latest).-**Linux, Windows, Intel Mac:** run the same editor as a local web app via the CLI ([Node.js 24+](https://nodejs.org) required):+**Linux, Windows, Intel Mac:** run the same editor as a local web app via the CLI ([Node.js 24+](https://nodejs.org) and git required):```bashnpm install -g @inkeep/open-knowledgecd your-project-ok init # scaffold the project + wire up Claude Code, Cursor, and Codex+ok init # scaffold the project + wire up your AI editors (Claude Code, Claude Desktop, Cursor, Codex, OpenCode, OpenClaw)ok start --open # serve the web editor and open it in your browser```diff --git a/docs/content/advanced/folders-and-templates.mdx b/docs/content/advanced/folders-and-templates.mdxindex 1da283632..c2e8d446b 100644--- a/docs/content/advanced/folders-and-templates.mdx+++ b/docs/content/advanced/folders-and-templates.mdx@@ -6,7 +6,7 @@ description: Describe a folder with its own properties, and offer reusable templFolders organize a project the same way they do on your computer: a place to group related docs. OpenKnowledge adds two things on top: a folder can **describe itself** (its own properties, exactly like a document's), and it can offer a set of **templates** for new documents.-Click any folder in the sidebar to open its **overview**: a page listing what's inside, plus two cards: **Folder properties** and **Templates available**.+Click any folder in the sidebar to open its **overview**: a page listing what's inside, plus cards: **Folder properties**, **Templates available**, and an **Activity** feed of changes to both (hidden while empty).## Properties, in one minute@@ -16,7 +16,7 @@ A doc's properties are its own: exactly what's written in that file, nothing inj## Folder properties-The **Folder properties** card on a folder's overview page describes the folder *itself*. It works exactly like a document's properties: add any property you like. `title`, `description`, and `tags` are the common ones (they show up in navigation, search, and the folder overview, and give an AI assistant a one-line sense of what the folder is for), but the card is open-shape: a `status`, an `owner`, whatever fits.+The **Folder properties** card on a folder's overview page describes the folder *itself*. It works exactly like a document's properties: add any property you like. `title`, `description`, and `tags` are the common ones (they show up in the folder overview and give an AI assistant listing the project a one-line sense of what the folder is for), but the card is open-shape: a `status`, an `owner`, whatever fits.Folder properties are **self-only**: they describe their own folder and nothing else. They are not inherited by the documents inside the folder, and they do not flow into subfolders. A `posts/` folder described as "Blog posts" stays a description of `posts/`; opening a doc under `posts/` shows only that doc's own properties.@@ -24,9 +24,9 @@ Click **Add a property**, give it a name and a value, and it's saved to the fold## Templates-A template is a reusable starting point for a new document: a heading skeleton, a checklist, a layout you fill in every time, optionally with starting properties baked in. Create a template once, and every new document made from it starts with that content. Templates are available both to you (in the New File dialog) and to AI assistants working in your project.+A template is a reusable starting point for a new document: a heading skeleton, a checklist, a layout you fill in every time, optionally with starting properties baked in. Create a template once, and every new document made from it starts with that content. Templates are available both to you (in the New file dialog) and to AI assistants working in your project.-A template is just a markdown file. It lives at `.ok/templates/<name>.md` inside your project, with a little information at the top: its name and description.+A template is just a markdown file. It lives at `.ok/templates/<name>.md` inside your project, with a little information at the top: its title and description.### Create a template@@ -34,18 +34,19 @@ There are two places to create a template, depending on how widely you want it t**For one folder**: open the folder's overview page and find the **Templates available** card, then click **New template**. The template is created in that folder and applies to documents created there and in its subfolders.-**For the whole project**: open Settings (`Cmd/Ctrl-,`) → **This project** → **Project templates** → **New template**. The template is created at the project root and applies everywhere.+**For the whole project**: open Settings (`Cmd/Ctrl-,`) → **This project** → **Templates** → **New template**. The template is created at the project root and applies everywhere.Either way, the **New template** dialog asks for:-- **Name**: the human-readable name, shown wherever a template is picked. Required.-- **Filename**: derived automatically from the name (`Blog post` → `blog-post.md`). Click **Edit** to set it yourself. The filename is the id agents use, and it cannot be changed after the template is created.-- **Description**: an optional one-line summary shown under the name.+- **Title**: the human-readable name, shown wherever a template is picked. Required.+- **Filename**: derived automatically from the title (`Blog post` → `blog-post.md`). Click **Edit** to set it yourself. The filename is the id agents use.+- **Description**: an optional one-line summary shown under the title.+- **Type** and **Default properties**: the starting properties the new document gets (below).- **Starter content**: the markdown that becomes the new document's content.### Use a template-When you create a new file, the **New File** dialog shows a **Start from** picker listing every template that applies to the target folder. Pick one and the new document opens pre-filled with that template's starter content. Pick **Blank note** for an empty document.+When you create a new file, the **New file** dialog shows a **Start from** picker listing every template that applies to the target folder. Pick one and the new document opens pre-filled with that template's starter content. Pick **Blank note** for an empty document.### Auto-filled placeholders@@ -76,7 +77,7 @@ These two are the only placeholders OpenKnowledge fills in. Any other `{{...}}`### Give new documents their own properties-The standup template above produces documents with just a body. To give every new doc in a folder the same **starting properties** (a `type`, a `status`, a date, a `tags` array), you don't hand-edit anything — the **Edit template** dialog has a **Type** field and a **Default properties** section (key/value rows) for exactly this. The starter content stays pure markdown.+The standup template above produces documents with just a body. To give every new doc in a folder the same **starting properties** (a `type`, a `status`, a date, a `tags` array), fill in the **New template** dialog's **Type** field and **Default properties** section (key/value rows); on an existing template, edit the frontmatter block at the top of the template file. The starter content stays pure markdown.On disk it all lives in one frontmatter block: the template's own identity sits under a reserved `template:` key, and every other top-level key is a property new documents start with:@@ -97,13 +98,13 @@ tags: [daily](...)```-The `template:` block is the template's own info (the name and description shown in the picker); OpenKnowledge strips it when a document is created. Every other key — `type`, `description`, `title`, `status`, `tags` above — becomes the new document's own properties, written as real bytes into the file. `description` gives each new document a starting one-line summary; edit it per document. Because these are the new doc's *own* properties, the doc owns them outright: editing one doc never touches another.+The `template:` block is the template's own info (the title and description shown in the picker); OpenKnowledge strips it when a document is created. Every other key — `type`, `description`, `title`, `status`, `tags` above — becomes the new document's own properties, written as real bytes into the file. `description` gives each new document a starting one-line summary; edit it per document. Because these are the new doc's *own* properties, the doc owns them outright: editing one doc never touches another.(Older templates that used two stacked frontmatter blocks still work — OpenKnowledge reads them and rewrites them to the single-block form the next time they're saved.)### Edit and delete-In both the folder card and the Settings list, click a template row to edit its name, description, or starter content, or use the row's menu to **Edit** or **Delete**. Editing an **inherited** template edits the file in the ancestor folder that owns it, which affects every folder under that ancestor; the dialog calls this out.+In both the folder card and the Settings list, click a template row (or its menu's **Edit**) to open the template as a document tab: the body is the starter content, and the **Properties** panel holds its title, description, and name — change the name to rename the template file. The row's menu also has **Delete**. Editing an **inherited** template edits the file in the ancestor folder that owns it, which affects every folder under that ancestor; the row's **inherited** badge names the owning folder, and the opened tab shows that folder read-only in its Properties.Deleting a template removes the `.ok/templates/<name>.md` file. Folders and agents that referenced it fall back to an inherited template of the same name, if one exists, or report the template as missing.@@ -126,9 +127,9 @@ Agents create documents from templates the same way you do. Through MCP, an agenwrite({ document: { path: "posts/launch", template: "blog-post" } })```-OpenKnowledge finds the `blog-post` template the same way the New File dialog does: the agent gets the one that applies to `posts/`. The template's **starter content** becomes the new document; the template's own name and description stay behind as template info and are not copied into the document.+OpenKnowledge finds the `blog-post` template the same way the New file dialog does: the agent gets the one that applies to `posts/`. The template's **starter content** becomes the new document; the template's own title and description stay behind as template info and are not copied into the document.-This is why a template's **Name** matters: it is the label an agent reads when choosing which template fits the document it is about to create.+When an agent creates a document without a template in a folder that offers them, the write result lists the folder's available templates (filename and description). This is why a template's **Filename** and **Description** matter: they are what an agent reads when choosing which template fits the document it is about to create.## Where it's storeddiff --git a/docs/content/features/agent-activity.mdx b/docs/content/features/agent-activity.mdxindex 38da3ec6c..b539d3a5c 100644--- a/docs/content/features/agent-activity.mdx+++ b/docs/content/features/agent-activity.mdx@@ -8,7 +8,7 @@ Agent activity shows all edits made by an agent during its current editing sessi## Open agent activity-Avatar icons will appear in the top right of the editor whenever an agent or a human is editing a document. You can click on an agent's avatar icon to open the activity panel for that agent.+Avatar icons will appear in the top right of the editor whenever an agent or a human has the document open. Agents working in other documents appear in an adjacent group. You can click on any agent's avatar icon to open the activity panel for that agent.The activity panel displays the list of files that the agent has edited in the current session.@@ -25,4 +25,8 @@ While an agent's session is still active, you can undo:- The agent's latest edit in a file- All edits made by an agent in a file at once-After the agent session ends, the activity panel still shows the session's edits for review, but undo is no longer available. Use the [timeline](/docs/features/timeline-and-recovery) to roll back changes from a closed session.+Activity history lives only as long as the agent's session: shortly after the agent disconnects, the panel and the agent's avatar clear. Use the [timeline](/docs/features/timeline-and-recovery) to review and roll back changes from a closed session.++## How attribution works++Every edit is attributed to its author — a specific agent, you, an upstream Git sync, or the file system — and recorded in a local edit history. The activity panel is a live view of a single agent session; the timeline is the durable record of who changed what.diff --git a/docs/content/features/assets-and-embeds.mdx b/docs/content/features/assets-and-embeds.mdxindex a4e0a33a2..28df38119 100644--- a/docs/content/features/assets-and-embeds.mdx+++ b/docs/content/features/assets-and-embeds.mdx@@ -4,7 +4,35 @@ icon: LuPaperclipdescription: Drop files into the editor and reference them with wiki-style embeds.----OpenKnowledge treats assets (images, PDFs, video, audio) as first-class content alongside markdown. This page covers how asset references behave when shared outside the editor.+OpenKnowledge treats assets (images, PDFs, video, audio) as first-class content alongside markdown.++## Adding files++Drag files into the editor or paste them — screenshots paste straight from the clipboard, and any file type is accepted. The file uploads into the project and the matching block is inserted. Uploads land beside the document by default; point [`content.attachmentFolderPath`](/docs/reference/configuration) at a different folder to change that. Dropping a file whose bytes already exist in the target folder reuses the existing file rather than writing a duplicate. You can also insert an image, video, or audio block from the `/` insert menu and upload from its settings.++AI agents add assets through the MCP [`write`](/docs/reference/mcp) tool's `asset` target, passing exactly one of `content` (the bytes as base64, for small files) or `source` (a local filesystem path the server reads — use it for large files).++## How assets render++- **Images render inline** with click-to-zoom. Select one to align it left / center / right from the bubble menu, or set alt text and dimensions in its settings.+- **Video and audio render native players.** The video block also takes YouTube, Vimeo, and Loom URLs and renders each host's own player.+- **PDFs and other documents** (`.docx`, `.zip`, `.csv`, …) insert a file attachment row — icon, name, size — linking to the file. To render pages in the doc, use the **PDF** block instead: a multi-page viewer with thumbnails, page navigation, and zoom; set `page=3` in its `anchor` setting to open at that page.++In the markdown source, dropped media serializes as `<img>` / `<video>` / `<audio>` and file attachments as wiki-style embeds (`![[report.pdf]]`). You can author the wiki form directly: `![[diagram.png]]` on its own line follows the type rules above, inside a sentence it stays a link, and a fragment (`![[report.pdf#page=3]]`) is preserved on the rendered link. Standard `` image syntax works too.++## Embedding web pages++The **Embed** block renders an external page in an inline iframe — docs, demos, Figma, CodeSandbox. Drag its handles to resize; the dimensions persist into the markdown. Only `http://` / `https://` URLs load, never the editor's own origin; a site that forbids framing renders an empty pane — that's the remote site's policy. YouTube, Vimeo, and Loom watch URLs are rewritten to their embeddable player URLs at render.++## Live HTML embeds++A code block fenced as ` ```html preview ` renders its HTML in a live sandboxed iframe instead of showing the code. The editor's theme tokens (`var(--foreground)`, `var(--chart-1)`, …) are injected into the preview so embeds track light and dark mode; toggle any HTML block between code and preview from its controls.++Type `/embed` for starters: a blank **HTML** canvas plus **Chart**, **Stat cards**, **Custom SVG**, and **Interactive control** templates. Agents get the same starters from the MCP [`palette`](/docs/reference/mcp) tool.++## Diagrams++A ` ```mermaid ` fence renders as a diagram — flowchart, sequence, class, state, ER, gantt, or pie; the **Mermaid** entry in the `/` menu inserts one. Rendered diagrams carry buttons for zoom, pan, and reset; mouse-wheel zoom and drag panning are off, so a diagram holds still while you scroll the doc.## Sharing across apps@@ -17,7 +45,7 @@ Local-path images (``), wiki-embeds (`![[diagram.png]]`)Two affordances are preserved across the cross-app boundary, not degradations themselves:- **Markdown-aware destinations get the source.** Linear, Outline, Obsidian, and similar apps that read `text/plain` first receive clean canonical markdown; the cross-app degradation only affects the `text/html` payload that destinations like Gmail render.-- **OpenKnowledge → OpenKnowledge paste round-trips faithfully.** Copying out of one OpenKnowledge doc and pasting into another preserves the original markdown image / wiki-link / wiki-embed shape, because the cross-app degradation only fires when the receiving app reads `text/html` instead of `text/plain`.+- **OpenKnowledge → OpenKnowledge paste round-trips images and wiki-links.** Copying out of one OpenKnowledge doc and pasting into another preserves the original markdown image and wiki-link shape. Wiki-embeds round-trip when the copied selection carries other markdown signals (a heading, a list, bold); a selection that is only a wiki-embed — or plain prose around one — pastes as literal source text, not a rendered embed.Source-mode copy (the CodeMirror toggle) works the same way: the clipboard's `text/html` payload is always a styled code block of the raw markdown bytes, never the rendered output. Pasting a `# Heading` from source-mode into Gmail produces a code block, not a rendered heading. This is consistent with VS Code, Obsidian source mode, GitHub textareas, and CodeMirror itself.diff --git a/docs/content/features/editor.mdx b/docs/content/features/editor.mdxindex a5fb5878d..d980feafe 100644--- a/docs/content/features/editor.mdx+++ b/docs/content/features/editor.mdx@@ -22,7 +22,23 @@ It opens in the desktop app when it's installed, and falls back to your browserOpen any doc from the sidebar. The body renders as WYSIWYG markdown with familiar conventions: bold / italic / headings / lists / tables / code fences / links / images. Toggle to source mode from the editor controls to edit the raw markdown directly; both views are bound to the same CRDT document, so they stay in sync across users and AI agents.-A backslash command (`/`) opens an insert menu for headings, lists, code blocks, callouts, and the other content shapes the editor supports.+A slash command (`/`) opens an insert menu for headings, lists, tables, code blocks, callouts, footnotes, inline math, and the other content shapes the editor supports.++### Tables++Insert a table from the slash menu. The header row stays visible as you scroll down a long table, the first column stays pinned as you scroll sideways, and dragging a row or column handle reorders it. Cells are single-line in the stored markdown: pressing Enter inside a cell — or pasting a table whose cells hold lists or paragraphs — joins the lines with `<br />`, the GFM line-break idiom, so the table stays valid for everyone else opening the file. `<br>` tags in existing files render as real line breaks and round-trip byte-for-byte.++### Mermaid diagrams++A `mermaid` code fence renders as a live diagram (the slash menu can insert one). On-diagram buttons pan, zoom, and reset the view; mouse-wheel zooming and drag panning are disabled so a large diagram never moves while you scroll past it.++### Live HTML embeds++An `html preview` code fence renders its contents live in a sandboxed iframe instead of showing the source. The slash menu's `/embed` group inserts starters — a blank theme-aware page, a chart, stat cards, custom SVG, an interactive control — that open straight into the preview.++### Find and replace++`Cmd+F` opens find in the visual editor; `Cmd+Option+F` (`Ctrl+H` on Windows / Linux) adds the replace controls. `Cmd+G` and `Shift+Cmd+G` step through matches.## Right-click menu and spell check@@ -42,15 +58,23 @@ Surfaces with their own specialized right-click menus — asset and wiki-link ch## Ask AI-A persistent **Ask AI** composer is docked at the bottom of the editor in the desktop app, above the status bar and above the terminal dock (it's pushed up when the terminal expands). It's a slim, single-line entry field — always present when a doc is open — that expands as you type to accept a fuller prompt (and `@`-mentions). Type an instruction — "condense this doc", "research X", "make a spec from this user story" — and press Enter to hand it to an agent. `Shift+Enter` inserts a newline; the field clears once the prompt is sent.+An **Ask AI** composer is docked at the bottom of the editor — in the desktop app and in a regular browser — whenever a doc or folder view is open. It's a slim, single-line entry field that expands as you type to accept a fuller prompt (and `@`-mentions); in the desktop app, `Cmd+L` opens and focuses it. Type an instruction — "condense this doc", "research X", "make a spec from this user story" — and press Enter to hand it to an agent. `Shift+Enter` inserts a newline; the field clears once the prompt is sent.-It's the primary in-editor way to hand work to an agent, and the freetext companion to the menu-driven [Open with AI](#open-with-ai) (whole file / folder / project). Submitting dispatches the typed prompt to your **default agent** — the first one installed, in Claude → Codex → Cursor order — scoped to the current doc, which the agent receives as an `@`-mention. The agent picker beside the field overrides the default per send (its targets include Claude, Codex, Cursor, and the Terminal CLI), and your choice is remembered on that machine. Success and failure use the same handoff toast as Open with AI.+It's the primary in-editor way to hand work to an agent, and the freetext companion to the menu-driven [Open with AI](#open-with-ai) (whole file / folder / project). Submitting dispatches the typed prompt to your **default agent** — the first one installed, in Claude → Codex → OpenCode → Cursor order — scoped to the current doc (or, in a folder view, the folder), which the agent receives as an `@`-mention. The agent picker beside the field overrides the default per send — the installed desktop agent apps plus, in the desktop app, the Terminal CLIs (Claude, Codex, OpenCode, Cursor) — and your choice is remembered on that machine. Success and failure use the same handoff toast as Open with AI.-The composer is desktop-only and stays out of the way where it doesn't belong: it's hidden inside an AI editor's embedded view, on the web build, and when no doc is open (the empty state already offers project handoff). Like the other handoffs it dispatches only to agents installed on your machine; when none are installed, the field is disabled.+The composer stays out of the way where it doesn't belong: it's hidden inside an AI editor's embedded view, while the [docked terminal](#terminal) is open (the terminal is its own AI entry point), and when no doc or folder is open (the empty state already offers project handoff). It's also dismissible — an **Ask AI** badge in the status bar brings it back.### 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 the selection shortcut — 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. (macOS desktop only; selecting an image or other non-text node doesn't show the affordance.)+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.)++## Terminal++The desktop app has a built-in terminal: real login shells, docked in the editor window. Toggle it with `Cmd+J`, **View ▸ Show / Hide Terminal**, or the edge **Show terminal** tab that sits where you last closed it. It opens as a right-side column by default; buttons in its tab strip move it between the right column and the bottom dock or collapse it (sessions keep running), and the dock position is remembered.++The terminal is also the editor's AI-chat surface: the **Show terminal** tab starts your default CLI when no session is open, and the tab strip's **New chat** split button opens another CLI tab — its dropdown switches CLI (the pick sticks, shared with the Ask AI composer) or opens a plain shell tab. **Terminal ▸ New Terminal Window** (see [Terminal menu](#terminal-menu)) opens a dedicated window with the same multi-session tabs, `Cmd+<number>` tab switching, and shells starting at the project root.++The shells run at full user privilege. To turn the terminal off for a project on this machine, use **Settings ▸ Terminal** or set `terminal.enabled: false` in `.ok/local/config.yml` (see the [configuration reference](/docs/reference/configuration)); the setting is project-local, never shared via git or sync, and not agent-settable — only a human can flip it.## Properties@@ -75,17 +99,18 @@ Right-click anywhere in the sidebar to get a context-aware menu. Three shapes sh| New Folder | yes | yes | no || Reveal in Finder | yes (project root) | yes | yes || Open with AI ▸ | yes (project scope) | yes (folder scope) | yes (file scope) |-| Open in Terminal | yes (project root) | yes (folder) | yes (parent dir) |+| Share | yes (project root) | yes | yes || Copy full path / Copy Path ▸ | yes (full path of project root) | yes (Full / Relative) | yes (Full / Relative) || Show Hidden Files | yes | yes | no || Expand all / Collapse all | yes (tree-scoped) | yes (subtree-scoped) | no |+| Duplicate | no | yes | yes || Rename | no | yes | yes || Hide folder / Hide this file | no | yes | yes || Delete | no | yes | yes |-Items that depend on the desktop app (Reveal in Finder, Open in Terminal, Delete via Trash) are hidden in the web build. Asset rows (images, PDFs, other non-markdown files) suppress Rename, Open with AI, Hide, and Delete; they show Reveal, Open in Terminal (parent dir), and Copy Path only.+Items that depend on the desktop app (Reveal in Finder, Delete via Trash) are hidden in the web build. Asset rows (images, PDFs, other non-markdown files) suppress Open with AI, Share, Duplicate, and Hide; they keep Reveal, Copy Path, Rename, and Delete.-Expand all and Collapse all only appear when they have work to do: Expand all is hidden when no folder is collapsed; Collapse all is hidden when no folder is expanded.+Expand all and Collapse all only appear when they have work to do: Expand all is hidden when no folder is collapsed; Collapse all is hidden when no folder is expanded. New from template appears only when templates are available for the target folder, and Share only when the project has a GitHub remote.### Creating files and folders@@ -113,7 +138,7 @@ On very large trees the disk walk is capped per level, and the sidebar shows a n### Open with AI-**Open with AI ▸** dispatches the project, the folder, or the file to one of your installed agent apps (Claude, Codex, or Cursor). The agent receives a short text prompt asking it to open the target in the OpenKnowledge web preview, then grounds the rest of the conversation via the [OpenKnowledge MCP](/docs/reference/mcp). Three scopes, three prompt shapes:+**Open with AI ▸** dispatches the project, the folder, or the file to one of your installed agents. The agent receives a short text prompt asking it to open the target in the OpenKnowledge web preview, then grounds the rest of the conversation via the [OpenKnowledge MCP](/docs/reference/mcp). Three scopes, three prompt shapes:| Scope | Triggered from | Prompt template || --- | --- | --- |@@ -125,26 +150,27 @@ The trailing `Open the OK editor in web view.` directive is dropped when the [`aTo send your own freetext instruction along with the handoff, use the bottom [Ask AI](#ask-ai) composer (or the empty-state create composer on a fresh project) rather than these one-click submenus.-**Install detection** filters the submenu to just the agents you have. When the server and your browser are on the same machine (`localhost`), the filter is accurate. When you're running the server elsewhere (a hosted preview, SSH tunnel, remote dev), the submenu lists every supported agent and lets your browser's OS protocol-dispatch dialog be the truth signal.--The Claude **claude.ai** web fallback row appears on file-scope dispatches only; the cloud agent has no project-root parameter, so folder and project dispatches hide it rather than send a context-less prompt.+**Install detection** filters the submenu to just the agents you have. The desktop app probes locally; the web build asks the server (`GET /api/installed-agents`), so the answer reflects the machine the server runs on — exact on `localhost`, while against a remote server (a hosted preview, SSH tunnel, remote dev) it's the server's installs that count. When nothing is detected, the submenu shows a disabled "No installed agents found" row.See the [per-integration pages](/docs/integrations/claude-code) for what each agent receives once dispatched.-The menu is organized into two sections. **Desktop** lists the installed agent apps (Claude, Codex, Cursor); selecting one launches it via its deep link. **Terminal** (desktop app only) adds a row for each CLI — **Claude**, **Codex**, and **Cursor** — that runs the corresponding CLI (`claude`, `codex`, `cursor`) in OpenKnowledge's docked terminal with the same scoped prompt. Because both sections can list the same name, a Desktop **Claude** (the app) and a Terminal **Claude** (the CLI) can appear together; screen readers tell them apart by the Terminal row's "Claude CLI" accessible name (and likewise "Codex CLI" / "Cursor CLI"). Each section renders only when it has something to launch, so on the web build — which has no docked terminal — the Terminal section is absent and a CLI pick falls back to the first installed Desktop app target.+The menu is organized into two sections. **Terminal** (desktop app only) leads: a row for each agent CLI — **Claude**, **Codex**, **OpenCode**, and **Cursor** — that runs the corresponding CLI (`claude`, `codex`, `opencode`; Cursor's is `cursor-agent`) in OpenKnowledge's [docked terminal](#terminal) with the same scoped prompt. **Desktop** follows, listing the installed agent apps (Claude, Codex, Cursor); selecting one launches it via its deep link. Because both sections can list the same name, a Terminal **Claude** (the CLI) and a Desktop **Claude** (the app) can appear together; screen readers tell them apart by the Terminal row's "Claude CLI" accessible name. Each section renders only when it has something to launch, so on the web build — which has no docked terminal — the Terminal section is absent and a CLI pick falls back to the first installed Desktop app target.-The empty-state create composer on a fresh project carries the same Desktop / Terminal split: its Desktop rows pick the default agent the **Create** button uses, while its Terminal **Claude** row (desktop only, disabled until the workspace resolves) launches the `claude` CLI with the brief you typed.+The empty-state create composer on a fresh project carries the same Desktop / Terminal split: its Desktop rows pick the default agent the **Create** button uses, while its Terminal rows (desktop only, disabled until the workspace resolves) launch any of the four CLIs with the brief you typed.-### Open in Terminal+## Command palette-Spawns `open -a Terminal.app <dir>` at the right path: the folder for a folder row, the file's parent for a file row, the project root for the empty-space menu, the parent dir for an asset row. Terminal.app is hardcoded for v1; user-configurable terminal preference is on the roadmap. This is distinct from the **Terminal** section inside **Open with AI**, which runs a CLI (`claude`, `codex`, or `cursor`) in OpenKnowledge's docked terminal rather than opening Terminal.app.+`Cmd+K` opens the command palette in both the desktop app and the browser. Type to jump to any file or folder, run create commands, open the graph or settings, or dispatch to an agent; recently opened entries surface first. In the desktop app it also switches projects and worktrees.++A `tag:` prefix searches by tag: `tag:` alone lists every tag, `tag:fr` narrows the tag list, and `tag:frontend` lists the docs tagged `#frontend` (including its hierarchy children). When semantic search is configured for the project, a **By meaning** pill switches the palette to meaning-based search — press Enter to run it; typing alone never fires a query.## Sidebars and window widthThe editor has two sidebars: the file sidebar on the left and the document panel on the right (Outline, Links, Properties, Timeline). Both adapt to the window:-- At comfortable widths (about 1024px and up) both sidebars open by default.-- Below that, both default to collapsed so the editor canvas isn't squeezed off-screen.+- At comfortable widths (1280px and up) both sidebars open by default.+- Between 1024px and 1279px the document panel defaults to collapsed so the editor keeps its breathing room; the file sidebar stays open.+- Below 1024px both default to collapsed so the editor canvas isn't squeezed off-screen.- When OpenKnowledge is opened inside an AI editor's webview (Cursor, Codex, Claude Desktop), both sidebars start collapsed regardless of width; the embedded view is for reading the content you were sent, not for file management.The defaults only apply until you toggle. OpenKnowledge remembers your most recent Show / Hide for each sidebar in your browser and survives reloads. When you come back to the same layout context (narrow window, comfortable window, or embedded view) you used last, your toggle is what you'll see. Toggling in a different context replaces that memory; only your most recent choice sticks, so a stale preference from a wide-monitor session can't quietly override what you just chose on a narrow screen.@@ -161,8 +187,14 @@ Keyboard shortcuts (use `Ctrl` on Windows / Linux in place of `Cmd`, unless the| `Cmd+Shift+T` | Reopen the most recently closed editor tab. || `Cmd+Option+S` | Show / Hide the file sidebar (left). Matches Apple's standard sidebar accelerator. || `Cmd+Option+B` | Show / Hide the document panel (right). Matches VS Code's Secondary Side Bar accelerator. |+| `Cmd+J` | Show / Hide the docked terminal (desktop app). |+| `Cmd+K` | Open the [command palette](#command-palette). |+| `Cmd+L` | Open and focus the [Ask AI](#ask-ai) composer (desktop app). |+| `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. |-In the desktop app the same actions live in the **View** menu (see below) and each menu label flips between **Show …** and **Hide …** based on current state, matching Finder.+In the desktop app the sidebar and terminal toggles also live in the **View** menu (see below), where each label flips between **Show …** and **Hide …** based on current state, matching Finder.Inside an AI editor's embedded view, the **Open with AI** menus, the bottom Ask AI composer, and the empty-state agent grid are hidden; you're already inside an agent, so the handoff would loop back into the same surface. OpenKnowledge's MCP tools and the document itself stay fully available; only the launchers are gone.@@ -172,22 +204,20 @@ The OpenKnowledge desktop app keeps its menu bar in sync with the active editor### File menu-Below the project navigation items (Switch Project, Open Folder, Open Recent, CLI Tools, Configure AI, Close), the File menu surfaces the most-used sidebar affordances so they're reachable from the keyboard:+Alongside the project items (Recent project, New project…, Switch Project… `Cmd+Shift+P`, Open Folder… `Cmd+O`), the worktree pair (New worktree…, Switch worktree…), **Set up OpenKnowledge integrations…** (re-runs the first-launch integrations setup), and Close tab, the File menu surfaces the most-used sidebar affordances so they're reachable from the keyboard:| Item | Accelerator | Behavior || --- | --- | --- || **New File** | `Cmd+N` | Creates a new file at the project root (or under the active folder if one is selected). || **New Folder** | `Cmd+Shift+N` | Creates a new folder. || **New from Template…** | (none) | Opens the template picker. |+| **Duplicate** | `Cmd+D` | Duplicates the active file or folder. Disabled when nothing is selected. || **Rename** | (none) | Inline-renames the active file or folder. Disabled when nothing is selected. || **Move to Trash** | `Cmd+Delete` | Sends the active file or folder to Trash (with the same confirm modal as the sidebar). Disabled when nothing is selected. || **Reveal in Finder** | (none) | Reveals the active target in Finder. Empty selection reveals the project root. |-| **Open in Terminal** | (none) | Opens Terminal.app at the active target's directory. || **Open with AI ▸** | (none) | Same submenu as the sidebar, dispatched at the active scope. || **Copy Path ▸** | (none) | Full / Relative path of the active target. |-**Switch Project…** moved to `Cmd+Shift+P`. The old `Cmd+Shift+N` binding now creates a new folder, matching macOS Finder, VS Code, and the broader convention.-### Edit menuAlongside the standard Undo / Redo / Cut / Copy / Paste / Select All items:@@ -204,12 +234,21 @@ Before the existing Zoom and Toggle Fullscreen items, the View menu gets:| --- | --- | --- || **Show / Hide Sidebar** | `Cmd+Option+S` | Toggles the file sidebar (left). Label flips between Show and Hide based on current state, matching Finder. || **Show / Hide Document Panel** | `Cmd+Option+B` | Toggles the document panel (right). |-| **Show Hidden Files** | (none) | `appearance.sidebar.showHiddenFiles`; same toggle as the sidebar's right-click menu. |+| **Show / Hide Terminal** | `Cmd+J` | Toggles the docked terminal. |+| **Show Hidden Files** | `Cmd+Shift+.` | `appearance.sidebar.showHiddenFiles`; same toggle as the sidebar's right-click menu. || **Expand All** | (none) | Expands every folder in the tree. Hidden when nothing is collapsed. || **Collapse All** | (none) | Collapses every folder in the tree. Hidden when nothing is expanded. |Toggling the menu checkboxes flips the underlying config field, which propagates back to the sidebar via the standard CRDT subscription; both surfaces stay synchronized.+### Terminal menu++| Item | Accelerator | Behavior |+| --- | --- | --- |+| **New Terminal** | (none) | Opens a new terminal tab, revealing the dock if it's hidden. |+| **New Terminal Window** | (none) | Opens a terminal in its own window — the same multi-session tabs, switched with `Cmd+<number>`, shells starting at the project root. |+| **Kill Terminal** | (none) | Closes the active terminal tab and kills its shell. |+## Real-time collaborationEverything in the editor (body, frontmatter, sidebar toggles) is backed by a CRDT. You and multiple AI agents writing through MCP can edit the same doc concurrently. Per-user presence is shown in the editor header; the **agent activity** view ([Agent activity](/docs/features/agent-activity)) groups every burst of agent edits with per-burst diffs and selective undo.diff --git a/docs/content/features/github-sync.mdx b/docs/content/features/github-sync.mdxindex 2ce017bb5..bcd98fb3e 100644--- a/docs/content/features/github-sync.mdx+++ b/docs/content/features/github-sync.mdx@@ -20,6 +20,8 @@ It helps you:## Clone an existing GitHub repository+These steps use the desktop app; from a terminal, [`ok clone`](/docs/reference/cli#clone-from-github) does the same.+<Steps><Step>@@ -31,7 +33,7 @@ It helps you:<Step>### Sign into GitHub- If you are already signed in with the GitHub CLI, OpenKnowledge will use those credentials by default. If not, click **Sign into GitHub** and complete the device authentication flow.+ If you are already signed in with the GitHub CLI, OpenKnowledge will use those credentials by default. If not, click **Connect GitHub** and complete the device authentication flow.</Step><Step>@@ -63,21 +65,23 @@ While sync is active, OpenKnowledge:- Commits your edits locally using the configured Git identity- Pushes those commits back to the remote so collaborators see your changes+If your Git identity isn't set, sync still commits under a default "OpenKnowledge" author; the sync status indicator reminds you to set one so teammates see your name.+Pulls can overwrite uncommitted local file changes, so commit or discard work-in-progress before you enable sync.-If you want to set a default auto-sync setting for future collaborators, go to the project settings page and navigate to the **Sync** -> **Shared default** section.+If you want to set a default auto-sync setting for future collaborators, go to the project settings page and navigate to the **Sync** -> **Shared default** section. This writes [`autoSync.default`](/docs/reference/configuration) to the project's committed `.ok/config.yml`, pre-answering the enable-sync prompt for everyone who clones the repo; each machine's own auto-sync choice overrides it.## AuthenticationIf you are logged in with the GitHub CLI, OpenKnowledge will use those credentials for GitHub operations. If not, you can complete device authentication to generate an OAuth token. OpenKnowledge stores this token in the keychain and reuses it for syncing, cloning, and publishing.-Manage the connection from **Settings → Account**. **Connect GitHub** authorizes OpenKnowledge to browse and sync your repositories; **Disconnect** clears OpenKnowledge's GitHub token only.+Manage the connection from **Settings → Account**. **Connect GitHub** authorizes OpenKnowledge to browse and sync your repositories; **Disconnect** clears OpenKnowledge's GitHub token only. From a terminal, the [`ok auth`](/docs/reference/cli) subcommands manage the same credentials: `ok auth signout` matches **Disconnect**, `ok auth pat` stores a Personal Access Token when device authentication isn't an option, and `--host` targets GitHub Enterprise.The sync status indicator surfaces an auth-error state when stored credentials stop working, and sync pauses until you reconnect.## Sync status and conflicts-The sync status indicator in the editor shows the current state of the connection: how many commits you are ahead or behind the remote, when the last sync ran, whether sync is paused, and how many files have unresolved conflicts. You can also trigger an immediate sync from the same control instead of waiting for the next scheduled run.+The sync status indicator in the editor shows the current state of the connection: how many commits you are ahead or behind the remote, when the last sync ran, whether sync is paused, and how many files have unresolved conflicts. You can also trigger an immediate sync from the same control instead of waiting for the next scheduled run. From a terminal, `ok sync` commits, pulls, and pushes in one pass; `ok pull` and `ok push` cover one direction each. All three work whether or not the editor is open (see the [CLI reference](/docs/reference/cli)).## Resolving a conflict@@ -87,14 +91,18 @@ Click the badged tab or any row in the Conflicts section to focus the conflict.You can't edit a page with conflicts until they're resolved; the same applies to agents writing over MCP.+## Work on multiple branches++In the desktop app you can open several branches of the same project at once, each in its own window. Click your project name in the bottom left and pick a branch or worktree from the project switcher (open worktrees also appear in the Command Palette); **New worktree** starts a fresh branch or checks out an existing one. Opening a branch that has no worktree yet creates one on demand under `.ok/worktrees/`, kept out of `git status`, so each window runs its own editor and server without touching your main working copy.+## Common failure modes-A few situations stop sync from completing successfully. In each case the sync status indicator changes color and tells you what's wrong. Sync stays paused until the underlying issue is fixed, then picks back up on its own.+A few situations stop sync from completing successfully. In each case the sync status indicator changes color and tells you what's wrong. Except where noted, sync stays paused until the underlying issue is fixed, then picks back up on its own.### Conflicts and pending changes- **Unresolved conflicts.** If even one file has a conflict between your edits and your team's, sync waits. You can keep working on every other doc; only the conflicted files are frozen until you choose a side from the diff view. See [Resolving a conflict](#resolving-a-conflict) above.-- **Local changes would be overwritten by an incoming update.** A teammate's update is ready to pull, but you have uncommitted local edits to the same file. Sync pauses rather than clobber your work. Commit or discard the in-progress edit from the editor's git surface and sync resumes.+- **Local changes would be overwritten by an incoming update.** A teammate's update is ready to pull, but a file it touches has uncommitted local changes. Doc edits are committed automatically before merging, so this usually means other tracked files, like configs. Sync pauses rather than clobber your work; commit, stash, or discard those changes from a terminal and sync resumes.- **Edits made outside the app aren't ready yet.** If you (or another tool) edited a file directly on disk while sync wanted to merge, OpenKnowledge waits until those external edits settle before merging. Usually this clears in a second or two on its own.### Project isn't on a normal branch@@ -106,8 +114,7 @@ A few situations stop sync from completing successfully. In each case the sync s- **Authentication errors.** Your stored credentials expired, were revoked, or don't have access to this repository anymore. Reconnect from the sync indicator (or from **Settings → Account**) to clear the error.- **You don't have permission to push to this repo.** Someone shared a project backed by a GitHub repo where your account isn't a collaborator (or has read-only access on a private repo). OpenKnowledge checks this up front: instead of prompting you to enable sync that would just fail, the toggle is disabled with an inline "You don't have permission to push to this repo" message in both the sync indicator popover and **Settings → Sync**. If you had sync enabled on a different repo and switch to one you can't push to, OpenKnowledge pauses sync in-memory rather than mutating your preference; your `Auto-sync: on` setting is preserved for the next repo you have full access to. Ask the project owner for write access, then click sync to re-check.-- **Protected branches and rejected pushes.** If the target branch requires reviews, signed commits, or status checks, GitHub rejects the push. OpenKnowledge turns sync off automatically so it stops retrying. Switch to a branch you can push to, or use a pull request for the protected branch instead.-- **Missing Git identity.** Commits need a name and email attached. The status indicator prompts you to set one the first time sync needs to commit.+- **Protected branches and rejected pushes.** If the target branch requires reviews, signed commits, or status checks, GitHub rejects the push. OpenKnowledge turns sync off automatically so it stops retrying, and it stays off until you turn it back on from the sync indicator or **Settings → Sync**. Switch to a branch you can push to, or use a pull request for the protected branch instead.### Temporary problemsdiff --git a/docs/content/features/ignore-patterns.mdx b/docs/content/features/ignore-patterns.mdxindex f89bb9040..fc3306baf 100644--- a/docs/content/features/ignore-patterns.mdx+++ b/docs/content/features/ignore-patterns.mdx@@ -1,18 +1,18 @@---title: Ignore patternsicon: LuEyeOff-description: Hide files and folders from the editor, search, and your AI agents.+description: Hide files and folders from search and your AI agents.----OpenKnowledge indexes the markdown in your project so it can power the file tree, search, and the tools your AI agents call. When you don't want a file in that picture (drafts, scratch notes, vendor-pasted material), hide it with an ignore pattern. Hidden items don't appear in the file tree, don't show up in search, and don't reach AI agents through MCP. Nothing on disk is deleted.+OpenKnowledge indexes the markdown in your project so it can power search and the tools your AI agents call. When you don't want a file in that picture (drafts, scratch notes, vendor-pasted material), hide it with an ignore pattern. Hidden items don't show up in search and don't reach AI agents through MCP; they stay visible in the sidebar, which lists what's on disk, not what's indexed. Nothing on disk is deleted.-## Hide a file from the file tree+## Hide a file-Right-click any file in the sidebar and pick **Hide this file**. The file disappears from the tree immediately.+Right-click any file in the sidebar and pick **Hide this file**. OpenKnowledge appends a matching pattern to `.okignore` and confirms with a toast pointing at Settings; the row stays in the sidebar.Right-click a folder and pick **Hide folder** to hide every file inside it.-The hidden item is now ignored everywhere: search, agent context, and the document list returned by MCP tools. To bring it back, remove the matching row from Settings.+The hidden item is now ignored in search, agent context, and the document list returned by MCP tools. To bring it back, remove the matching row from Settings.## Manage patterns from Settings@@ -29,15 +29,15 @@ There is no Save button; every edit auto-saves to `.okignore` on disk.### Pattern preview-Each row shows a **matches N visible files** preview as you type. The count reflects what's currently visible; files already hidden by another row, or excluded by `.gitignore`, don't count toward it. A pattern that reports `matches 0` is usually a typo, but can also mean the file is already hidden by another rule.+Each row shows a **matches N files** preview as you type. Files already hidden by another row, or excluded by `.gitignore`, don't count toward it. A pattern that reports `matches 0` is usually a typo, but can also mean the file is already hidden by another rule.### Heuristic warnings-A small amber warning icon appears next to a row when the pattern has a syntax oddity (a stray `[`, a trailing backslash, leading whitespace, a lone `!`, or a CRLF inside the line). These warnings are non-blocking nudges, not errors. The pattern still saves; the icon is a hint that you may have meant something different.+A small amber warning icon appears next to a row when the pattern has a syntax oddity (a stray `[`, a trailing backslash, leading whitespace, a lone `!`, or an embedded line break). These warnings are non-blocking nudges, not errors. The pattern still saves; the icon is a hint that you may have meant something different.## Edits take effect immediately-Adding, editing, or removing a pattern updates the running editor in under a second. The file tree refreshes, search re-indexes, and the next MCP tool call sees the new scope. No restart, no manual refresh.+Adding, editing, or removing a pattern updates the running editor in under a second. Search re-indexes and the next MCP tool call sees the new scope. No restart, no manual refresh.External edits work the same way: open `.okignore` in another editor, save, and the running editor picks up the change.@@ -58,7 +58,7 @@ drafts/## Where the patterns live-Patterns are stored in a `.okignore` file at your project root, alongside `.gitignore`. It's checked into version control and shared with anyone who clones the repo. Hand-edit it directly in any editor; OpenKnowledge picks up changes the same way it picks up Settings edits.+Patterns are stored in a `.okignore` file at your project root, alongside `.gitignore`. If `content.dir` points somewhere other than the project root, Settings manages the `.okignore` at the content directory root instead. The file is checked into version control and shared with anyone who clones the repo. Hand-edit it directly in any editor; OpenKnowledge picks up changes the same way it picks up Settings edits. To check the resulting scope from the terminal, run `ok preview`; it shows what content OpenKnowledge will track, no server required.OpenKnowledge scaffolds a starter `.okignore` with a commented header the first time it sets up a project, so the file is there from day one.@@ -82,9 +82,9 @@ The negation is an OpenKnowledge behavior; `git` itself only reads `.gitignore`,## Temporarily surfacing hidden files-The sidebar always lists every file on disk under the content directory, including files excluded by `.gitignore` / `.okignore`. Dot-prefixed entries are the exception, so the sidebar's right-click menu and the macOS **View** menu carry a project-local **Show Hidden Files** toggle for when you need to see them without permanently editing `.okignore`:+The sidebar always lists every file on disk under the content directory, including files excluded by `.gitignore` / `.okignore` (listings truncate at 50,000 entries, deepest paths first). Dot-prefixed entries are the exception, so the sidebar's right-click menu and the macOS **View** menu carry a project-local **Show Hidden Files** toggle for when you need to see them without permanently editing `.okignore`:-- **Show Hidden Files** stops the client from hiding paths that start with `.` (recovers allowed dotfiles like `brain/.archived/note.md`). Tooling internals (`.git/`, `.ok/`, `node_modules/`) stay hidden in every mode.+- **Show Hidden Files** stops the client from hiding paths that start with `.` (recovers allowed dotfiles like `brain/.archived/note.md`). Tooling internals (`.git/`, `.ok/`, `node_modules/`), secret-bearing paths (`.env` files, private keys, credential files, `.ssh/`), and OS junk (`.DS_Store`) stay hidden in every mode.The setting persists per-project per-machine. See [Editor → Show Hidden Files](/docs/features/editor#show-hidden-files) for the full UX.diff --git a/docs/content/features/share.mdx b/docs/content/features/share.mdxindex d00397233..957df9262 100644--- a/docs/content/features/share.mdx+++ b/docs/content/features/share.mdx@@ -15,9 +15,9 @@ Click the Share button to copy a deep link to the current doc or folder to yourIf the project has no `origin` configured, the Share button opens the **Publish to GitHub** wizard. The wizard:1. Lists the GitHub accounts and orgs you can push to.-2. Validates the repo name as you type; name collisions, SAML SSO blocks, and rate-limit errors all surface inline.-3. On submit, creates the repository through GitHub's API, sets it as `origin`, and runs the initial `git push`.-4. Once the push lands, copies the share URL to your clipboard automatically.+2. Validates the repo name as you type; name collisions surface inline.+3. On submit, creates the repository through GitHub's API, sets it as `origin`, and runs the initial `git push`. SAML SSO blocks and other GitHub errors surface as a banner.+4. Once the push lands, shows the share URL with a **Copy share link** button.If the push fails after the repo was created (auth lost mid-flow, network blip), the wizard shows a **Retry push** affordance. The GitHub-side repo isn't recreated, only the push is retried.@@ -28,15 +28,15 @@ A share link points at GitHub, but your local edits only reach GitHub through au- **Not on GitHub yet.** The target has never been pushed, so the link won't resolve until it is. With auto-sync off, the row offers **Enable auto-sync** and **How to push manually**; with auto-sync on, it offers **Sync now** and clears itself once the push lands.- **Unpushed changes.** The target is on GitHub but has local edits that aren't, so recipients see the last pushed version. With auto-sync on this stays silent — the next sync closes the gap.-If you don't have write access to the repo, the row explains that instead of offering a push action. The check is local, adds no network round-trip, and never blocks sharing: if it can't run, the link still copies with no warning. Folder shares get the same treatment as docs.+If you don't have write access to the repo, the row explains that instead of offering a push action. The check is local, adds no network round-trip, and never blocks sharing: if it can't run, the link still copies with no warning. Folder shares get the same treatment as docs. Links minted by an agent get the same check: the [`share_link` MCP tool](/docs/reference/mcp) prepends the warning to its response so the agent can relay it with the link.## Opening a share link-The recipient clicks the URL and lands on a splash page showing the target (file or folder) name, the `owner/repo` path, and the branch from which it was shared.+The recipient clicks the URL and lands on a splash page showing the target (file or folder) name, the `owner/repo` path, and — for shares from a non-default branch — the branch name.The splash offers two ways to receive:-- **Desktop app (macOS).** Click **Open in OpenKnowledge** to fire the deep link into the OpenKnowledge desktop app — on the shared doc, folder overview, or project root depending on what was shared. **Download for macOS** ships the arm64 DMG for recipients who don't yet have the app.+- **Desktop app (macOS).** Click **Open in macOS app** to fire the deep link into the OpenKnowledge desktop app — on the shared doc, folder overview, or project root depending on what was shared. **Download the app** ships the arm64 DMG for recipients who don't yet have the app; the download remembers the share (a first-party cookie, valid for seven days), and the app opens the shared target on its first launch.- **CLI (macOS and Linux).** Copy the pre-filled `npm install -g @inkeep/open-knowledge` then `ok clone <owner/repo> -b <branch>` from the splash to clone the repo locally and open the editor. The clone command is always branch-pinned, but if the feature branch has been deleted, it will fall back to the default branch. See the [CLI reference](/docs/reference/cli#clone-from-github) for `ok clone` and related commands.## What the desktop app does when it receives the link@@ -56,14 +56,16 @@ If you have the repo open locally but on a different branch, the app opens a bra- **Moved.** If GitHub shows the target was renamed, the dialog offers to open it at its new path.- **Removed, or never pushed.** A deleted target is messaged as removed from the branch; a path that never existed on the branch is messaged as "may not have been pushed yet." The two are distinct, and neither drops you into an empty create-mode editor.-If OpenKnowledge can't reach GitHub to make this call, it falls back to today's "pull the latest, then re-open" guidance.+If uncommitted changes conflict with the switch, switching is disabled until you commit or stash them; if the share's branch is already checked out in another worktree, the dialog offers to open that worktree instead.++If OpenKnowledge can't reach GitHub to make this call, the dialog falls back to the plain switch; the "pull the latest changes, then open the link again" guidance appears only if the target is still missing after the switch.### When the shared target has moved or been removed-Even on the right branch, a doc or folder can be renamed or deleted after a link is minted. Rather than opening an empty editor at the old path — where you could unknowingly start a divergent copy — OpenKnowledge shows an honest terminal panel with the same verdict-driven copy as the branch-switch dialog: an offer to open a renamed target at its new path, a plain "removed from this branch" message with a link back to the parent folder, or "not pushed yet" when the path never existed. If the check can't reach GitHub, it falls back to the usual pull-and-retry guidance.+Even on the right branch, a doc or folder can be renamed or deleted after a link is minted. Rather than opening an empty editor at the old path — where you could unknowingly start a divergent copy — OpenKnowledge shows a dialog before navigating (or an in-tab panel, if the miss is only discovered after a tab opens) with the same verdict-driven copy as the branch-switch dialog: an offer to open a renamed target at its new path, a plain "removed from this branch" message with a link back to the parent folder, or "not pushed yet" when the path never existed. A target you moved, renamed, or deleted in your own local copy gets a fourth verdict: commit your changes or enable auto-sync. If the check can't reach GitHub, it falls back to the usual pull-and-retry guidance.### Receiving without push permission-If the shared repo is one your GitHub account can't push to (you're not a collaborator on a public repo, or you have read-only access on a private one), OpenKnowledge skips the usual "Enable auto-sync?" prompt. Sync is also disabled for the same reason in **Settings → Sync**. If the project owner grants you write access later, click the sync indicator to re-check; OpenKnowledge will pick up the change without an app restart. See [GitHub sync: GitHub-side blockers](/docs/features/github-sync#github-side-blockers) for the full set of permission shapes the sync UI handles.+If the shared repo is one your GitHub account can't push to (you're not a collaborator on a public repo, or you have read-only access on a private one), OpenKnowledge skips the usual "Enable auto-sync?" prompt. Sync is also disabled for the same reason in **Settings → Sync**. If the project owner grants you write access later, push permission is re-checked the next time the project's server starts. See [GitHub sync: GitHub-side blockers](/docs/features/github-sync#github-side-blockers) for the full set of permission shapes the sync UI handles.See [GitHub sync](/docs/features/github-sync) for how to automatically sync changes to GitHub, and [Timeline and recovery](/docs/features/timeline-and-recovery) for per-doc history once the doc is open.diff --git a/docs/content/features/skills.mdx b/docs/content/features/skills.mdxindex 81e8dd00b..7121888a1 100644--- a/docs/content/features/skills.mdx+++ b/docs/content/features/skills.mdx@@ -1,10 +1,10 @@---title: Skillsicon: LuGraduationCap-description: "What's different about skills in OpenKnowledge: you edit them in the WYSIWYG editor like any doc, version them as content, and symlink one skill into every editor you use."+description: "What's different about skills in OpenKnowledge: you edit them in the WYSIWYG editor like any doc, version them with your base, and symlink one skill into every editor you use."----A skill in OpenKnowledge is content, not a config file: authored in the WYSIWYG editor, versioned like any doc, and symlinked into every editor from one source.+A skill in OpenKnowledge is content, not a config file: authored in the WYSIWYG editor, versioned with your base, and symlinked into every editor from one source.```html preview<div style="padding:18px">@@ -64,10 +64,34 @@ A project skill is not a raw text file you hand-edit in a dotfile. It is a docum`install` **symlinks** the skill into each editor's skills directory (Claude Code, Cursor, Codex, OpenCode). Every editor points at the one `.ok/skills/<name>` source, so nothing is copied and nothing drifts: edit the skill once and every agent has the change, with no re-install.+## Create and install a skill++Create a skill from the sidebar's **Skills** section: **New skill** asks for a scope, a name (the id agents use to invoke it), and a description (what agents match on to decide when to use it), then opens the new `SKILL.md` as an editor tab. A skill can also bundle `references/` and `scripts/` files beside its `SKILL.md`; agents read those through the [`skills` MCP tool](/docs/reference/mcp), never by browsing `.ok/`.++A new skill starts as a **Draft**: authored but installed nowhere. Install it from the skill's toolbar, per editor or all at once, and it becomes **Installed**. The project's default editor set lives in **Settings → Skills**, saved to `.ok/skill-targets.json` in the base so teammates inherit it.+## Two scopes-- **Project** skills live in the base, versioned and shared with it like any other content. The one every project ships with is what makes an agent behave well the moment you connect it: read and write through the tools, cite sources, keep the link graph healthy.-- **Global** skills follow you across every project on your machine.+- **Project** skills live in the base, versioned and shared with it like any other content.+- **Global** skills live in `~/.ok/skills` and follow you across every project on your machine. Outside any base, they carry no version history.++The skill that makes an agent behave well the moment you connect it (read and write through the tools, cite sources, keep the link graph healthy) is neither: `open-knowledge` is built into the product and never appears in your skills list.++Moving a skill between scopes re-creates it in the destination scope: history does not transfer, and it lands as a Draft you install again.++## Import existing editor skills++By default, OpenKnowledge manages only the skills under `.ok/skills`: anything you already keep in `.claude/skills`, `.cursor/skills`, and the like is left alone. When the app finds editor skills it could manage, it offers to import them, moving each one into `.ok/skills` and replacing the editor copy with a symlink.++The same switch is available from the CLI:++```bash+ok skills manage --on # import existing editor skills and adopt new ones+ok skills manage --off # stop adopting; existing skills and symlinks stay+ok skills manage --status # print the current setting+```++Skills already under `.ok/skills` stay managed either way.<Callout type="warn">Skills are an open standard, and a skill can carry scripts that run on your machine. Treat a third-party skill like installing software. Use trusted sources, and read what it does first.diff --git a/docs/content/features/timeline-and-recovery.mdx b/docs/content/features/timeline-and-recovery.mdxindex b470f075b..52e4a65f7 100644--- a/docs/content/features/timeline-and-recovery.mdx+++ b/docs/content/features/timeline-and-recovery.mdx@@ -18,11 +18,15 @@ Timeline entries include:- **Upstream sync** entries from Git- **File system** changes made outside of OpenKnowledge+Project-wide checkpoints saved by agents via the [`checkpoint` MCP tool](/docs/reference/mcp#tools) do not appear on the timeline; agents find and restore them with the `history` and `restore_version` tools.++The timeline is per branch: it shows the branch's own edits, plus history from before the branch diverged from `main`. History is stored in a shadow git repo inside your project, so entries and attribution survive app restarts and agent sessions — see [Attribution and collaboration](/docs/reference/core-concepts#attribution-and-collaboration).+## Review changes-Click a timeline entry to expand it. OpenKnowledge shows an inline diff so you can compare that version with the current document. If that version is the same as the current document, you will see `no changes`.+Click a timeline entry to expand it. OpenKnowledge shows an inline diff so you can compare that version with the current document. If that version has the same body as the current document ([properties](/docs/features/editor#properties) are not part of the diff), you will see `No changes`.-You can switch between unified and split diff layouts from the editor controls.+You can switch between unified and split diff layouts from the toggle at the top of the timeline panel (shown once the timeline has entries).diff --git a/docs/content/get-started/overview.mdx b/docs/content/get-started/overview.mdxindex 5ac44ab46..1beea7ec4 100644--- a/docs/content/get-started/overview.mdx+++ b/docs/content/get-started/overview.mdx@@ -20,7 +20,7 @@ OpenKnowledge is three layers working together: a "WYSIWYG" editor for you, MCP## Additional Features- "Ask AI" experience for opening your knowledge base in your favorite agent- No-code **team sharing** and **Auto-sync** powered by git/GitHub under the hood.-- A **built-in TUI** in the desktop app for Claude and Codex+- A **built-in TUI** in the desktop app for Claude, Codex, OpenCode, and Cursor- Graph and wiki link visualizations- **Embeddable HTML** for writing engineering specs and visualized reports.diff --git a/docs/content/get-started/quickstart.mdx b/docs/content/get-started/quickstart.mdxindex 4235818b3..06c8a291f 100644--- a/docs/content/get-started/quickstart.mdx+++ b/docs/content/get-started/quickstart.mdx@@ -28,7 +28,8 @@ Download the latest version of the OpenKnowledge desktop app for macOS.### Create a new project-- Open the OpenKnowledge app and click **Create new project**.+- Open the OpenKnowledge app. On first launch, approve the **Add OpenKnowledge to your AI tools** dialog — it wires up your AI editors and can add the `ok` command to your terminal. If you skip it, re-open it later from **File → Set up OpenKnowledge integrations…**.+- Click **Create new project**.- Type a name for your project (for example, *Team Wiki*).- Optionally click **Browse** to change where the project is saved, then click **Create**.@@ -121,7 +122,7 @@ Install the CLI from npm, initialize a project, and start the editor in your bronpm install -g @inkeep/open-knowledge# Create (or enter) a project folder, then initialize a knowledge base.-# `ok init` scaffolds .ok/ and wires up Claude Code, Cursor, Codex, and OpenCode.+# `ok init` scaffolds .ok/ and wires up Claude Code, Claude Desktop, Cursor, Codex, OpenCode, and OpenClaw.mkdir my-knowledge-base && cd my-knowledge-baseok init@@ -139,7 +140,7 @@ ok start --open### Open the knowledge base in your AI agent-`ok init` already registered OpenKnowledge with the AI editors it could configure, so your agent can use the OpenKnowledge tools right away. Open your project in your agent — or, from the editor, right-click the project in the sidebar, choose **Open with AI ▸**, and pick one. (The bottom **Ask AI** field is available in the desktop app only.) If a tool's MCP entry didn't appear, see [registration outcomes](/docs/reference/cli#set-up-a-project).+`ok init` already registered OpenKnowledge with the AI editors it could configure, so your agent can use the OpenKnowledge tools right away. Open your project in your agent — or, from the editor, right-click the project in the sidebar, choose **Open with AI ▸**, and pick one. (With a document open, the bottom **Ask AI** field hands a prompt to your agent too.) If a tool's MCP entry didn't appear, see [registration outcomes](/docs/reference/cli#set-up-a-project).In the agent's chat window, add the following to get started or use a topic of your choice:diff --git a/docs/content/integrations/claude-code.mdx b/docs/content/integrations/claude-code.mdxindex e4b23d588..c33c16ba3 100644--- a/docs/content/integrations/claude-code.mdx+++ b/docs/content/integrations/claude-code.mdx@@ -9,6 +9,8 @@ OpenKnowledge works with Claude Code through MCP plus an installed skill that te- **Claude Code CLI** — the `claude` command in your terminal.- **Claude Desktop app** — Claude Code in the **Code** tab.+Claude Desktop's regular chat can use the tools too — see [Claude Desktop chat](#claude-desktop-chat).+## Install<McpInstall editor="Claude Code" />@@ -25,8 +27,16 @@ Open the project in Claude Code and ask:<VerifyExec subject="Claude Code" />-If Claude Code doesn't use the OpenKnowledge `exec` tool, restart it so it picks up the new MCP entry. If it's still missing and `ok init` reported your config was `left unchanged`, OpenKnowledge couldn't parse `~/.claude.json` safely and left it untouched — fix the config and re-run `ok init`.+If Claude Code doesn't use the OpenKnowledge `exec` tool, restart it so it picks up the new MCP entry. If it's still missing and `ok init` reported your config was `left unchanged`, OpenKnowledge couldn't edit `~/.claude.json` safely and left it untouched — the summary names the reason in parentheses; fix the config and re-run `ok init`.## Live editingWhen Claude Code writes to a doc, you'll see the change land live in OpenKnowledge. Just ask Claude Code to open it for you.++## Claude Desktop chat++`ok init` and the consent dialog also register the MCP server with Claude Desktop when it's installed — user-level, in `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS or `%APPDATA%\Claude\claude_desktop_config.json` on Windows. Claude Desktop picks up the entry only after you quit and relaunch it.++After relaunching, ask in any chat:++<VerifyExec subject="Claude Desktop" />diff --git a/docs/content/integrations/codex.mdx b/docs/content/integrations/codex.mdxindex 7deafed6b..ddaffccdc 100644--- a/docs/content/integrations/codex.mdx+++ b/docs/content/integrations/codex.mdx@@ -12,7 +12,7 @@ OpenKnowledge plugs into Codex through MCP.## Open with AI-From the editor, **Open with AI ▸ Codex** dispatches the current file, folder, or project to Codex in one click. Two entry points: the sidebar's right-click menu (file / folder / empty space) and the macOS **File → Open with AI** menu. You can also hand the current doc to Codex from the bottom **Ask AI** composer.+From the editor, **Open with AI ▸ Codex** dispatches the current file, folder, or project to Codex in one click. Entry points include the sidebar's right-click menu (file / folder / empty space), the macOS **File → Open with AI** menu, and the Command Palette. You can also hand the current doc to Codex from the bottom **Ask AI** composer.Codex receives a short prompt asking it to open the target in OpenKnowledge's web preview. The agent then grounds the rest of the conversation through MCP. See [Editor → Open with AI](/docs/features/editor#open-with-ai) for the full UX.@@ -22,4 +22,4 @@ Open the project in Codex and ask:<VerifyExec />-If you don't see the tool, restart Codex. If it's still missing and `ok init` reported your config was `left unchanged`, OpenKnowledge couldn't parse `~/.codex/config.toml` safely and left it untouched — fix the config and re-run `ok init`.+If you don't see the tool, restart Codex. If it's still missing and `ok init` reported your config was `left unchanged`, the reason in parentheses says why `~/.codex/config.toml` (or `$CODEX_HOME/config.toml` if set) was left untouched. For config problems, fix the file and re-run `ok init`; for `no format-preserving writer available`, your config isn't the problem — OpenKnowledge can't rewrite the file safely on this platform, so add an `open-knowledge` entry to `mcp_servers` by hand (command: `ok mcp`).diff --git a/docs/content/integrations/cursor.mdx b/docs/content/integrations/cursor.mdxindex 3bbd0d48b..1aca95c9a 100644--- a/docs/content/integrations/cursor.mdx+++ b/docs/content/integrations/cursor.mdx@@ -16,11 +16,11 @@ Cursor prompts you to approve a new MCP server when you next open the project. A## Open with AI-From the editor, **Open with AI ▸ Cursor** dispatches the current file, folder, or project to Cursor. Two entry points: the sidebar's right-click menu (file / folder / empty space) and the macOS **File → Open with AI** menu. You can also hand the current doc to Cursor from the bottom **Ask AI** composer.+From the editor, **Open with AI ▸ Cursor** dispatches the current file, folder, or project to Cursor. Entry points: the sidebar's right-click menu (file / folder / empty space), the command palette, and the macOS **File → Open with AI** menu. You can also hand the current doc to Cursor from the bottom **Ask AI** composer.Cursor uses a two-step handoff: OpenKnowledge spawns `cursor <projectDir>` to open the workspace first, then fires the `cursor://` URL with a short prompt asking Cursor to open the target in OpenKnowledge's web preview. The agent then grounds the rest of the conversation through MCP. See [Editor → Open with AI](/docs/features/editor#open-with-ai) for the full UX.-In the web app, Cursor's spawn step runs through a local `POST /api/spawn-cursor` fallback, so the **Open with AI ▸ Cursor** row works there too — not just in the desktop app.+Both steps run through the local server's `POST /api/handoff`, the same path in the web app and the desktop app — so the **Open with AI ▸ Cursor** row works in both.## Verify@@ -28,4 +28,4 @@ Ask the agent:<VerifyExec />-If it still doesn't see the tool after approval, restart Cursor so it picks up the new MCP entry. If it's still missing and `ok init` reported your config was `left unchanged`, OpenKnowledge couldn't parse `~/.cursor/mcp.json` safely and left it untouched — fix the config and re-run `ok init`.+If it still doesn't see the tool after approval, restart Cursor so it picks up the new MCP entry. If it's still missing and `ok init` reported your config was `left unchanged`, OpenKnowledge couldn't safely edit `~/.cursor/mcp.json` for the reason shown in parentheses (unreadable, too large, or a duplicate server block) — fix the config and re-run `ok init`.diff --git a/docs/content/integrations/openclaw.mdx b/docs/content/integrations/openclaw.mdxindex 38c707c93..6be94403a 100644--- a/docs/content/integrations/openclaw.mdx+++ b/docs/content/integrations/openclaw.mdx@@ -10,9 +10,9 @@ OpenClaw is an agent gateway: it runs agents that connect to MCP servers. Once O<McpInstall editor="OpenClaw"><p>- After <code>ok init</code> writes the config, run <code>openclaw mcp reload</code> so active- agents pick up the entry — <code>ok start</code> isn't needed here, since OpenClaw manages its- own server lifecycle.+ After <code>ok init</code> writes the config, restart the OpenClaw gateway so running agents+ pick up the entry — <code>openclaw mcp reload</code> refreshes the current CLI process only.+ <code>ok start</code> isn't needed here, since OpenClaw manages its own server lifecycle.</p></McpInstall>@@ -39,14 +39,14 @@ Unrelated config-health or plugin-version warnings for *other* servers don't blo<VerifyExec subject="OpenClaw" />-If the agent doesn't see the tool, run tool discovery — some runtimes lazy-load MCP tools and only surface them after a search, so absence from the initial list means "not discovered yet," not "not registered" — then `openclaw mcp reload`.+If the agent doesn't see the tool, run tool discovery — some runtimes lazy-load MCP tools and only surface them after a search, so absence from the initial list means "not discovered yet," not "not registered" — then restart the gateway.## Initialize a knowledge base`ok init` turns a folder into a knowledge base (and, on the same run, registers the MCP server above):```bash-ok init /path/to/your/knowledge-base+cd /path/to/your/knowledge-base && ok init```<Callout type="warn">@@ -62,7 +62,7 @@ A copy-pasteable, end-to-end check that proves the whole stack — not just "the<Step>### Discover the tools-If `mcp__open-knowledge__*` isn't in the agent's tool list, run tool discovery first — absence from the initial list means "not discovered yet," not "not registered."+If the `open-knowledge` server's tools aren't in the agent's tool list, run tool discovery first — absence from the initial list means "not discovered yet," not "not registered."</Step><Step>@@ -105,7 +105,7 @@ Write and edit responses include a route-only preview path like `/#/notes/mcp-ro## Agent contract-`ok init` installs the **OpenKnowledge skill** — the authoritative agent contract for tool use, grounding, and linking — and OpenClaw loads installed skills from `~/.agents/skills/`. Rather than restate the contract here, two OpenClaw-specific reminders:+The **OpenKnowledge skill** — the authoritative agent contract for tool use, grounding, and linking — is project-scoped, written for Claude, Cursor, Codex, and OpenCode; OpenClaw has no project skill directory to receive it. The bundles OpenKnowledge installs to `~/.agents/skills/` (which OpenClaw loads) cover discovery and skill authoring, not tool use — so for OpenClaw agents, the contract is these two reminders:- **Markdown is MCP-owned.** Inside an OK project, read and write `.md` / `.mdx` through OK's tools (`exec`, `search`, `write`, `edit`, `links`), not native shell or file tools — native access loses attribution and skips the frontmatter, backlinks, and history OK returns.- **Discover before concluding the MCP is missing.** Not seeing `exec` in the initial tool list isn't the escape hatch; run tool discovery first.@@ -117,9 +117,9 @@ For the complete tool surface, see the [MCP reference](/docs/reference/mcp).| Symptom | Cause | Fix || --- | --- | --- || `ok init` showed OpenClaw as `config root missing; skipped` | `~/.openclaw/` doesn't exist yet, so OpenClaw wasn't detected | Launch OpenClaw once (it creates its home directory), then re-run `ok init` |-| `ok init` reported the config was `left unchanged` | OpenKnowledge couldn't safely parse `~/.openclaw/openclaw.json` | Fix the JSON and re-run `ok init` |+| `ok init` reported the config was `left unchanged` | OpenKnowledge declined to edit `~/.openclaw/openclaw.json` for the reason shown in parentheses | Fix what the reason names (invalid JSON, a duplicated server block, an oversize config), then re-run `ok init` || `openclaw mcp probe` shows 0 tools | server couldn't launch, or the folder isn't a KB yet | Confirm `ok` is installed (desktop app or `npm i -g @inkeep/open-knowledge`), and `ok init` the folder |-| Agent doesn't see `mcp__open-knowledge__*` | MCP tools lazy-loaded | Run tool discovery, then `openclaw mcp reload` |+| Agent doesn't see the `open-knowledge` tools | MCP tools lazy-loaded, or the agent's process predates the entry | Run tool discovery, then restart the gateway || `ok init` "refreshed" a parent project, no new KB | upward project resolution | Run `ok init` outside any existing `.ok` tree || Broken-link warning on a just-written doc | forward link to a not-yet-created target | Create the target, then re-check `links({ kind: "dead" })` || `write` / `edit` -> "Hocuspocus server is not running" | OK server not started | Run `ok start` (or leave the desktop app running) and retry |diff --git a/docs/content/integrations/opencode.mdx b/docs/content/integrations/opencode.mdxindex 94df821bd..f48e926ef 100644--- a/docs/content/integrations/opencode.mdx+++ b/docs/content/integrations/opencode.mdx@@ -10,7 +10,7 @@ OpenKnowledge plugs into [OpenCode](https://opencode.ai) through MCP. OpenCode i<McpInstall editor="OpenCode" />-OpenCode reads MCP servers from `opencode.json` in the project root, or `~/.config/opencode/opencode.json` for a global install. `ok init` writes the `open-knowledge` server under the top-level `mcp` key in both, using the same resilient launcher every other editor gets. OpenCode also picks up the OpenKnowledge skill from the shared `.agents/skills/` directory automatically.+OpenCode reads MCP servers from `opencode.json` in the project root, or `~/.config/opencode/opencode.json` for a global install. `ok init` writes the `open-knowledge` server under the top-level `mcp` key in both, using the same resilient launcher every other editor gets. It also installs the OpenKnowledge skill to `.opencode/skills/open-knowledge/`, which OpenCode scans automatically.## Use a local model@@ -42,4 +42,4 @@ Open the project in OpenCode and ask:<VerifyExec subject="OpenCode" />-If OpenCode doesn't use the OpenKnowledge `exec` tool, restart it so it picks up the new MCP entry, and make sure the model you selected supports tool calling. If it's still missing and `ok init` reported your config was `left unchanged`, OpenKnowledge couldn't parse your `opencode.json` safely and left it untouched — fix the config and re-run `ok init`.+If OpenCode doesn't use the OpenKnowledge `exec` tool, restart it so it picks up the new MCP entry, and make sure the model you selected supports tool calling. If it's still missing and `ok init` reported your config was `left unchanged`, OpenKnowledge declined to edit your `opencode.json` for the reason shown in parentheses — an unreadable file, a duplicate `mcp` block, or a config too large to edit safely. Fix that and re-run `ok init`.diff --git a/docs/content/meta.json b/docs/content/meta.jsonindex ee64d4832..1c24cbd65 100644--- a/docs/content/meta.json+++ b/docs/content/meta.json@@ -4,16 +4,16 @@"pages": ["---GET STARTED---","...get-started",- "---WORKFLOWS---",+ "---USE CASES---","...workflows",- "---MIGRATE---",- "...migrate","---INTEGRATIONS---","...integrations","---FEATURES---","...features","---ADVANCED---","...advanced",+ "---IMPORT & TRY---",+ "...migrate","---REFERENCE---","...reference"]diff --git a/docs/content/migrate/notion.mdx b/docs/content/migrate/notion.mdxindex d88c15ba0..edb28aef8 100644--- a/docs/content/migrate/notion.mdx+++ b/docs/content/migrate/notion.mdx@@ -4,7 +4,7 @@ description: How to export a Notion workspace to Markdown and open it in OpenKnoicon: LuFileInput----This guide will cover exporting your Notion workspace to markdown files so that you can access them from OpenKnowledge. There are several key differences between OpenKnowledge and Notion that make this export incomplete and those will be covered here.+This guide will cover exporting your Notion workspace to markdown files so that you can access them from OpenKnowledge. OpenKnowledge and Notion differ in a few key ways, so a Notion export needs some cleanup — this guide covers what carries over and what to fix.## Install OpenKnowledge@@ -42,10 +42,10 @@ ok migrate notion /path/to/unzipped-export --apply```<Callout type="info">- The desktop app installs the CLI automatically the- first time you launch it. If `ok` isn't found: make sure you've opened the- OpenKnowledge app at least once, then open a new terminal window. If it's still missing, add- `$HOME/.ok/bin` to your `PATH` manually.+ The desktop app installs the CLI to `$HOME/.ok/bin`; a pre-checked toggle in+ its first-launch dialog puts `ok` on your `PATH`. If `ok` isn't found, add it+ from **File → Set up OpenKnowledge integrations…**, then open a new terminal+ window. If it's still missing, add `$HOME/.ok/bin` to your `PATH` manually.</Callout>Every transform is **idempotent**, so re-running is safe. See the tables below for a full list of differences between the Notion export and what OpenKnowledge supports.diff --git a/docs/content/migrate/obsidian.mdx b/docs/content/migrate/obsidian.mdxindex ca25f8b0e..c0c79076b 100644--- a/docs/content/migrate/obsidian.mdx+++ b/docs/content/migrate/obsidian.mdx@@ -7,7 +7,7 @@ description: How to open an existing Obsidian vault in OpenKnowledge, which markOpenKnowledge and Obsidian are both editors over a [folder of plain markdown](/docs/reference/core-concepts#the-file-system-is-the-database). This means that you can point OpenKnowledge at your existing vault and your notes, links, tags, and frontmatter work out of the box.<Callout type="info">- OpenKnowledge works **directly on your markdown files** — it never moves, renames, or rewrites them just for opening a vault. It keeps its own state in a `.ok/` directory and ignores Obsidian's `.obsidian/` folder, so your Obsidian setup stays exactly where it is.+ OpenKnowledge works **directly on your markdown files** — it never moves, renames, or rewrites them just for opening a vault. It keeps its own state in a `.ok/` directory and ignores Obsidian's `.obsidian/` folder, so your Obsidian setup stays exactly where it is. To back out, `ok deinit` removes everything OpenKnowledge added to the vault and leaves your markdown untouched.</Callout>## Open your vault@@ -63,7 +63,7 @@ A handful of Obsidian features are not supported, or behave differently. None ofGetting an AI agent to work *well* inside an Obsidian vault usually means adding an agent-skills layer on top — a set of `SKILL.md` instructions that teach the agent your conventions and how to read and write the vault. OpenKnowledge builds that layer in, so there's nothing to bolt on:- **A project skill is installed for you.** `ok init` (or the desktop setup) drops in a project-local skill that teaches your agent OpenKnowledge's tools and conventions — no hand-written `CLAUDE.md` to maintain.-- **Agents get first-class tools, not just file access.** The [MCP server](/docs/reference/mcp) gives any MCP-capable agent — Claude Code, Cursor, Codex, OpenCode — typed `read` / `write` / `search` / `links` tools over the same files, so edits are consistent, attributed, and keep your link graph healthy.+- **Agents get first-class tools, not just file access.** The [MCP server](/docs/reference/mcp) gives any MCP-capable agent — Claude Code, Cursor, Codex, OpenCode, OpenClaw — typed `exec` (read) / `write` / `search` / `links` tools over the same files, so edits are consistent, attributed, and keep your link graph healthy.## See alsodiff --git a/docs/content/reference/agentic-search.mdx b/docs/content/reference/agentic-search.mdxindex b89fc9c84..e1c6a245e 100644--- a/docs/content/reference/agentic-search.mdx+++ b/docs/content/reference/agentic-search.mdx@@ -191,7 +191,7 @@ set("ok");That folder briefing is why the loop stays short: the backlinks are what it follows, and the purpose plus recency tell it where to look next.-Three read tools ride this layer: ranked **search** (BM25 and recency, the same index as cmd-K), **`exec`** (sandboxed `grep`/`ls`/`cat`, straight off disk, works with the server down), and the **link graph** (`dead`, `orphans`, `hubs`, `suggest`).+Three read tools ride this layer: ranked **search** (BM25 and recency, the same index as cmd-K), **`exec`** (sandboxed `grep`/`ls`/`cat`/`find` and friends, pipeable, straight off disk; works with the server down, minus backlinks and outbound links), and **`links`** (the link graph: `backlinks`, `forward`, `dead`, `orphans`, `hubs`, `suggest`). `search` takes an `intent` (`omnibar` for fast title/path/folder lookups; the default `full_text` ranks body content too), result `scopes`, and a `limit` (default 20, max 100). Right after the server boots it can answer `ready: false` with empty results while the index builds; retry after a couple of seconds instead of treating that as no matches, and fall back to `exec` grep if it persists.## Writing talks back too@@ -240,13 +240,13 @@ set("ok");</script>```-`brokenLinks` comes back on every write and edit (empty when they all resolve), so the agent never needs a follow-up dead-link check. A brand-new doc nothing points to comes back flagged as an orphan with a hub to link it from. Every write and edit is versioned, attributed, and the preview updates as it lands. None of that happens when you append to a file by hand. [Skills](../features/skills.mdx) teach the conventions, and the write path enforces the connective tissue.+`brokenLinks` comes back on every write and edit (empty when they all resolve), so the agent never needs a follow-up dead-link check. A brand-new doc nothing points to comes back flagged as an orphan with a hub to link it from. Every write and edit is versioned, attributed, and the preview updates as it lands. Append to a file by hand and the edit still lands: the file watcher folds it into the live doc and versions it, but anonymously, as `file-system`, and nothing talks back. [Skills](../features/skills.mdx) teach the conventions, and the write path enforces the connective tissue.## The index is authored, not extracted-No vector store means no second copy to rebuild, mis-chunk, or drift. Your links, folders, titles, and folder descriptions *are* the index. Other tools extract structure with an embedding model or an entity-guessing LLM; OpenKnowledge reads the structure you already wrote, so the agent traverses the source of truth. A well-linked base retrieves better because good links shorten the loop. [Folder templates](../advanced/folders-and-templates.mdx) keep that structure consistent as it grows: a folder can carry a template, so every new doc the agent creates starts with the same frontmatter and shape, and the fields search ranks on stay uniform.+No vector store means no second copy to rebuild, mis-chunk, or drift. Your links, folders, titles, and folder descriptions *are* the index. Other tools extract structure with an embedding model or an entity-extracting LLM; OpenKnowledge reads the structure you already wrote, so the agent traverses the source of truth. A well-linked base retrieves better because good links shorten the loop. [Folder templates](../advanced/folders-and-templates.mdx) keep that structure consistent as it grows: a folder can carry a template that the write path surfaces at create time, so docs the agent starts from it share the same frontmatter and shape, and the fields search ranks on stay uniform.## Semantic search (optional)-Off by default. Enable it per project and an embeddings signal blends into the ranking; it never replaces lexical search. Vectors sit in a local cache. Turning it on sends your query and matching text to your configured provider. See [Configuration](./configuration.mdx).+Off by default. Enable it per project, per machine (each collaborator opts in on their own), and an embeddings signal blends into the ranking; it never replaces lexical search. Vectors sit in a local cache. Turning it on sends your query and matching text to your configured provider. See [Configuration](./configuration.mdx).diff --git a/docs/content/reference/cli.mdx b/docs/content/reference/cli.mdxindex 91c50bda0..93a44fd29 100644--- a/docs/content/reference/cli.mdx+++ b/docs/content/reference/cli.mdx@@ -1,13 +1,13 @@---title: CLI & web appicon: LuTerminal-description: Install the ok CLI and run the OpenKnowledge web app in your browser — on Linux or an Intel Mac.+description: Install the ok CLI and run the OpenKnowledge web app in your browser — on Linux, Windows, or an Intel Mac.----On macOS, use the [desktop app](/docs/get-started/quickstart) for the smoothest experience. On **Linux** or an **Intel Mac**, install the `ok` CLI from npm and run the **same editor as a local web app** in your browser.+On macOS, use the [desktop app](/docs/get-started/quickstart) for the smoothest experience. On **Linux**, **Windows**, or an **Intel Mac**, install the `ok` CLI from npm and run the **same editor as a local web app** in your browser.<Callout type="info" title="Prerequisites">- **Node.js 24+.** OpenKnowledge requires [Node.js](https://nodejs.org) 24 or higher.- - **`git`.** OpenKnowledge initializes a git repo for your project (used for the timeline and recovery features). On macOS it comes with the Xcode Command Line Tools (`xcode-select --install`); on Linux, install it from [git-scm.com](https://git-scm.com) or your package manager.+ - **`git`.** OpenKnowledge initializes a git repo for your project (used for the timeline and recovery features). On macOS it comes with the Xcode Command Line Tools (`xcode-select --install`); on Linux or Windows, install it from [git-scm.com](https://git-scm.com) or your package manager.</Callout>@@ -21,13 +21,17 @@ npm install -g @inkeep/open-knowledge## Set up a project-Run `ok init` in any folder to turn it into an OpenKnowledge project. It scaffolds a `.ok/` directory and registers the OpenKnowledge MCP server with the AI editors it detects on your machine (Claude Code, Cursor, Codex, OpenCode). It only ever adds its own entry — your other settings, comments, and formatting are left untouched.+Run `ok init` in any folder to turn it into an OpenKnowledge project. It scaffolds a `.ok/` directory and registers the OpenKnowledge MCP server with the AI editors it detects on your machine (Claude Code, Claude Desktop, Cursor, Codex, OpenCode, OpenClaw). It only ever adds its own entry — your other settings, comments, and formatting are left untouched.```bashcd my-projectok init```+`ok init` asks two questions: where to register the MCP server (user-level, project-level, or both) and whether to share the OpenKnowledge config files with your team (committed alongside your content) or keep them local to this machine.++In a sub-folder of a git repo, `ok init` sets the project up at the git root — one `.ok/` per repo — and the whole repo becomes the content scope. Pass `--content-dir <dir>` to limit content to one folder (`ok init --content-dir .` scopes it to the folder you run in); the choice is saved as `content.dir` in `.ok/config.yml`. For scripts, `--json` prints a structured JSON summary.+<Callout type="info" title="If an editor shows “left unchanged”">When an editor's config can't be parsed safely — it's not valid JSON/TOML, has two MCP server blocks, or is unusually large — OpenKnowledge leaves the file **byte-for-byte untouched** and prints `left unchanged (<reason>)` instead of registering. It never rewrites or resets a config it can't fully understand. Fix the underlying config (the editor itself usually reports the parse error) and re-run `ok init`.</Callout>@@ -38,6 +42,8 @@ Once you have initialized your project, launch the app in your browser:ok start --open```+`ok start` also takes `-p/--port` and `-H/--host` to pick the address, and `--mode app` to hand off to the desktop app instead of running a server in the terminal (macOS with the desktop app installed; can't be combined with `--open`).+For a complete list of every file OpenKnowledge creates or changes — during install, at runtime, and in the desktop app — see [What OpenKnowledge writes to your system](/docs/reference/what-open-knowledge-writes).## Editing a single file@@ -58,7 +64,7 @@ You can pull repositories directly from GitHub and open them with OpenKnowledge:ok clone <owner/repo>```-`ok clone` accepts a full `https://github.com/...` URL or the `owner/repo` shorthand. It clones the repository, initializes OpenKnowledge if it isn't already, and opens the editor.+`ok clone` accepts a full `https://github.com/...` URL or the `owner/repo` shorthand. It clones the repository, initializes OpenKnowledge if it isn't already, and starts the local server — open the printed Editor URL in your browser.Pin a branch with `-b <branch>`:@@ -76,6 +82,20 @@ ok auth loginIf you're already logged in with the `gh` CLI, you can skip this step.+`ok auth` also provides `status` (show who's logged in), `repos` (list repositories you can access), `signout` (remove stored credentials), and `pat` (store a Personal Access Token). Every subcommand takes `--host <hostname>` for GitHub Enterprise.++## Sync with GitHub++Sync a project with its remote from the terminal:++| Command | What it does |+| --- | --- |+| `ok sync` | Commit, pull, and push to the remote |+| `ok pull` | Pull changes from the remote |+| `ok push` | Push commits to the remote |++Each command goes through the running server when one is up and falls back to plain git otherwise; pass `--json` for JSONL progress events when scripting. See [GitHub sync](/docs/features/github-sync) for how syncing works.+## Manage local serversEach project runs its own local server. These commands let you see and stop them:@@ -84,9 +104,32 @@ Each project runs its own local server. These commands let you see and stop them| --- | --- || `ok status` | Show whether a server and UI are running for the current project || `ok ps` | List every running OpenKnowledge server on your machine |-| `ok stop` | Stop the server for the current directory (or pass a port, a path, pid or `all` to stop all servers). |+| `ok stop` | Stop the server for the current directory — or pass a port, path, or PID to stop a specific server, or `all` to stop every server || `ok clean` | Remove stale lock files left behind by a crash (never touches live servers) |+## More commands++| Command | What it does |+| --- | --- |+| `ok seed` | Scaffold a starter pack into the project (`--list-packs` to browse, `--pack <id>` to choose, `--root <dir>` to nest in a subfolder, `--dry-run` to preview) |+| `ok preview` | Show what content the watcher will track (read-only) — the quick check after a `content.dir` or `.okignore` change |+| `ok migrate notion <dir>` | Clean up a Notion export in place, dry-run unless `--apply` (see [migrating from Notion](/docs/migrate/notion)) |+| `ok config validate` | Validate the merged config (defaults → user → project) |+| `ok config migrate` | Remove deprecated keys from `config.yml` (`--dry-run` to preview; `--scope` project, user, or both) |+| `ok skills manage` | Control whether OpenKnowledge adopts your editor skills into this project (`--on`, `--off`, `--status`; default off) |++## Global flags++Every command takes `--cwd <path>` to run from another directory, `--log-level <level>` (`silent`, `error`, `warn`, `info`, `debug`, or `trace`), and `--no-color` to disable color output. `ok start` runs quiet by default; `--log-level debug` turns everything on.+## Commands that run for youThe rest of the CLI exists mostly for tooling and automation. Your AI editor spawns `ok mcp` to talk to the knowledge base; `ok repair-skills` refreshes bundled editor skills automatically during `ok start`; and `ok diagnose` / `ok bug-report` produce support bundles when something goes wrong. Run `ok --help` if you want to see an overview of all commands.++## Remove OpenKnowledge++`ok deinit` reverses `ok init` for one project: it removes the project's `.ok/` directory, its editor MCP entries, git-exclude lines, and shadow repo, leaving your markdown untouched.++`ok uninstall` removes OpenKnowledge from the whole machine — running servers, credentials, the PATH shim, its own editor MCP entries, skill bundles, app data, and `~/.ok`. Your markdown content stays, and skills you authored under `~/.ok/skills` are kept unless you pass `--purge-content`. It never deletes the CLI binary itself; it ends by printing the removal command (`npm uninstall -g @inkeep/open-knowledge` for the install above).++Both commands print their plan and ask before acting; `--dry-run` previews without changing anything.diff --git a/docs/content/reference/configuration.mdx b/docs/content/reference/configuration.mdxindex 5e0b5f21e..4976439ad 100644--- a/docs/content/reference/configuration.mdx+++ b/docs/content/reference/configuration.mdx@@ -16,31 +16,36 @@ You can inspect and edit config three ways:- **Settings pane** in the editor: Cmd/Ctrl-, or App menu → Settings…- **Your IDE**: `.ok/config.yml` ships with a `$schema` magic comment for autocomplete and inline field descriptions-- **CLI**: `ok config validate` checks the merged result and reports wrong-scope keys+- **CLI**: `ok config validate` checks the merged resultEdits made anywhere reflect everywhere; an open Settings pane refreshes live.## Schema-The **Scope** column says which file a setting belongs in: **project** → `.ok/config.yml` (shared in git), **user** → `~/.ok/global.yml` (personal, all projects), **project-local** → `.ok/local/config.yml` (this machine only, gitignored). Setting a key in the wrong-scope file is ignored; `ok config validate` reports it.+The **Scope** column says which file a setting belongs in: **project** → `.ok/config.yml` (shared in git), **user** → `~/.ok/global.yml` (personal, all projects), **project-local** → `.ok/local/config.yml` (this machine only, gitignored). A key set in a file more specific than its scope (a user-scope key in `.ok/config.yml`, for example) is ignored.| Field | Type | Default | Scope | Description || --- | --- | --- | --- | --- |-| `content.dir` | string | `"."` | project | Content directory, relative to project root. Defaults to `.` (the project root) even when `.ok/` is scaffolded at the git working-tree root from a sub-folder, so opened folder and content scope align by default. To narrow scope to a sub-folder, uncomment `content.dir` in `.ok/config.yml` post-init. Excluded paths live in `.okignore`; see [Ignore patterns](/docs/features/ignore-patterns). |+| `content.dir` | string | `"."` | project | Content directory, relative to project root. Defaults to `.` (the project root) even when `.ok/` is scaffolded at the git working-tree root from a sub-folder, so opened folder and content scope align by default. To narrow scope to a sub-folder, pass `--content-dir <dir>` to `ok init`, or uncomment `content.dir` in `.ok/config.yml` post-init. Excluded paths live in `.okignore`; see [Ignore patterns](/docs/features/ignore-patterns). || `content.attachmentFolderPath` | string | `"./"` | project | Where pasted and dropped assets are stored. `"./"` colocates beside the current document; `"/"` targets the content root; `"./subdir"` targets a subfolder under the current folder; `"folder"` targets a fixed folder under the content root. || `appearance.theme` | `"light" \| "dark" \| "system"` | (unset) | user | Editor theme. || `appearance.sidebar.showHiddenFiles` | boolean | `false` | project-local | Show files whose path segments start with `.`. The sidebar otherwise lists every file on disk under the content directory; tooling internals (`.git/`, `.ok/`, `node_modules/`) stay hidden regardless. Toggled from the sidebar's right-click menu or the macOS **View → Show Hidden Files** item. || `autoSync.enabled` | `boolean \| null` | `null` | project-local | Per-machine git auto-sync toggle. `null` means "unanswered"; the editor's onboarding modal triggers on first remote-detected open. |+| `autoSync.default` | `boolean \| null` | `null` | project | Committed seed for each machine's first-open auto-sync choice: `true` = on, `false` = off, `null` = ask. Lets a maintainer pre-answer the onboarding prompt for everyone who clones; a per-machine `autoSync.enabled` overrides it. || `editor.wordWrap` | boolean | `true` | user | Soft-wrap long lines in the source-mode CodeMirror editor. A personal preference, not project-shared. Toggle from the Settings pane. || `appearance.preview.autoOpen` | boolean | `true` | user | Whether the agent should open or refresh the OpenKnowledge preview when it edits a doc through the MCP. Default `true` lets the agent route the preview by host capability: the host's in-app browser (Cursor preview pane, Codex's built-in browser, Claude Code Desktop) when one exists, the system browser otherwise. Set `false` to keep the agent's hands off your preview window. This is useful when you're already viewing the doc in OK Desktop, a browser tab on a second display, a non-default browser, or any flow where your extensions / accessibility tooling only work in your own browser. The agent then surfaces the URL on request but does not navigate. The change takes effect on the next preview-related tool call. Toggle from **Settings → Preferences → "Open preview when agent edits"**. |+| `terminal.enabled` | `boolean \| null` | `null` | project-local | Opt-out for the in-app terminal (a real OS shell at full user privilege). On by default; set `false` to disable it for this project on this machine. || `telemetry.localSink.enabled` | boolean | `true` | project | Write local diagnostic spans + logs under `.ok/local/` for `ok diagnose bundle` to collect. Local-only: nothing leaves the machine until you run `bundle`. Set `false` for sensitive workspaces. || `telemetry.localSink.spans.maxBytes` | number | `52428800` (~50 MB) | project | Max size of the local diagnostic spans file before it rotates. || `telemetry.localSink.logs.maxBytes` | number | `26214400` (~25 MB) | project | Max size of the local diagnostic logs file before it rotates. || `telemetry.localSink.attributeDenylist` | `string[]` | 8 credential keys | project | Attribute keys whose values are redacted (`[REDACTED]`) before any local span/log is written. Extends the built-in denylist (`authorization`, `password`, `cookie`, etc.). |-| `search.semantic.enabled` | boolean | `false` | project-local | Add embeddings-based semantic ranking to the MCP `search` tool. Default off. **When on and a key is set, the search query and matching page content are sent to the configured embeddings provider** (content egress). See [Semantic search](#semantic-search) below. |+| `search.semantic.enabled` | boolean | `false` | project-local | Add embeddings-based semantic ranking to the MCP `search` tool and a **By meaning** mode to the cmd-K omnibar. Default off. **When on and a key is set, the search query and matching page content are sent to the configured embeddings provider** (content egress). See [Semantic search](#semantic-search) below. || `search.semantic.baseUrl` | string | `"https://api.openai.com/v1"` | project-local | Base URL of the OpenAI-compatible embeddings API. Override for Azure / self-hosted / other providers. The API key is **not** stored here — set it with `ok embeddings set-key`. || `search.semantic.model` | string | `"text-embedding-3-small"` | project-local | Embeddings model id. Must be served by the provider at `baseUrl`. Changing it re-embeds the corpus. || `search.semantic.dimensions` | number | (native) | project-local | Optional output vector size. Omit for the model's native size (1536 for `text-embedding-3-small`). Set a smaller value to shrink the on-disk cache, trading a little quality. |+| `search.semantic.similarityFloor` | number | (unset) | project-local | Optional hard cutoff (0–1): drops semantic matches whose cosine similarity is below it. Retrieval is rank-based, so most setups leave it unset; set it only for a provider/model whose cosine scale you know. |++If `.ok/config.yml` contains a key that has been removed from the schema, config load fails with an error naming the replacement — a stale key is never a silent no-op. `ok config migrate` (`--dry-run` to preview; `--scope project|user|both`) strips removed keys from your config files.## Folder properties@@ -64,7 +69,7 @@ Most users never set these — the schema settings above cover the common cases.| --- | --- || `HOST` | Server bind host. The `--host` flag wins over this. || `PORT` | Server bind port. The `--port` flag wins over this. |-| `OK_MCP_AUTOSTART` | Set to `0` to disable auto-starting the MCP server |+| `OK_MCP_AUTOSTART` | Set to `0` to stop MCP tool calls from auto-starting the project's OpenKnowledge server; tools error until you run `ok start` || `OK_LOG_LEVEL` | Log verbosity (`info`, `debug`, `trace`). Falls back to `LOG_LEVEL` if unset. |**Advanced / operator:**@@ -79,16 +84,16 @@ Most users never set these — the schema settings above cover the common cases.## Semantic search-The MCP `search` tool can fuse an **embeddings-based semantic signal** into its ranking, so an agent's query surfaces conceptually-related pages even when they share no keywords (a query about "auth retries" can surface a page titled "Session Token Refresh"). It is **off by default** and additive — with it off, search is byte-for-byte today's lexical ranking, and the cmd-K omnibar stays purely lexical and instant either way (semantic applies only to the agent-facing MCP tool).+The MCP `search` tool can fuse an **embeddings-based semantic signal** into its ranking, so an agent's query surfaces conceptually-related pages even when they share no keywords (a query about "auth retries" can surface a page titled "Session Token Refresh"). It is **off by default** and additive — with it off, search everywhere (the MCP tool and the cmd-K omnibar) is purely lexical and stays on-machine. With it on, the omnibar gains a **By meaning** mode alongside its default lexical mode: typing never embeds; pressing Enter fires one semantic search, sending the query to the embeddings provider.<Callout type="warn">- **Content egress.** When semantic search is enabled **and** a key is set, the search query and the matching page content are sent to the configured embeddings provider (OpenAI by default). Only content that is already in your corpus is embedded — anything excluded by `.okignore` / `.gitignore` is never sent — and embedding is lazy: nothing leaves the machine until an agent actually runs a semantic search. The key lives only in a 0600 `~/.ok/secrets.yml` file (never in `config.yml`, logs, or telemetry).+ **Content egress.** When semantic search is enabled **and** a key is set, the search query and the matching page content are sent to the configured embeddings provider (OpenAI by default). Only content that is already in your corpus is embedded — anything excluded by `.okignore` / `.gitignore` is never sent — and embedding is lazy: nothing leaves the machine until a semantic search actually runs. The key lives only in a 0600 `~/.ok/secrets.yml` file (never in `config.yml`, logs, or telemetry).</Callout>To turn it on (per machine):-1. Store the provider key in `~/.ok/secrets.yml` (0600, this machine only): `ok embeddings set-key` (reads the key from a hidden prompt or stdin). Check it with `ok embeddings status`.-2. Set `search.semantic.enabled: true` in project-local config (`<project>/.ok/local/config.yml`).+1. Store the provider key in `~/.ok/secrets.yml` (0600, this machine only): `ok embeddings set-key` (reads the key from a hidden prompt or stdin). Check it with `ok embeddings status`; remove it with `ok embeddings clear-key`.+2. Enable it for the project: `ok embeddings enable`, or the **Settings → This project → Search** toggle. Either sets `search.semantic.enabled: true` in project-local config (`<project>/.ok/local/config.yml`), picked up live by a running server; `ok embeddings disable` turns it off.3. (Optional) point at a non-OpenAI provider via `search.semantic.baseUrl` / `model` / `dimensions`.The first semantic search kicks off a background embed of the corpus (cents for a whole vault with `text-embedding-3-small`); vectors are cached incrementally under `.ok/local/` and only changed docs re-embed. If the key is missing, the provider errors, or you're offline, search silently degrades to lexical — it never blocks or errors. Each MCP `search` response reports embedding coverage so an agent knows when vectors are still filling in.diff --git a/docs/content/reference/core-concepts.md b/docs/content/reference/core-concepts.mdindex e5d1e1786..84fa65bd7 100644--- a/docs/content/reference/core-concepts.md+++ b/docs/content/reference/core-concepts.md@@ -57,10 +57,10 @@ if(!matchMedia("(prefers-reduced-motion:reduce)").matches){setInterval(function(```<Cards>- <Card title="The editor" href="../features/editor.mdx">+ <Card title="The editor" href="/docs/features/editor">The application you see: a beautiful, themeable markdown editor that renders rich extensions (Mermaid, LaTeX, video and asset embeds, callouts, collapsible sections, interactive HTML) and lets you read and write your knowledge base directly.</Card>- <Card title="The knowledge engine" href="./mcp.mdx">+ <Card title="The knowledge engine" href="/docs/reference/mcp">The framework underneath: an MCP server that lets any AI agent read and write your knowledge base while keeping front matter consistent, references intact, and the link graph healthy.</Card><Card title="The content" href="#the-file-system-is-the-database">@@ -70,7 +70,7 @@ if(!matchMedia("(prefers-reduced-motion:reduce)").matches){setInterval(function(All three layers operate on the **same files**. You can edit through the editor, an agent can edit through the knowledge engine's MCP tools, and you can always drop down to any text editor and change the markdown by hand. Nothing locks you out.-Because the knowledge engine is exposed over [MCP](https://modelcontextprotocol.io), it is **agent-agnostic**. Bring Claude Code, Cursor, Codex, OpenCode, Gemini, or any MCP-capable client, and any model you have access to.+Because the knowledge engine is exposed over [MCP](https://modelcontextprotocol.io), it is **agent-agnostic**. Bring Claude Code, Cursor, Codex, OpenCode, OpenClaw, or any MCP-capable client, and any model you have access to.## The file system is the database@@ -232,4 +232,6 @@ That gives you:- **Point-in-time history.** Revert to any earlier state.- **Per-author views.** See exactly what one human or one agent changed.+Browse this history and restore earlier versions from the editor's [timeline](../features/timeline-and-recovery.mdx).+Because humans and agents edit the same files through the same tracked layer, collaboration is a first-class property of the system rather than something bolted on.diff --git a/docs/content/reference/mcp.mdx b/docs/content/reference/mcp.mdxindex dbfdb30b1..187f67ba1 100644--- a/docs/content/reference/mcp.mdx+++ b/docs/content/reference/mcp.mdx@@ -4,28 +4,28 @@ icon: custom/MCPdescription: Tools the OpenKnowledge MCP server exposes to AI agents.----The MCP server gives AI agents structured access to your knowledge base. A few tools answer without a running server: `exec` (fs-direct shell reads straight off the disk — only the backlink and history enrichment needs the server), plus `config` and `palette`. `preview_url` resolves from the project's lock files, but treats opening a preview as demand: if no server is running it auto-starts one (under the `OK_MCP_AUTOSTART` gate). Every other read tool (`search`, `links`, `history`, etc.) and all write tools route through the Hocuspocus server, which OpenKnowledge starts for you on the first write.+The MCP server gives AI agents structured access to your knowledge base. A few tools answer without a running server: `exec` (fs-direct shell reads straight off the disk — only the backlink and forward-link enrichment needs the server; history comes from the shadow repo on disk), plus `config`, `palette`, and `workflow`. `preview_url` resolves from the project's lock files, but treats opening a preview as demand: if no server is running it auto-starts one (under the `OK_MCP_AUTOSTART` gate). Every other read tool (`search`, `links`, `history`, etc.) and all write tools route through the Hocuspocus server, which OpenKnowledge auto-starts on the first call that needs it, under the same `OK_MCP_AUTOSTART` gate. All tools take a `cwd` (an absolute path inside the target project) that selects which project the call lands on; a globally registered server requires it unless the client advertises exactly one root.-The surface is **19 tools**. The four write verbs — `write`, `edit`, `delete`, `move` — are native CRUD operations polymorphic over a target. `write`, `edit`, and `delete` nest per-target fields inside the address key (`write({ document: { path, content } })`) and take exactly one target per call: `document`, `folder`, `template`, or `skill` — plus `asset` for `write` and `delete`. `move` takes flat `from`/`to` paths and auto-detects a document, folder, or asset, with nested `template` and `skill` targets for those two.+The surface is **19 tools**. The four write verbs — `write`, `edit`, `delete`, `move` — are native CRUD operations polymorphic over a target. `write`, `edit`, and `delete` nest per-target fields inside the address key (`write({ document: { path, content } })`) and take exactly one target per call: `document`, `folder`, `template`, or `skill` — plus `asset` for `write` and `delete`, and a `documents` batch on `write` that writes several docs in order, each entry carrying its own `summary`. `move` takes flat `from`/`to` paths and auto-detects a document, folder, or asset, with nested `template` and `skill` targets for those two.## Tools| Tool | Purpose || --- | --- || `exec` | Read-only shell (`cat`, `ls`, `grep`, `find`, `head`, `tail`, `wc`, `sort`, `uniq`, `cut`); reads return frontmatter, backlinks, and recent history. Fs-direct; works without the server. |-| `search` | Ranked workspace search (title boost + body BM25 + recency; same engine the cmd-K palette uses). 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. |+| `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 |-| `history` | Version timeline for a `document`, `folder`, or `skill`. Each entry carries a `version` (commit SHA) you pass to `restore_version` |-| `skills` | Find and read agent skills. Omit `name` to list every skill across Project + Global; pass `name` to read one (addressed by `name`+`scope`, never by path) |+| `history` | Version timeline for a `document`, `folder`, or `skill`. Each entry carries a `version` (commit SHA) you pass to `restore_version`. Filter with `kind` (`checkpoint` / `wip` / `upstream`), `author` / `excludeAuthor`, and `branch`; paginate with `limit` / `offset` (default 50, max 200). `folder: ""` selects the project-root timeline |+| `skills` | Find and read agent skills. Omit `name` to list every skill across Project + Global (rows carry `installed` + `hosts`); pass `name` to read one (addressed by `name`+`scope`, never by path); pass `name` + `file` to read one bundle file's text — the read path for `references/` and `scripts/` content || `config` | Read the effective merged config (`config({ key: "appearance.theme" })` for a sub-tree; omit `key` for the whole config) || `palette` | Markdown-native authoring forms, themed `html preview` embed starters, and theme tokens. Pass `components` for the canonical components' full JSX prop schemas |-| `preview_url` | Resolve the browser-reachable preview URL. Per-response `previewUrl` fields elsewhere are route-only (`/#/<doc>`); call this when you need the full openable URL |-| `share_link` | Build a GitHub-substrate share URL for a doc to send to a teammate (read-only against `.git/`; never publishes) |-| `write` | Create or overwrite a `document`, `folder`, `template`, `skill`, or `asset`. For a document: `{ path, content }`, or `{ path, template }` to instantiate from a folder template. `position` selects `replace` (full rewrite; the only mode that touches frontmatter), `append`, or `prepend` |-| `edit` | Modify a `document` (body find/replace **or** a frontmatter merge-patch), a `folder` (frontmatter merge-patch), a `template`, or a `skill` |+| `preview_url` | Resolve the browser-reachable preview URL. Targets a `document`, `folder`, or `skill` in the current project, or — via `file`, an absolute path — a markdown file outside it (resolved through the session serving that file). Per-response `previewUrl` fields elsewhere are route-only (`/#/<doc>`); call this when you need the full openable URL. `armPaneTarget` briefly arms the target so a host preview pane opens on it |+| `share_link` | Build a GitHub-substrate share URL for a doc or folder to send to a teammate (`kind` disambiguates; `path: ""` with `kind: "folder"` shares the content root). Responses carry a `freshness` verdict — `current`, `stale` (unpushed changes), or `absent` (never pushed), omitted when the probe can't run — and prepend a matching warning to relay with the link. Read-only against `.git/`; never publishes |+| `write` | Create or overwrite a `document`, `folder`, `template`, `skill`, or `asset`. For a document: `{ path, content }`, or `{ path, template }` to instantiate from a folder template. `position` selects `replace` (full rewrite; the only mode that touches frontmatter), `append`, or `prepend`. `extension` selects `.md` (default) or `.mdx` for a new document; an existing doc keeps its extension (the MCP cannot change it). An `asset` takes exactly one of `content` (base64, for small files) or `source` (a local path the server reads, for large files) |+| `edit` | Modify a `document` (body find/replace **or** a frontmatter merge-patch), a `folder` (frontmatter merge-patch), a `template`, or a `skill`. Body edits take `{ path, find, replace, occurrence? }`; `occurrence` selects which match (1 = first) || `delete` | Delete a `document` (one path or an array), `folder`, `template`, `skill`, or `asset` |-| `move` | Move or rename a `document`, `folder`, `asset`, `template`, or `skill`, rewriting every affected link (templates and skills carry no inbound links) |-| `install` | Project an authored skill (the Draft produced by `write({ skill })`) into your editors — the Draft → Installed step |+| `move` | Move or rename a `document`, `folder`, `asset`, `template`, or `skill`, rewriting every affected link (templates and skills carry no inbound links). A skill also moves between Project and Global scope via `scope` + `toScope`: history does not transfer, and the moved skill lands as a Draft — run `install` afterward |+| `install` | Project an authored skill (the Draft produced by `write({ skill })`) into your editors — the Draft → Installed step. `targets` (`claude` / `cursor` / `codex` / `opencode`) overrides the project-configured editor set; the source is validated before projection || `checkpoint` | Save a project-wide version snapshot — a single restore point. Returns its `version` || `restore_version` | Restore one `document` or `skill` to a historical `version` (the SHA from `history` or `checkpoint`) || `conflicts` | Read GitHub-sync merge conflicts. `kind: "list"` enumerates tracked conflicts; `kind: "content"` returns one file's base / ours / theirs stages |@@ -34,7 +34,11 @@ The surface is **19 tools**. The four write verbs — `write`, `edit`, `delete`,## Output shape mirrors the input-The write verbs nest their result under the same target key you wrote, mirroring the input: `write({ folder })` returns `{ folder: { ok, path } }`, `edit({ document })` returns `{ document: { … } }` (with any `contentDivergence`), and a batch returns `{ documents: [ … ] }`. The uniform preview envelope (`previewUrl`, `previewUrlSource`, `warning`) always stays at the top level — every tool surfaces it the same way. `conflicts` and `links` nest the same way under their `kind`.+The write verbs nest their result under the same target key you wrote, mirroring the input: `write({ folder })` returns `{ folder: { ok, path } }`, `edit({ document })` returns `{ document: { … } }`, and a batch returns `{ documents: [ … ] }`. The preview envelope (`previewUrl`, `previewUrlSource`, `warning`) stays at the top level on `write` and `edit` responses; read tools (`search`, `links`, `exec`) attach a route-only `previewUrl` to each hit or entry instead. `conflicts` and `links` nest the same way under their `kind`.++## Advisory warnings++`write` and `edit` results may carry a `warnings` array on the document entry (per entry for a batch); `restore_version` carries it at the top level. Entries are discriminated by `kind`. `content-divergence` and `disk-edit-reconciled` are write-integrity signals — the stored doc differs from what the call composed, so re-read it before editing further. `mermaid-parse-error` means the write landed but that fence won't render — fix the fence and re-edit.## Instantiating from a template@@ -44,7 +48,7 @@ The write verbs nest their result under the same target key you wrote, mirroring## Editing frontmatter-Use `edit({ document: { path, frontmatter } })` for frontmatter edits: it applies a JSON Merge Patch (set or create a key with a value, delete a key by passing `null`). A document body find/replace (`edit({ document: { path, find, replace } })`) is body-only and refuses patterns that touch frontmatter; `write` with `position: "replace"` is the only write mode that includes the `---\n…\n---` block (other positions ignore any frontmatter in the payload). Folders and templates take frontmatter the same way: `edit({ folder: { path, frontmatter } })`.+Use `edit({ document: { path, frontmatter } })` for frontmatter edits: it applies a top-level merge patch (set or create a key with a value, delete a key by passing `null`; a nested object replaces that key's whole subtree, and `null` inside a subtree is rejected). A document body find/replace (`edit({ document: { path, find, replace } })`) is body-only and refuses patterns that touch frontmatter; `write` with `position: "replace"` is the only write mode that includes the `---\n…\n---` block (other positions ignore any frontmatter in the payload). Folders and templates take frontmatter the same way: `edit({ folder: { path, frontmatter } })`.## Edit summaries@@ -63,7 +67,7 @@ To recover, call `conflicts({ kind: "content", file })` to inspect the merge sta- `content`: write the exact bytes you supply (for example, a merged result you composed by reading both stages).- `delete`: `git rm` the file (for delete-vs-modify shapes where one stage is missing).-To detect conflict state proactively without waiting for a 409, call `conflicts({ kind: "list" })`; it enumerates every conflicted doc with its `lifecycle: { status, reason }`. `exec("cat …")` also returns that `lifecycle` field for any doc.+To detect conflict state proactively without waiting for a 409, call `conflicts({ kind: "list" })`; each entry is `{ file, detectedAt, … }`. `conflicts({ kind: "content" })` adds the doc's `lifecycleStatus` alongside the merge stages.## Preview linksdiff --git a/docs/content/reference/what-open-knowledge-writes.mdx b/docs/content/reference/what-open-knowledge-writes.mdxindex 5aa249f04..c46c36f32 100644--- a/docs/content/reference/what-open-knowledge-writes.mdx+++ b/docs/content/reference/what-open-knowledge-writes.mdx@@ -1,6 +1,6 @@---title: What OpenKnowledge writes to your system-sidebarTitle: What it writes+sidebarTitle: Installation detailsicon: LuHardDrivedescription: Every file OpenKnowledge creates or changes — when, where, in-project vs. your home directory — plus the opt-outs and what leaves your machine (nothing by default).---@@ -10,7 +10,7 @@ OpenKnowledge keeps your knowledge base as plain markdown in your own project diThis page lists every one of them: **when** each write happens, **what** it is, and **where** it is written.<Callout type="info" title="The short version">- **Nothing leaves your machine by default.** Diagnostic logs and telemetry are local-only — there's no usage phone-home. The handful of things that *can* send data off your machine — semantic search, a diagnostic bundle, GitHub sync, and the desktop app's update check — are opt-in or on-demand, except the desktop app's update check, which runs automatically on launch. All of them are listed under [What leaves your machine](#what-leaves-your-machine).+ **Nothing leaves your machine by default — except the desktop app's automatic checks.** Diagnostic logs and telemetry stay on your machine. The things that *can* send data off it — semantic search, a diagnostic bundle, and GitHub sync — are opt-in or on-demand. The desktop app is the exception: it checks for updates automatically (sending its app version and channel), and on its first launch opens your browser once to check for a pending share link. All of them are listed under [What leaves your machine](#what-leaves-your-machine).</Callout>## How to read this page@@ -22,7 +22,7 @@ Writes fall into two buckets, and each table's **Scope** column tells you which:OpenKnowledge installs one of two ways, and the footprint differs a little between them. Pick yours below — each tab lists the complete set of writes for that path. The [opt-outs](#opt-outs-in-one-place) and [what leaves your machine](#what-leaves-your-machine) at the end apply to both.-<Tabs groupId="ok-install" persist className="ok-flush-tabs ok-tabs-h2" items={['MacOS app', 'CLI']}>+<Tabs groupId="ok-install" persist className="ok-flush-tabs ok-tabs-h2" items={['macOS app', 'CLI']}><Tab>@@ -38,7 +38,9 @@ The macOS app ships as a signed `.dmg` you drag into `/Applications`. On launch| `~/.ok/mcp-status.json` | Records your first-launch MCP-setup consent choice | Outside-project (home dir) || `~/Library/Caches/OpenKnowledge-updater/` | Staged auto-update downloads (electron-updater) | Outside-project (home dir) |-The app registers the `openknowledge://` URL scheme (for deep links) and checks for updates against the OpenKnowledge GitHub releases feed. Updates are **not** downloaded automatically until you choose to update; they install on the next quit. Override the feed with `OK_UPDATER_FEED_URL`.+The app registers the `openknowledge://` URL scheme (for deep links) and checks for updates — on launch and periodically while it runs — against the OpenKnowledge update service at `openknowledge.ai/updates`, which redirects to the GitHub release asset and counts the update per version and channel (falling back to GitHub directly if it's unreachable). An update on your channel downloads in the background and installs on the next quit; you can also check on demand from **Check for updates…** in the app and Help menus. The channel (stable or beta) is fixed by the build you installed — switch by reinstalling the other from `openknowledge.ai/download/stable` or `/download/beta`. Override the feed with `OK_UPDATER_FEED_URL`.++On its first launch the app also opens your default browser once to `openknowledge.ai/continue`, to check whether you installed from a share link and redeem it if so; the exchange completes over a short-lived local loopback listener.### Shell and `PATH`@@ -58,6 +60,8 @@ The managed block is clearly fenced so you can see and remove it:```bash# >>> open-knowledge cli >>>+# ! Contents within this block are managed by OpenKnowledge. Do not edit.+# ! Delete this whole block to opt out — OpenKnowledge will not re-add it.[ -f "$HOME/.ok/env.sh" ] && . "$HOME/.ok/env.sh"# <<< open-knowledge cli <<<```@@ -79,10 +83,11 @@ When you initialize or open a project, the app scaffolds the same project files| `.ok/`, `.ok/config.yml` | Project directory and its [config](/docs/reference/configuration) | In-project, committed || `.ok/.gitignore` | Keeps machine-local runtime state (`local/`, `principal.json`, `server.lock`, …) out of git | In-project, committed || `.okignore` | Paths excluded from the editor, search, and agents — see [Ignore patterns](/docs/features/ignore-patterns) | In-project, committed |-| `.mcp.json`, `.cursor/mcp.json`, `.codex/config.toml`, `opencode.json` | Project-scoped MCP registration, one per detected editor | In-project, committed |-| `.claude/skills/`, `.cursor/skills/`, `.codex/skills/`, `.opencode/skills/` | Project-local "rich" OpenKnowledge skill (`SKILL.md`), one per detected editor | In-project, committed |+| `.mcp.json`, `.cursor/mcp.json`, `.codex/config.toml`, `opencode.json` | Project-scoped MCP registration for all four project-capable editors (Claude, Cursor, Codex, OpenCode), written regardless of what's installed so the repo is ready for teammates | In-project, committed |+| `.claude/skills/`, `.cursor/skills/`, `.codex/skills/`, `.opencode/skills/` | Project-local "rich" OpenKnowledge skill (`SKILL.md`) for the same four editors | In-project, committed |+| `.ok/skill-targets.json` | Committed list of which editors receive skills, written when you customize the targets | In-project, committed || `.claude/launch.json` | Configures Claude Code's preview pane to open the editor (on a local UI port, `39848`) | In-project, committed |-| `~/.claude.json`, `~/Library/Application Support/Claude/claude_desktop_config.json`, `~/.cursor/mcp.json`, `~/.codex/config.toml`, `~/.config/opencode/opencode.json` | User-level `open-knowledge` MCP registration, one per detected editor (so it's available in every project) | Outside-project (editor config) |+| `~/.claude.json`, `~/Library/Application Support/Claude/claude_desktop_config.json`, `~/.cursor/mcp.json`, `~/.codex/config.toml`, `~/.config/opencode/opencode.json`, `~/.openclaw/openclaw.json` | User-level `open-knowledge` MCP registration, one per detected editor, so it's available in every project (`~/.openclaw/openclaw.json` only when `~/.openclaw/` exists) | Outside-project (editor config) |### While a project is open@@ -97,11 +102,13 @@ The app runs a collaboration server for the open project. It writes runtime stat| `.ok/local/telemetry/spans-*.jsonl` | Local diagnostic spans, rotated at ~50 MB | In-project, gitignored || `.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 |-| `.git/ok/` | Shadow git repo holding per-writer work-in-progress refs | In-project, gitignored (inside `.git/`) |+| `.ok/local/skill-management.json`, `.ok/local/installed-skills.json` | Skill-management toggle (`ok skills manage`) and per-project skill-install markers | 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/`) |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](/docs/reference/configuration).-On each launch and project open, the app also runs **repair sweeps**: it rewrites *existing* `open-knowledge` MCP entries (in the editor configs above, plus that project's `.vscode/settings.json`), `.claude/launch.json`, and skill files to the current canonical form — a no-op when nothing has drifted, and it **never adds** an entry to an editor that doesn't already have one. Same `OK_RECLAIM_DISABLE=1` opt-out.+On each launch and project open, the app also runs **repair sweeps**: it rewrites *existing* `open-knowledge` MCP entries (in the editor configs above), `.claude/launch.json`, and the OpenKnowledge skill bundles (`open-knowledge-discovery` and `open-knowledge-write-skill`, in `~/.agents/skills/` and each detected editor's `~/.claude/skills/`, `~/.cursor/skills/`, `~/.codex/skills/`, `~/.opencode/skills/`) to the current canonical form — a no-op when nothing has drifted. It **never adds** an MCP entry to an editor that doesn't already have one; and when you turn on skill management for a project, it also adopts your existing editor skills into `.ok/skills/`. Same `OK_RECLAIM_DISABLE=1` opt-out.### Home directory and credentials (`~/.ok/`)@@ -111,13 +118,16 @@ On each launch and project open, the app also runs **repair sweeps**: it rewrite| `~/.ok/secrets.yml` | Embeddings provider API key for [semantic search](/docs/reference/configuration#semantic-search), if you set one. Written `0600`; never in `config.yml` | **Yes** (`0600`) || `~/.ok/auth.yml` | Auth-token fallback, used only when the Keychain is unavailable. Written `0600` | **Yes** (`0600`) || `~/.ok/skill-state.yml`, `~/.ok/skill-install-events.jsonl` | Skill-install bookkeeping | No |+| `~/.ok/skills/<name>/` | Your global-scope authored skills (kept by `ok uninstall` unless `--purge-content`) | No || `~/.ok/stats.jsonl` | Local "open with AI" handoff stats — local-only, no phone-home | No || `~/.ok/mcp-status.json` | First-launch MCP consent record | No |-| `~/.ok/logs/`, `~/.ok/bug-reports/` | Desktop logs and generated diagnostic bundles | No |+| `~/.ok/logs/`, `~/.ok/bug-reports/` | Desktop and CLI logs, and bug-report bundles from `ok bug-report` (`ok diagnose bundle` writes into the project, under `.ok/local/diagnostics/`) | No || `~/.ok/bin/`, `~/.ok/env.sh` | `PATH` shim (see [Shell and `PATH`](#shell-and-path) above) | No |**Auth tokens** (for GitHub sync, sharing, and cloning) are stored in the macOS **Keychain** under the service name `open-knowledge`. The `~/.ok/auth.yml` file is only a fallback for headless environments where the Keychain isn't reachable; when the Keychain becomes available, the token is migrated into it and the file copy is removed.+The **Install for Claude Chat & Cowork** command (command palette or Help menu) builds `~/Downloads/openknowledge.skill` on demand and hands it to Claude Desktop for upload; the build is version-gated via `~/.ok/skill-state.yml`.+</Tab><Tab>@@ -134,7 +144,7 @@ Installing `@inkeep/open-knowledge` from npm (or invoking it with `npx`) drops t| `~/.ok/skill-state.yml` | Records which skill version is installed, so the step is skipped next time | Outside-project (home dir) || `~/.ok/skill-install-events.jsonl` | Append-only local log of skill-install attempts | Outside-project (home dir) |-The `postinstall` step is **non-fatal** (install always succeeds even if it fails) and **version-gated** (it does nothing if the current version is already installed). It writes only the discovery skill into the shared `~/.agents/skills/` directory; it does not touch your editors' individual skill folders. The only network access is npm fetching the `skills` helper.+The `postinstall` step is **non-fatal** (install always succeeds even if it fails) and **version-gated** (it does nothing if the current version is already installed). It installs the discovery skill for every detected agent host: the shared `~/.agents/skills/` directory and each detected editor's user-level skills folder (`~/.claude/skills/`, `~/.cursor/skills/`, `~/.codex/skills/`, `~/.opencode/skills/`). The only network access is npm fetching the `skills` helper.<Callout type="info" title="Opt out">Install with `npm install --ignore-scripts` to skip the `postinstall` skill step entirely. You can always add the skills later from `ok init`.@@ -150,8 +160,9 @@ The `postinstall` step is **non-fatal** (install always succeeds even if it fail| `.ok/.gitignore` | Keeps machine-local runtime state (`local/`, `principal.json`, `server.lock`, …) out of git | In-project, committed || `.okignore` | Paths excluded from the editor, search, and agents — see [Ignore patterns](/docs/features/ignore-patterns) | In-project, committed || `.gitignore` (project root) | Seeded (with `.DS_Store`) **only** when `ok init` creates a new git repo | In-project, committed |-| `.mcp.json`, `.cursor/mcp.json`, `.codex/config.toml`, `opencode.json` | Project-scoped MCP registration, one per detected editor (with `--scope project` or `both`) | In-project, committed |-| `.claude/skills/`, `.cursor/skills/`, `.codex/skills/`, `.opencode/skills/` | Project-local "rich" OpenKnowledge skill (`SKILL.md`), one per detected editor | In-project, committed |+| `.mcp.json`, `.cursor/mcp.json`, `.codex/config.toml`, `opencode.json` | Project-scoped MCP registration for all four project-capable editors (Claude, Cursor, Codex, OpenCode) regardless of what's installed — prepares the repo for teammates (with `--scope project` or `both`) | In-project, committed |+| `.claude/skills/`, `.cursor/skills/`, `.codex/skills/`, `.opencode/skills/` | Project-local "rich" OpenKnowledge skill (`SKILL.md`) for the same four editors | In-project, committed |+| `.ok/skill-targets.json` | Committed list of which editors receive skills, written when you customize the targets | In-project, committed || `.claude/launch.json` | Configures Claude Code's preview pane to open the editor (on a local UI port, `39848`) | In-project, committed |With `--scope user` or `both` (the default), `ok init` also registers the `open-knowledge` MCP server in each detected editor's **user-level** config, so it's available in every project:@@ -163,8 +174,11 @@ With `--scope user` or `both` (the default), `ok init` also registers the `open-| `~/.cursor/mcp.json` | Cursor | Outside-project (editor config) || `~/.codex/config.toml` | Codex | Outside-project (editor config) || `~/.config/opencode/opencode.json` | OpenCode | Outside-project (editor config) |+| `~/.openclaw/openclaw.json` | OpenClaw (only when `~/.openclaw/` exists) | Outside-project (editor config) |++On Windows, Claude Desktop and OpenCode configs live under `%APPDATA%\Claude\` and `%APPDATA%\opencode\`, and the MCP entry is a PowerShell launcher.-`ok init` also installs the two user-global skills (`open-knowledge-discovery` and `open-knowledge-write-skill`), honoring any prior consent choice, and, if you choose **local-only** sharing, adds the OpenKnowledge paths to `.git/info/exclude` so `.ok/` stays off your remote.+`ok init` also installs the two user-global skills (`open-knowledge-discovery` and `open-knowledge-write-skill`), honoring any prior consent choice, and, if you choose **local-only** sharing, adds the OpenKnowledge paths to `.git/info/exclude` so `.ok/` stays off your remote. Switch modes later with `ok config-sharing share` / `unshare` (`unshare` refuses if an OK config file is already tracked); `ok config-sharing status` prints the current mode and the excluded paths.<Callout type="info" title="Controlling it">- `--no-mcp` — scaffold `.ok/` only; register nothing with any editor.@@ -186,7 +200,8 @@ With `--scope user` or `both` (the default), `ok init` also registers the `open-| `.ok/local/telemetry/spans-*.jsonl` | Local diagnostic spans, rotated at ~50 MB | In-project, gitignored || `.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 |-| `.git/ok/` | Shadow git repo holding per-writer work-in-progress refs (powers the timeline) | In-project, gitignored (inside `.git/`) |+| `.ok/local/skill-management.json`, `.ok/local/installed-skills.json` | Skill-management toggle (`ok skills manage`) and per-project skill-install markers | 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](/docs/reference/configuration).@@ -196,13 +211,13 @@ On each boot, `ok start` also runs **repair sweeps**: it re-checks a few things| --- | --- | --- || Existing `open-knowledge` MCP entries | The same editor configs `ok init` writes — **both** user-level (`~/.claude.json`, `~/.cursor/mcp.json`, …) and project-level | Outside-project (editor config) **and** in-project || `.claude/launch.json` | Your project | In-project, committed |-| OpenKnowledge skill files | Project (`.claude/skills/…`) and user-global (`~/.agents/skills/…`) | In-project **and** outside-project (home dir) |+| OpenKnowledge skill bundles (`open-knowledge-discovery`, `open-knowledge-write-skill`) | Project (`.claude/skills/…`) and user-global — `~/.agents/skills/` plus each detected editor's `~/.claude/skills/`, `~/.cursor/skills/`, `~/.codex/skills/`, `~/.opencode/skills/` | In-project **and** outside-project (home dir) |Disable all three with `OK_RECLAIM_DISABLE=1`.### `ok mcp`-`ok mcp` is the stdio bridge your editor spawns to talk to the server. It **writes nothing to disk** — it routes tool calls to a running `ok start` backend (starting one on the first write).+`ok mcp` is the stdio bridge your editor spawns to talk to the server. It **writes nothing to disk** — it routes tool calls to a running `ok start` backend (starting one on the first tool call that needs it — reads included).### Home directory and credentials (`~/.ok/`)@@ -212,10 +227,12 @@ Disable all three with `OK_RECLAIM_DISABLE=1`.| `~/.ok/secrets.yml` | Embeddings provider API key for [semantic search](/docs/reference/configuration#semantic-search), if you set one. Written `0600`; never in `config.yml` | **Yes** (`0600`) || `~/.ok/auth.yml` | Auth-token fallback, used when no OS credential store is reachable. Written `0600` | **Yes** (`0600`) || `~/.ok/skill-state.yml`, `~/.ok/skill-install-events.jsonl` | Skill-install bookkeeping | No |+| `~/.ok/skills/<name>/` | Your global-scope authored skills (kept by `ok uninstall` unless `--purge-content`) | No || `~/.ok/stats.jsonl` | Local "open with AI" handoff stats — local-only, no phone-home | No |-| `~/.ok/bug-reports/` | Generated diagnostic bundles (`ok diagnose` / `ok bug-report`) | No |+| `~/.ok/logs/` | CLI logs (`cli.<date>.log`), size- and age-capped | No |+| `~/.ok/bug-reports/` | Bug-report bundles from `ok bug-report` (`ok diagnose bundle` writes into the project, under `.ok/local/diagnostics/`) | No |-**Auth tokens** (for GitHub sync, sharing, and cloning) are stored in your operating system's secure credential store when one is available — the macOS **Keychain** on an Intel Mac (service `open-knowledge`), or the platform equivalent — falling back to a `0600` `~/.ok/auth.yml` file on headless systems (a Linux server, CI) where none is reachable.+**Auth tokens** (for GitHub sync, sharing, and cloning) are stored in your operating system's secure credential store when one is available — the macOS **Keychain** (service `open-knowledge`), or the platform equivalent (Windows Credential Manager, Linux Secret Service) — falling back to a `0600` `~/.ok/auth.yml` file on headless systems (a Linux server, CI) where none is reachable.</Tab>@@ -234,18 +251,19 @@ Disable all three with `OK_RECLAIM_DISABLE=1`.| Local diagnostic logs and telemetry | `telemetry.localSink.enabled: false` in config || Auto-starting the MCP server | `OK_MCP_AUTOSTART=0` |-To review or reverse the footprint after the fact, `ok diagnose` reports what's on disk, and the desktop `path-install.json` records exactly which shell/`PATH` changes were made.+To review the footprint after the fact, `ok diagnose` reports what's on disk (and the desktop `path-install.json` records exactly which shell/`PATH` changes were made). To reverse it, `ok deinit` removes OpenKnowledge from one project and `ok uninstall` removes it from the whole machine — both keep your markdown content (and your authored `~/.ok/skills`) unless you pass `--purge-content`, and both take `--dry-run` to preview. See the [CLI reference](/docs/reference/cli) for the full semantics.## What leaves your machine-By default, **nothing.** Everything above is written to your own disk. The only ways data leaves your machine are these — all opt-in or on-demand, except the desktop app's update check, which is automatic:+By default, **nothing.** Everything above is written to your own disk. The only ways data leaves your machine are these — all opt-in or on-demand, except two automatic desktop-app actions (the update check, and a one-time share-link check on first launch):| What | When | Where it goes || --- | --- | --- || Diagnostic bundle | Only when you run `ok diagnose bundle` (you can inspect it first) | Wherever you send it || Semantic search embeddings | Only when you enable [semantic search](/docs/reference/configuration#semantic-search) **and** set a key — off by default | Your configured embeddings provider (OpenAI by default) || GitHub sync / share | When you sync, clone, publish, or share | GitHub |-| Update check | Automatically, on desktop-app launch | OpenKnowledge releases feed (GitHub) |+| Update check | Automatically — on launch and periodically while the desktop app runs | OpenKnowledge update service (`openknowledge.ai/updates`), which redirects to GitHub; sends the app version and channel |+| First-launch share check | Once, automatically, on the desktop app's first launch | `openknowledge.ai/continue` — redeems a share link if you installed from one || npm/`npx` fetch | During install (CLI) | The npm registry |Local diagnostic logs and telemetry are scrubbed of credential-bearing attributes and never sent anywhere on their own.diff --git a/docs/content/workflows/codebase-wiki.mdx b/docs/content/workflows/codebase-wiki.mdxindex 4dca3cf92..4a3a1c600 100644--- a/docs/content/workflows/codebase-wiki.mdx+++ b/docs/content/workflows/codebase-wiki.mdx@@ -63,7 +63,7 @@ You don't configure the wiki in a settings file — you say what you want in pla| Knob | Values | Default | What it changes || --- | --- | --- | --- |-| **audience** | `internal`, `public` | `internal` | `public` means polished prose, no secrets or internal infra or ticket numbers, and GitHub-URL source references instead of relative paths |+| **audience** | `internal`, `public` | `internal` | `public` means polished prose, no secrets or internal infra or ticket numbers, and GitHub-URL source references when the repo has a remote (relative paths otherwise) || **depth** | `tour`, `standard`, `exhaustive` | `standard` | Scales coverage from OVERVIEW + architecture + top flows, up through per-package module pages, concepts, and task guides |So "build the wiki, public and exhaustive" and "just give me a quick internal tour" produce very different artifacts from the same pack.@@ -74,7 +74,7 @@ You've inherited a 200-file TypeScript service and have to add a feature this we<CopyPrompt>Build a codebase wiki for this repo. Internal audience, standard depth.</CopyPrompt>-The agent surveys the repo, writes `OVERVIEW.md` with a top-level architecture diagram, then fills `architecture/`, `modules/`, `flows/`, and `concepts/` — each page carrying a mermaid diagram and links to the specific files it read. An hour later you open `flows/request-lifecycle.md`, see the sequence diagram, follow the link into `modules/auth.md`, and know exactly where your feature slots in. Next week, after you've merged, `refresh` updates only the pages your diff touched.+The agent surveys the repo, confirms its proposed page list with you, writes `OVERVIEW.md` with a top-level architecture diagram, then fills `architecture/`, `modules/`, `flows/`, and `concepts/` — architecture and flow pages carrying mermaid diagrams, every page linking to the specific files it read. An hour later you open `flows/request-lifecycle.md`, see the sequence diagram, follow the link into `modules/auth.md`, and know exactly where your feature slots in. Next week, after you've merged, `refresh` updates only the pages your diff touched.## What's in your project after seeding@@ -87,7 +87,7 @@ ok seed --pack codebase-wikiThe pack scaffolds the `wiki/` tree above with a stubbed `OVERVIEW.md` (empty `source_commit`), a starter template per section (`architecture-page`, `module-page`, `flow-page`, `concept-page`, `guide-page`), and `wiki/log.md`. Each folder's `.ok/frontmatter.yml` teaches the agent that section's job, so guidance lives next to the action rather than inside every page.<Callout type="info" title="Seeding also installs a skill">- `ok seed --pack codebase-wiki` installs the **Codebase wiki** project skill into your agent editors (Claude Code, Cursor, Codex, OpenCode). It's the "how to work here" guidance behind the generate / refresh procedure, the audience and depth knobs, and the source-reference discipline — read automatically, and editable like any other doc. It lands as a real `SKILL.md` committed to your repo, one per detected editor. See [Skills](../features/skills.mdx) and [what OpenKnowledge writes to disk](../reference/what-open-knowledge-writes.mdx).+ `ok seed --pack codebase-wiki` installs the **Codebase wiki** project skill into your agent editors (Claude Code, Cursor, Codex, OpenCode). It's the "how to work here" guidance behind the generate / refresh procedure, the audience and depth knobs, and the source-reference discipline — read automatically, and editable like any other doc. It lands as a real `SKILL.md` committed to your repo — one source under `.ok/skills/`, symlinked into each detected editor's skills directory. See [Skills](../features/skills.mdx) and [what OpenKnowledge writes to disk](../reference/what-open-knowledge-writes.mdx).</Callout>## Generate, then refresh@@ -102,7 +102,7 @@ To update it later, once it exists:Either prompt works — the pack auto-detects which mode to run from `source_commit` in `OVERVIEW.md`:-- **Generate** (a stubbed `OVERVIEW.md`): survey → overview → architecture → modules → flows → concepts → a final link-graph audit that catches orphans and dead links.+- **Generate** (a stubbed `OVERVIEW.md`): survey → overview → architecture → modules → flows → concepts → a final link-graph audit that catches orphans and dead links. It stops twice for your confirmation — first the knobs and coverage, then the proposed page list — before writing anything.- **Refresh** (a stamped `OVERVIEW.md`): diff the recorded `source_commit` against current `HEAD`, update only the affected pages, and re-stamp.`OVERVIEW.md` carries `source_commit` — the git commit the wiki was last built against. It's the freshness anchor: refresh diffs from it, so the wiki tracks the code instead of drifting into fiction.@@ -116,7 +116,7 @@ Either prompt works — the pack auto-detects which mode to run from `source_com| When | Do || --- | --- || First arrival at a repo | Generate at `standard` depth; skim `OVERVIEW.md` and the architecture pages |-| Onboarding someone | Point them at the wiki; regenerate at `exhaustive` if they need module-level depth |+| Onboarding someone | Point them at the wiki; regenerate at `exhaustive` if they need sub-module pages, task guides, and per-flow failure modes || After a significant merge | Refresh — the agent updates only the pages the diff touched and re-stamps `source_commit` || Going public | Regenerate with `audience: public` for GitHub-linked, secret-free prose |diff --git a/docs/content/workflows/entity-vault.mdx b/docs/content/workflows/entity-vault.mdxindex bb668af19..cb330a280 100644--- a/docs/content/workflows/entity-vault.mdx+++ b/docs/content/workflows/entity-vault.mdx@@ -1,14 +1,17 @@---title: Entity vault (GBrain-compatible) workflow+sidebarTitle: Entity vault (GBrain)icon: LuBoxesdescription: "A personal memory for the people, companies, and meetings in your world. Each one gets its own page that an AI keeps up to date as you learn more, and you can correct anything by hand. Works with Garry Tan's gbrain if you use it, but doesn't need it."----An **Entity vault (GBrain-compatible Markdown)** is a Markdown brain organized around typed dossiers: people, companies, meetings, concepts, originals, and media. Each durable dossier has two zones:+An **Entity vault (GBrain-compatible Markdown)** is a Markdown brain organized around typed dossiers: people, companies, meetings, concepts, originals, and media. Each person, company, and concept dossier has two zones:1. **Compiled truth** — the current synthesis, rewritten as evidence changes.2. **Timeline** — append-only evidence bullets, dated and attributable.+Meetings, originals, and media stay raw records.+OpenKnowledge scaffolds and edits that Markdown. Garry Tan's [`gbrain`](https://github.com/garrytan/gbrain), if you install it, can import/sync the same vault and add its DB-backed retrieval, graph extraction, embedding, and automation. OK does **not** replace `gbrain`; it gives GBrain-style Markdown brains a human cockpit for review, correction, attribution, and Git-visible edits.```html preview@@ -24,7 +27,7 @@ OpenKnowledge scaffolds and edits that Markdown. Garry Tan's [`gbrain`](https://<div id="dv-tl" style="margin-top:6px;display:flex;flex-direction:column;gap:5px"></div></div></div>- <div class="cap">Two zones per dossier: a compiled truth the agent rewrites as evidence changes, and a timeline it only ever appends to.</div>+ <div class="cap">Two zones per person, company, or concept dossier: a compiled truth the agent rewrites as evidence changes, and a timeline it only ever appends to.</div></div><style>.cap{margin-top:12px;color:var(--muted-foreground);font-size:12.5px;text-align:center}@@ -56,7 +59,7 @@ Founders and investors get a second brain over **people, companies, meetings, an## What the pack creates-Pick **Entity vault (GBrain-compatible)** in the starter-pack picker, or run:+Seeding needs an initialized project — run [`ok init`](../get-started/quickstart.mdx) first. Pick **Personal CRM** in the starter-pack picker, or run:```bashok seed --pack entity-vault@@ -83,7 +86,7 @@ your-project/Each folder includes an `.ok/frontmatter.yml` description that agents see during file listings/searches, plus templates under `.ok/templates/`.<Callout type="info" title="Seeding also installs a skill">- `ok seed --pack entity-vault` installs the **Entity vault** project skill into your agent editors (Claude Code, Cursor, Codex, OpenCode). It's the "how to work here" guidance behind the dossier conventions — compiled-truth vs. append-only timeline, path-qualified links, the correction loop — read automatically, and editable like any other doc. It lands as a real `SKILL.md` committed to your repo, one per detected editor. See [Skills](../features/skills.mdx) and [what OpenKnowledge writes to disk](../reference/what-open-knowledge-writes.mdx).+ `ok seed --pack entity-vault` installs the **Entity vault** project skill into your agent editors (Claude Code, Cursor, Codex, OpenCode). It's the "how to work here" guidance behind the dossier conventions — compiled-truth vs. append-only timeline, path-qualified links, the correction loop — read automatically, and editable like any other doc. It lands as a single `SKILL.md` in your repo under `.ok/skills/`, symlinked into the skills folder of each editor already set up for the project. See [Skills](../features/skills.mdx) and [what OpenKnowledge writes to disk](../reference/what-open-knowledge-writes.mdx).</Callout>## Markdown shape@@ -196,13 +199,13 @@ Aha moment: **GBrain makes agent memory useful; OK makes the Markdown memory ins| --- | --- || After each meeting | Drop raw notes into `meetings/<date>-<slug>.md`; link mentioned people/companies/concepts. || End of day | Ask an agent to create/update dossiers and append timeline bullets from new meetings. |-| Weekly | Run OK's dead-link audit; triage new entities vs typos vs intentional placeholders. |-| Monthly | Audit stale dossiers, empty timelines, and compiled truth that conflicts with recent evidence. |+| Weekly | Audit stale dossiers, empty timelines, and compiled truth that conflicts with recent evidence. |+| Monthly | Run OK's dead-link audit; triage new entities vs typos vs intentional placeholders. || When using `gbrain` | Commit OK edits, then run `gbrain sync --repo <vault>` and `gbrain embed --stale` as needed. |## Naming note-The pack is presented as **Entity vault (GBrain-compatible)**, not **GBrain Entity Vault**. "Entity vault" names the portable Markdown workflow OK scaffolds. "GBrain-compatible" describes the interop contract with Garry Tan's `gbrain` without claiming ownership of his project or implying OK is a replacement engine.+The starter-pack picker presents the pack as **Personal CRM**; its CLI pack id is `entity-vault`. "Entity vault" names the portable Markdown workflow OK scaffolds. "GBrain-compatible" describes the interop contract with Garry Tan's `gbrain` without claiming ownership of his project or implying OK is a replacement engine.## Further readingdiff --git a/docs/content/workflows/karpathy-llm-wiki.mdx b/docs/content/workflows/karpathy-llm-wiki.mdxindex d49f84d22..2acf39c94 100644--- a/docs/content/workflows/karpathy-llm-wiki.mdx+++ b/docs/content/workflows/karpathy-llm-wiki.mdx@@ -65,7 +65,7 @@ Either way, by the end of this guide you'll have a working source-grounded knowlYou need:- **The OpenKnowledge desktop app.** The native macOS app is the canonical surface: WYSIWYG editor, file sidebar, agent activity panel, version timeline, and the starter-pack picker all live there. Install it from the [Quickstart](../get-started/quickstart.mdx).-- **An MCP-capable agent assistant.** [Claude Code](../integrations/claude-code.mdx), [Cursor](../integrations/cursor.mdx), [Codex](../integrations/codex.mdx), or [OpenCode](../integrations/opencode.mdx). The OK desktop app's first-launch flow detects them and wires them up.+- **An MCP-capable agent assistant.** [Claude Code](../integrations/claude-code.mdx), [Cursor](../integrations/cursor.mdx), [Codex](../integrations/codex.mdx), [OpenCode](../integrations/opencode.mdx), or [OpenClaw](../integrations/openclaw.mdx). The OK desktop app's first-launch flow detects them and wires them up.- **A read of the source pattern.** Andrej Karpathy's [LLM wiki gist](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) is the canonical description of what we're implementing here. It's a 10-minute read and worth doing first; this guide builds on it directly.If you're brand new to OK, run the [Quickstart](../get-started/quickstart.mdx) (≤5 minutes to first agent-driven edit) and come back here.@@ -100,9 +100,9 @@ your-project/└── log.md (append-only audit trail)```-- **`external-sources/`.** Five `.md` files, each carrying the verbatim source text plus YAML frontmatter with the original URL, fetch date, and author metadata. *Immutable* after capture. The agent reads these but never edits them. (Karpathy's gist calls this folder `raw/`; OK's pack ships it as `external-sources/` for clearer intent.)+- **`external-sources/`.** Five `.md` files, each carrying the verbatim source text plus YAML frontmatter with the original URL, fetch date, and author metadata. *Immutable* after capture. The agent reads these but never edits them. (This is Karpathy's raw-sources layer; his gist leaves the folder name open.)- **`research/`.** One provisional article synthesizing the five sources into an evaluation. Every claim cites a specific path in `external-sources/`. Status: `provisional` (you can change it).-- **`articles/`.** Still empty. You consolidate to here only when you've actually decided (e.g., "yes we're adopting this framework"). Premature consolidation is how wikis go stale. (Karpathy's gist puts both provisional and canonical pages in a single `wiki/` folder; OK splits them so the promotion step is explicit.)+- **`articles/`.** Still empty. You consolidate to here only when you've actually decided (e.g., "yes we're adopting this framework"). Premature consolidation is how wikis go stale. (Karpathy's gist puts both provisional and canonical pages in a single wiki layer; OK splits them so the promotion step is explicit.)- **`log.md`.** One append-only file at project root recording each ingest, research pass, and consolidation. The audit trail. (Direct from Karpathy's pattern.)## The workflow behind it@@ -111,8 +111,8 @@ Karpathy's pattern, summarized from the [gist](https://gist.github.com/karpathy/| Element | What it is | Karpathy's filenames ||---|---|---|-| **Raw sources** | Immutable collection of the actual documents (articles, papers, repo READMEs, transcripts). The LLM reads but does not modify. | `raw/` (with `raw/assets/` for attachments) |-| **The wiki** | LLM-generated markdown files: summaries, entity pages, concept pages, cross-references. Single layer; the LLM owns it entirely. | `wiki/` |+| **Raw sources** | Immutable collection of the actual documents (articles, papers, repo READMEs, transcripts). The LLM reads but does not modify. | left open (`raw/assets/` appears only as an example attachment path) |+| **The wiki** | LLM-generated markdown files: summaries, entity pages, concept pages, cross-references. Single layer; the LLM owns it entirely. | left open || **The log** | Append-only record of ingests, queries, lint passes: *"what happened and when."* | `log.md` || **The index** | Content-oriented catalog listing every page with link, summary, optional metadata. | `index.md` || **The schema** | Config document telling the LLM how the wiki is structured. | `CLAUDE.md` (Claude Code) or `AGENTS.md` (other hosts) |@@ -134,12 +134,12 @@ The **Knowledge base** pack scaffolds Karpathy's pattern with one significant ad| Karpathy | OpenKnowledge ||---|---|-| `raw/` (verbatim sources, immutable) | `external-sources/` (OK's name; same role) + `clip` template + `ingest` workflow |-| `wiki/` (single LLM-owned layer) | **Split**: `research/` (provisional, status:`provisional`, sources cited) + `articles/` (canonical, status:`canonical`, supersedes chain); `consolidate` promotes |+| Raw sources (verbatim, immutable) | `external-sources/` + `clip` template + `ingest` workflow |+| The wiki (single LLM-owned layer) | **Split**: `research/` (provisional, status:`provisional`, sources cited) + `articles/` (canonical, status:`canonical`, supersedes chain); `consolidate` promotes || `log.md` (append-only record) | `log.md` at project root, written by the pack || `index.md` (static content catalog) | Provided dynamically via `exec` (`ls`) + the file sidebar. The agent reads folder frontmatter + per-doc metadata on every list call, so a static index isn't required. You can still hand-write `index.md` if you prefer. || `CLAUDE.md` / `AGENTS.md` (centralized schema) | `<folder>/.ok/frontmatter.yml` + per-folder templates; schema lives next to the action |-| LLM agent | [Claude Code](../integrations/claude-code.mdx), [Cursor](../integrations/cursor.mdx), [Codex](../integrations/codex.mdx), [OpenCode](../integrations/opencode.mdx) |+| LLM agent | [Claude Code](../integrations/claude-code.mdx), [Cursor](../integrations/cursor.mdx), [Codex](../integrations/codex.mdx), [OpenCode](../integrations/opencode.mdx), [OpenClaw](../integrations/openclaw.mdx) |When your agent lists `external-sources/`, it reads the folder description telling it to ingest verbatim and *not* analyze in those files. That's the schema layer doing its job, without you hand-writing a `CLAUDE.md` from scratch.@@ -147,25 +147,25 @@ When your agent lists `external-sources/`, it reads the folder description telli### 1. Open the desktop app and pick a project folder-Launch **OpenKnowledge** (the macOS app). Either drag-and-drop a folder, open one from **Pick Existing Project**, or click **Start Fresh** to create a new vault. The first-launch consent dialog scaffolds `.ok/` and offers to wire up any MCP-capable editors it detects (Claude Code, Cursor, Codex, OpenCode).+Launch **OpenKnowledge** (the macOS app). Either drag-and-drop a folder, click **Open folder on disk**, or click **Create new project** to start a new vault. The first-launch consent dialog scaffolds `.ok/` and offers to wire up any MCP-capable editors it detects (Claude Code, Cursor, Codex, OpenCode, OpenClaw).Don't have the desktop app yet? See the [Quickstart](../get-started/quickstart.mdx).### 2. Initialize the Knowledge base starter pack-In the editor, on a fresh project, click the empty-state **Pick a starter pack** button → select **Knowledge base** → confirm the subfolder (leave blank for project-root, or use something like `brain/` to nest the layers). Apply.+In the editor, on a fresh project, click the **Knowledge base** card in the empty state, leave **Project root** selected (or choose **In a subfolder** to nest the layers under something like `brain/`), and click **Initialize**. On a project with existing documents, the same flow starts from the **Add a starter pack** button.-You'll get `external-sources/`, `research/`, `articles/`, the three matching templates, and `log.md` at the chosen root. The folders carry descriptions written *for the agent*; see them in the file sidebar's folder tooltips, and in any `exec` directory listing from an agent.+You'll get `external-sources/`, `research/`, `articles/`, the three matching templates, and `log.md` at the chosen root. The folders carry descriptions written *for the agent*; see them on the folder's overview page (click the folder in the sidebar), and in any `exec` directory listing from an agent.The starter-pack picker is idempotent (safe to re-run on the same project).<Callout type="info" title="Seeding also installs a skill">- `ok seed --pack knowledge-base` (or the desktop starter-pack picker) installs the **Knowledge base** project skill into your agent editors (Claude Code, Cursor, Codex, OpenCode). It's the "how to work here" guidance behind the layer discipline described below — the `ingest` / `research` / `consolidate` conventions and the provisional-to-canonical promotion — read automatically, and editable like any other doc. It lands as a real `SKILL.md` committed to your repo, one per detected editor. See [Skills](../features/skills.mdx) and [what OpenKnowledge writes to disk](../reference/what-open-knowledge-writes.mdx).+ `ok seed --pack knowledge-base` (or the desktop starter-pack picker) installs the **Knowledge base** project skill into your agent editors (Claude Code, Cursor, Codex, OpenCode). It's the "how to work here" guidance behind the layer discipline described below — the `ingest` / `research` / `consolidate` conventions and the provisional-to-canonical promotion — read automatically, and editable like any other doc. It lands as a single `SKILL.md` in your repo under `.ok/skills/`, symlinked into the skills folder of each editor already set up for the project. See [Skills](../features/skills.mdx) and [what OpenKnowledge writes to disk](../reference/what-open-knowledge-writes.mdx).</Callout>### 3. Confirm your agent host is wired-If you accepted the desktop app's first-launch offer to wire up your agent assistant, you're done. If not, in your agent assistant ([Claude Code](../integrations/claude-code.mdx), [Cursor](../integrations/cursor.mdx), or [Codex](../integrations/codex.mdx)), ask:+If you accepted the desktop app's first-launch offer to wire up your agent assistant, you're done. If not, in your agent assistant, ask:<CopyPrompt>list the workflow tools available</CopyPrompt>@@ -201,9 +201,9 @@ The agent reads `research/agent-framework-evaluation.md` first, follows the citaThe pack doesn't just create three folders. It scaffolds the **agent-readable schema layer** that makes the LLM behave per Karpathy's conventions without you hand-writing a `CLAUDE.md`.-Each folder gets a `.ok/frontmatter.yml` (the agent reads it on every `exec` directory listing) plus a `.ok/templates/<name>.md` (the agent picks it on every `write({ document: { template } })` call). `external-sources/.ok/frontmatter.yml`, for example, opens with:+Each folder gets a `.ok/frontmatter.yml` (the agent reads it on every `exec` directory listing) plus a `.ok/templates/<name>.md` (the agent picks it on every `write({ document: { template } })` call). `external-sources/.ok/frontmatter.yml`, for example, carries this description:-> Raw sources SAVED verbatim, not just cited. Produced by `ingest`... Immutable after capture. No analysis in these files; that belongs in `research/`.+> Raw sources saved verbatim — the fetched text of URLs, extracted PDFs, and copied files, each with the original URL and access date in frontmatter. Produced by `ingest`. Immutable after capture; no analysis here (that goes in `research/`).Result: the agent learns each layer's discipline without a separate prompt or skills file. `research/` and `articles/` carry analogous descriptions. This is Karpathy's centralized `CLAUDE.md` schema, distributed per-folder, so schema lives closest to the agent action. Customize via `mcp__open-knowledge__edit` (with a `folder` target).@@ -228,7 +228,7 @@ When to use each tool, and when *not* to:| You're synthesizing 2+ sources into an answer | `research` | Provisional article, citations required, status:provisional || Team decided; this is the canonical position | `consolidate` | Writes status:canonical with supersedes chain || You just want to write a note | `write` | Not every doc needs the workflow (scratch notes, project pages, runbooks) |-| You ran a one-off query and the answer's useful | Save the chat to a new doc in `research/` | Per Karpathy: *"valuable query results become new wiki pages"*; don't let them die in chat history |+| You ran a one-off query and the answer's useful | Save the chat to a new doc in `research/` | Per Karpathy, good answers get filed back into the wiki as new pages; don't let them die in chat history |**Anti-pattern: consolidating too early.** If you `consolidate` before the team has actually decided, you'll be rewriting canonical articles every week. Status `provisional` exists for a reason. Keep things in `research/` until decisions are real.@@ -249,7 +249,7 @@ The compounding move: end each ingest session with one synthesis query. The answ- **Folder descriptions are agent-readable.** The pack writes `<folder>/.ok/frontmatter.yml` so the agent learns layer discipline on every `exec` directory listing, with no separate `CLAUDE.md`.- **`log.md` doubles as a journal.** Every `ingest` / `research` / `consolidate` lands there with timestamps. Underrated.-- **`New from template…`** in the sidebar gives you the right frontmatter shape instantly. Don't hand-author.+- **`New from template`** in the sidebar gives you the right frontmatter shape instantly. Don't hand-author.## Looking for entity tracking instead?@@ -264,7 +264,7 @@ This guide is the **source-grounded** posture: bring sources, the LLM curates th### OpenKnowledge internals that support this workflow- **[Agent activity](../features/agent-activity.mdx).** How every agent edit lands in the shadow repo with attribution.-- **[Claude Code](../integrations/claude-code.mdx)**, **[Cursor](../integrations/cursor.mdx)**, **[Codex](../integrations/codex.mdx)**, **[OpenCode](../integrations/opencode.mdx).** Agent-assistant integrations.+- **[Claude Code](../integrations/claude-code.mdx)**, **[Cursor](../integrations/cursor.mdx)**, **[Codex](../integrations/codex.mdx)**, **[OpenCode](../integrations/opencode.mdx)**, **[OpenClaw](../integrations/openclaw.mdx).** Agent-assistant integrations.- **[`STARTER_PACKS` registry](https://github.com/inkeep/open-knowledge/blob/main/packages/server/src/seed/starter.ts).** Canonical source for the Knowledge base pack content.### Adjacent OK workflowdiff --git a/docs/content/workflows/meta.json b/docs/content/workflows/meta.jsonindex d3d69ef6a..e26d7de20 100644--- a/docs/content/workflows/meta.json+++ b/docs/content/workflows/meta.json@@ -1,14 +1,14 @@{- "title": "Workflows",- "icon": "LuWorkflow",+ "title": "Use Cases",+ "icon": "LuLightbulb","pages": ["karpathy-llm-wiki","codebase-wiki","software-lifecycle",- "entity-vault","writing-pipeline",- "supporting-open-knowledge-format",+ "plain-notes","worldbuilding",- "plain-notes"+ "supporting-open-knowledge-format",+ "entity-vault"]}diff --git a/docs/content/workflows/plain-notes.mdx b/docs/content/workflows/plain-notes.mdxindex 86a559e1a..2fb7fdc73 100644--- a/docs/content/workflows/plain-notes.mdx+++ b/docs/content/workflows/plain-notes.mdx@@ -61,7 +61,7 @@ On the first entry of a day the agent links back to yesterday's entry and pre-fi## What's in your project after seeding-Pick **Plain notes** in the starter-pack picker, or run:+Seeding needs an initialized project — run [`ok init`](../get-started/quickstart.mdx) first. Pick **Plain notes** in the starter-pack picker, or run:```bashok seed --pack plain-notes@@ -70,7 +70,7 @@ ok seed --pack plain-notesThe pack creates `notes/` and `daily/` at the project root (no subfolder), each with its `.ok/frontmatter.yml` guidance and template. That's the whole footprint — minimal on purpose.<Callout type="info" title="Seeding also installs a skill">- `ok seed --pack plain-notes` installs the **Plain notes** project skill into your agent editors (Claude Code, Cursor, Codex, OpenCode). It's the "how to work here" guidance that gives the agent the linking habit and the daily-chain behavior — read automatically, and editable like any other doc. It lands as a real `SKILL.md` committed to your repo, one per detected editor. See [Skills](../features/skills.mdx) and [what OpenKnowledge writes to disk](../reference/what-open-knowledge-writes.mdx).+ `ok seed --pack plain-notes` installs the **Plain notes** project skill into your agent editors (Claude Code, Cursor, Codex, OpenCode). It's the "how to work here" guidance that gives the agent the linking habit and the daily-chain behavior — read automatically, and editable like any other doc. It lands as a real `SKILL.md` committed to your repo under `.ok/skills/`, symlinked into each detected editor. See [Skills](../features/skills.mdx) and [what OpenKnowledge writes to disk](../reference/what-open-knowledge-writes.mdx).</Callout>## Cadence@@ -88,4 +88,4 @@ The pack creates `notes/` and `daily/` at the project root (no subfolder), each- **[Writing pipeline workflow](./writing-pipeline.mdx).** When your notes grow into essays or newsletters, this pack adds ideas → drafts → published stage gates.- **[Core Concepts](../reference/core-concepts.md).** Links, backlinks, and the well-connected graph that make the emergent structure visible.- **[Skills](../features/skills.mdx).** What the installed pack skill is, and how to edit it.-- **[Claude Code](../integrations/claude-code.mdx)**, **[Cursor](../integrations/cursor.mdx)**, **[Codex](../integrations/codex.mdx).** MCP-capable agent hosts.+- **[Claude Code](../integrations/claude-code.mdx)**, **[Cursor](../integrations/cursor.mdx)**, **[Codex](../integrations/codex.mdx)**, **[OpenCode](../integrations/opencode.mdx).** MCP-capable agent hosts.diff --git a/docs/content/workflows/software-lifecycle.mdx b/docs/content/workflows/software-lifecycle.mdxindex dfda4a242..dce817c61 100644--- a/docs/content/workflows/software-lifecycle.mdx+++ b/docs/content/workflows/software-lifecycle.mdx@@ -8,7 +8,7 @@ A **software lifecycle** knowledge base is where an engineering team's thinking```html preview<div style="padding:18px"><div id="flow" style="display:flex;flex-wrap:wrap;gap:8px;align-items:stretch"></div>- <div class="cap">Each stage is a folder of markdown. The arrows are links the agent maintains, so a spec always points back to the decision that authorized it.</div>+ <div class="cap">Each stage is a folder of markdown. The arrows are links the agent maintains, so a spec always points back to the proposal it implements.</div></div><style>#flow .node{flex:1;min-width:118px;border:1px solid var(--border);border-radius:12px;padding:11px 13px;background:var(--card);transition:box-shadow .3s,border-color .3s;cursor:pointer}@@ -40,7 +40,7 @@ if(!matchMedia("(prefers-reduced-motion:reduce)").matches){setInterval(function(</script>```-The stages are the standard artifacts an engineering org already produces — RFCs, ADRs, specs, blameless postmortems, runbooks — but here they live as linked markdown an agent reads and writes alongside you, not as scattered Google Docs, Notion pages, and Slack threads that nobody can trace six months later.+The stages are the standard artifacts an engineering org already produces — RFCs, ADRs, specs, blameless postmortems, runbooks — but here they live as linked markdown an agent reads and writes alongside you, not scattered across Google Docs, Notion pages, and Slack threads that are hard to trace six months later.Engineering leads get every proposal, decision, and spec in one linked graph, with the agent surfacing what supersedes what, so design docs stop rotting across scattered tools. OSS maintainers give contributors the *why* behind the code — in accepted proposals and frozen ADRs — instead of leaving them to do archaeology through closed PRs. On-call engineers get postmortems that link to each other and stub the follow-up guides automatically, so recurring incidents become visible instead of quietly repeating.@@ -57,7 +57,7 @@ postmortems/ blameless incident write-upsguides/ how-to / onboarding / runbooks — referenced throughout```-The pack ships a template for each: `proposal`, `decision`, `spec` / `plan` / `tasks` (the [GitHub spec-kit](https://github.com/github/spec-kit) three-file shape), `postmortem`, and `guide` / `onboarding-guide` / `runbook`. Templates carry only structure; what each section is for is taught to the agent by the folder itself, so document bodies stay clean.+The pack ships a template for each: `proposal`, `decision`, `spec` / `spec-plan` / `spec-tasks` (the [GitHub spec-kit](https://github.com/github/spec-kit) three-file shape), `postmortem`, and `guide` / `onboarding-guide` / `runbook`. Templates carry only structure; what each section is for is taught to the agent by the folder itself, so document bodies stay clean.## The scenario@@ -65,7 +65,7 @@ Your team is deciding whether to move the job queue off Postgres onto a dedicate1. An engineer writes `proposals/0007-dedicated-job-broker.md` — motivation, design, drawbacks, alternatives, unresolved questions. Status `draft`.2. After review it reaches `fcp` (final comment period), then `accepted`. The agent graduates it into `decisions/0007-adopt-nats-for-jobs.md`, a frozen ADR that links back to the proposal.-3. Implementation gets a `specs/007-job-broker/` folder — `spec.md`, `plan.md`, `tasks.md` — referencing the parent decision.+3. Implementation gets a `specs/007-job-broker/` folder — `spec.md`, `plan.md`, `tasks.md` — referencing the parent proposal.4. Three weeks post-ship the broker drops messages under load. `postmortems/2026-07-14-job-broker-message-loss.md` captures the timeline and root cause, and the agent surfaces a `Related:` link to an older queue postmortem that shares the subsystem.Nothing here is new to your team. What's new: it's all one linked graph an agent can read back to you, and the links stay correct because the agent maintains them.@@ -78,22 +78,21 @@ Pick **Software lifecycle** in the starter-pack picker, or run:ok seed --pack software-lifecycle```-By default the pack nests everything under a `project-docs/` subfolder:+By default the pack scaffolds everything at the project root:```your-project/-└── project-docs/- ├── proposals/ 0001-feature-name.md …- ├── decisions/ NNNN-title.md (ADRs)- ├── specs/ NNN-name/{spec,plan,tasks}.md- ├── postmortems/ YYYY-MM-DD-name.md- └── guides/ how-to / onboarding / runbooks+├── proposals/ 0001-feature-name.md …+├── decisions/ NNNN-title.md (ADRs)+├── specs/ NNN-name/{spec,plan,tasks}.md+├── postmortems/ YYYY-MM-DD-name.md+└── guides/ how-to / onboarding / runbooks```Each folder carries an `.ok/frontmatter.yml` description the agent reads on every directory listing, plus its templates under `.ok/templates/`. That description is where the workflow lives — so the agent knows an accepted proposal graduates to `decisions/`, that ADRs freeze once accepted, and that a new decision superseding an old one links back via `Supersedes:`.<Callout type="info" title="Seeding also installs a skill">- `ok seed --pack software-lifecycle` installs the **Software lifecycle** project skill into your agent editors (Claude Code, Cursor, Codex, OpenCode). It's the "how to work here" guidance behind the behaviors below — the status flows, the `Supersedes:` scanning, the postmortem follow-ups — read automatically, and editable like any other doc. It lands as a real `SKILL.md` committed to your repo, one per detected editor. See [Skills](../features/skills.mdx) and [what OpenKnowledge writes to disk](../reference/what-open-knowledge-writes.mdx).+ `ok seed --pack software-lifecycle` installs the **Software lifecycle** project skill into your agent editors (Claude Code, Cursor, Codex, OpenCode). It's the "how to work here" guidance behind the behaviors below — the status flows, the `Supersedes:` scanning, the postmortem follow-ups — read automatically, and editable like any other doc. It lands as a real `SKILL.md` in your repo under `.ok/skills/`, symlinked into each editor's skills directory. See [Skills](../features/skills.mdx) and [what OpenKnowledge writes to disk](../reference/what-open-knowledge-writes.mdx).</Callout>## What the agent does for you@@ -111,7 +110,7 @@ The pack teaches the agent behaviors you'd otherwise have to remember. _They're### 1. Seed the pack-In a fresh project, open the starter-pack picker and choose **Software lifecycle** (or run `ok seed --pack software-lifecycle`). Confirm the subfolder — leave `project-docs/` or point it at wherever your team's docs live.+In an initialized project (run `ok init` first — see the [quickstart](../get-started/quickstart.mdx)), open the starter-pack picker and choose **Software lifecycle** (or run `ok seed --pack software-lifecycle`). To nest everything under a subfolder — `project-docs/` or wherever your team's docs live — select **In a subfolder** in the picker or pass `--root project-docs`.### 2. Write the first proposal@@ -129,7 +128,7 @@ The agent writes the frozen record and — per the pack behavior — checks the### 4. Derive the spec-<CopyPrompt>Create an implementation spec for the accepted broker decision under specs/, using the spec / plan / tasks templates. Reference the parent decision.</CopyPrompt>+<CopyPrompt>Create an implementation spec for the accepted broker decision under specs/, using the spec / spec-plan / spec-tasks templates. Reference the parent proposal.</CopyPrompt>### 5. Write postmortems as incidents happendiff --git a/docs/content/workflows/supporting-open-knowledge-format.mdx b/docs/content/workflows/supporting-open-knowledge-format.mdxindex 29230ac93..641b8bb4c 100644--- a/docs/content/workflows/supporting-open-knowledge-format.mdx+++ b/docs/content/workflows/supporting-open-knowledge-format.mdx@@ -1,9 +1,10 @@---title: Supporting the Open Knowledge Format+sidebarTitle: Open Knowledge Formaticon: LuFileCodedescription: "Start a knowledge base that already follows Google's Open Knowledge Format, so any OKF tool can read it later. You get the right setup out of the box, and you're still free to write however you like."----Open Knowledge ships a starter pack named **`okf`** that scaffolds a knowledge base **conformant with Google's [Open Knowledge Format (OKF)](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) from the first commit** — without enforcing anything. You get a portable, OKF-ready bundle out of the box, and you stay free to author however you like.+OpenKnowledge ships a starter pack named **`okf`** that scaffolds a knowledge base **conformant with Google's [Open Knowledge Format (OKF)](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) from the first commit** — without enforcing anything. You get a portable, OKF-ready bundle out of the box, and you stay free to author however you like.<Callout type="info">**OKF here means Google's Open Knowledge _Format_** — a vendor-neutral file-format spec (a directory of markdown files with YAML frontmatter), announced by Google Cloud in June 2026. Read the [OKF v0.1 spec](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md).@@ -39,14 +40,14 @@ The point is portability from day one: a knowledge base you can hand to any tool## What the pack seeds-Run it with `ok seed --pack okf`. It scaffolds:+In an initialized project (`ok init` first), pick **Open Knowledge Format** in the starter-pack picker (behind **Show more**), or run `ok seed --pack okf`. It scaffolds:| Path | Purpose | Template ||---|---|---|| `concepts/` | Durable ideas and definitions | `concept` || `references/` | External sources and citations | `reference` || `notes/` | Working notes and observations | `note` |-| `welcome.md` | A real typed concept, so a strict OKF consumer has something to accept | — (seeded file) |+| `welcome.md` | A real typed document (`type: Document`), so a strict OKF consumer has something to accept | — (seeded file) || `index.md` | Reserved OKF navigation hub | — (reserved) || `log.md` | Reserved OKF change history | — (reserved) |@@ -56,9 +57,9 @@ Each of the three content folders (`concepts/`, `references/`, `notes/`) ships iThis is the key design decision. OKF asks exactly one thing of every **non-reserved** document: a **non-empty `type`** in its frontmatter. Reserved `index.md` / `log.md` stay frontmatter-free, and links are standard markdown.-The pack bakes those habits into the seeded content and documents them — but it changes nothing about how Open Knowledge itself behaves:+The pack bakes those habits into the seeded content and documents them — but it changes nothing about how OpenKnowledge itself behaves:-- Open Knowledge's native frontmatter schema stays **open-shaped**.+- OpenKnowledge's native frontmatter schema stays **open-shaped**.- Nothing is **linted** for OKF conformance.So three habits are all it takes to keep the KB handable to a strict OKF consumer as it grows:@@ -67,7 +68,7 @@ So three habits are all it takes to keep the KB handable to a strict OKF consume2. `index.md` / `log.md` stay lowercase and frontmatter-free.3. Links use standard markdown (`[text](./path.md)`).-Open Knowledge also accepts `[[wiki-link]]` shorthand as a native superset, and the OKF export normalizes it to standard links — but seeded content uses standard links so the bundle is conformant as-is.+OpenKnowledge also accepts `[[wiki-link]]` shorthand as a native superset, but nothing normalizes it to standard links — seeded content uses standard links so the bundle is conformant as-is.## Cadence@@ -77,11 +78,11 @@ Three habits keep the bundle handable to a strict OKF consumer as it grows. The|---|---|| Creating a doc | Use **New from template** — it sets `type` for you || Reserved files | Keep `index.md` / `log.md` lowercase and frontmatter-free |-| Links | Use standard markdown links; `[[wiki-link]]` shorthand normalizes on export |+| Links | Use standard markdown links; `[[wiki-link]]` shorthand stays as written || Handing it off | Nothing special — the bundle is conformant as you go |## Further reading- **[Open Knowledge Format spec](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)** — the canonical OKF v0.1 specification (Google Cloud).- **[`STARTER_PACKS` registry](https://github.com/inkeep/open-knowledge/blob/main/packages/server/src/seed/starter.ts)** — canonical source for the `okf` pack content.-- **[Karpathy's LLM wiki workflow](./karpathy-llm-wiki.mdx)** and **[Entity vault workflow](./entity-vault.mdx)** — other starter-pack-driven workflows in Open Knowledge.+- **[Karpathy's LLM wiki workflow](./karpathy-llm-wiki.mdx)** and **[Entity vault workflow](./entity-vault.mdx)** — other starter-pack-driven workflows in OpenKnowledge.diff --git a/docs/content/workflows/worldbuilding.mdx b/docs/content/workflows/worldbuilding.mdxindex d8380fed2..77a890821 100644--- a/docs/content/workflows/worldbuilding.mdx+++ b/docs/content/workflows/worldbuilding.mdx@@ -67,13 +67,13 @@ The agent stubs `characters/kael.md` linked to `factions/iron-pact.md` and `sett## What's in your project after seeding-Pick **Worldbuilding** in the starter-pack picker, or run:+In an initialized project (`ok init`), pick **Worldbuilding** in the starter-pack picker, or run:```bashok seed --pack worldbuilding```-By default the pack nests under a `world/` subfolder:+Pass `--root world` (or pick **In a subfolder** in the picker) to nest the pack under `world/`:```your-project/@@ -85,10 +85,10 @@ your-project/└── lore/```-Each folder's `.ok/frontmatter.yml` teaches the agent that entity type and its auto-stub / contradiction behavior, so the guidance never clutters the entries themselves.+Each folder's `.ok/frontmatter.yml` teaches the agent that entity type and what belongs there, so the guidance never clutters the entries themselves.<Callout type="info" title="Seeding also installs a skill">- `ok seed --pack worldbuilding` installs the **Worldbuilding** project skill into your agent editors (Claude Code, Cursor, Codex, OpenCode). It's the "how to work here" guidance behind the auto-stub and contradiction-flagging behaviors — read automatically, and editable like any other doc. It lands as a real `SKILL.md` committed to your repo, one per detected editor. See [Skills](../features/skills.mdx) and [what OpenKnowledge writes to disk](../reference/what-open-knowledge-writes.mdx).+ `ok seed --pack worldbuilding` installs the **Worldbuilding** project skill into your agent editors (Claude Code, Cursor, Codex, OpenCode). It's the "how to work here" guidance behind the auto-stub and contradiction-flagging behaviors — read automatically, and editable like any other doc. It lands as one real `SKILL.md` under `.ok/skills/`, committed to your repo and symlinked into each set-up editor's skills folder. See [Skills](../features/skills.mdx) and [what OpenKnowledge writes to disk](../reference/what-open-knowledge-writes.mdx).</Callout>## Cadence@@ -105,4 +105,4 @@ Each folder's `.ok/frontmatter.yml` teaches the agent that entity type and its a- **[LLM wiki workflow](./karpathy-llm-wiki.mdx).** The same wiki-graph discipline, aimed at real-world sources instead of a fictional world.- **[Entity vault workflow](./entity-vault.mdx).** The non-fiction sibling — track real people, companies, and meetings the same way you track characters and factions.- **[Core Concepts](../reference/core-concepts.md).** Links and backlinks — the connected graph you navigate the world through.-- **[Claude Code](../integrations/claude-code.mdx)**, **[Cursor](../integrations/cursor.mdx)**, **[Codex](../integrations/codex.mdx).** MCP-capable agent hosts.+- **[Claude Code](../integrations/claude-code.mdx)**, **[Cursor](../integrations/cursor.mdx)**, **[Codex](../integrations/codex.mdx)**, **[OpenCode](../integrations/opencode.mdx).** MCP-capable agent hosts.diff --git a/docs/content/workflows/writing-pipeline.mdx b/docs/content/workflows/writing-pipeline.mdxindex 1a2b82942..1ebbedaa1 100644--- a/docs/content/workflows/writing-pipeline.mdx+++ b/docs/content/workflows/writing-pipeline.mdx@@ -70,10 +70,10 @@ You write it with your agent over a few sessions — every revision captured inPick **Writing pipeline** in the starter-pack picker, or run:```bash-ok seed --pack writing-pipeline+ok seed --pack writing-pipeline --root writing```-By default the pack nests under a `writing/` subfolder:+The picker pre-fills the `writing/` subfolder; `--root writing` does the same from the CLI (omit it to scaffold at the project root):```your-project/@@ -86,7 +86,7 @@ your-project/Each folder carries its `.ok/frontmatter.yml` guidance and templates. If a draft needs research notes, the agent creates `drafts/<slug>/research/` on demand rather than cluttering the top level.<Callout type="info" title="Seeding also installs a skill">- `ok seed --pack writing-pipeline` installs the **Writing pipeline** project skill into your agent editors (Claude Code, Cursor, Codex, OpenCode). It's the "how to work here" guidance behind the behaviors below — the stage promotions, the idle-draft nudges, the publish-time URL fill — read automatically, and editable like any other doc. It lands as a real `SKILL.md` committed to your repo, one per detected editor. See [Skills](../features/skills.mdx) and [what OpenKnowledge writes to disk](../reference/what-open-knowledge-writes.mdx).+ `ok seed --pack writing-pipeline` installs the **Writing pipeline** project skill into your agent editors (Claude Code, Cursor, Codex, OpenCode). It's the "how to work here" guidance behind the behaviors below — the stage promotions, the idle-draft nudges, the publish-time URL fill — read automatically, and editable like any other doc. It lands as a single `SKILL.md` under `.ok/skills/`, committed to your repo and symlinked into each detected editor's skills directory. See [Skills](../features/skills.mdx) and [what OpenKnowledge writes to disk](../reference/what-open-knowledge-writes.mdx).</Callout>## What the agent does for you@@ -106,7 +106,7 @@ _These behaviors are encoded in the pack skill and run **when you prompt the age| --- | --- || Whenever a premise strikes | One line into `ideas/`. That's the whole capture step || When you commit to a piece | Promote the idea into `drafts/`; write with your agent, revisions tracked automatically |-| On ship | Move to `published/`; let the agent fill `canonical_url` and `channel` |+| On ship | Move to `published/`; let the agent fill `canonical_url` || To revise a published piece | Copy it back to a new draft — never edit `published/` in place || Monthly | Ask the agent to surface stale ideas and stalled drafts |@@ -115,4 +115,4 @@ _These behaviors are encoded in the pack skill and run **when you prompt the age- **[LLM wiki workflow](./karpathy-llm-wiki.mdx).** If your writing is source-grounded research rather than original prose, the source-curation posture fits better.- **[Editor](../features/editor.mdx).** The WYSIWYG surface you'll actually draft in.- **[Timeline and recovery](../features/timeline-and-recovery.mdx).** Where your draft revisions live — the reason there are no named-revision folders.-- **[Claude Code](../integrations/claude-code.mdx)**, **[Cursor](../integrations/cursor.mdx)**, **[Codex](../integrations/codex.mdx).** MCP-capable agent hosts.+- **[Claude Code](../integrations/claude-code.mdx)**, **[Cursor](../integrations/cursor.mdx)**, **[Codex](../integrations/codex.mdx)**, **[OpenCode](../integrations/opencode.mdx).** MCP-capable agent hosts.diff --git a/docs/src/components/agent-icons.tsx b/docs/src/components/agent-icons.tsxindex eb4f879bc..9bfb24d64 100644--- a/docs/src/components/agent-icons.tsx+++ b/docs/src/components/agent-icons.tsx@@ -1,6 +1,7 @@import { ClaudeIcon } from '@/components/icons/claude';import { CodexIcon } from '@/components/icons/codex';import { CursorIcon } from '@/components/icons/cursor';+import { OpenClawIcon } from '@/components/icons/openclaw';import { OpenCodeIcon } from '@/components/icons/opencode';const AGENTS = [@@ -8,6 +9,7 @@ const AGENTS = [{ name: 'Cursor', Icon: CursorIcon },{ name: 'Codex', Icon: CodexIcon },{ name: 'OpenCode', Icon: OpenCodeIcon },+ { name: 'OpenClaw', Icon: OpenClawIcon },] as const;export function AgentIcons() {diff --git a/docs/src/components/mcp-install.tsx b/docs/src/components/mcp-install.tsxindex c11aea957..7198ed6b5 100644--- a/docs/src/components/mcp-install.tsx+++ b/docs/src/components/mcp-install.tsx@@ -1,12 +1,10 @@import type { ReactNode } from 'react';/**- * Shared "Install" body for the MCP integrations — Claude Code, Codex, and- * Cursor. Covers both ways the editor gets wired up: the macOS desktop app's- * first-launch consent dialog, and `ok init` for the web app / terminal path.- * The reset path (`~/.ok/mcp-status.json`) is single-sourced here. Optional- * editor-specific notes go in `children`. Claude Desktop's DMG install is- * bespoke and does not use this.+ * Shared "Install" body for the MCP integration pages. Covers both ways the+ * editor gets wired up: the macOS desktop app's first-launch consent dialog,+ * and `ok init` for the web app / terminal path. The consent-dialog re-trigger+ * is single-sourced here. Optional editor-specific notes go in `children`.*/export function McpInstall({ editor, children }: { editor: string; children?: ReactNode }) {return (@@ -15,17 +13,18 @@ export function McpInstall({ editor, children }: { editor: string; children?: Re<ul><li><strong>macOS desktop app.</strong> The first time you open a project, a consent dialog- detects {editor} and configures it for you. To re-trigger the dialog, delete{' '}- <code>~/.ok/mcp-status.json</code> and relaunch.+ detects {editor} and configures it for you. To re-trigger the dialog, choose{' '}+ {/* biome-ignore lint/plugin/microcopy-ellipsis: quoting the literal macOS menu label (menu.ts) */}+ <strong>File → Set up OpenKnowledge integrations…</strong>.</li><li>- <strong>Web app / terminal</strong> (Linux, Intel Mac — see the{' '}+ <strong>Web app / terminal</strong> (Linux, Windows, Intel Mac — see the{' '}<a href="/docs/get-started/quickstart#ok-install-web-app-linux-windows-intel-mac">web app guide</a>). Run <code>ok init</code> in your project: it registers the OpenKnowledge MCP server- with {editor} and the other editors it detects. Every <code>ok start</code> refreshes the- entry.+ with {editor} and the other editors it detects. Every <code>ok start</code> repairs the+ entry if it has drifted (it never adds one you removed).</li></ul>{children}diff --git a/docs/src/components/overview-blocks.tsx b/docs/src/components/overview-blocks.tsxindex 3e712d30f..9f870503f 100644--- a/docs/src/components/overview-blocks.tsx+++ b/docs/src/components/overview-blocks.tsx@@ -98,7 +98,7 @@ const PATHS: Path[] = [{href: '/docs/integrations/claude-code',title: 'Setting up an editor?',- desc: 'Use with Claude, Cursor, Codex, or OpenCode.',+ desc: 'Use with Claude, Cursor, Codex, OpenCode, or OpenClaw.',},{href: '/docs/workflows/karpathy-llm-wiki',diff --git a/docs/src/components/verify-exec.tsx b/docs/src/components/verify-exec.tsxindex 5feee9d2b..9cd4ec414 100644--- a/docs/src/components/verify-exec.tsx+++ b/docs/src/components/verify-exec.tsx@@ -1,9 +1,9 @@import { CopyPrompt } from '@/components/copy-prompt';/**- * Shared "Verify" body for the MCP-based integration docs (Claude Code, Codex,- * Cursor). Single-sources the verification prompt and the success expectation so- * the wording stays consistent across pages. The prompt is capped at five docs+ * Shared "Verify" body for the MCP-based integration docs. Single-sources the+ * verification prompt and the success expectation so the wording stays+ * consistent across pages. The prompt is capped at five docs* to keep the agent's verification response cheap. The expectation is generic —* OpenKnowledge's `exec` tool decides which command to run, so no specific* command is named. Per-editor restart/troubleshooting guidance stays in eachdiff --git a/packages/app/src/components/BottomComposer.tsx b/packages/app/src/components/BottomComposer.tsxindex be92b90e2..06f4e99ff 100644--- a/packages/app/src/components/BottomComposer.tsx+++ b/packages/app/src/components/BottomComposer.tsx@@ -1,22 +1,28 @@/**- * Persistent "Ask AI" composer docked as a slim single-line field directly- * above the editor footer (and above the docked terminal when it is open).+ * "Ask AI" composer docked as a slim single-line field above the editor+ * footer. Mounted in two modes (`bottom-composer-gate.ts` holds both+ * predicates): for the open doc via `shouldShowBottomComposer` — desktop app+ * and browser alike, hidden while the docked terminal owns the bottom of the+ * column and inside embedded AI webviews — and by the folder overview via+ * `shouldShowFolderComposer` (same gates, no doc-open requirement). In doc+ * mode it renders as an absolute overlay and the editor content is inset by+ * `--ask-composer-height`; in folder mode it is an in-flow field below the+ * folder list.*- * It is always present while a doc is open — a short, single-line input at rest- * that auto-grows as the instruction spans multiple lines, wrapped in a rounded- * card that owns the focus ring. It carries a segmented "Ask <agent>" send- * control (the shared `AgentSplitButton`: primary submit + joined agent-picker- * chevron), a rotating-suggestion placeholder that cross-fades between prompts- * while empty, and the ⌘L focus shortcut. Because it is an in-flow flex child of- * the editor column (not a floating overlay), the terminal dock pushes it up as- * it expands instead of overlapping it.+ * A short, single-line input at rest that auto-grows as the instruction spans+ * multiple lines, wrapped in a rounded card that owns the focus ring. It+ * carries a segmented "Ask <agent>" send control (the shared+ * `AgentSplitButton`: primary submit + joined agent-picker chevron), a+ * rotating-suggestion placeholder that cross-fades between prompts while+ * empty, and the ⌘L focus shortcut.** Submitting dispatches the typed instruction to the resolved default agent- * (first installed, or the user's sticky pick) scoped to the current doc, via- * the shared handoff plumbing (`useHandoffDispatch` -> ask-scope input ->- * `composeAskPrompt`). Picking a Terminal CLI (Claude / Codex / Cursor) hands- * the composed prompt to the docked terminal instead of a deep-link dispatch —- * injecting into a matching idle session if one is open, else a new tab.+ * (first installed, or the user's sticky pick) scoped to the current doc or+ * folder, via the shared handoff plumbing (`useHandoffDispatch` -> ask-scope+ * input -> `composeAskPrompt`). Picking a Terminal CLI (Claude / Codex /+ * OpenCode / Cursor) hands the composed prompt to the docked terminal instead+ * of a deep-link dispatch — always in a new terminal tab (reusing a live+ * shell is exclusively the selection-bubble path).*/import {diff --git a/packages/app/src/components/EditorArea.tsx b/packages/app/src/components/EditorArea.tsxindex 96cf01386..81dff4488 100644--- a/packages/app/src/components/EditorArea.tsx+++ b/packages/app/src/components/EditorArea.tsx@@ -903,10 +903,12 @@ function EditorAreaInner({requestAddProperty(activeDocName);}- // The "Ask AI" composer — a slim in-flow field docked below the editor- // (above the footer, and above the terminal when it is open). It takes real- // layout space, so the terminal dock pushes it up as it expands and it never- // overlaps content; no scroll-inset reservation is needed.+ // Visibility for the open doc's "Ask AI" composer — the pure gate in+ // bottom-composer-gate.ts (hidden while the docked terminal is open, in+ // embedded webviews, and with no doc open). The folder overview mounts its+ // own instance under shouldShowFolderComposer. Positioning and the+ // --ask-composer-height scroll inset are documented at the render site+ // below.const showBottomComposer = shouldShowBottomComposer({terminalVisible,isEmbedded,diff --git a/packages/app/src/components/TemplateForm.tsx b/packages/app/src/components/TemplateForm.tsxindex 951fc05d9..b3594e8a5 100644--- a/packages/app/src/components/TemplateForm.tsx+++ b/packages/app/src/components/TemplateForm.tsx@@ -213,7 +213,7 @@ export interface TemplateFormState {/*** State + submit logic for the template create/edit form. The user fills one- * `Name` field; the filename `slug` is derived from it until the user takes+ * `Title` field; the filename `slug` is derived from it until the user takes* manual control via the `Edit` affordance, after which the two decouple.** Rendering is `TemplateFormFields` — split out so the create and edit dialogs@@ -362,7 +362,7 @@ export function useTemplateForm({}/**- * Renders the template form's fields: the `Name` field (with the derived,+ * Renders the template form's fields: the `Title` field (with the derived,* overridable filename beneath it), `Description`, and the body.*/export function TemplateFormFields({@@ -428,7 +428,7 @@ export function TemplateFormFields({id={descriptionId}value={form.description}onChange={(e) => form.setDescription(e.target.value)}- placeholder={t`A short line shown under the name in the template list.`}+ placeholder={t`A short line shown under the title in the template list.`}disabled={form.isSaving}rows={2}/>@@ -539,7 +539,7 @@ function TemplateDefaultProperties({ form }: { form: TemplateFormState }) {}/**- * The filename line beneath the `Name` field (create mode). Collapsed, it+ * The filename line beneath the `Title` field (create mode). Collapsed, it* shows the derived `<slug>.md` with an `Edit` affordance; expanded — or when* the derived slug is unusable — it shows the editable filename input.*/@@ -606,7 +606,7 @@ function DerivedFilename({ form }: { form: TemplateFormState }) {</FieldDescription>) : (<FieldDescription>- <Trans>The file on disk, and the id agents use. It can't be changed later.</Trans>+ <Trans>The file on disk, and the id agents use.</Trans></FieldDescription>)}</Field>diff --git a/packages/app/src/components/TimelinePanel.tsx b/packages/app/src/components/TimelinePanel.tsxindex f9c7f4231..fabaf9a8b 100644--- a/packages/app/src/components/TimelinePanel.tsx+++ b/packages/app/src/components/TimelinePanel.tsx@@ -6,10 +6,12 @@* timeline surfaces only actor/system commits — WIP writes from agents,* principals, the file watcher, the service, plus upstream syncs — as a flat* reverse-chronological list. Checkpoint rows are filtered out: checkpoints- * are now produced solely by background cleanup jobs (shadow-branch GC,- * auto-consolidation, silent rescue) and are not user-facing history. The- * WIP commits those checkpoints fold over remain visible (the server walks- * their ancestry), so dropping the checkpoint rows loses no edit history.+ * — from background cleanup jobs (shadow-branch GC, auto-consolidation,+ * silent rescue) and from agents via the MCP `checkpoint` tool — are restore+ * points, not user-facing edit history (agents reach them through `history` /+ * `restore_version`). The WIP commits those checkpoints fold over remain+ * visible (the server walks their ancestry), so dropping the checkpoint rows+ * loses no edit history.** Per-row UX (shape parity with AgentActivityPanel's burst rows):* - Click anywhere on a row except the Restore icon → toggle inline expand.diff --git a/packages/app/src/locales/en/messages.json b/packages/app/src/locales/en/messages.jsonindex 653912b15..fc32ca9f4 100644--- a/packages/app/src/locales/en/messages.json+++ b/packages/app/src/locales/en/messages.json@@ -140,6 +140,7 @@"38foVZ": ["Loading diff"],"3BnyYc": ["This doc isn't on GitHub yet. The link won't work until it's pushed."],"3DTatP": ["Copy a prompt for your agent, start a blank file, or scaffold from a template."],+ "3FMvls": ["A short line shown under the title in the template list."],"3Fcb0I": ["Open graph"],"3HNlwb": ["Hello, world!"],"3Ib6FN": ["Move down"],@@ -1058,7 +1059,6 @@"QOINDn": ["empty"],"QQghPu": ["Install in Claude Desktop"],"QR5SP1": ["created template"],- "QWks14": ["A short line shown under the name in the template list."],"QYfQdv": [["displayName"], " CLI"],"QcpeeE": ["Navigate to ", ["docName"]],"QfFBdJ": ["The template's filename (without `.md`)."],@@ -1136,7 +1136,6 @@"\" could not be cleared in time. Reload to retry."],"ScwcF2": ["A project already exists at this location. Pick a different parent folder."],- "Sfh6zL": ["The file on disk, and the id agents use. It can't be changed later."],"SgKLfA": ["Not connected to GitHub."],"Sh3Qkg": ["No matching branches."],"SiUUCS": ["Next match"],@@ -1158,6 +1157,7 @@"TbjyhA": ["Docs"],"ThmUrC": ["Could not finalize project setup. Try again."],"Tjc1pH": ["Section <0>(optional heading anchor)</0>"],+ "TsZmgr": ["The file on disk, and the id agents use."],"TwYboS": ["Navigate CodeMirror source search results or dismiss the search panel."],"Tz0i8g": ["Settings"],"Tz9pJB": ["Clone stream ended unexpectedly — check if the clone completed"],diff --git a/packages/app/src/locales/en/messages.po b/packages/app/src/locales/en/messages.poindex c36ca60b7..07ec484be 100644--- a/packages/app/src/locales/en/messages.po+++ b/packages/app/src/locales/en/messages.po@@ -532,8 +532,8 @@ msgid "A reusable starting point for new documents in this folder."msgstr "A reusable starting point for new documents in this folder."#: src/components/TemplateForm.tsx-msgid "A short line shown under the name in the template list."-msgstr "A short line shown under the name in the template list."+msgid "A short line shown under the title in the template list."+msgstr "A short line shown under the title in the template list."#: src/components/SeedDialog.tsxmsgid "A simple place to write, with one file per topic and a daily journal. Pick this if you just want to start writing and let the links between notes build up over time."@@ -6733,8 +6733,8 @@ msgid "The file is in your Trash; the file-watcher will reconcile."msgstr "The file is in your Trash; the file-watcher will reconcile."#: src/components/TemplateForm.tsx-msgid "The file on disk, and the id agents use. It can't be changed later."-msgstr "The file on disk, and the id agents use. It can't be changed later."+msgid "The file on disk, and the id agents use."+msgstr "The file on disk, and the id agents use."#: src/components/NewSkillDialog.tsx#: src/components/SkillProperties.tsxdiff --git a/packages/app/src/locales/pseudo/messages.json b/packages/app/src/locales/pseudo/messages.jsonindex 9619fa878..7b3f05c2d 100644--- a/packages/app/src/locales/pseudo/messages.json+++ b/packages/app/src/locales/pseudo/messages.json@@ -140,6 +140,7 @@"38foVZ": ["Ĺōàďĩńĝ ďĩƒƒ"],"3BnyYc": ["Ţĥĩś ďōć ĩśń'ţ ōń ĜĩţĤũƀ ŷēţ. Ţĥē ĺĩńķ ŵōń'ţ ŵōŕķ ũńţĩĺ ĩţ'ś ƥũśĥēď."],"3DTatP": ["Ćōƥŷ à ƥŕōḿƥţ ƒōŕ ŷōũŕ àĝēńţ, śţàŕţ à ƀĺàńķ ƒĩĺē, ōŕ śćàƒƒōĺď ƒŕōḿ à ţēḿƥĺàţē."],+ "3FMvls": ["À śĥōŕţ ĺĩńē śĥōŵń ũńďēŕ ţĥē ţĩţĺē ĩń ţĥē ţēḿƥĺàţē ĺĩśţ."],"3Fcb0I": ["Ōƥēń ĝŕàƥĥ"],"3HNlwb": ["Ĥēĺĺō, ŵōŕĺď!"],"3Ib6FN": ["Ḿōvē ďōŵń"],@@ -1058,7 +1059,6 @@"QOINDn": ["ēḿƥţŷ"],"QQghPu": ["Ĩńśţàĺĺ ĩń Ćĺàũďē Ďēśķţōƥ"],"QR5SP1": ["ćŕēàţēď ţēḿƥĺàţē"],- "QWks14": ["À śĥōŕţ ĺĩńē śĥōŵń ũńďēŕ ţĥē ńàḿē ĩń ţĥē ţēḿƥĺàţē ĺĩśţ."],"QYfQdv": [["displayName"], " ĆĹĨ"],"QcpeeE": ["Ńàvĩĝàţē ţō ", ["docName"]],"QfFBdJ": ["Ţĥē ţēḿƥĺàţē'ś ƒĩĺēńàḿē (ŵĩţĥōũţ `.ḿď`)."],@@ -1136,7 +1136,6 @@"\" ćōũĺď ńōţ ƀē ćĺēàŕēď ĩń ţĩḿē. Ŕēĺōàď ţō ŕēţŕŷ."],"ScwcF2": ["À ƥŕōĴēćţ àĺŕēàďŷ ēxĩśţś àţ ţĥĩś ĺōćàţĩōń. Ƥĩćķ à ďĩƒƒēŕēńţ ƥàŕēńţ ƒōĺďēŕ."],- "Sfh6zL": ["Ţĥē ƒĩĺē ōń ďĩśķ, àńď ţĥē ĩď àĝēńţś ũśē. Ĩţ ćàń'ţ ƀē ćĥàńĝēď ĺàţēŕ."],"SgKLfA": ["Ńōţ ćōńńēćţēď ţō ĜĩţĤũƀ."],"Sh3Qkg": ["Ńō ḿàţćĥĩńĝ ƀŕàńćĥēś."],"SiUUCS": ["Ńēxţ ḿàţćĥ"],@@ -1158,6 +1157,7 @@"TbjyhA": ["Ďōćś"],"ThmUrC": ["Ćōũĺď ńōţ ƒĩńàĺĩźē ƥŕōĴēćţ śēţũƥ. Ţŕŷ àĝàĩń."],"Tjc1pH": ["Śēćţĩōń <0>(ōƥţĩōńàĺ ĥēàďĩńĝ àńćĥōŕ)</0>"],+ "TsZmgr": ["Ţĥē ƒĩĺē ōń ďĩśķ, àńď ţĥē ĩď àĝēńţś ũśē."],"TwYboS": ["Ńàvĩĝàţē ĆōďēḾĩŕŕōŕ śōũŕćē śēàŕćĥ ŕēśũĺţś ōŕ ďĩśḿĩśś ţĥē śēàŕćĥ ƥàńēĺ."],"Tz0i8g": ["Śēţţĩńĝś"],"Tz9pJB": ["Ćĺōńē śţŕēàḿ ēńďēď ũńēxƥēćţēďĺŷ — ćĥēćķ ĩƒ ţĥē ćĺōńē ćōḿƥĺēţēď"],diff --git a/packages/app/src/locales/pseudo/messages.po b/packages/app/src/locales/pseudo/messages.poindex efc3410b3..300a5aed8 100644--- a/packages/app/src/locales/pseudo/messages.po+++ b/packages/app/src/locales/pseudo/messages.po@@ -527,7 +527,7 @@ msgid "A reusable starting point for new documents in this folder."msgstr ""#: src/components/TemplateForm.tsx-msgid "A short line shown under the name in the template list."+msgid "A short line shown under the title in the template list."msgstr ""#: src/components/SeedDialog.tsx@@ -6728,7 +6728,7 @@ msgid "The file is in your Trash; the file-watcher will reconcile."msgstr ""#: src/components/TemplateForm.tsx-msgid "The file on disk, and the id agents use. It can't be changed later."+msgid "The file on disk, and the id agents use."msgstr ""#: src/components/NewSkillDialog.tsxdiff --git a/packages/cli/src/commands/seed.ts b/packages/cli/src/commands/seed.tsindex 4cbf2c18d..8a48f70aa 100644--- a/packages/cli/src/commands/seed.ts+++ b/packages/cli/src/commands/seed.ts@@ -28,8 +28,7 @@ interface SeedCommandOptions {cwd?: string;/*** Subfolder (relative to `cwd`) where the chosen starter pack is- * scaffolded. `.` / `''` scaffolds at the project root (historical behavior).- * When omitted and stdin is a TTY, the user is prompted interactively.+ * scaffolded. `.` / `''` — or omitting it — scaffolds at the project root.*/root?: string;/**@@ -250,7 +249,7 @@ export function seedCommand(): Command {).option('-r, --root <path>',- 'Subfolder (relative to the project dir) to scaffold into — created if missing. Defaults to the project root when omitted in non-interactive runs; prompts on a TTY.',+ 'Subfolder (relative to the project dir) to scaffold into — created if missing. Defaults to the project root.',).option('--list-packs', 'List available starter packs and exit.').option('-y, --yes', 'Skip confirmation prompt')diff --git a/packages/core/src/bridge/bind-frontmatter-doc.ts b/packages/core/src/bridge/bind-frontmatter-doc.tsindex c014b1413..8f9d95287 100644--- a/packages/core/src/bridge/bind-frontmatter-doc.ts+++ b/packages/core/src/bridge/bind-frontmatter-doc.ts@@ -1,3 +1,4 @@+import type * as Y from 'yjs';import type { Err, Ok, Result } from '../config/result.ts';import { type FrontmatterValidationError, toFrontmatterIssue } from '../frontmatter/errors.ts';diff --git a/packages/core/src/bridge/bridge-invariant.ts b/packages/core/src/bridge/bridge-invariant.tsindex 005627195..8bfdb40cd 100644--- a/packages/core/src/bridge/bridge-invariant.ts+++ b/packages/core/src/bridge/bridge-invariant.ts@@ -1,3 +1,4 @@+import { fnv1aDigest } from './hash-util.ts';export type BridgeInvariantSite = 'observer-b' | 'persistence' | 'test-harness';diff --git a/packages/core/src/bridge/doc-boundary-space.ts b/packages/core/src/bridge/doc-boundary-space.tsindex 8890f6739..c18c086d5 100644--- a/packages/core/src/bridge/doc-boundary-space.ts+++ b/packages/core/src/bridge/doc-boundary-space.ts@@ -1,3 +1,4 @@+import { FRONTMATTER_RE, stripFrontmatter } from '../extensions/frontmatter.ts';const LEADING_BOUNDARY_RE = /^(?:\r?\n)+/;diff --git a/packages/core/src/bridge/merge-three-way.ts b/packages/core/src/bridge/merge-three-way.tsindex b0a80fbd9..864bc7245 100644--- a/packages/core/src/bridge/merge-three-way.ts+++ b/packages/core/src/bridge/merge-three-way.ts@@ -37,6 +37,7 @@ function mergeThreeWayImpl(baseline: string, userText: string, agentText: stringreturn parts.join('\n');}+export type BridgeMergeContentLossSide = 'user' | 'agent';export type BridgeMergeContentLossWhich = 'substring' | 'order';diff --git a/packages/core/src/bridge/normalize.ts b/packages/core/src/bridge/normalize.tsindex e67f33b40..592f0b956 100644--- a/packages/core/src/bridge/normalize.ts+++ b/packages/core/src/bridge/normalize.ts@@ -1,3 +1,4 @@+const COMMONMARK_ESCAPE_RE = /\\([!"#$%&'()*+,\-./:;<=>?@[\]^_`{|}~])/g;const TABLE_ALIGN_ROW_RE = /^\s*\|?\s*:?-+:?\s*(\|\s*:?-+:?\s*)+\|?\s*$/;diff --git a/packages/core/src/markdown/callout-transformer.ts b/packages/core/src/markdown/callout-transformer.tsindex 83d47404a..a363dfd54 100644--- a/packages/core/src/markdown/callout-transformer.ts+++ b/packages/core/src/markdown/callout-transformer.ts@@ -1,3 +1,4 @@+import type { Blockquote, Paragraph, Root } from 'mdast';import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';import { visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/comment-promoter.ts b/packages/core/src/markdown/comment-promoter.tsindex 193e286b0..47f0d07e4 100644--- a/packages/core/src/markdown/comment-promoter.ts+++ b/packages/core/src/markdown/comment-promoter.ts@@ -1,3 +1,4 @@+import type { Nodes, Paragraph, PhrasingContent, Root, RootContent, Text } from 'mdast';import { SKIP, visit } from 'unist-util-visit';import type { VFile } from 'vfile';diff --git a/packages/core/src/markdown/dedent-block-jsx-close.ts b/packages/core/src/markdown/dedent-block-jsx-close.tsindex ece5c02a1..b6299a948 100644--- a/packages/core/src/markdown/dedent-block-jsx-close.ts+++ b/packages/core/src/markdown/dedent-block-jsx-close.ts@@ -1,3 +1,4 @@+import { findFencedRegions, isInsideFence } from './fence-regions.ts';const INDENTED_BLOCK_JSX_CLOSE_RE = /^([ ]{1,3})(<\/[A-Z][A-Za-z0-9_]*\s*>)([ \t]*)$/gm;diff --git a/packages/core/src/markdown/details-accordion-promoter.ts b/packages/core/src/markdown/details-accordion-promoter.tsindex 54774764a..acd398aa6 100644--- a/packages/core/src/markdown/details-accordion-promoter.ts+++ b/packages/core/src/markdown/details-accordion-promoter.ts@@ -1,3 +1,4 @@+import type { Nodes, Paragraph, Parent, Root, Text } from 'mdast';import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';import { visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/fence-regions.ts b/packages/core/src/markdown/fence-regions.tsindex c7518d614..fb5ac8e8a 100644--- a/packages/core/src/markdown/fence-regions.ts+++ b/packages/core/src/markdown/fence-regions.ts@@ -1,3 +1,4 @@+const FENCE_RE = /^(`{3,}|~{3,})/gm;export function findFencedRegions(src: string): Array<[number, number]> {diff --git a/packages/core/src/markdown/fixtures/index.ts b/packages/core/src/markdown/fixtures/index.tsindex 00f5771ee..6931623c7 100644--- a/packages/core/src/markdown/fixtures/index.ts+++ b/packages/core/src/markdown/fixtures/index.ts@@ -1,3 +1,4 @@+import { readFileSync } from 'node:fs';import { dirname, resolve } from 'node:path';import { fileURLToPath } from 'node:url';@@ -8,6 +9,7 @@ function fixturePath(...segments: string[]): string {return resolve(FIXTURES_DIR, ...segments);}+interface GfmExample {section: string;markdown: string;@@ -17,6 +19,7 @@ export function loadGfmExamples(): GfmExample[] {return JSON.parse(readFileSync(fixturePath('gfm', 'examples.json'), 'utf8')) as GfmExample[];}+interface MdxCrashEntry {id: string;input: string;@@ -68,6 +71,7 @@ export function loadLargeEmbedFixtures(): LargeEmbedFixture[] {) as LargeEmbedFixture[];}+export function loadPrd6955Before(): string {return readFileSync(fixturePath('regression', 'prd-6955-before.md'), 'utf8');}@@ -76,6 +80,7 @@ export function loadPrd6955CorruptedTriplicated(): string {return readFileSync(fixturePath('regression', 'prd-6955-corrupted-triplicated.md'), 'utf8');}+export interface NgPinnedCase {id: string;name: string;@@ -92,6 +97,7 @@ export function loadNgPinnedCases(): NgPinnedCase[] {) as NgPinnedCase[];}+export function loadLargeRealistic(): string {return readFileSync(fixturePath('perf', 'large-realistic.md'), 'utf8');}diff --git a/packages/core/src/markdown/fixtures/perf/generate.ts b/packages/core/src/markdown/fixtures/perf/generate.tsindex 8b1eb8519..daa3ef82b 100644--- a/packages/core/src/markdown/fixtures/perf/generate.ts+++ b/packages/core/src/markdown/fixtures/perf/generate.ts@@ -1,3 +1,4 @@+import { writeFileSync } from 'node:fs';import { dirname, resolve } from 'node:path';import { fileURLToPath } from 'node:url';@@ -10,6 +11,7 @@ const BASELINE_ONLY_COUNTS = [500, 2500] as const;const SEED = 0xf1de1117;+function mulberry32(seed: number): () => number {let a = seed >>> 0;return () => {@@ -36,6 +38,7 @@ function pickWeighted<T>(rand: () => number, items: readonly [T, number][]): T {return items[items.length - 1][0];}+const WORDS = ['lorem','ipsum',@@ -153,6 +156,7 @@ function mdxBlock(rand: () => number): string {return `<${name}>\n\n${sentence(rand)}\n\n</${name}>`;}+type BlockKind = 'paragraph' | 'heading' | 'list' | 'code' | 'table' | 'mdx';const MIX: readonly [BlockKind, number][] = [@@ -191,6 +195,7 @@ function generateDocument(blockCount: number, seed: number): string {return `${blocks.join('\n\n')}\n`;}+function main(): void {for (const count of [...BLOCK_COUNTS, ...BASELINE_ONLY_COUNTS]) {const doc = generateDocument(count, SEED);diff --git a/packages/core/src/markdown/guard-flanking-matrix.ts b/packages/core/src/markdown/guard-flanking-matrix.tsindex 420dc0fe5..32c055c5b 100644--- a/packages/core/src/markdown/guard-flanking-matrix.ts+++ b/packages/core/src/markdown/guard-flanking-matrix.ts@@ -7,6 +7,7 @@ import {import { BACKSLASH_GUARD_SUBSTITUTIONS, encodeBackslashEscapes } from './backslash-escape-guard.ts';import { ENTITY_REF_GUARD_SUBSTITUTIONS, encodeEntityRefs } from './entity-ref-guard.ts';+export const ATTENTION_DELIMITERS = ['*', '_', '**', '~~', '=='] as const;export type FlankClass = 'whitespace' | 'punctuation' | 'other';diff --git a/packages/core/src/markdown/handler-shadow-audit.ts b/packages/core/src/markdown/handler-shadow-audit.tsindex 2653473da..283913255 100644--- a/packages/core/src/markdown/handler-shadow-audit.ts+++ b/packages/core/src/markdown/handler-shadow-audit.ts@@ -1,3 +1,4 @@+export interface HandlerShadowWitness {input: string;expect: 'byte' | 'byte-and-reparse-type';diff --git a/packages/core/src/markdown/highlight-promoter.ts b/packages/core/src/markdown/highlight-promoter.tsindex f758cf737..7a22e8016 100644--- a/packages/core/src/markdown/highlight-promoter.ts+++ b/packages/core/src/markdown/highlight-promoter.ts@@ -1,3 +1,4 @@+import type { Nodes, Parent, PhrasingContent, Root, Text } from 'mdast';import type { MdxJsxTextElement } from 'mdast-util-mdx';import { SKIP, visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/html-to-mdast.ts b/packages/core/src/markdown/html-to-mdast.tsindex 78fdfeb02..2f082e6d0 100644--- a/packages/core/src/markdown/html-to-mdast.ts+++ b/packages/core/src/markdown/html-to-mdast.ts@@ -1,3 +1,4 @@+import type { Root as HastRoot } from 'hast';import type { Root as MdastRoot } from 'mdast';import rehypeParse from 'rehype-parse';@@ -75,7 +76,8 @@ export function htmlToMdast(html: string, options?: HtmlToMdastOptions): MdastRothrow new HtmlPayloadTooLargeError(html.length, maxBytes);}- const processor = unified().use(rehypeParse, { fragment: true });+ const processor = unified()+ .use(rehypeParse, { fragment: true });for (const plugin of cleanupPlugins) {processor.use(plugin);diff --git a/packages/core/src/markdown/image-promoter.ts b/packages/core/src/markdown/image-promoter.tsindex 706fa9afb..994eb6917 100644--- a/packages/core/src/markdown/image-promoter.ts+++ b/packages/core/src/markdown/image-promoter.ts@@ -1,3 +1,4 @@+import type { Image, Paragraph, Root } from 'mdast';import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';import { visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/index.ts b/packages/core/src/markdown/index.tsindex 58a810193..064fa0773 100644--- a/packages/core/src/markdown/index.ts+++ b/packages/core/src/markdown/index.ts@@ -1,3 +1,4 @@+import {type FromProseMirrorOptions,fromPmMark,@@ -164,6 +165,7 @@ export class MarkdownManager {}}+const registry = createRegistry();function destructureAttrs(@@ -212,6 +214,7 @@ function destructureAttrs(return result;}+function hasDirtyDescendant(node: PmNode): boolean {let found = false;node.descendants((child) => {@@ -230,6 +233,7 @@ function effectiveDirty(node: PmNode): boolean {return node.attrs.sourceDirty || hasDirtyDescendant(node);}+function isEmptyMdastParagraph(node: MdastNodes): boolean {if (node.type !== 'paragraph') return false;const children = node.children ?? [];@@ -298,6 +302,7 @@ function extractTextFromMdastNodes(nodes: MdastNodes[]): string {return out;}+import {AUDIO_EXTENSIONS,FILE_ATTACHMENT_EXTENSIONS,@@ -547,6 +552,7 @@ function buildMdastToPmHandlers(}));}+if (m.emphasis) {handlers.emphasis = toPmMark(m.emphasis, (node: Emphasis) => ({sourceDelimiter: node.data?.sourceDelimiter ?? '*',@@ -626,6 +632,7 @@ function buildMdastToPmHandlers(}));}+if (m.link) {const sourceLiteralMark = m.sourceLiteral;handlers.link = (node: Link, _parent: MdastParent, state: MdastToPmState) => {@@ -904,6 +911,7 @@ function buildMdastToPmHandlers(};}+const blockUnknownHandler = (node: {type: string;position?: { start: { offset: number }; end: { offset: number } };@@ -1029,6 +1037,7 @@ function buildMdastToPmHandlers(return handlers as RemarkProseMirrorOptions['handlers'];}+function buildPmToMdastHandlers(schema: Schema): {nodeHandlers: FromProseMirrorOptions<string, string>['nodeHandlers'];markHandlers: FromProseMirrorOptions<string, string>['markHandlers'];diff --git a/packages/core/src/markdown/math-promoter.ts b/packages/core/src/markdown/math-promoter.tsindex a5b511f25..bd79424c7 100644--- a/packages/core/src/markdown/math-promoter.ts+++ b/packages/core/src/markdown/math-promoter.ts@@ -1,3 +1,4 @@+import type { Code, Root } from 'mdast';import type { Math as MdastMath } from 'mdast-util-math';import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';diff --git a/packages/core/src/markdown/mdast-to-hast-handlers.ts b/packages/core/src/markdown/mdast-to-hast-handlers.tsindex 679c72ef7..f84967798 100644--- a/packages/core/src/markdown/mdast-to-hast-handlers.ts+++ b/packages/core/src/markdown/mdast-to-hast-handlers.ts@@ -1,3 +1,4 @@+import type { Comment, Element, ElementContent, Properties } from 'hast';import type { FootnoteDefinition, FootnoteReference } from 'mdast';import type { MdxJsxFlowElement, MdxJsxTextElement } from 'mdast-util-mdx';diff --git a/packages/core/src/markdown/mdast-to-html.ts b/packages/core/src/markdown/mdast-to-html.tsindex 79072375c..153fdc1d8 100644--- a/packages/core/src/markdown/mdast-to-html.ts+++ b/packages/core/src/markdown/mdast-to-html.ts@@ -1,3 +1,4 @@+import type { Element, Root as HastRoot } from 'hast';import type { Root as MdastRoot } from 'mdast';import { normalizeUri } from 'micromark-util-sanitize-uri';diff --git a/packages/core/src/markdown/merged-walker.ts b/packages/core/src/markdown/merged-walker.tsindex 35d74b85e..a58f8c720 100644--- a/packages/core/src/markdown/merged-walker.ts+++ b/packages/core/src/markdown/merged-walker.ts@@ -1,3 +1,4 @@+import type { Nodes, Parent, Root } from 'mdast';import { SKIP, visit } from 'unist-util-visit';import type { VFile } from 'vfile';diff --git a/packages/core/src/markdown/mermaid-promoter.ts b/packages/core/src/markdown/mermaid-promoter.tsindex 1a897fca8..17ed2b829 100644--- a/packages/core/src/markdown/mermaid-promoter.ts+++ b/packages/core/src/markdown/mermaid-promoter.ts@@ -1,3 +1,4 @@+import type { Code, Root } from 'mdast';import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';import { visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/parse-with-fallback.ts b/packages/core/src/markdown/parse-with-fallback.tsindex 9864b3b60..7e4a9a48b 100644--- a/packages/core/src/markdown/parse-with-fallback.ts+++ b/packages/core/src/markdown/parse-with-fallback.ts@@ -168,6 +168,7 @@ export function parseRecursive(}}+interface VFilePlace {offset?: number;start?: { offset?: number };@@ -186,6 +187,7 @@ function extractErrorOffset(err: unknown): number | undefined {return undefined;}+interface Region {start: number;end: number;@@ -209,6 +211,7 @@ function nearestBlankLineAfter(src: string, offset: number): number | null {return null;}+export interface TagEvent {kind: 'open' | 'close' | 'self-close';name: string;@@ -355,6 +358,7 @@ function findFallbackRegion(src: string, errorOffset: number): Region {return { start: blockStart, end: blockEnd };}+interface SourceBlock {src: string;start: number;@@ -452,6 +456,7 @@ function tryPerBlockFallback(};}+function wholeDocRawText(source: string): JSONContent {return {type: 'doc',diff --git a/packages/core/src/markdown/parser-drop-closure.ts b/packages/core/src/markdown/parser-drop-closure.tsindex e6ab4fd57..43d420187 100644--- a/packages/core/src/markdown/parser-drop-closure.ts+++ b/packages/core/src/markdown/parser-drop-closure.ts@@ -1,3 +1,4 @@+export type DroppedTokenAdjudication =| {kind: 'format-dof-axis';diff --git a/packages/core/src/markdown/pipeline.ts b/packages/core/src/markdown/pipeline.tsindex 5d6db7aa8..5b9550e90 100644--- a/packages/core/src/markdown/pipeline.ts+++ b/packages/core/src/markdown/pipeline.ts@@ -1,3 +1,4 @@+import {type FromProseMirrorOptions,fromProseMirror,diff --git a/packages/core/src/markdown/position-aware-join.ts b/packages/core/src/markdown/position-aware-join.tsindex 248685cfe..4ac5731e7 100644--- a/packages/core/src/markdown/position-aware-join.ts+++ b/packages/core/src/markdown/position-aware-join.ts@@ -1,3 +1,4 @@+import type { Join } from 'mdast-util-to-markdown';import type { Position } from 'unist';diff --git a/packages/core/src/markdown/position-slice.ts b/packages/core/src/markdown/position-slice.tsindex 50a193a16..240be90e6 100644--- a/packages/core/src/markdown/position-slice.ts+++ b/packages/core/src/markdown/position-slice.ts@@ -1,3 +1,4 @@+import type { Nodes, Root } from 'mdast';import { visit } from 'unist-util-visit';import type { VFile } from 'vfile';@@ -466,7 +467,8 @@ export function applyPositionSliceToNode(const first = source[startOff];if (first !== '[' && first !== '<' && !node.title) {node.data.sourceStyle = 'gfm-autolink';- } else if (first === '[') {+ }+ else if (first === '[') {const slice = source.slice(startOff, endOff);const closeBracketIdx = slice.lastIndexOf('](');if (closeBracketIdx !== -1) {diff --git a/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts b/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.tsindex db10fa54b..ca225ce9b 100644--- a/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts+++ b/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts@@ -1,3 +1,4 @@+import type { Comment, Element, Root, Text } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts b/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.tsindex 34068d103..3a2524a9a 100644--- a/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts@@ -1,3 +1,4 @@+import type { Element, ElementContent, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts b/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.tsindex 93151d43b..2279a0189 100644--- a/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts@@ -1,3 +1,4 @@+import type { Element, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts b/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.tsindex 188f02d83..a0f467c42 100644--- a/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts@@ -1,3 +1,4 @@+import type { Element, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts b/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.tsindex 4ba2c3418..4e8542a21 100644--- a/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts@@ -1,3 +1,4 @@+import type { Element, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts b/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.tsindex 1a74b1272..a3c96b24a 100644--- a/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts@@ -1,3 +1,4 @@+import type { Element, ElementContent, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts b/packages/core/src/markdown/rehype-plugins/strip-mso-styles.tsindex de35e7b79..e95cf43d6 100644--- a/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts@@ -1,3 +1,4 @@+import type { Comment, Element, ElementContent, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts b/packages/core/src/markdown/rehype-plugins/strip-slack-classes.tsindex b4be1b2ea..ffdb4d5b5 100644--- a/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts@@ -1,3 +1,4 @@+import type { Element, ElementContent, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts b/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.tsindex 3c8d88b7c..e2a96d1a7 100644--- a/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts@@ -1,3 +1,4 @@+import type { Element, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/resolve-image-url.ts b/packages/core/src/markdown/resolve-image-url.tsindex cf2c9da8e..0389575ac 100644--- a/packages/core/src/markdown/resolve-image-url.ts+++ b/packages/core/src/markdown/resolve-image-url.ts@@ -1,3 +1,4 @@+import { isRelativeUrl } from './safe-url.ts';function isDevDiagnosticContext(): boolean {diff --git a/packages/core/src/markdown/safe-url.ts b/packages/core/src/markdown/safe-url.tsindex 4d3250d3a..8be632ba4 100644--- a/packages/core/src/markdown/safe-url.ts+++ b/packages/core/src/markdown/safe-url.ts@@ -1,3 +1,4 @@+export const SAFE_URL_SCHEMES = ['https', 'http', 'mailto', 'tel', 'ftp', 'sms'] as const;const SCHEME_ALT = SAFE_URL_SCHEMES.map((s) => `${s}:`).join('|');diff --git a/packages/core/src/markdown/serialize-helpers.ts b/packages/core/src/markdown/serialize-helpers.tsindex 46cc6a074..542204403 100644--- a/packages/core/src/markdown/serialize-helpers.ts+++ b/packages/core/src/markdown/serialize-helpers.ts@@ -1,3 +1,4 @@+import type { Node as PmNode } from '@tiptap/pm/model';import type { MdxJsxAttribute, MdxJsxExpressionAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';import type { PropDef, SerializeContext } from '../registry/types.ts';diff --git a/packages/core/src/markdown/single-dollar-math-promoter.ts b/packages/core/src/markdown/single-dollar-math-promoter.tsindex be97d4d62..fe73659e6 100644--- a/packages/core/src/markdown/single-dollar-math-promoter.ts+++ b/packages/core/src/markdown/single-dollar-math-promoter.ts@@ -1,3 +1,4 @@+import type { PhrasingContent, Root, Text } from 'mdast';import type { InlineMath } from 'mdast-util-math';import { SKIP, visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/to-markdown-handlers.ts b/packages/core/src/markdown/to-markdown-handlers.tsindex 1a2fb5d50..e1161455b 100644--- a/packages/core/src/markdown/to-markdown-handlers.ts+++ b/packages/core/src/markdown/to-markdown-handlers.ts@@ -1,3 +1,4 @@+import type { Nodes, Parents } from 'mdast';import type { MdxJsxAttribute, MdxJsxExpressionAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';import type { Handle, Info, State } from 'mdast-util-to-markdown';diff --git a/packages/core/src/markdown/unknown-mdast-guard.ts b/packages/core/src/markdown/unknown-mdast-guard.tsindex cd245c38c..c5bfd2386 100644--- a/packages/core/src/markdown/unknown-mdast-guard.ts+++ b/packages/core/src/markdown/unknown-mdast-guard.ts@@ -1,3 +1,4 @@+import type { Root as MdastRoot } from 'mdast';import type { VFile } from 'vfile';diff --git a/packages/core/src/markdown/whitespace-char-ref.ts b/packages/core/src/markdown/whitespace-char-ref.tsindex a100cad76..1b75ba564 100644--- a/packages/core/src/markdown/whitespace-char-ref.ts+++ b/packages/core/src/markdown/whitespace-char-ref.ts@@ -1,3 +1,4 @@+const INLINE_WHITESPACE_BY_CODE: ReadonlyMap<number, string> = new Map([[0x20, ' '],[0x09, '\t'],diff --git a/packages/core/src/markdown/wiki-link-micromark.ts b/packages/core/src/markdown/wiki-link-micromark.tsindex 6dad26200..afd9936fe 100644--- a/packages/core/src/markdown/wiki-link-micromark.ts+++ b/packages/core/src/markdown/wiki-link-micromark.ts@@ -17,6 +17,7 @@ declare module 'micromark-util-types' {}}+const CODE_BANG = 33; // !const CODE_LBRACKET = 91; // [const CODE_RBRACKET = 93; // ]@@ -260,6 +261,7 @@ export function wikiLinkSyntax(): Extension {};}+function enterWikiLink(this: CompileContext, token: Token) {this.enter({@@ -385,6 +387,7 @@ export const wikiLinkToMarkdown: {unsafe: [{ character: '[', inConstruct: ['phrasing'] }],};+const MICROMARK_EXT = wikiLinkSyntax();export function remarkWikiLink(this: Processor) {diff --git a/packages/core/src/skill-targets/schema.ts b/packages/core/src/skill-targets/schema.tsindex ed79de07b..3cb732670 100644--- a/packages/core/src/skill-targets/schema.ts+++ b/packages/core/src/skill-targets/schema.ts@@ -14,7 +14,8 @@* absent, OK falls back to the editors the project is already configured for.** Only editors with a project skill surface are valid targets- * (`claude` / `cursor` / `codex`; Claude Desktop reads user-global skills).+ * (`claude` / `cursor` / `codex` / `opencode`; Claude Desktop and OpenClaw+ * read user-global skills only).*/import { z } from 'zod';@@ -34,10 +35,11 @@ export const SKILL_TARGETS_SCHEMA_VERSION = 1;* Editor ids valid as install-projection targets. Runtime values come from the* single source `PROJECT_SKILL_EDITOR_IDS` (derived from `EDITOR_PROJECT_SKILL_ROOT`)* so the two can't drift. z.enum needs a literal tuple, which the derived array's- * `.filter` widens to `EditorId`, so the cast restates the narrow literal shape:- * `Exclude<EditorId, 'claude-desktop'>` is exactly the set of editors WITH a- * project skill surface (`claude` / `cursor` / `codex`). schema.test.ts asserts- * the cast stays value-equal to the derived list as a backstop.+ * `.filter` widens to `EditorId`, so the cast restates a narrower literal shape:+ * `Exclude<EditorId, 'claude-desktop'>` still admits `openclaw` (also without a+ * project skill surface), so the type over-approximates the runtime set+ * (`claude` / `cursor` / `codex` / `opencode`); schema.test.ts asserts the cast+ * stays value-equal to the derived list as a backstop.*/type ProjectSkillEditorId = Exclude<EditorId, 'claude-desktop'>;export const SkillTargetEditorSchema = z.enum(diff --git a/packages/server/assets/skills/packs/entity-vault/SKILL.md b/packages/server/assets/skills/packs/entity-vault/SKILL.mdindex ad0db0cea..7bd2aff9e 100644--- a/packages/server/assets/skills/packs/entity-vault/SKILL.md+++ b/packages/server/assets/skills/packs/entity-vault/SKILL.md@@ -1,16 +1,16 @@---name: open-knowledge-pack-entity-vaultversion: "0.18.0"-description: "How to work in an Entity vault project (the `entity-vault` starter pack, GBrain-compatible): a typed-entity vault of people, companies, meetings, and concepts, each a dossier with a rewritable summary plus an append-only timeline. Read when the project has these folders. Carries the dossier convention and entity-extraction behaviors so that guidance does not live inside template bodies or folder descriptions. Complements the platform `open-knowledge` skill; does not replace it."+description: "How to work in a Personal CRM project (the `entity-vault` starter pack, GBrain-compatible): a typed-entity vault of people, companies, meetings, and concepts, each a dossier with a rewritable summary plus an append-only timeline. Read when the project has these folders. Carries the dossier convention and entity-extraction behaviors so that guidance does not live inside template bodies or folder descriptions. Complements the platform `open-knowledge` skill; does not replace it."compatibility: "Claude Code, Claude Desktop, Claude Cowork, Claude.ai web. Requires OpenKnowledge MCP server. Installed project-local by `ok seed --pack entity-vault`."metadata:pack: "entity-vault"author: "Inkeep"repository: "https://github.com/inkeep/open-knowledge"----# Entity vault pack (GBrain-compatible) — how to work here+# Personal CRM (GBrain-compatible) — how to work here-A typed-entity vault inspired by Garry Tan's gbrain. Each entity is a dossier; the agent keeps dossiers current by extracting entities from meeting notes and original thinking. This skill holds those behaviors so templates and folder descriptions stay clean. The Markdown shape is **GBrain-compatible**: if the external `gbrain` CLI is installed, it can import/sync the same vault.+A Personal CRM built as a typed-entity vault, inspired by Garry Tan's gbrain. Each entity is a dossier; the agent keeps dossiers current by extracting entities from meeting notes and original thinking. This skill holds those behaviors so templates and folder descriptions stay clean. The Markdown shape is **GBrain-compatible**: if the external `gbrain` CLI is installed, it can import/sync the same vault.> Pack guidance. The platform `open-knowledge` skill still governs every markdown operation.diff --git a/packages/server/assets/skills/packs/okf/SKILL.md b/packages/server/assets/skills/packs/okf/SKILL.mdindex e0ab0f42f..144334134 100644--- a/packages/server/assets/skills/packs/okf/SKILL.md+++ b/packages/server/assets/skills/packs/okf/SKILL.md@@ -33,7 +33,7 @@ OKF requires exactly one thing of every **non-reserved** document: a **non-empty- **`references/`** — external sources and citations you rely on (`type: reference`).- **`notes/`** — working notes and observations (`type: note`).-Link liberally with **standard markdown links** (`[text](./path.md)`) — the value is the graph that emerges from the links between typed docs, and standard links keep that graph portable to any OKF consumer. (OpenKnowledge also accepts `[[wiki-link]]` shorthand as a native superset, and the OKF export normalizes it to standard links — but seeded content uses standard links so the bundle is conformant as-is.)+Link liberally with **standard markdown links** (`[text](./path.md)`) — the value is the graph that emerges from the links between typed docs, and standard links keep that graph portable to any OKF consumer. (OpenKnowledge also accepts `[[wiki-link]]` shorthand as a native superset and preserves it byte-for-byte — but seeded content uses standard links so the bundle is conformant as-is.)## Reserved files (keep them frontmatter-free)diff --git a/packages/server/src/seed/okf-conformance.test.ts b/packages/server/src/seed/okf-conformance.test.tsindex 5431d5018..983cdda46 100644--- a/packages/server/src/seed/okf-conformance.test.ts+++ b/packages/server/src/seed/okf-conformance.test.ts@@ -161,9 +161,9 @@ describe('okf pack — OKF §9 conformance by construction', () => {true,);// §6 navigation is a link-list in STANDARD markdown — a conformant OKF- // bundle's links are plain markdown, not OK's `[[…]]` superset (which the- // OKF export normalizes away). Pin every seeded nav link's format so the- // graph stays portable to a strict consumer.+ // bundle's links are plain markdown, not OK's `[[…]]` superset. Pin every+ // seeded nav link's format so the graph stays portable to a strict+ // consumer.for (const link of ['[welcome](./welcome.md)','[concepts/](./concepts/)',diff --git a/packages/server/src/seed/starter.ts b/packages/server/src/seed/starter.tsindex cf105ff0e..1936337a4 100644--- a/packages/server/src/seed/starter.ts+++ b/packages/server/src/seed/starter.ts@@ -8,7 +8,7 @@* - `plain-notes` — Just notes/ + daily/ — escape hatch for casual users* - `worldbuilding` — Fiction encyclopedia (characters / settings / themes / factions / lore)* - `writing-pipeline` — ideas → drafts → published, lean three-stage- * - `entity-vault` — Entity vault (people / companies / meetings / concepts / originals / media)+ * - `entity-vault` — Personal CRM (people / companies / meetings / concepts / originals / media)* - `okf` — Open Knowledge Format conformant-by-construction mini-KB** `codebase-wiki` is the only pack whose folder paths nest (`wiki/architecture`,@@ -1120,7 +1120,7 @@ tags: [published]`,};-// ─── Pack 7: Entity vault (GBrain-compatible Markdown) ────────────────────+// ─── Pack 7: Personal CRM (`entity-vault`, GBrain-compatible Markdown) ────//// Inspired by Garry Tan's gbrain (https://github.com/garrytan/gbrain): a// typed-entity vault with `people/`, `companies/`, `meetings/`, `concepts/`,@@ -1460,9 +1460,9 @@ description: "When the agent does scheduled work: daily briefings, end-of-day do// every other pack.//// Seeded content uses STANDARD markdown links (`[text](./path.md)`), not OK's-// `[[…]]` shorthand: a conformant OKF bundle's link graph is plain markdown-// (OKF's export normalizes `[[doc]]` → `[text](./target.md)`), so authoring-// standard links keeps the seeded bundle portable to a strict OKF consumer.+// `[[…]]` shorthand: a conformant OKF bundle's link graph is plain markdown,+// so authoring standard links keeps the seeded bundle portable to a strict+// OKF consumer.//// Reserved files are frontmatter-free convention exemplars, valid at seed time;// the tool does not keep them live (the pack skill tells the author to maintain