Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
docs(open-knowledge): surface the cross-platform web-app install path (#1790)
mike-inkeep6975454aebad
diff --git a/README.md b/README.mdindex fa8fc1cfb..3a4d51e8c 100644--- a/README.md+++ b/README.md@@ -4,6 +4,23 @@ Open Knowledge is a local-first knowledge base for teams that want docs, help-ceThe project includes a desktop app, web app, server, CLI, shared core packages, and docs site. It uses Bun workspaces and Turbo for builds.+## Install++**macOS:** download the desktop app — open the DMG, drag **Open Knowledge** to **Applications**, and launch it. [Latest release](https://github.com/inkeep/open-knowledge/releases/latest).++**Linux or an Intel Mac:** run the same editor as a local web app via the CLI (Windows isn't supported yet) ([Node.js 24+](https://nodejs.org) required):++```bash+npm install -g @inkeep/open-knowledge+cd your-project+ok init # scaffold the project + wire up Claude Code, Cursor, and Codex+ok start --open # serve the editor and open it in your browser+```++Full documentation: <https://openknowledge.ai/docs>.++The sections below are for **contributing to** Open Knowledge.+## Repository ModelThis public repository is mirrored from Inkeep's internal monorepo with Copybara. The internal source path is `public/open-knowledge/` in `inkeep/agents-private`.diff --git a/docs/content/get-started/overview.mdx b/docs/content/get-started/overview.mdxindex 709dbb363..5d129e6e1 100644--- a/docs/content/get-started/overview.mdx+++ b/docs/content/get-started/overview.mdx@@ -4,7 +4,7 @@ description: A markdown knowledge base your AI coding agents can read and edit,footer: false----Open Knowledge is a native macOS app for creating and maintaining a portable markdown knowledge base alongside the agents you already use. It works with any MCP-capable agent.+Open Knowledge is a native macOS app for creating and maintaining a portable markdown knowledge base alongside the agents you already use. On Linux or an Intel Mac, the same editor runs as a local [web app](/docs/reference/cli) you launch from the terminal. It works with any MCP-capable agent.<AgentIcons />diff --git a/docs/content/get-started/quickstart.mdx b/docs/content/get-started/quickstart.mdxindex 13a7c3d8e..ee1cdb7c0 100644--- a/docs/content/get-started/quickstart.mdx+++ b/docs/content/get-started/quickstart.mdx@@ -2,9 +2,12 @@title: Quickstartdescription: Set up your agent-maintained knowledge base in less than five minutes.---+<Tabs groupId="ok-install" persist className="ok-flush-tabs" items={['macOS app', 'Web app (Linux · Intel Mac)']}>++<Tab>+<Callout type="info" title="Prerequisites">- - **macOS.** Windows and Linux are not yet supported. If you are using Linux or an Intel-based Mac, you can use the [CLI](/docs/reference/cli) instead.- - **Node.js ≥24.** Open Knowledge requires Node.js 24 or higher. Download from [nodejs.org](https://nodejs.org/en/download/).+ - **macOS on Apple Silicon** (M1 or later).- **`git`.** Open Knowledge initializes a git repo for your project (used for the timeline and recovery features). Install from [git-scm.com](https://git-scm.com/install/mac).</Callout>@@ -91,6 +94,93 @@ Right-click anywhere in the sidebar (empty space, a folder, or a file) to create</Steps>+</Tab>++<Tab>++<Callout type="info" title="Prerequisites">+ - **Node.js 24+.** Open Knowledge requires Node.js 24 or higher. Download from [nodejs.org](https://nodejs.org/en/download/).+ - **`git`.** Open Knowledge initializes a git repo for your project (used for the timeline and recovery features). Install it from [git-scm.com](https://git-scm.com) or your package manager.+</Callout>++<Steps>++<Step>++### Install the CLI and open the editor++Install the CLI from npm, initialize a project, and start the editor in your browser:++```bash+# Install the CLI (puts `ok` on your PATH)+npm 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, and Codex.+mkdir my-knowledge-base && cd my-knowledge-base+ok init++# Serve the editor and open it in your browser.+ok start --open+```++</Step>++<Step>++### Open the knowledge base in your AI agent++`ok init` already registered Open Knowledge with the AI editors it detected, so your agent can use the Open Knowledge tools right away. Open your project in your agent — or, from the editor, click **Open with AI** and pick one.++In the agent's chat window, add the following to get started or use a topic of your choice:++<CopyPrompt>Create a knowledge base about Large Language Models. Include an overview page and separate pages for three key concepts.</CopyPrompt>++<Callout type="info">+ To avoid having to approve all Open Knowledge tool calls, set your agent to auto-mode, full-access, or an equivalent setting.+</Callout>++<Callout type="info">+ If your agent prompts you to approve a new MCP server (Cursor does this), approve `open-knowledge`.+</Callout>++</Step>++<Step>++### Watch your agent work++You will see your agent's icon in the top right of the editor window. Click on the icon to see the agent's [activity](/docs/features/agent-activity) across files in the knowledge base.++If the agent icon is greyed out, your agent may not have started writing yet. Wait a few seconds and check again.++</Step>++<Step>++### Explore the knowledge base++The editor's sidebar shows every doc in your knowledge base. Each doc has:++- A WYSIWYG body and a source-mode toggle+- A frontmatter panel for properties++When viewing a document, check out the right side pane for:+- An outline of the document's structure+- A list of incoming and outgoing links to other docs+- A graph view of the document's links in the knowledge base+- A [timeline](/docs/features/timeline-and-recovery) of recent edits with per-burst diffs and selective rollback++Right-click anywhere in the sidebar (empty space, a folder, or a file) to create, reveal, rename, hide, delete, and **Open with AI**. The full feature tour is under [Features](/docs/features/editor).++</Step>++</Steps>++</Tab>++</Tabs>+## What's next- Syncing your knowledge base to GitHub: [Syncing](/docs/features/github-sync)diff --git a/docs/content/integrations/claude-code.mdx b/docs/content/integrations/claude-code.mdxindex f38da97a8..bcaf8ed5c 100644--- a/docs/content/integrations/claude-code.mdx+++ b/docs/content/integrations/claude-code.mdx@@ -30,4 +30,4 @@ If Claude Code doesn't use the Open Knowledge `exec` tool, restart it so it pick## Live editing-When Claude Code writes to a doc, you'll see the change land live in the Open Knowledge app — just ask Claude to open it for you.+When Claude Code writes to a doc, you'll see the change land live in Open Knowledge. Just ask Claude Code to open it for you.diff --git a/docs/content/integrations/cursor.mdx b/docs/content/integrations/cursor.mdxindex 4fcf818de..09817cdbe 100644--- a/docs/content/integrations/cursor.mdx+++ b/docs/content/integrations/cursor.mdx@@ -19,7 +19,7 @@ From the editor, **Open with AI ▸ Cursor** dispatches the current file, folderCursor uses a two-step handoff: Open Knowledge spawns `cursor <projectDir>` to open the workspace first, then fires the `cursor://` URL with a short prompt asking Cursor to open the target in Open Knowledge'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.-Cursor's spawn step requires the local Electron app. The row is hidden in the web build, where there's no process-spawn API.+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.## Verifydiff --git a/docs/content/reference/cli.mdx b/docs/content/reference/cli.mdxindex ee938bf83..4d076ab81 100644--- a/docs/content/reference/cli.mdx+++ b/docs/content/reference/cli.mdx@@ -1,13 +1,12 @@----title: CLI-description: Set up a project and open the editor from your terminal with the ok command.+title: CLI & web app+description: Install the ok CLI and run the Open Knowledge web app in your browser — on Linux or an Intel Mac.----If you are on macOS you should use the Open Knowledge desktop app. Use the `ok` CLI if you are on Linux or have an Intel-based 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.<Callout type="info" title="Prerequisites">- - **macOS or Linux.** Windows is not supported.- - **Node.js ≥24.** Open Knowledge requires Node.js 24 or higher.- - **`git`.** Open Knowledge initializes a git repo for your project (used for the timeline and recovery features). Pre-installed via Xcode Command Line Tools on most macOS machines; install with `xcode-select --install` if missing.+ - **Node.js 24+.** Open Knowledge requires [Node.js](https://nodejs.org) 24 or higher.+ - **`git`.** Open Knowledge 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.</Callout>@@ -21,7 +20,7 @@ npm install -g @inkeep/open-knowledge## Set up a project-Run `ok init` in any folder to turn it into an Open Knowledge project. It scaffolds a `.ok/` directory and registers the Open Knowledge MCP server with the AI editors it detects on your machine (Claude, Cursor, Codex).+Run `ok init` in any folder to turn it into an Open Knowledge project. It scaffolds a `.ok/` directory and registers the Open Knowledge MCP server with the AI editors it detects on your machine (Claude Code, Cursor, Codex).```bashcd my-project@@ -59,7 +58,7 @@ 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 Open Knowledge server on your machine |-| `ok stop` | Stop the server for the current directory (or pass a port, a path, pid or `all` to nuke all servers). |+| `ok stop` | Stop the server for the current directory (or pass a port, a path, pid or `all` to stop all servers). || `ok clean` | Remove stale lock files left behind by a crash (never touches live servers) |## Commands that run for youdiff --git a/docs/src/app/global.css b/docs/src/app/global.cssindex d00e45b05..85dae155b 100644--- a/docs/src/app/global.css+++ b/docs/src/app/global.css@@ -201,47 +201,43 @@}/* ------------------------------------------------------------------- * .ok-route-tabs — render the Quickstart "pick a path" tabs as an- * obvious full-width segmented control (boxed pills) instead of- * Fumadocs' default underline tabs, so it clearly reads as a choice.- * Rules are unlayered (they win over Tailwind utility classes) and- * target ARIA roles, so Radix a11y + the shared-groupId sync are kept;- * this is purely visual.+ * .ok-flush-tabs — strip Fumadocs' tab "card" (outer border + secondary+ * bg, and the inner panel's bg + padding) so the tab content flows like+ * normal page content (no double left-rail against <Steps>). Keeps a+ * hairline under the trigger row so it still reads as tabs. Unlayered so+ * it wins over Tailwind utilities; targets ARIA roles so Radix a11y + the+ * shared-groupId sync are preserved. Purely visual.* ------------------------------------------------------------------ */-.ok-route-tabs {- --ok-route-accent: #3784ff;-}-.dark .ok-route-tabs {- --ok-route-accent: #69a3ff;+.ok-flush-tabs {+ border: 0;+ border-radius: 0;+ background: transparent;+ overflow: visible;}-.ok-route-tabs [role="tablist"] {- gap: 0.375rem;- padding: 0.375rem;+.ok-flush-tabs > [role="tablist"] {+ gap: 1.5rem;+ padding-inline: 0;+ border-bottom: 1px solid var(--color-fd-border);+ margin-bottom: 1.5rem;}-.ok-route-tabs [role="tab"] {- flex: 1 1 0;- justify-content: center;- border: 1px solid transparent;- border-radius: 0.5rem;- padding: 0.4rem 0.75rem;- font-weight: 500;+.ok-flush-tabs [role="tab"] {+ font-size: 1rem;+ line-height: 1.25;+ font-weight: 600;+ padding-block: 0.15rem 0.6rem;color: var(--color-fd-muted-foreground);- white-space: nowrap;- transition:- background-color 120ms ease,- color 120ms ease,- border-color 120ms ease;}-.ok-route-tabs [role="tab"]:hover {+.ok-flush-tabs [role="tab"]:hover {color: var(--color-fd-foreground);- background: color-mix(in oklch, var(--color-fd-card) 70%, transparent);}-.ok-route-tabs [role="tab"][data-state="active"] {- background: var(--color-fd-card);+.ok-flush-tabs [role="tab"][data-state="active"] {color: var(--color-fd-foreground);- border-color: var(--ok-route-accent);- font-weight: 600;- box-shadow: 0 1px 2px rgba(0, 0, 0, 0.06);+ font-weight: 700;+}+.ok-flush-tabs [role="tabpanel"] {+ padding: 0;+ background: transparent;+ border-radius: 0;}.slide-btn-accent {diff --git a/docs/src/components/mcp-install.tsx b/docs/src/components/mcp-install.tsxindex 2be9f5cc0..8b7cf2e49 100644--- a/docs/src/components/mcp-install.tsx+++ b/docs/src/components/mcp-install.tsx@@ -3,14 +3,21 @@ import type { ReactNode } from 'react';export function McpInstall({ editor, children }: { editor: string; children?: ReactNode }) {return (<>- <p>- The Open Knowledge desktop app handles this for you. The first time you open a project, a- consent dialog detects {editor} and configures it.- </p>+ <p>There are two ways to connect {editor}, depending on how you run Open Knowledge:</p>+ <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.+ </li>+ <li>+ <strong>Web app / terminal</strong> (Linux, Intel Mac — see the{' '}+ <a href="/docs/reference/cli">web app guide</a>). Run <code>ok init</code> in your+ project: it registers the Open Knowledge MCP server with {editor} and the other editors it+ detects. Every <code>ok start</code> refreshes the entry.+ </li>+ </ul>{children}- <p>- To re-trigger the dialog, delete <code>~/.ok/mcp-status.json</code> and relaunch.- </p></>);}