Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

update quickstart docs (#1705)

Andrew Mikofalvy5df9de5890ae
diff --git a/docs/content/get-started/quickstart.mdx b/docs/content/get-started/quickstart.mdx
index c4575fbee..eb4a129c4 100644
--- a/docs/content/get-started/quickstart.mdx
+++ b/docs/content/get-started/quickstart.mdx
@@ -1,6 +1,6 @@
---
title: Quickstart
-description: Get your Agent maintained knowledge base up and running in less than five minutes.
+description: Setup your agent maintained knowledge base in less than five minutes.
---
<Callout type="info" title="Prerequisites">
@@ -14,27 +14,55 @@ description: Get your Agent maintained knowledge base up and running in less tha
### Install the desktop app
-Download Open Knowledge for macOS. Open the DMG, drag **Open Knowledge** to **Applications**, and launch it.
+Click the below button to download the latest version of the Open Knowledge desktop app for macOS.
<DownloadButton href="https://github.com/inkeep/open-knowledge-legacy/releases/latest/download/Open-Knowledge-arm64.dmg" label="Download for macOS" />
-_Apple Silicon (M1 and later) only for now; Intel Macs are not yet supported._
-
</Step>
<Step>
-### Pick a project
+### Open or create an Open Knowledge project
+
+Choose how you want to start, then follow that path through the rest of this guide. You can switch anytime; your choice carries over to the prompts below.
+
+<Tabs groupId="ok-start-route" persist className="ok-route-tabs" items={['Tech IPOs KB Example', 'Your own repo', 'New project']}>
+
+<Tab>
+
+**Recommended: the fastest way to explore, with no setup and no files of your own.** Our example knowledge base is a collection of notes on notable tech IPOs happening this year.
+
+<CtaButton href="https://openknowledge.ai/d/AWh0dHBzOi8vZ2l0aHViLmNvbS9pbmtlZXAvdGVjaC1pcG9zL2Jsb2IvbWFpbi9SRUFETUUubWQ" label="Open inkeep/tech-ipos-kb-example" />
+
+- Click **Open inkeep/tech-ipos-kb-example** button above.
+- Follow the prompts to open the example repo in the Open Knowledge app.
+
+</Tab>
+
+<Tab>
+
+Point Open Knowledge at a code repository you already work in to organize your technical specs; they live in git, right next to the code they describe.
+
+- Open the Open Knowledge app and click **Pick Existing Project**.
+- Choose your repo (or a `docs/` or `specs/` folder inside it).
+- Working off GitHub? **Clone from GitHub** pulls it down first.
-**Want to explore without any setup?** Open our example knowledge base — a collection of notes on notable tech IPOs — and poke around:
+</Tab>
-<CtaButton href="https://openknowledge.ai/d/AWh0dHBzOi8vZ2l0aHViLmNvbS9pbmtlZXAvdGVjaC1pcG9zL2Jsb2IvbWFpbi9SRUFETUUubWQ" label="Open the example knowledge base" />
+<Tab>
-Follow the prompts to open the example repo in the Open Knowledge app.
+Starting from scratch? Build a brand-new, empty knowledge base.
-Otherwise, open the Open Knowledge app and click **Pick Existing Project** to choose your own project, **Create New Project** to scaffold a fresh one, or **Clone from GitHub** to pull down a remote repo.
+- Open the Open Knowledge app.
+- Click **Create New Project** to scaffold a fresh, empty knowledge base.
-The first-launch consent dialog detects every MCP-capable editor on your machine (Claude Code, Cursor, Codex, Claude Desktop) and offers to wire them up to Open Knowledge.
+</Tab>
+
+</Tabs>
+
+<Callout type="info">
+ Whichever route you pick, the first-launch consent dialog detects every MCP-capable editor on your machine (Claude Code, Cursor, Codex, Claude Desktop) and offers to wire them up to Open Knowledge.
+</Callout>
</Step>
@@ -42,9 +70,19 @@ The first-launch consent dialog detects every MCP-capable editor on your machine
### Open the project in your AI tool
-Click the **Open with AI** button and select your preferred tool. This dispatches the current file, folder, or project to your chosen agent with a starter prompt.
+With Open Knowledge app open, click the **Open with AI** button and select your preferred agent from the list. This dispatches the current file, folder, or project to your chosen agent with a starter prompt.
+
+![The Open with AI button in the Open Knowledge app, showing the agent picker with Claude and Cursor](/screenshots/open-with-ai.png)
+
+<Callout type="info">
+ If your tool prompts you to approve a new MCP server (Cursor does this), approve `open-knowledge`.
+</Callout>
+
+</Step>
+
+<Step>
-If your tool prompts you to approve a new MCP server (Cursor does this), approve `open-knowledge`.
+Opening a project initializes the Open Knowledge MCP tools for that project. From then on, your agent prefers Open Knowledge's tool wrappers over its built-in file operations, so its edits keep your front matter consistent and your links intact.
</Step>
@@ -52,19 +90,49 @@ If your tool prompts you to approve a new MCP server (Cursor does this), approve
### Ask the agent to edit a doc
-Opening a project initializes the Open Knowledge MCP tools for that project. From then on, your agent prefers Open Knowledge's tool wrappers over its built-in file operations, so its edits keep your front matter consistent and your links intact.
+Add your own instructions to steer the agent. These starters match the path you picked above (switch tabs to change it). Click any prompt to copy it.
+
+<Tabs groupId="ok-start-route" persist className="ok-route-tabs" items={['Tech IPOs KB Example', 'Your own repo', 'New project']}>
+
+<Tab>
+
+Explore the example knowledge base of notable tech IPOs:
+
+<CopyPrompt>Create a report on which IPO topics are trending on Hacker News this month.</CopyPrompt>
+
+<CopyPrompt>Update the SpaceX note with the latest news about its IPO.</CopyPrompt>
+
+<CopyPrompt>What references are there to under or overvaluation?</CopyPrompt>
+
+<CopyPrompt>Update the historical IPO prices to account for inflation.</CopyPrompt>
+
+</Tab>
+
+<Tab>
-If you opened the example knowledge base, try one of these:
+Turn your codebase into living technical specs the agent can read and maintain:
-> Update the SpaceX note with the latest news about its IPO.
+<CopyPrompt>Read through this codebase and draft a technical spec for the most complex module: an overview, the architecture, key files, and open questions, all linked from a specs index page.</CopyPrompt>
-> Search for any docs that mention valuation.
+<CopyPrompt>Organize my existing specs into a linked index grouped by area, and flag any that have drifted out of sync with the current code.</CopyPrompt>
-> List the recent docs.
+<CopyPrompt>Document the architecture of this repo: create an overview page that links to a page per major module describing its responsibilities and entry points.</CopyPrompt>
-Or something that spans the whole knowledge base:
+</Tab>
-> Update the historical IPO prices across these notes to account for inflation.
+<Tab>
+
+Hand the agent a topic for your empty project. Try a fan wiki about something you love:
+
+<CopyPrompt>Build a fan wiki about Avatar: The Last Airbender. Start with an overview page, then add cross-linked pages for the main characters, the four nations, notable episodes, and a timeline of major events.</CopyPrompt>
+
+<CopyPrompt>Build an in-depth knowledge base about the evolution of prequel vs sequel memes over the span of several decades. Start with an overview page, then add cross-linked pages for each era, the defining meme formats, the films and franchises that spawned them, and a timeline tracing how the rivalry evolved.</CopyPrompt>
+
+<CopyPrompt>Build a knowledge wiki about the different types of flightless birds. Start with an overview page, then add cross-linked pages for each major group (ratites like ostriches, emus, and kiwis; penguins; and flightless rails), the regions they live in, and a timeline of how flightlessness evolved.</CopyPrompt>
+
+</Tab>
+
+</Tabs>
</Step>
@@ -77,7 +145,7 @@ 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
- A timeline of recent edits with per-burst diffs and selective rollback
-- Backlinks to other docs that reference it
+- Backlinks to other docs that reference it and a graph view to see doc connectivity
Right-click anywhere in the sidebar (empty space, a folder, or a file) to create, reveal, rename, hide, delete (to Trash), and **Open with AI**. The full feature tour is under [Features](/docs/features/editor).
@@ -85,16 +153,6 @@ Right-click anywhere in the sidebar (empty space, a folder, or a file) to create
</Steps>
-## Configure it (optional)
-
-Open Knowledge works out of the box; configuration is optional. When you do want to change something, settings live in three files, and the most specific one wins:
-
-- **Project** — `.ok/config.yml`, shared with your team via git
-- **User** — `~/.ok/global.yml`, personal to you across every project on your machine
-- **This machine** — `.ok/local/config.yml`, per-machine and not shared (gitignored)
-
-Change settings in the editor's **Settings** pane (Cmd/Ctrl-,), or edit `.ok/config.yml` directly (it ships with a `$schema` comment for autocomplete and inline descriptions). Full reference: [Configuration](/docs/reference/configuration).
-
## What's next
- Per-editor setup details: [Integrations](/docs/integrations/claude-code)
diff --git a/docs/content/integrations/claude-code.mdx b/docs/content/integrations/claude-code.mdx
index 91879b49a..1776220a8 100644
--- a/docs/content/integrations/claude-code.mdx
+++ b/docs/content/integrations/claude-code.mdx
@@ -3,7 +3,7 @@ title: Claude Code
description: Use Open Knowledge with Claude Code.
---
-Open Knowledge plugs into Claude Code through MCP plus an installed skill that teaches the agent how to use the tools.
+Open Knowledge works with Claude Code Agent via MCP and Skills.
## Install
@@ -17,16 +17,9 @@ Open the project in Claude Code and ask:
> List all the docs in this project.
-Claude Code should call `exec` (e.g. `ls`) and respond with your knowledge base. If it doesn't see the tool, restart Claude Code so it picks up the new MCP entry.
+Claude Code should call `exec` (e.g. `ls`) and respond with your knowledge base. If Claude Code doesn't use the Open Knowledge `exec` tool, restart Claude Code so it picks up the new MCP entry.
## Live editing
-When Claude Code writes to a doc, the desktop editor focuses on that doc and the change streams in live.
+When Claude Code writes to a doc, You will be able to see that change in the Open Knowledge app. Just ask Claude to open it for you.
-## Open with AI
-
-From the editor, **Open with AI ▸ Claude** dispatches the current file, folder, or project to Claude Code in one click. Three entry points: the editor header's sparkle icon, the sidebar's right-click menu (any file, folder, or empty space), and the macOS **File → Open with AI** menu.
-
-Claude Code receives a short prompt asking it to open the target in Open Knowledge's web preview. The agent then grounds the rest of the conversation through the MCP tools, with no file attachment and no content over the wire. See [Editor → Open with AI](/docs/features/editor#open-with-ai) for the full UX.
-
-Install detection hides the Claude row from the submenu when the desktop app isn't on the machine the OK server is running on. On remote-hosted setups (where the browser and server are on different machines) every agent renders and your browser's OS protocol-dispatch dialog decides what fires.
diff --git a/docs/public/screenshots/open-with-ai.png b/docs/public/screenshots/open-with-ai.png
new file mode 100644
index 000000000..7e94f4b52
Binary files /dev/null and b/docs/public/screenshots/open-with-ai.png differ
diff --git a/docs/src/app/global.css b/docs/src/app/global.css
index 95e73a45c..f2bd27b5b 100644
--- a/docs/src/app/global.css
+++ b/docs/src/app/global.css
@@ -122,6 +122,50 @@
padding: 0.12em 0.4em;
}
+/* ------------------------------------------------------------------
+ * .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-route-tabs {
+ --ok-route-accent: #3784ff;
+}
+.dark .ok-route-tabs {
+ --ok-route-accent: #69a3ff;
+}
+.ok-route-tabs [role="tablist"] {
+ gap: 0.375rem;
+ padding: 0.375rem;
+}
+.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;
+ 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 {
+ 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);
+ 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);
+}
+
.slide-btn-accent {
background-color: var(--slide-accent);
color: #fff;
diff --git a/docs/src/components/copy-prompt.tsx b/docs/src/components/copy-prompt.tsx
new file mode 100644
index 000000000..881896adc
--- /dev/null
+++ b/docs/src/components/copy-prompt.tsx
@@ -0,0 +1,44 @@
+'use client';
+
+import { Check, Copy } from 'lucide-react';
+import { useState } from 'react';
+
+type CopyPromptProps = {
+ children: string;
+};
+
+export function CopyPrompt({ children }: CopyPromptProps) {
+ const [copied, setCopied] = useState(false);
+ const text = children.trim();
+
+ const copy = async () => {
+ try {
+ await navigator.clipboard.writeText(text);
+ setCopied(true);
+ window.setTimeout(() => setCopied(false), 2000);
+ } catch {}
+ };
+
+ return (
+ <button
+ type="button"
+ onClick={copy}
+ aria-label="Copy prompt to clipboard"
+ data-copied={copied}
+ className="ok-overview not-prose group my-2.5 flex w-full cursor-pointer items-start gap-3 rounded-lg border border-fd-border bg-fd-card px-4 py-3 text-start text-[0.9375rem] leading-relaxed text-fd-foreground shadow-sm transition hover:border-[var(--ok-accent)] hover:bg-fd-accent/40"
+ >
+ <span className="flex-1 whitespace-pre-wrap">{text}</span>
+ <span
+ className="mt-px inline-flex shrink-0 items-center gap-1.5 text-[12.5px] font-medium text-fd-muted-foreground transition-colors group-hover:text-[var(--ok-accent)]"
+ style={copied ? { color: 'var(--ok-accent)' } : undefined}
+ >
+ {copied ? (
+ <Check className="size-3.5" aria-hidden="true" />
+ ) : (
+ <Copy className="size-3.5" aria-hidden="true" />
+ )}
+ <span aria-live="polite">{copied ? 'Copied' : 'Copy'}</span>
+ </span>
+ </button>
+ );
+}
diff --git a/docs/src/mdx-components.tsx b/docs/src/mdx-components.tsx
index 20e15474b..3803cf5c5 100644
--- a/docs/src/mdx-components.tsx
+++ b/docs/src/mdx-components.tsx
@@ -7,6 +7,7 @@ import { TypeTable } from 'fumadocs-ui/components/type-table';
import defaultMdxComponents from 'fumadocs-ui/mdx';
import type { MDXComponents } from 'mdx/types';
import { AgentIcons } from '@/components/agent-icons';
+import { CopyPrompt } from '@/components/copy-prompt';
import { CtaButton } from '@/components/cta-button';
import { DownloadButton } from '@/components/download-button';
import { Mermaid } from '@/components/mermaid';
@@ -20,6 +21,7 @@ export function getMDXComponents(): MDXComponents {
AgentIcons,
Card,
Cards,
+ CopyPrompt,
CtaButton,
DownloadButton,
Image: ImageZoom,