From 6975454aebad1c459701e33e090d2c33c12de2e0 Mon Sep 17 00:00:00 2001 From: mike-inkeep Date: Thu, 18 Jun 2026 16:22:27 -0400 Subject: [PATCH] docs(open-knowledge): surface the cross-platform web-app install path (#1790) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs(open-knowledge): surface the cross-platform web-app install path Make the web app (launched via the npm `ok` CLI) a first-class, discoverable install path for users on Linux, Intel Macs, and Windows, without diluting the macOS desktop app as the recommended path. - Quickstart: the install step now tabs `macOS app` (default) vs `Web app` (npm install -g + ok init + ok start --open); fix the self-contradictory prereqs callout and the macOS-only git hint. - Overview: reframe the "native macOS app" opening to acknowledge the web app. - McpInstall component: present BOTH wiring paths (desktop consent dialog AND `ok init`), fixing the Claude Code / Cursor / Codex integration pages at once. - Integrations: remove the stale "Open with AI hidden in the web build" claim (the web app has it via a `/api/spawn-cursor` + claude.ai fallback). - reference/cli reframed as the "CLI & web app" guide; Linux stated supported (advisory cli-e2e), Windows untested-but-expected per CLAUDE.md. - New packages/cli/README.md (the npm landing page) + an end-user Install section in the public overlay README. - Cross-link the web-app guide from overview, quickstart, and share. Docs-only; no published behavior change (no changeset). Spec + rationale: public/open-knowledge/specs/2026-06-10-cli-only-install-docs/ * docs(open-knowledge): address claude[bot] review — web path for the Tech IPOs example - Quickstart: the recommended "Tech IPOs" example tab fired a macOS-only deep link that dead-ended Linux/Windows/Intel users. Add an `ok clone https://github.com/inkeep/tech-ipos` + `ok start --open` terminal alternative inside that tab. - Quickstart: reword the Web-tab bridging line so it stops forward-referencing desktop-only terms ("Pick Project", "consent dialog") web users haven't seen. - cli.mdx: align "Node.js ≥24" → "Node.js 24+" (matches quickstart + both READMEs) and link nodejs.org. * docs(open-knowledge): consistency polish from claude[bot] re-review - Standardize on "web app" (two words) in mcp-install.tsx + the quickstart consent callout (was "web-app", mismatching the "CLI & web app" page title). - Align the platform triple to "Linux, Windows, or an Intel Mac" in cli.mdx + share.mdx (the Web-tab intro keeps Windows last so its "unverified" caveat reads naturally). - Complete the step-2 web-app pattern: add `ok init` / `ok start --open` notes to the "Your own repo" and "New project" tabs, parallel to the Tech IPOs tab. All three were non-blocking "Consider" items; the prior commit cleared the blocking findings. The mirror-runnable failure on 58e0daf was a bun-install --frozen-lockfile 600s timeout (known CI flake), not a content issue. * docs(open-knowledge): drop the unverified-Windows hedge from the CLI page prereqs * docs(open-knowledge): rebuild quickstart as a platform toggle (desktop / web app) Re-applies the cross-platform install path onto the rewritten upstream quickstart (#1935): a single `macOS app` / `Web app` tab selection at the top drives two self-contained walkthroughs, eliminating every inline "on the web app?" conditional. Per-tab prerequisites. The macOS walkthrough preserves the upstream desktop flow verbatim; the web walkthrough uses npm + `ok init` + `ok start --open`. The shared tail (open-in-agent / watch / explore) is duplicated per platform for an unbroken read. * docs(open-knowledge): align Node notation + "Claude Code" naming (review nits) - quickstart.mdx: macOS-tab prereq "Node.js ≥24" → "24+" to match the web tab and the rest of the PR (the ≥24 form was inherited from the upstream rewrite). - cli.mdx: "(Claude, Cursor, Codex)" → "(Claude Code, Cursor, Codex)". * docs(open-knowledge): drop the Node prereq from the macOS quickstart tab The desktop app bundles its own runtime, so Node.js isn't a user prerequisite for the macOS path. The web-app tab keeps it. * docs(open-knowledge): trim integration + CLI copy - claude-code.mdx: drop the "— the desktop app or the web app, whichever you're running" clause from the live-editing line. - cli.mdx: remove the platform line from the prereqs callout (the page intro already states the platforms); "nuke all servers" → "stop all servers". * docs(open-knowledge): flush quickstart tabs + fix share-page accuracy - Add `.ok-flush-tabs` (global.css) and apply it to the quickstart install ``: strips Fumadocs' tab card (outer border, secondary bg, inner panel bg + padding) so the tab content flows flush with the page and the rail is the only left line. Keeps a hairline under the trigger row. - share.mdx: drop the "(install the web app instead)" parenthetical — the share splash page only offers the desktop deep link + the macOS DMG, with no web-app affordance, so the note was misleading. * docs(open-knowledge): emphasize quickstart tabs (~H2) + space below the row Bump the install tab labels to ~1.5rem / semibold (active 700) so the platform choice reads as a primary decision, and add 1.5rem spacing below the tab row. * docs(open-knowledge): dial quickstart tab size 1.5rem -> 1rem * docs(open-knowledge): fix web-tab delete copy, drop dead CSS, naming nit - quickstart web tab: remove "(to Trash)" from the delete affordance — the web app deletes via POST /api/delete-path (permanent), not OS Trash. The macOS desktop tab keeps "(to Trash)" (Electron shell.trashItem). - global.css: remove the now-dead `.ok-route-tabs` block (no call sites after the quickstart rebuild). - claude-code.mdx: "ask Claude" -> "ask Claude Code". * docs(open-knowledge): Windows not yet supported (showstopper bugs found) Reverses the earlier "untested-but-likely" stance (spec D6). Drops Windows from every web-app platform list (overview, quickstart tab label, cli.mdx, McpInstall, both READMEs) — the web app is Linux + Intel Mac — and adds an explicit "Windows isn't supported yet" callout to the quickstart Web tab and the CLI & web app guide, plus a parenthetical on the npm/GitHub READMEs. * docs(open-knowledge): drop the "Windows isn't supported yet" callout Remove the warn callout from the CLI guide and the quickstart Web tab; Windows is still omitted from every platform list (and noted parenthetically on the READMEs). --------- GitOrigin-RevId: 1871202dd15ef30c1fb988431d1c723db9d59f45 --- README.md | 17 ++++ docs/content/get-started/overview.mdx | 2 +- docs/content/get-started/quickstart.mdx | 94 ++++++++++++++++++++++- docs/content/integrations/claude-code.mdx | 2 +- docs/content/integrations/cursor.mdx | 2 +- docs/content/reference/cli.mdx | 15 ++-- docs/src/app/global.css | 62 +++++++-------- docs/src/components/mcp-install.tsx | 21 +++-- 8 files changed, 162 insertions(+), 53 deletions(-) diff --git a/README.md b/README.md index fa8fc1cf..3a4d51e8 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: . + +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 709dbb36..5d129e6e 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. diff --git a/docs/content/get-started/quickstart.mdx b/docs/content/get-started/quickstart.mdx index 13a7c3d8..ee1cdb7c 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. --- + + + + - - **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). @@ -91,6 +94,93 @@ Right-click anywhere in the sidebar (empty space, a folder, or a file) to create + + + + + + - **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. + + + + + + +### 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 +``` + + + + + +### 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: + +Create a knowledge base about Large Language Models. Include an overview page and separate pages for three key concepts. + + + To avoid having to approve all Open Knowledge tool calls, set your agent to auto-mode, full-access, or an equivalent setting. + + + + If your agent prompts you to approve a new MCP server (Cursor does this), approve `open-knowledge`. + + + + + + +### 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. + + + + + +### 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). + + + + + + + + + ## 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 f38da97a..bcaf8ed5 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 4fcf818d..09817cdb 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 ` 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 ee938bf8..4d076ab8 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. - - **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. @@ -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 d00e45b0..85dae155 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 ). 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 2be9f5cc..8b7cf2e4 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 ( <> -

- The Open Knowledge desktop app handles this for you. The first time you open a project, a - consent dialog detects {editor} and configures it. -

+

There are two ways to connect {editor}, depending on how you run Open Knowledge:

+
    +
  • + macOS desktop app. The first time you open a project, a consent dialog + detects {editor} and configures it for you. To re-trigger the dialog, delete{' '} + ~/.ok/mcp-status.json and relaunch. +
    • +
  • + Web app / terminal (Linux, Intel Mac — see the{' '} + web app guide). Run ok init in your + project: it registers the Open Knowledge MCP server with {editor} and the other editors it + detects. Every ok start refreshes the entry. +
    • +
{children} -

- To re-trigger the dialog, delete ~/.ok/mcp-status.json and relaunch. -

); }