Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

docs(open-knowledge): cover post-v0.28 features from docs-impact audit (#2574)

Nick Gomez6ceebb5942ac
diff --git a/docs/content/features/assets-and-embeds.mdx b/docs/content/features/assets-and-embeds.mdx
index 28df38119..ced7d3cd6 100644
--- a/docs/content/features/assets-and-embeds.mdx
+++ b/docs/content/features/assets-and-embeds.mdx
@@ -32,7 +32,7 @@ Type `/embed` for starters: a blank **HTML** canvas plus **Chart**, **Stat cards
## Diagrams
-A ` ```mermaid ` fence renders as a diagram — flowchart, sequence, class, state, ER, gantt, or pie; the **Mermaid** entry in the `/` menu inserts one. Rendered diagrams carry buttons for zoom, pan, and reset; mouse-wheel zoom and drag panning are off, so a diagram holds still while you scroll the doc.
+A ` ```mermaid ` fence renders as a diagram — flowchart, sequence, class, state, ER, gantt, or pie; the **Mermaid** entry in the `/` menu inserts one. Rendered diagrams carry buttons for zoom, pan, and reset; mouse-wheel zoom and drag panning are off, so a diagram holds still while you scroll the doc. Standalone Mermaid files (`.mmd`, `.mermaid`) open the same way — rendered as a diagram in their own pane, with a toggle to read or edit the raw source directly.
## Sharing across apps
diff --git a/docs/content/features/editor.mdx b/docs/content/features/editor.mdx
index 5d77d5c7c..1a5b96917 100644
--- a/docs/content/features/editor.mdx
+++ b/docs/content/features/editor.mdx
@@ -69,7 +69,7 @@ Surfaces with their own specialized right-click menus — asset and wiki-link ch
An **Ask AI** composer is docked at the bottom of the editor — in the desktop app and in a regular browser — whenever a doc or folder view is open. It's a slim, single-line entry field that expands as you type to accept a fuller prompt (and `@`-mentions); in the desktop app, `Cmd+L` opens and focuses it. Type an instruction — "condense this doc", "research X", "make a spec from this user story" — and press Enter to hand it to an agent. `Shift+Enter` inserts a newline; the field clears once the prompt is sent.
-It's the primary in-editor way to hand work to an agent, and the freetext companion to the menu-driven [Open with AI](#open-with-ai) (whole file / folder / project). Submitting dispatches the typed prompt to your **default agent** — the first one installed, in Claude → Codex → OpenCode → Cursor order — scoped to the current doc (or, in a folder view, the folder), which the agent receives as an `@`-mention. The agent picker beside the field overrides the default per send — the installed desktop agent apps plus, in the desktop app, the Terminal CLIs (Claude, Codex, OpenCode, Cursor) — and your choice is remembered on that machine. Success and failure use the same handoff toast as Open with AI.
+It's the primary in-editor way to hand work to an agent, and the freetext companion to the menu-driven [Open with AI](#open-with-ai) (whole file / folder / project). Submitting dispatches the typed prompt to your **default agent** — the first one installed, in Claude → Codex → OpenCode → Cursor → Pi order — scoped to the current doc (or, in a folder view, the folder), which the agent receives as an `@`-mention. The agent picker beside the field overrides the default per send — the installed desktop agent apps plus, in the desktop app, the Terminal CLIs (Claude, Codex, OpenCode, Cursor, Pi) — and your choice is remembered on that machine. Success and failure use the same handoff toast as Open with AI.
The composer stays out of the way where it doesn't belong: it's hidden inside an AI editor's embedded view, while the [docked terminal](#terminal) is open (the terminal is its own AI entry point), and when no doc or folder is open (the empty state already offers project handoff). It's also dismissible — an **Ask AI** badge in the status bar brings it back.
@@ -77,12 +77,18 @@ The composer stays out of the way where it doesn't belong: it's hidden inside an
Select text in the WYSIWYG editor and the selection bubble menu shows an **Ask AI** button (Sparkles icon) alongside the formatting controls. Clicking it — or pressing `Cmd+Shift+I` (macOS only; that chord is the DevTools shortcut elsewhere) — opens and focuses the bottom Ask AI composer with the selected passage pinned as a removable context pill, so the exact text rides along as context. Type your instruction, pick an agent, and send. While the docked terminal is open, the button sends the selection into the active shell session instead. (Selecting an image or other non-text node doesn't show the affordance.)
+### From a code block
+
+Hovering a code block reveals a toolbar above it with its own **Ask AI** button (Sparkles icon). Clicking it sends the whole fenced block — info string and body — into the docked terminal's active shell session; with no terminal open, it opens and focuses the bottom Ask AI composer.
+
## Terminal
The desktop app has a built-in terminal: real login shells, docked in the editor window. Toggle it with `Cmd+J`, **View ▸ Show / Hide Terminal**, or the edge **Show terminal** tab that sits where you last closed it. It opens as a right-side column by default; buttons in its tab strip move it between the right column and the bottom dock or collapse it (sessions keep running), and the dock position is remembered.
The terminal is also the editor's AI-chat surface: the **Show terminal** tab starts your default CLI when no session is open, and the tab strip's **New chat** split button opens another CLI tab — its dropdown switches CLI (the pick sticks, shared with the Ask AI composer) or opens a plain shell tab. With text selected in the editor, `Cmd+J` stages the passage into the active CLI's input (or opens a new CLI tab when none is running) instead of toggling, and `Cmd+Shift+J` always stages it into a new CLI tab — the passage sits in the input for you to add to, and nothing is submitted until you press Enter. **Terminal ▸ New Terminal Window** (see [Terminal menu](#terminal-menu)) opens a dedicated window with the same multi-session tabs, `Cmd+<number>` tab switching, and shells starting at the project root.
+Rename a tab by double-clicking it or pressing `F2`; the name you set pins over whatever title the running program reports, and clearing it falls back to that title. Reorder tabs by dragging, or move the active tab with `Cmd+Shift+←` / `Cmd+Shift+→` — untitled tabs keep a number that stays with their session as the strip is rearranged.
+
The shells run at full user privilege. To turn the terminal off for a project on this machine, use **Settings ▸ Terminal** or set `terminal.enabled: false` in `.ok/local/config.yml` (see the [configuration reference](/docs/reference/configuration)); the setting is project-local, never shared via git or sync, and not agent-settable — only a human can flip it.
## Properties
@@ -163,9 +169,9 @@ To send your own freetext instruction along with the handoff, use the bottom [As
See the [per-integration pages](/docs/integrations/claude-code) for what each agent receives once dispatched.
-The menu is organized into two sections. **Terminal** (desktop app only) leads: a row for each agent CLI — **Claude**, **Codex**, **OpenCode**, and **Cursor** — that runs the corresponding CLI (`claude`, `codex`, `opencode`; Cursor's is `cursor-agent`) in OpenKnowledge's [docked terminal](#terminal) with the same scoped prompt. **Desktop** follows, listing the installed agent apps (Claude, Codex, Cursor); selecting one launches it via its deep link. Because both sections can list the same name, a Terminal **Claude** (the CLI) and a Desktop **Claude** (the app) can appear together; screen readers tell them apart by the Terminal row's "Claude CLI" accessible name. Each section renders only when it has something to launch, so on the web build — which has no docked terminal — the Terminal section is absent and a CLI pick falls back to the first installed Desktop app target.
+The menu is organized into two sections. **Terminal** (desktop app only) leads: a row for each agent CLI — **Claude**, **Codex**, **OpenCode**, **Cursor**, and **Pi** — that runs the corresponding CLI (`claude`, `codex`, `opencode`, `pi`; Cursor's is `cursor-agent`) in OpenKnowledge's [docked terminal](#terminal) with the same scoped prompt. **Desktop** follows, listing the installed agent apps (Claude, Codex, Cursor); selecting one launches it via its deep link. Because both sections can list the same name, a Terminal **Claude** (the CLI) and a Desktop **Claude** (the app) can appear together; screen readers tell them apart by the Terminal row's "Claude CLI" accessible name. Each section renders only when it has something to launch, so on the web build — which has no docked terminal — the Terminal section is absent and a CLI pick falls back to the first installed Desktop app target.
-The empty-state create composer on a fresh project carries the same Desktop / Terminal split: its Desktop rows pick the default agent the **Create** button uses, while its Terminal rows (desktop only, disabled until the workspace resolves) launch any of the four CLIs with the brief you typed.
+The empty-state create composer on a fresh project carries the same Desktop / Terminal split: its Desktop rows pick the default agent the **Create** button uses, while its Terminal rows (desktop only, disabled until the workspace resolves) launch any of the five CLIs with the brief you typed.
When Claude or Codex launches from the docked terminal, OpenKnowledge auto-approves its own MCP tools, so the agent searches, reads, and edits the knowledge base without a per-call approval prompt. Claude additionally auto-approves the `ok open` command. OpenCode, Cursor, and Pi launch unchanged.
diff --git a/docs/content/get-started/quickstart.mdx b/docs/content/get-started/quickstart.mdx
index 40550ba9b..968f64f0e 100644
--- a/docs/content/get-started/quickstart.mdx
+++ b/docs/content/get-started/quickstart.mdx
@@ -28,8 +28,8 @@ Download the latest version of the OpenKnowledge desktop app for macOS.
### Create a new project
-- Open the OpenKnowledge app. On first launch, approve the **Add OpenKnowledge to your AI tools** dialog — it wires up your AI editors and can add the `ok` command to your terminal. If you skip it, re-open it later from **File → Set up OpenKnowledge integrations…**.
-- Click **Create new project**.
+- Open the OpenKnowledge app. On first launch, approve the **Connect your AI tools to OpenKnowledge** dialog — it wires up your AI editors and can add the `ok` command to your terminal. If you skip it, re-open it later from **File → Set up OpenKnowledge integrations…**.
+- You'll then land on the starter-pack picker ("What do you want to build?"). To follow this guide, choose **Blank project** under "Have something else in mind?" — or pick a starter pack (for example **Knowledge base**) to scaffold ready-made folders and templates up front and skip the Initialize step below.
- Type a name for your project (for example, *Team Wiki*).
- Optionally click **Browse** to change where the project is saved, then click **Create**.
diff --git a/docs/content/reference/cli.mdx b/docs/content/reference/cli.mdx
index 8d5676625..9ce3e95c0 100644
--- a/docs/content/reference/cli.mdx
+++ b/docs/content/reference/cli.mdx
@@ -134,3 +134,5 @@ The rest of the CLI exists mostly for tooling and automation. Your AI editor spa
`ok uninstall` removes OpenKnowledge from the whole machine — running servers, credentials, the PATH shim, its own editor MCP entries, skill bundles, app data, and `~/.ok`. Your markdown content stays, and skills you authored under `~/.ok/skills` are kept unless you pass `--purge-content`. It never deletes the CLI binary itself; it ends by printing the removal command (`npm uninstall -g @inkeep/open-knowledge` for the install above).
Both commands print their plan and ask before acting; `--dry-run` previews without changing anything.
+
+On the macOS desktop app, **App menu → Uninstall OpenKnowledge…** covers both steps from one flow: it optionally deinitializes your projects, removes the global footprint, and then guides you through dragging the app to the Trash.
diff --git a/docs/content/reference/what-open-knowledge-writes.mdx b/docs/content/reference/what-open-knowledge-writes.mdx
index 57f70e5e0..a99ca8e42 100644
--- a/docs/content/reference/what-open-knowledge-writes.mdx
+++ b/docs/content/reference/what-open-knowledge-writes.mdx
@@ -258,6 +258,8 @@ Disable all three with `OK_RECLAIM_DISABLE=1`.
To review the footprint after the fact, `ok diagnose` reports what's on disk (and the desktop `path-install.json` records exactly which shell/`PATH` changes were made). To reverse it, `ok deinit` removes OpenKnowledge from one project and `ok uninstall` removes it from the whole machine — both keep your markdown content (and your authored `~/.ok/skills`) unless you pass `--purge-content`, and both take `--dry-run` to preview. See the [CLI reference](/docs/reference/cli) for the full semantics.
+In the desktop app you don't need the CLI for finer control. **Settings → AI tools & CLI** (under User) lists every global component OpenKnowledge manages — each editor's `open-knowledge` MCP entry, the `ok` PATH command, and the user-global skills — with a checkbox reflecting its live installed state; toggling a row installs or removes just that one component. **Settings → This project → AI tools** does the same for the open project's local footprint — its project-scoped MCP configs and the project skill. Removal keeps the same guest discipline as install: only entries OpenKnowledge recognizably wrote are removed, and anything you customized is left intact.
+
## What leaves your machine
By default, **nothing.** Everything above is written to your own disk. The only ways data leaves your machine are these — all opt-in or on-demand, except two automatic desktop-app actions (the update check, and a one-time share-link check on first launch):
diff --git a/packages/app/src/lib/default-cli-resolver.test.ts b/packages/app/src/lib/default-cli-resolver.test.ts
index c1d40de4d..1ae3540f9 100644
--- a/packages/app/src/lib/default-cli-resolver.test.ts
+++ b/packages/app/src/lib/default-cli-resolver.test.ts
@@ -6,7 +6,7 @@
* Resolution contract:
* 1. sticky parses to a CLI (via parseStickyCliId) → it, unconditionally
* (an explicit pick is honored even when the CLI is KNOWN-absent);
- * 2. else the first KNOWN-installed CLI by priority (claude > codex > opencode > cursor);
+ * 2. else the first KNOWN-installed CLI by priority (claude > codex > opencode > cursor > pi);
* 3. else 'claude'.
*/
@@ -69,9 +69,10 @@ describe('resolveDefaultCli', () => {
expect(resolveDefaultCli(null, installedMap(['codex', 'opencode', 'cursor']))).toBe('codex');
});
- test('respects the full priority order claude > codex > opencode > cursor', () => {
+ test('respects the full priority order claude > codex > opencode > cursor > pi', () => {
expect(resolveDefaultCli(null, installedMap(['opencode', 'cursor']))).toBe('opencode');
- expect(resolveDefaultCli(null, installedMap(['cursor']))).toBe('cursor');
+ expect(resolveDefaultCli(null, installedMap(['cursor', 'pi']))).toBe('cursor');
+ expect(resolveDefaultCli(null, installedMap(['pi']))).toBe('pi');
expect(resolveDefaultCli(null, installedMap(['claude', 'codex', 'opencode', 'cursor']))).toBe(
'claude',
);
@@ -85,7 +86,13 @@ describe('resolveDefaultCli', () => {
test('all-false install map → claude', () => {
expect(
- resolveDefaultCli(null, { claude: false, codex: false, opencode: false, cursor: false }),
+ resolveDefaultCli(null, {
+ claude: false,
+ codex: false,
+ opencode: false,
+ cursor: false,
+ pi: false,
+ }),
).toBe('claude');
});
diff --git a/packages/app/src/lib/default-cli-resolver.ts b/packages/app/src/lib/default-cli-resolver.ts
index 302339497..1a4bb261b 100644
--- a/packages/app/src/lib/default-cli-resolver.ts
+++ b/packages/app/src/lib/default-cli-resolver.ts
@@ -7,7 +7,7 @@
* (a `HandoffTarget` id, e.g. `claude-code`) is intentionally ignored here —
* `parseStickyCliId` returns `null` for it and resolution falls through to the
* installed-priority auto-pick. Priority order is `TERMINAL_CLI_IDS` itself
- * (claude > codex > opencode > cursor); reusing it keeps the auto-pick order in
+ * (claude > codex > opencode > cursor > pi); reusing it keeps the auto-pick order in
* lockstep with the visible launch-row order rather than duplicating a list.
*/