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

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`.

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 />
 

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)

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.

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
 

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

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 {

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>
     </>
   );
 }