Add a first-run onboarding card to OK Desktop. A dismissable checklist…

.changeset/onboarding-card.md

@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": minor
+---
+
+Add a first-run onboarding card to OK Desktop. A dismissable checklist in the sidebar footer guides genuinely new users through three momentum steps — create a project (pre-checked), create the first file (⌘N), and ask AI (⌘L) — each showing its keyboard shortcut. Steps check off as the user actually performs them; on finishing all three the card celebrates in place with the OK blob mascot before animating away for good. It shows only for a fresh single-project desktop session and never returns once dismissed or completed (device-local). Web and CLI render nothing.

.changeset/terminal-file-drop-and-ask-ai-reuse.md

@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge-desktop": patch
+---
+
+Two docked-terminal fixes. Dropping a file onto the terminal now inserts its shell-escaped absolute path at the prompt (matching VS Code / Cursor / JetBrains), so you can drag a screenshot straight into a running `claude` session instead of the drop being ignored. And highlighting text and choosing "Ask AI" now sends the selection straight into the open terminal (or opens the Ask AI composer when no terminal is open) — consistent with the fact that there is no composer visible while the terminal is up. Launching a CLI (Create with…, Open in terminal) always opens a new terminal tab rather than reusing the one already running.

docs/content/get-started/meta.json

@@ -1,5 +1,5 @@
 {
   "title": "Get Started",
   "icon": "LuRocket",
-  "pages": ["overview", "quickstart", "obsidian"]
+  "pages": ["overview", "quickstart"]
 }

docs/content/get-started/quickstart.mdx

@@ -40,6 +40,10 @@ Download the latest version of the OpenKnowledge desktop app for macOS.
 
 From your newly created project, select **Knowledge base** from the landing page, leave **Project root** selected, and click **Initialize**.
 
+<Callout type="info">
+  Curious what the app writes to your machine — including the shell and `PATH` changes it manages on macOS? See [What OpenKnowledge writes to your system](/docs/reference/what-open-knowledge-writes).
+</Callout>
+
 </Step>
 
 <Step>
@@ -127,6 +131,10 @@ ok init
 ok start --open
 ```
 
+<Callout type="info">
+  Want to know exactly what these commands write to your machine — in your project, your home directory, and your editors' configs? See [What OpenKnowledge writes to your system](/docs/reference/what-open-knowledge-writes).
+</Callout>
+
 </Step>
 
 <Step>

docs/content/integrations/meta.json

@@ -1,5 +1,5 @@
 {
   "title": "Integrations",
   "icon": "LuPlug",
-  "pages": ["claude-code", "cursor", "codex", "opencode"]
+  "pages": ["claude-code", "cursor", "codex", "opencode", "openclaw"]
 }

docs/content/integrations/openclaw.mdx

@@ -0,0 +1,149 @@
+---
+title: OpenClaw
+description: Use OpenKnowledge with OpenClaw agents over MCP.
+---
+
+OpenClaw is an agent gateway: it runs agents that connect to MCP servers. Register OpenKnowledge as one of those servers and every agent OpenClaw runs can read, search, and write your knowledge base through OK's tools — with full attribution, link-awareness, conflict-awareness, and a live browser preview. Inside an OK project, agents work markdown through those tools rather than native file access, so every edit stays attributed and previewable.
+
+<Callout type="info">
+  Unlike Cursor, Codex, and Claude Code, OpenClaw is **not** auto-detected by `ok init`. You register the OpenKnowledge MCP server in OpenClaw's own config — the JSON block below. `ok init` is still how you turn a folder into a knowledge base.
+</Callout>
+
+## Register the OpenKnowledge MCP server
+
+Add the server to `~/.openclaw/openclaw.json` under `mcp.servers`, pointing `cwd` at the knowledge base you want agents to land in:
+
+```jsonc
+// ~/.openclaw/openclaw.json
+{
+  "mcp": {
+    "servers": {
+      "open-knowledge": {
+        "command": "ok",
+        "args": ["mcp"],
+        "cwd": "/path/to/your/knowledge-base"
+      }
+    }
+  }
+}
+```
+
+OpenClaw can also register servers from the command line (`openclaw mcp add …`) — run `openclaw mcp add --help` for the flags on your build. The JSON block above is the path we've verified end to end.
+
+<Callout type="warn">
+  **`ok` may not be on OpenClaw's PATH.** OpenClaw's runtime shell often doesn't have `ok` on `PATH`, so `"command": "ok"` can fail to launch the server. If it does, point `command` at the absolute binary the installer drops — `~/.ok/bin/ok` on a standard install. A JSON config isn't shell-expanded, so write the path out in full rather than with `~`:
+
+  ```jsonc
+  "command": "/Users/<your-username>/.ok/bin/ok"
+  ```
+</Callout>
+
+`cwd` is the default knowledge base the server targets, but you can override it per call: every OK tool accepts a `cwd` argument, so an agent can point at a different project (or a git worktree) without touching the config — pass it once and it sticks for that session.
+
+## Reload
+
+After editing the config, run `openclaw mcp reload` so active agents pick up the change. If your build needs a full gateway restart instead, restart it.
+
+## Verify
+
+Two complementary checks — the probe confirms the gateway can reach the server; the prompt confirms an agent can actually call its tools.
+
+**Server-side** — confirm OpenClaw can launch the server and its tools enumerate:
+
+```bash
+openclaw mcp doctor --probe         # -> open-knowledge: ok
+openclaw mcp probe open-knowledge   # -> open-knowledge: 19 tools
+```
+
+Unrelated config-health or plugin-version warnings for *other* servers don't block OpenKnowledge from probing.
+
+**Agent-side** — open the project with an OpenClaw agent and ask:
+
+<VerifyExec subject="OpenClaw" />
+
+If the agent doesn't see the tool, run tool discovery — some runtimes lazy-load MCP tools and only surface them after a search, so absence from the initial list means "not discovered yet," not "not registered" — then `openclaw mcp reload`.
+
+## Initialize a knowledge base
+
+If the folder in `cwd` isn't an OK project yet, make it one:
+
+```bash
+ok init /path/to/your/knowledge-base
+```
+
+<Callout type="warn">
+  **`ok init` resolves upward into an existing project.** Run inside a subdirectory of an existing OK project, `ok init` finds the *parent* project and refreshes that one — it does not create a nested project, and it writes no markdown in the subdirectory. To create a genuinely separate knowledge base, run `ok init` in a folder that sits **outside any existing `.ok` project tree**.
+</Callout>
+
+## Smoke test
+
+A copy-pasteable, end-to-end check that proves the whole stack — not just "the server starts." Point an OpenClaw agent at a fresh knowledge base and have it run:
+
+<Steps>
+
+<Step>
+### Discover the tools
+
+If `mcp__open-knowledge__*` isn't in the agent's tool list, run tool discovery first — absence from the initial list means "not discovered yet," not "not registered."
+</Step>
+
+<Step>
+### Read config, list the root
+
+`config` (resolved OK config) and `exec("ls -A")` confirm the agent is pointed at the right project.
+</Step>
+
+<Step>
+### Write a folder, a README, and a linked note
+
+`write` a `notes` folder, a `README`, and a note that links to a second doc you'll create. A forward link to a not-yet-created target comes back as a broken-link warning — expected when you're about to create it.
+</Step>
+
+<Step>
+### Read them back
+
+`exec("cat …")` on both docs returns content plus frontmatter, backlinks, and history that plain `cat` can't.
+</Step>
+
+<Step>
+### Audit links, then search
+
+`links({ kind: "dead" })` should return `[]` once every target exists; `search({ query })` should find the new docs.
+</Step>
+
+<Step>
+### Get the preview URL
+
+`preview_url` returns the full browser URL for the doc (see [Preview](#preview)).
+</Step>
+
+</Steps>
+
+That sequence exercises every layer — discovery, config, read, write, link graph, search, and preview — in one pass.
+
+## Preview
+
+Write and edit responses include a route-only preview path like `/#/notes/mcp-round-trip` — a route id, **not** a full URL. Call `preview_url` for the openable browser address, and don't screenshot the preview to confirm an edit (the tool response is the confirmation). See [MCP reference → Preview links](/docs/reference/mcp#preview-links) for the full semantics.
+
+## Agent contract
+
+`ok init` installs the **OpenKnowledge skill** — the authoritative agent contract for tool use, grounding, and linking — and OpenClaw loads installed skills from `~/.agents/skills/`. Rather than restate the contract here, two OpenClaw-specific reminders:
+
+- **Markdown is MCP-owned.** Inside an OK project, read and write `.md` / `.mdx` through OK's tools (`exec`, `search`, `write`, `edit`, `links`), not native shell or file tools — native access loses attribution and skips the frontmatter, backlinks, and history OK returns.
+- **Discover before concluding the MCP is missing.** Not seeing `exec` in the initial tool list isn't the escape hatch; run tool discovery first.
+
+For the complete tool surface, see the [MCP reference](/docs/reference/mcp).
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| Server won't launch / `command not found` | `ok` not on OpenClaw's PATH | Point `command` at the absolute binary: `/Users/<your-username>/.ok/bin/ok` |
+| `openclaw mcp probe` shows 0 tools | wrong `cwd`, or the folder isn't a KB yet | Set `cwd` to a real folder and `ok init` it |
+| Agent doesn't see `mcp__open-knowledge__*` | MCP tools lazy-loaded | Run tool discovery, then `openclaw mcp reload` |
+| `ok init` "refreshed" a parent project, no new KB | upward project resolution | Run `ok init` outside any existing `.ok` tree |
+| Broken-link warning on a just-written doc | forward link to a not-yet-created target | Create the target, then re-check `links({ kind: "dead" })` |
+| `write` / `edit` -> "Hocuspocus server is not running" | OK server not started | Run `ok start` (or leave the desktop app running) and retry |
+| Preview "doesn't open" | used the route-only `/#/…` path in a browser | Call `preview_url` for the full URL |
+
+New to OpenKnowledge itself? Start with the [quickstart](/docs/get-started/quickstart) for `ok init` and `ok start`.

docs/content/meta.json

@@ -4,6 +4,8 @@
   "pages": [
     "---GET STARTED---",
     "...get-started",
+    "---MIGRATE---",
+    "...migrate",
     "---INTEGRATIONS---",
     "...integrations",
     "---FEATURES---",

docs/content/migrate/meta.json

@@ -0,0 +1,5 @@
+{
+  "title": "Migrate",
+  "icon": "LuArrowRightLeft",
+  "pages": ["obsidian", "notion"]
+}

docs/content/migrate/notion.mdx

@@ -0,0 +1,70 @@
+---
+title: From Notion
+description: How to export a Notion workspace to Markdown and open it in OpenKnowledge, what carries over, and where the two differ.
+icon: LuFileInput
+---
+
+This guide will cover exporting your Notion workspace to markdown files so that you can access them from OpenKnowledge. There are several key differences between OpenKnowledge and Notion that make this export incomplete and those will be covered here.
+
+## Export your workspace from Notion
+
+1. In Notion, click on your workspace in the top left and go to **Settings**.
+2. Under **General**, scroll down to **Export**.
+3. Set **Export format** to **Markdown & CSV** and leave all the default settings.
+4. Download and **unzip** the export folder and move it to your desired location.
+
+## Open the export in OpenKnowledge
+
+### macOS Desktop app
+
+Open OpenKnowledge, choose **Open folder on disk**, select the unzipped export folder, and proceed through the **Setup** screen with defaults selected.
+
+### Linux, Windows, Intel Mac
+
+Install the [ok CLI](/docs/reference/cli), `cd` into the unzipped folder, and run `ok init && ok start --open`.
+
+## What exports cleanly
+
+| Notion content | In OpenKnowledge |
+| --- | --- |
+| Headings, paragraphs, bold / italic, quotes, and dividers | Render natively and are preserved in the exported markdown. |
+| Bulleted, numbered, and to-do lists | Render natively, including nesting and `- [ ]` checkboxes. |
+| Code blocks | Render with syntax highlighting. |
+| Simple (inline) tables | Convert to Markdown pipe tables and render as tables. |
+| Images and file attachments | Downloaded into the export folder next to each page and referenced with relative `![alt](path)` links; images render inline. See [Assets and embeds](/docs/features/assets-and-embeds). |
+
+## Where the two differ
+
+A number of Notion features don't survive the Markdown & CSV export, or land as plain text.
+
+| Notion feature | What happens |
+| --- | --- |
+| **Databases** (tables, boards, calendars, galleries, timelines) | Each exports as a stub page, a `<name>_all.csv` of the whole table, and a folder holding one markdown file per row. The per-row pages are first-class docs, but there is no support for viewing complete CSV tables. |
+| **Relations, rollups, formulas** | Not represented in the Markdown & CSV export. |
+| **Database row properties** | Exported as plain `Key: Value` lines under the page title, not YAML frontmatter. |
+| **Callouts** | Exported as raw `<aside>` HTML. The content is preserved, but it isn't converted to OpenKnowledge's native callout (`> [!note]`), so it doesn't pick up callout styling. |
+| **Toggles and toggle headings** | Nested content is preserved, but the collapsible toggle wrapper is lost. |
+| **Synced blocks** | Written out as ordinary content wherever they appear; the link between copies is gone. |
+| **Web bookmarks and embeds** (Figma, video, PDF, etc.) | Converted to plain links. The rich preview card or inline embed is gone. Uploaded files download alongside the page. |
+| **Links between pages** | Notion percent-encodes every link target (every exported filename ends in ` <id>`). Fixable in bulk after import by decoding `%20` and trimming the trailing ` <id>`. |
+| **Pasted or inline images** | Some images export inline as base64 `data:` URIs instead of downloaded files. They don't render and add very large lines to the file. Downloaded `![alt](file.png)` images are unaffected. |
+| **Page icons and cover images** | Not exported. |
+| **Comments, page history, and backlinks** | Not included in the export. |
+
+## Clean up after import (optional)
+
+Most of the rough edges above are mechanical to fix, and the AI agent connected to your project can do it in bulk through OpenKnowledge's [MCP tools](/docs/reference/mcp). Paste any of these prompts to your agent:
+
+- **Decode internal links.** _"In every markdown file, decode `%20` and other percent-escapes in relative `.md` link targets so the links resolve."_ Do this first so the next step can rewrite links.
+- **Drop the Notion ID from filenames.** _"Rename every page to remove the trailing ` <32-character hex id>` from its filename, and verify the links that point to it."_
+- **Promote row properties to frontmatter.** _"On pages exported from databases, turn the `Key: Value` lines under the title into a YAML frontmatter block."_ They then show up in the [Properties panel](/docs/features/editor#properties).
+- **Convert callouts.** _"Replace each `<aside>…</aside>` block with an OpenKnowledge callout (`> [!note]`)."_
+- **Remove inline base64 images.** _"Find `[](data:image/...;base64,...)` blobs and remove them — they don't render and bloat the file."_
+
+## See also
+
+- [GitHub sync](/docs/features/github-sync): keep your project synced with your team through GitHub
+- [Quickstart](/docs/get-started/quickstart): the five-minute setup
+- [Core concepts](/docs/reference/core-concepts): links, backlinks, and the file-system-as-database model
+- [Assets and embeds](/docs/features/assets-and-embeds): how images and file references behave
+

docs/content/get-started/obsidian.mdx → docs/content/migrate/obsidian.mdx

@@ -1,25 +1,29 @@
 ---
-title: Using with Obsidian
+title: From Obsidian
 icon: custom/Obsidian
 description: How to open an existing Obsidian vault in OpenKnowledge, which markdown syntax carries over, and where the two differ.
 ---
 
-OpenKnowledge and Obsidian are both editors over a folder of plain markdown — [the files are the database](/docs/reference/core-concepts#the-file-system-is-the-database). So there is nothing to import or convert: point OpenKnowledge at your existing vault and your notes, links, tags, and frontmatter come across as they are.
+OpenKnowledge and Obsidian are both editors over a [folder of plain markdown](/docs/reference/core-concepts#the-file-system-is-the-database). This means that you can point OpenKnowledge at your existing vault and your notes, links, tags, and frontmatter work out of the box.
 
 <Callout type="info">
   OpenKnowledge works **directly on your markdown files** — it never moves, renames, or rewrites them just for opening a vault. It keeps its own state in a `.ok/` directory and ignores Obsidian's `.obsidian/` folder, so your Obsidian setup stays exactly where it is.
 </Callout>
 
 ## Open your vault
 
-### MacOS Desktop app
+### macOS Desktop app
 
-Open OpenKnowledge, choose **Open folder on disk**, and select your existing vault folder, then proceed through the **Setup** screen. OpenKnowledge uses the folder in place — it doesn't copy or move your notes. 
+Open OpenKnowledge, choose **Open folder on disk**, and select your existing vault folder, then proceed through the **Setup** screen. OpenKnowledge uses the folder in place — it doesn't copy or move your notes.
 
 ### Linux, Windows, Intel Mac
 
 Install the [ok CLI](/docs/reference/cli), `cd` into your vault, and run `ok init && ok start --open`.
 
+<Callout type="info">
+  Want to know exactly what these commands write to your machine — in your vault, your home directory, and your editors' configs? See [What OpenKnowledge writes to your system](/docs/reference/what-open-knowledge-writes).
+</Callout>
+
 ## What carries over
 
 Most of what you write in Obsidian renders and round-trips in OpenKnowledge unchanged. Existing syntax is **preserved byte-for-byte** when a file is saved, so opening a vault is non-destructive.
@@ -69,3 +73,4 @@ Getting an AI agent to work *well* inside an Obsidian vault usually means adding
 - [Timeline and recovery](/docs/features/timeline-and-recovery): version history and point-in-time rollback
 - [Ignore patterns](/docs/features/ignore-patterns): keep folders out of the editor, search, and agents
 - [Assets and embeds](/docs/features/assets-and-embeds): how images and file references behave
+- [GitHub sync](/docs/features/github-sync): keep your project synced with your team through GitHub

docs/content/reference/cli.mdx

@@ -38,6 +38,8 @@ Once you have initialized your project, launch the app in your browser:
 ok start --open
 ```
 
+For a complete list of every file OpenKnowledge creates or changes — during install, at runtime, and in the desktop app — see [What OpenKnowledge writes to your system](/docs/reference/what-open-knowledge-writes).
+
 ## Editing a single file
 
 If you don't have a project initialized, you can still open a file directly in the editor.