Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

docs(open-knowledge): split write-footprint page into macOS app / Web app tabs (#2333)

mike-inkeep6004761ec724
diff --git a/docs/content/reference/what-open-knowledge-writes.mdx b/docs/content/reference/what-open-knowledge-writes.mdx
index ff5ec2b47..6209993bf 100644
--- a/docs/content/reference/what-open-knowledge-writes.mdx
+++ b/docs/content/reference/what-open-knowledge-writes.mdx
@@ -5,7 +5,7 @@ icon: LuHardDrive
description: Every file OpenKnowledge creates or changes — when, where, in-project vs. your home directory — plus the opt-outs and what leaves your machine (nothing by default).
---
-OpenKnowledge keeps your knowledge base as plain markdown in your own project directory, but the tooling around it — the CLI, the MCP server, and the desktop app — also writes a handful of supporting files, some of them **outside the project**, in your home directory, your shell startup files, your editors' configs, and the macOS Keychain.
+OpenKnowledge keeps your knowledge base as plain markdown in your own project directory, but the tooling around it — the CLI, the MCP server, and the desktop app — also writes a handful of supporting files, some of them **outside the project**, in your home directory, your shell startup files, your editors' configs, and the OS credential store.
This page lists every one of them: **when** each write happens, **what** it is, and **where** it lands. Everything here is verified against the source.
@@ -18,11 +18,101 @@ This page lists every one of them: **when** each write happens, **what** it is,
Writes fall into two buckets, and each table's **Scope** column tells you which:
- **In-project** — inside your project folder. Either **committed** (shared through git with your team) or **gitignored** (this machine only, under `.ok/local/` or `.git/`).
-- **Outside-project** — your **home directory** (`~/.ok/`, `~/Library/...`), your **shell startup files** (`~/.zshrc` and friends), your editors' **user-level configs**, or the macOS **Keychain**.
+- **Outside-project** — your **home directory** (`~/.ok/`, `~/Library/...`), your **shell startup files** (`~/.zshrc` and friends), your editors' **user-level configs**, or the OS credential store.
-There are five moments OpenKnowledge writes to disk: installing the package, `ok init`, `ok start`, `ok mcp`, and the desktop app. Jump to the [opt-outs](#opt-outs-in-one-place) if that's all you need.
+OpenKnowledge installs one of two ways, and the footprint differs a little between them. Pick yours below — each tab lists the complete set of writes for that path. The [opt-outs](#opt-outs-in-one-place) and [what leaves your machine](#what-leaves-your-machine) at the end apply to both.
-## When you install the package
+<Tabs groupId="ok-install" persist className="ok-flush-tabs ok-tabs-h2" items={['MacOS app', 'CLI']}>
+
+<Tab>
+
+### Installing and launching the app
+
+The macOS app ships as a signed `.dmg` you drag into `/Applications`. On launch it writes app-level state and logs, and — because a `.dmg` app can't put a CLI on your `PATH` on its own — first launch also sets up a `PATH` shim and, with your consent, registers the MCP server (both covered below).
+
+| Path | What it is | Scope |
+| --- | --- | --- |
+| `~/Library/Application Support/OpenKnowledge/state.json` | Recent projects, window/view state, update channel | Outside-project (home dir) |
+| `~/Library/Application Support/OpenKnowledge/path-install.json` | Records the `PATH`/shell changes it made, so they can be reverted | Outside-project (home dir) |
+| `~/.ok/logs/desktop.<date>.log` | Desktop app + renderer log | Outside-project (home dir) |
+| `~/.ok/mcp-status.json` | Records your first-launch MCP-setup consent choice | Outside-project (home dir) |
+| `~/Library/Caches/OpenKnowledge-updater/` | Staged auto-update downloads (electron-updater) | Outside-project (home dir) |
+
+The app registers the `openknowledge://` URL scheme (for deep links) and checks for updates against the OpenKnowledge GitHub releases feed. Updates are **not** downloaded automatically until you choose to update; they install on the next quit. Override the feed with `OK_UPDATER_FEED_URL`.
+
+### Shell and `PATH`
+
+So `ok` works in your terminal too, the packaged app manages a `PATH` shim. **This is macOS-only, packaged-build-only, and disabled by `OK_RECLAIM_DISABLE=1`.** It never uses `sudo`, never runs an admin prompt, and never installs a login item.
+
+| Path | What it is | Scope |
+| --- | --- | --- |
+| `~/.ok/bin/ok`, `~/.ok/bin/open-knowledge` | Symlinks to the CLI bundled inside the app | Outside-project (home dir) |
+| `~/.ok/env.sh` | A managed shim that prepends `~/.ok/bin` to your `PATH` | Outside-project (home dir) |
+| `~/.zshrc`, `~/.bash_profile`, `~/.config/fish/conf.d/open-knowledge.fish` | A **fenced managed block** that sources `~/.ok/env.sh` | Outside-project (shell config) |
+
+The managed block is clearly fenced so you can see and remove it:
+
+```bash
+# >>> open-knowledge cli >>>
+[ -f "$HOME/.ok/env.sh" ] && . "$HOME/.ok/env.sh"
+# <<< open-knowledge cli <<<
+```
+
+Delete the block and the app **won't re-add it** — the removal is recorded and respected. Or set `OK_RECLAIM_DISABLE=1` to disable all of this before first launch.
+
+### Setting up a project
+
+When you initialize or open a project, the app scaffolds the same project files the CLI's `ok init` creates, and registers the `open-knowledge` MCP server with the AI editors it detects. The MCP registration is **surgical** — it adds only its own entry and leaves your other settings, comments, and formatting byte-for-byte intact.
+
+| Path | What it is | Scope |
+| --- | --- | --- |
+| `.ok/`, `.ok/config.yml` | Project directory and its [config](/docs/reference/configuration) | In-project, committed |
+| `.ok/.gitignore` | Keeps machine-local runtime state (`local/`, `principal.json`, `server.lock`, …) out of git | In-project, committed |
+| `.okignore` | Paths excluded from the editor, search, and agents — see [Ignore patterns](/docs/features/ignore-patterns) | In-project, committed |
+| `.mcp.json`, `.cursor/mcp.json`, `.codex/config.toml`, `opencode.json` | Project-scoped MCP registration, one per detected editor | In-project, committed |
+| `.claude/skills/`, `.cursor/skills/`, `.codex/skills/`, `.opencode/skills/` | Project-local "rich" OpenKnowledge skill (`SKILL.md`), one per detected editor | In-project, committed |
+| `.claude/launch.json` | Configures Claude Code's preview pane to open the editor (on a local UI port, `39848`) | In-project, committed |
+| `~/.claude.json`, `~/Library/Application Support/Claude/claude_desktop_config.json`, `~/.cursor/mcp.json`, `~/.codex/config.toml`, `~/.config/opencode/opencode.json` | User-level `open-knowledge` MCP registration, one per detected editor (so it's available in every project) | Outside-project (editor config) |
+
+### While a project is open
+
+The app runs a collaboration server for the open project. It writes runtime state, gitignored under `.ok/local/`, plus a shadow git repo that powers the timeline and recovery features:
+
+| Path | What it is | Scope |
+| --- | --- | --- |
+| `.ok/local/server.lock`, `.ok/local/ui.lock` | Advertise the running server's and web UI's ports | In-project, gitignored |
+| `.ok/local/principal.json` | Your local identity (id, email) for edit attribution | In-project, gitignored |
+| `.ok/local/sync-state.json`, `.ok/local/conflicts.json` | GitHub-sync engine state | In-project, gitignored |
+| `.ok/local/state.json`, `.ok/local/last-spawn-error.log` | State-schema manifest and the UI sibling's error log | In-project, gitignored |
+| `.ok/local/telemetry/spans-*.jsonl` | Local diagnostic spans, rotated at ~50 MB | In-project, gitignored |
+| `.ok/local/logs/server-*.jsonl` | Local server logs, rotated at ~25 MB | In-project, gitignored |
+| `.ok/local/cache/<branch>/backlinks.json` | Backlink-graph cache | In-project, gitignored |
+| `.git/ok/` | Shadow git repo holding per-writer work-in-progress refs | In-project, gitignored (inside `.git/`) |
+
+Diagnostic logs and telemetry are **on by default but local-only** — credential-bearing attributes are redacted (`[REDACTED]`) before anything is written, the files rotate at the size caps above, and nothing leaves the machine until you explicitly run `ok diagnose bundle`. Turn the local sink off with `telemetry.localSink.enabled: false`; see [Configuration](/docs/reference/configuration).
+
+On each launch and project open, the app also runs **repair sweeps**: it rewrites *existing* `open-knowledge` MCP entries (in the editor configs above, plus that project's `.vscode/settings.json`), `.claude/launch.json`, and skill files to the current canonical form — a no-op when nothing has drifted, and it **never adds** an entry to an editor that doesn't already have one. Same `OK_RECLAIM_DISABLE=1` opt-out.
+
+### Home directory and credentials (`~/.ok/`)
+
+| Path | What it is | Sensitive? |
+| --- | --- | --- |
+| `~/.ok/global.yml` | User-global [config](/docs/reference/configuration) (applies to every project) | No |
+| `~/.ok/secrets.yml` | Embeddings provider API key for [semantic search](/docs/reference/configuration#semantic-search), if you set one. Written `0600`; never in `config.yml` | **Yes** (`0600`) |
+| `~/.ok/auth.yml` | Auth-token fallback, used only when the Keychain is unavailable. Written `0600` | **Yes** (`0600`) |
+| `~/.ok/skill-state.yml`, `~/.ok/skill-install-events.jsonl` | Skill-install bookkeeping | No |
+| `~/.ok/stats.jsonl` | Local "open with AI" handoff stats — local-only, no phone-home | No |
+| `~/.ok/mcp-status.json` | First-launch MCP consent record | No |
+| `~/.ok/logs/`, `~/.ok/bug-reports/` | Desktop logs and generated diagnostic bundles | No |
+| `~/.ok/bin/`, `~/.ok/env.sh` | `PATH` shim (see [Shell and `PATH`](#shell-and-path) above) | No |
+
+**Auth tokens** (for GitHub sync, sharing, and cloning) are stored in the macOS **Keychain** under the service name `open-knowledge`. The `~/.ok/auth.yml` file is only a fallback for headless environments where the Keychain isn't reachable; when the Keychain becomes available, the token is migrated into it and the file copy is removed.
+
+</Tab>
+
+<Tab>
+
+### Installing the package
Installing `@inkeep/open-knowledge` from npm (or invoking it with `npx`) drops the two CLI binaries plus a bundled native addon, and runs a `postinstall` step that registers a small "discovery" skill so the AI editors on your machine know OpenKnowledge exists.
@@ -40,12 +130,10 @@ The `postinstall` step is **non-fatal** (install always succeeds even if it fail
Install with `npm install --ignore-scripts` to skip the `postinstall` skill step entirely. You can always add the skills later from `ok init`.
</Callout>
-## `ok init`
+### `ok init`
`ok init` turns a folder into an OpenKnowledge project. It scaffolds the project's `.ok/` directory, and — unless you pass `--no-mcp` — registers the `open-knowledge` MCP server with the AI editors it detects. The MCP registration is **surgical**: it adds only its own entry and leaves your other settings, comments, and formatting byte-for-byte intact (if a config can't be parsed safely, it's left untouched and reported).
-### In-project (this project)
-
| Path | What it is | Scope |
| --- | --- | --- |
| `.ok/`, `.ok/config.yml` | Project directory and its [config](/docs/reference/configuration) | In-project, committed |
@@ -56,8 +144,6 @@ The `postinstall` step is **non-fatal** (install always succeeds even if it fail
| `.claude/skills/`, `.cursor/skills/`, `.codex/skills/`, `.opencode/skills/` | Project-local "rich" OpenKnowledge skill (`SKILL.md`), one per detected editor | In-project, committed |
| `.claude/launch.json` | Configures Claude Code's preview pane to open the editor (on a local UI port, `39848`) | In-project, committed |
-### Outside-project (user-level editor configs)
-
With `--scope user` or `both` (the default), `ok init` also registers the `open-knowledge` MCP server in each detected editor's **user-level** config, so it's available in every project:
| Path | Editor | Scope |
@@ -76,9 +162,9 @@ With `--scope user` or `both` (the default), `ok init` also registers the `open-
- `--local-only` (vs `--shared`) — keep `.ok/` out of git.
</Callout>
-## `ok start`
+### `ok start`
-`ok start` runs the collaboration server. Most of what it writes stays **inside your project**, gitignored under `.ok/local/`, plus a shadow git repo for the timeline and recovery features. It also runs a few **repair sweeps** on each boot that can touch files outside the project — see [below](#repair-sweeps).
+`ok start` runs the collaboration server. Most of what it writes stays **inside your project**, gitignored under `.ok/local/`, plus a shadow git repo for the timeline and recovery features:
| Path | What it is | Scope |
| --- | --- | --- |
@@ -91,11 +177,9 @@ With `--scope user` or `both` (the default), `ok init` also registers the `open-
| `.ok/local/cache/<branch>/backlinks.json` | Backlink-graph cache | In-project, gitignored |
| `.git/ok/` | Shadow git repo holding per-writer work-in-progress refs (powers the timeline) | In-project, gitignored (inside `.git/`) |
-Diagnostic logs and telemetry are **on by default but local-only** — credential-bearing attributes are redacted (`[REDACTED]`) before anything is written, the files rotate at the size caps above, and nothing leaves the machine until you explicitly run `ok diagnose bundle`. Turn the local sink off entirely with `telemetry.localSink.enabled: false`; see [Configuration](/docs/reference/configuration).
+Diagnostic logs and telemetry are **on by default but local-only** — credential-bearing attributes are redacted (`[REDACTED]`) before anything is written, the files rotate at the size caps above, and nothing leaves the machine until you explicitly run `ok diagnose bundle`. Turn the local sink off with `telemetry.localSink.enabled: false`; see [Configuration](/docs/reference/configuration).
-### Repair sweeps
-
-On each boot, `ok start` also re-checks a few things that drift as OpenKnowledge updates and rewrites any that have fallen out of the current canonical form — a no-op when nothing has changed. These sweeps **only update entries that already exist**; they never add one where there wasn't one.
+On each boot, `ok start` also runs **repair sweeps**: it re-checks a few things that drift as OpenKnowledge updates and rewrites any that have fallen out of the current canonical form — a no-op when nothing has changed, and it **never adds** an entry that isn't already there.
| What it re-checks | Where | Scope |
| --- | --- | --- |
@@ -103,76 +187,38 @@ On each boot, `ok start` also re-checks a few things that drift as OpenKnowledge
| `.claude/launch.json` | Your project | In-project, committed |
| OpenKnowledge skill files | Project (`.claude/skills/…`) and user-global (`~/.agents/skills/…`) | In-project **and** outside-project (home dir) |
-These are the same sweeps the [desktop app](#ok-desktop-macos-app) runs. Disable all three with `OK_RECLAIM_DISABLE=1`.
+Disable all three with `OK_RECLAIM_DISABLE=1`.
-## `ok mcp`
+### `ok mcp`
`ok mcp` is the stdio bridge your editor spawns to talk to the server. It **writes nothing to disk** — it routes tool calls to a running `ok start` backend (starting one on the first write).
-## OK Desktop (macOS app)
-
-The packaged macOS app writes some app-level state and logs, and — because a `.dmg` app can't put a CLI on your `PATH` on its own — it manages a `PATH` shim and shell startup entries so `ok` works in your terminal too. **All of the shell and `PATH` behavior below is macOS-only, packaged-build-only, and disabled by `OK_RECLAIM_DISABLE=1`.** It never uses `sudo`, never runs an admin prompt, and never installs a login item.
-
-### App data, logs, and updates
-
-| Path | What it is | Scope |
-| --- | --- | --- |
-| `~/Library/Application Support/OpenKnowledge/state.json` | Recent projects, window/view state, update channel | Outside-project (home dir) |
-| `~/Library/Application Support/OpenKnowledge/path-install.json` | Records the `PATH`/shell changes it made, so they can be reverted | Outside-project (home dir) |
-| `~/.ok/logs/desktop.<date>.log` | Desktop app + renderer log | Outside-project (home dir) |
-| `~/.ok/mcp-status.json` | Records your first-launch MCP-setup consent choice | Outside-project (home dir) |
-| `~/Library/Caches/OpenKnowledge-updater/` | Staged auto-update downloads (electron-updater) | Outside-project (home dir) |
-
-The app registers the `openknowledge://` URL scheme (for deep links) and checks for updates against the OpenKnowledge GitHub releases feed. Updates are **not** downloaded automatically until you choose to update; they install on the next quit. Override the feed with `OK_UPDATER_FEED_URL`.
-
-### Shell and `PATH`
-
-| Path | What it is | Scope |
-| --- | --- | --- |
-| `~/.ok/bin/ok`, `~/.ok/bin/open-knowledge` | Symlinks to the CLI bundled inside the app | Outside-project (home dir) |
-| `~/.ok/env.sh` | A managed shim that prepends `~/.ok/bin` to your `PATH` | Outside-project (home dir) |
-| `~/.zshrc`, `~/.bash_profile`, `~/.config/fish/conf.d/open-knowledge.fish` | A **fenced managed block** that sources `~/.ok/env.sh` | Outside-project (shell config) |
-
-The managed block is clearly fenced so you can see and remove it:
-
-```bash
-# >>> open-knowledge cli >>>
-[ -f "$HOME/.ok/env.sh" ] && . "$HOME/.ok/env.sh"
-# <<< open-knowledge cli <<<
-```
-
-Delete the block and the app **won't re-add it** — the removal is recorded and respected. Or set `OK_RECLAIM_DISABLE=1` to disable all of this before first launch.
-
-### Keeping MCP entries current
-
-On each launch (and on each project open), the app runs the **same [repair sweeps](#repair-sweeps) as `ok start`** — rewriting *existing* `open-knowledge` MCP entries, `.claude/launch.json`, and skill files to the current canonical form, and **never adding** an entry to an editor that doesn't already have one. On a project open it also rewrites an existing `open-knowledge` entry in that project's `.vscode/settings.json`. This keeps a working setup from drifting as the app updates, and is covered by the same first-launch consent and the `OK_RECLAIM_DISABLE=1` opt-out.
-
-## Your home directory and credentials (`~/.ok/`)
-
-Pulling the home-directory writes together — this is everything that can live under `~/.ok/`, across all of the above:
+### Home directory and credentials (`~/.ok/`)
| Path | What it is | Sensitive? |
| --- | --- | --- |
| `~/.ok/global.yml` | User-global [config](/docs/reference/configuration) (applies to every project) | No |
| `~/.ok/secrets.yml` | Embeddings provider API key for [semantic search](/docs/reference/configuration#semantic-search), if you set one. Written `0600`; never in `config.yml` | **Yes** (`0600`) |
-| `~/.ok/auth.yml` | Auth-token fallback, used only when the Keychain is unavailable. Written `0600` | **Yes** (`0600`) |
+| `~/.ok/auth.yml` | Auth-token fallback, used when no OS credential store is reachable. Written `0600` | **Yes** (`0600`) |
| `~/.ok/skill-state.yml`, `~/.ok/skill-install-events.jsonl` | Skill-install bookkeeping | No |
| `~/.ok/stats.jsonl` | Local "open with AI" handoff stats — local-only, no phone-home | No |
-| `~/.ok/mcp-status.json` | Desktop first-launch MCP consent record | No |
-| `~/.ok/logs/`, `~/.ok/bug-reports/` | Desktop logs and generated diagnostic bundles | No |
-| `~/.ok/bin/`, `~/.ok/env.sh` | Desktop `PATH` shim (see above) | No |
+| `~/.ok/bug-reports/` | Generated diagnostic bundles (`ok diagnose` / `ok bug-report`) | No |
-**Auth tokens** (for GitHub sync, sharing, and cloning) are stored in the macOS **Keychain** under the service name `open-knowledge`. The `~/.ok/auth.yml` file is only a fallback for headless environments where the Keychain isn't reachable; when the Keychain becomes available, the token is migrated into it and the file copy is removed.
+**Auth tokens** (for GitHub sync, sharing, and cloning) are stored in your operating system's secure credential store when one is available — the macOS **Keychain** on an Intel Mac (service `open-knowledge`), or the platform equivalent — falling back to a `0600` `~/.ok/auth.yml` file on headless systems (a Linux server, CI) where none is reachable.
+
+</Tab>
+
+</Tabs>
## Opt-outs in one place
| To skip… | Do this |
| --- | --- |
-| The `postinstall` skill install | `npm install --ignore-scripts` |
+| The `postinstall` skill install (CLI) | `npm install --ignore-scripts` |
| All editor MCP registration in `ok init` | `ok init --no-mcp` |
| User-level (vs project) MCP writes | `ok init --scope project` |
| Committing `.ok/` to git | `ok init --local-only` (or choose "local only" when prompted) |
-| The `ok start` / desktop repair sweeps and the desktop app's shell / `PATH` changes | `OK_RECLAIM_DISABLE=1` (also delete the managed block from your shell config to remove the `PATH` entry) |
+| The repair sweeps and the desktop app's shell / `PATH` changes | `OK_RECLAIM_DISABLE=1` (also delete the managed block from your shell config to remove the `PATH` entry) |
| Local diagnostic logs and telemetry | `telemetry.localSink.enabled: false` in config |
| Auto-starting the MCP server | `OK_MCP_AUTOSTART=0` |
@@ -188,7 +234,7 @@ By default, **nothing.** Everything above is written to your own disk. The only
| Semantic search embeddings | Only when you enable [semantic search](/docs/reference/configuration#semantic-search) **and** set a key — off by default | Your configured embeddings provider (OpenAI by default) |
| GitHub sync / share | When you sync, clone, publish, or share | GitHub |
| Update check | Automatically, on desktop-app launch | OpenKnowledge releases feed (GitHub) |
-| npm/`npx` fetch | During install | The npm registry |
+| npm/`npx` fetch | During install (CLI) | The npm registry |
Local diagnostic logs and telemetry are scrubbed of credential-bearing attributes and never sent anywhere on their own.
diff --git a/docs/src/app/global.css b/docs/src/app/global.css
index 537a49aad..4a121cb43 100644
--- a/docs/src/app/global.css
+++ b/docs/src/app/global.css
@@ -261,6 +261,20 @@
border-radius: 0;
}
+/* ------------------------------------------------------------------
+ * .ok-tabs-h2 — opt-in modifier (layered on .ok-flush-tabs) that gives a
+ * page's install-path tabs the visual weight of an <h2> section heading:
+ * extra space above so they stand out from the preceding paragraph, and
+ * trigger labels sized to match a Fumadocs prose `##`. Scoped to the page
+ * that opts in — the shared .ok-flush-tabs (e.g. Quickstart) is unchanged.
+ * ------------------------------------------------------------------ */
+.ok-tabs-h2 {
+ margin-top: 2.5rem;
+}
+.ok-tabs-h2 [role="tab"] {
+ font-size: 1.5rem;
+}
+
.slide-btn-accent {
background-color: var(--slide-accent);
color: #fff;