Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

docs(open-knowledge): surface the cross-platform web-app install path (#1790)

mike-inkeep6975454aebad
diff --git a/README.md b/README.md
index 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-ce
The 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 Model
This 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.mdx
index 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.mdx
index 13a7c3d8e..ee1cdb7c0 100644
--- a/docs/content/get-started/quickstart.mdx
+++ b/docs/content/get-started/quickstart.mdx
@@ -2,9 +2,12 @@
title: Quickstart
description: 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.mdx
index 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.mdx
index 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, folder
Cursor 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.
## Verify
diff --git a/docs/content/reference/cli.mdx b/docs/content/reference/cli.mdx
index 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).
```bash
cd 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 you
diff --git a/docs/src/app/global.css b/docs/src/app/global.css
index 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.tsx
index 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>
</>
);
}