Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
OK: name per-host in-app browser tools in preview guidance (#1862)
tim-inkeep6b4cf6b65d80
diff --git a/.changeset/preview-host-browser-tool-names.md b/.changeset/preview-host-browser-tool-names.mdnew file mode 100644index 000000000..08a067727--- /dev/null+++ b/.changeset/preview-host-browser-tool-names.md@@ -0,0 +1,13 @@+---+"@inkeep/open-knowledge": patch+---++OK skill preview guidance is now framed around the three apps OK ships first-class preview support for, naming the exact in-app browser tool to drive in each so the agent opens the preview in the host's own surface instead of falling back to the system browser:++- **Claude Code Desktop** → `preview_start` / `preview_eval` (the preview pane).+- **Cursor** → its built-in Browser tool's `Navigate` action (`browser_navigate`, via Cursor's `cursor-ide-browser`). Notes that only the agent's own `Navigate` reaches the pane (a third-party MCP cannot push a URL in) and that a surfaced link follows Cursor's "Browser Tab" vs "Google Chrome" picker.+- **Codex desktop app** → the in-app `@Browser` plugin (drives via `tab.goto`).++The **Claude Code CLI** is now a clearly separate track: pure stdio, no browser — use `ok open <doc>` to deep-link into OK Desktop, never print/fake a browser. The Codex CLI, IDE extension, and Cloud live on this track too (web search only, no localhost browser). The underlying capability-not-host-name principle is retained so unknown hosts still route correctly.++The runtime "no browser attached" warning (`attach-preview-once`) now names the same per-host paths (`preview_start`, in-app browser `Navigate`/`@Browser`, CLI `ok open`) instead of only `preview_start`, so the in-band recovery signal matches the bundled skill.diff --git a/packages/server/assets/skills/project/SKILL.md b/packages/server/assets/skills/project/SKILL.mdindex 2bbca58c6..2150f6bee 100644--- a/packages/server/assets/skills/project/SKILL.md+++ b/packages/server/assets/skills/project/SKILL.md@@ -75,13 +75,17 @@ The user watches your edits land in a live browser preview. Open it once at sess**`previewUrl` is a route, not a URL to open.** Every read response (per-doc, on `exec` / `search` / `links` rows) and every write response carries a `previewUrl` — a route fragment like `/#/specs/foo/SPEC`, with **no scheme, host, or port**. It identifies *which doc* to preview, not a URL to hand a browser by itself. Never construct or guess preview URLs.-**Pick how to open the preview by tool capability — not by host name.** Look at the tools actually available to you this session. If a tool can navigate to a URL, it counts as an in-app browser — match on the capability, not on what your host is called.+**OK ships first-class preview support for three apps — Claude Code Desktop, Cursor, and the Codex desktop app — plus the Claude Code CLI on a separate track (below). Make the preview seamless in each.** Match on the tool you actually have (capability, not host name): if a tool can navigate to a URL, it counts as an in-app browser. The three apps map to:-- **You have `preview_*` tools** (e.g. `preview_start` + `preview_eval`) → **First open of the session:** to land directly on a doc, arm it first with `preview_url({ armPaneTarget: true, document })` (or `folder`), then `preview_start("open-knowledge-ui")` — `ok ui` redirects the base-open straight to the armed route, so the pane opens on the doc, not root. Plain `preview_start` (no arm) opens at root. **Moving between docs once the pane is open: do it in one `preview_eval` step — set `window.location.hash` to the target's route fragment from the response `previewUrl`, the part from `#` on (e.g. `window.location.hash = '#/specs/foo/SPEC'`).** That drives the SPA router directly. Arm + `preview_start` only redirects a *fresh* open; it can't move an already-open pane (`preview_start` reuses the live process without reloading), so use `preview_eval` there. Don't read or edit `.claude/launch.json` — host-managed; the OK lock-collision proxy handles the UI-already-running case. If `preview_start` fails, report it; don't "fix" `launch.json`.-- **No `preview_*` tool, but you have an in-app / built-in browser tool** — Codex's built-in browser, or any host tool that navigates to a URL (`browser`, `view_url`, `open_url`, `web.browse`, etc.) → call `preview_url` once for the **exact** target (`document` for a doc, `folder` for a folder) and navigate your **in-app browser** straight to the returned `url`. Open that deep URL directly — never the root then navigate. Omit both args only for the root.-- **Truly no browser-capable tool — if you have ANY tool that navigates to a URL, use the in-app branch above** (a pure stdio host with no URL-navigation tool at all, e.g. the Claude Code CLI) → for an "open `<doc>`/`<folder>`" request, run **`ok open <doc>`** (`--folder` for a folder) — opens the doc in OK Desktop via deep link (folders in the browser), with browser fallback; an action, not a URL to print. No `ok` on PATH or no shell → `preview_url`, then `open <url>` in the system browser as a last resort, and say so plainly. The system browser is the fallback, never the default.+- **Claude Code Desktop — you have `preview_*` tools** (e.g. `preview_start` + `preview_eval`) → **First open of the session:** to land directly on a doc, arm it first with `preview_url({ armPaneTarget: true, document })` (or `folder`), then `preview_start("open-knowledge-ui")` — `ok ui` redirects the base-open straight to the armed route, so the pane opens on the doc, not root. Plain `preview_start` (no arm) opens at root. **Moving between docs once the pane is open: do it in one `preview_eval` step — set `window.location.hash` to the target's route fragment from the response `previewUrl`, the part from `#` on (e.g. `window.location.hash = '#/specs/foo/SPEC'`).** That drives the SPA router directly. Arm + `preview_start` only redirects a *fresh* open; it can't move an already-open pane (`preview_start` reuses the live process without reloading), so use `preview_eval` there. Don't read or edit `.claude/launch.json` — host-managed; the OK lock-collision proxy handles the UI-already-running case. If `preview_start` fails, report it; don't "fix" `launch.json`.+- **Cursor / Codex desktop — no `preview_*` tool, but you have an in-app / built-in browser tool** → call `preview_url` once for the **exact** target (`document` for a doc, `folder` for a folder) and navigate your **in-app browser** straight to the returned `url`. Open that deep URL directly — never the root then navigate; omit both args only for the root. Drive the tool your host gives you:+ - **Cursor** → its built-in **Browser** tool, the **`Navigate`** action (`browser_navigate`, via Cursor's own `cursor-ide-browser`). Navigate it to the `url` yourself — don't print the URL or shell out to the system browser. (A *surfaced* link in Cursor follows its "Browser Tab" vs "Google Chrome" picker and may open the system browser; you calling `Navigate` avoids that. A third-party MCP like OK cannot push a URL into the pane — only the agent's own `Navigate` can.)+ - **Codex desktop app** → its in-app **Browser** plugin (`@Browser`); drive it to the `url` (Codex navigates via `tab.goto`).+ - **Any other host** with a URL-navigation tool (`browser`, `view_url`, `open_url`, `web.browse`, …) → navigate it to the `url`. **This is also the fallback when a named tool above isn't present under that exact name** (hosts rename tools): match on the capability, not the name. If no URL-navigation tool exists at all, drop to the Claude Code CLI track below.- **Honor `autoOpen`** (on `preview_url`, or on `warning` for write tools). If `false`, do not open or refresh any preview UI; surface the URL only if asked.+**Claude Code CLI — a separate track (no browser).** The CLI is pure stdio: don't open or fake a browser. For an "open `<doc>`/`<folder>`" request, run **`ok open <doc>`** (`--folder` for a folder) — it deep-links the doc into OK Desktop (folders open in the browser); an action you run, not a URL to print. Any other pure-stdio host with **no** URL-navigation tool is on this track too — but if you *do* have a tool that navigates to a URL, use the in-app branch above, not this track. The Codex **CLI**, **IDE extension**, and **Cloud** also live here (web search only, no localhost browser). No `ok` on PATH or no shell → `preview_url`, then `open <url>` in the system browser as a last resort, and say so plainly. The system browser is the fallback, never the default.+**Opening or reading a file IS a preview navigation.** On any "open `<file>`" / "read `<file>`" request, navigate the browser to that doc's `previewUrl` route from the tool response — not a separate fetch, not a fresh system-browser launch.**Four signals to check if the preview is already attached** (read these from each write response):diff --git a/packages/server/scripts/generate-instructions.test.ts b/packages/server/scripts/generate-instructions.test.tsindex 41881de4d..5739af12a 100644--- a/packages/server/scripts/generate-instructions.test.ts+++ b/packages/server/scripts/generate-instructions.test.ts@@ -123,7 +123,7 @@ describe('generateInstructions — byte budget', () => {test('stays within the structural ceiling (truncation / cache-cost guard)', () => {const skill = readFileSync(SKILL_PATH, 'utf8');const result = generateInstructions(skill);- expect(result.byteLength).toBeLessThan(12544);+ expect(result.byteLength).toBeLessThan(13776);});test('reports per-section byte lengths so maintainers can spot the heaviest', () => {diff --git a/packages/server/src/mcp/instructions.test.ts b/packages/server/src/mcp/instructions.test.tsindex 603523e36..cf265ee10 100644--- a/packages/server/src/mcp/instructions.test.ts+++ b/packages/server/src/mcp/instructions.test.ts@@ -83,5 +83,5 @@ test('buildInstructions exceeds the legacy 2 KB Claude Code cap (generator emitsconst text = buildInstructions(defaultContent());const bytes = Buffer.byteLength(text, 'utf8');expect(bytes).toBeGreaterThan(2048);- expect(bytes).toBeLessThan(12544);+ expect(bytes).toBeLessThan(13776);});diff --git a/packages/server/src/mcp/instructions.ts b/packages/server/src/mcp/instructions.tsindex 939d3f7bf..044d33f6f 100644--- a/packages/server/src/mcp/instructions.ts+++ b/packages/server/src/mcp/instructions.ts@@ -36,13 +36,17 @@ The user watches your edits land in a live browser preview. Open it once at sess**\`previewUrl\` is a route, not a URL to open.** Every read response (per-doc, on \`exec\` / \`search\` / \`links\` rows) and every write response carries a \`previewUrl\` — a route fragment like \`/#/specs/foo/SPEC\`, with **no scheme, host, or port**. It identifies *which doc* to preview, not a URL to hand a browser by itself. Never construct or guess preview URLs.-**Pick how to open the preview by tool capability — not by host name.** Look at the tools actually available to you this session. If a tool can navigate to a URL, it counts as an in-app browser — match on the capability, not on what your host is called.+**OK ships first-class preview support for three apps — Claude Code Desktop, Cursor, and the Codex desktop app — plus the Claude Code CLI on a separate track (below). Make the preview seamless in each.** Match on the tool you actually have (capability, not host name): if a tool can navigate to a URL, it counts as an in-app browser. The three apps map to:-- **You have \`preview_*\` tools** (e.g. \`preview_start\` + \`preview_eval\`) → **First open of the session:** to land directly on a doc, arm it first with \`preview_url({ armPaneTarget: true, document })\` (or \`folder\`), then \`preview_start("open-knowledge-ui")\` — \`ok ui\` redirects the base-open straight to the armed route, so the pane opens on the doc, not root. Plain \`preview_start\` (no arm) opens at root. **Moving between docs once the pane is open: do it in one \`preview_eval\` step — set \`window.location.hash\` to the target's route fragment from the response \`previewUrl\`, the part from \`#\` on (e.g. \`window.location.hash = '#/specs/foo/SPEC'\`).** That drives the SPA router directly. Arm + \`preview_start\` only redirects a *fresh* open; it can't move an already-open pane (\`preview_start\` reuses the live process without reloading), so use \`preview_eval\` there. Don't read or edit \`.claude/launch.json\` — host-managed; the OK lock-collision proxy handles the UI-already-running case. If \`preview_start\` fails, report it; don't "fix" \`launch.json\`.-- **No \`preview_*\` tool, but you have an in-app / built-in browser tool** — Codex's built-in browser, or any host tool that navigates to a URL (\`browser\`, \`view_url\`, \`open_url\`, \`web.browse\`, etc.) → call \`preview_url\` once for the **exact** target (\`document\` for a doc, \`folder\` for a folder) and navigate your **in-app browser** straight to the returned \`url\`. Open that deep URL directly — never the root then navigate. Omit both args only for the root.-- **Truly no browser-capable tool — if you have ANY tool that navigates to a URL, use the in-app branch above** (a pure stdio host with no URL-navigation tool at all, e.g. the Claude Code CLI) → for an "open \`<doc>\`/\`<folder>\`" request, run **\`ok open <doc>\`** (\`--folder\` for a folder) — opens the doc in OK Desktop via deep link (folders in the browser), with browser fallback; an action, not a URL to print. No \`ok\` on PATH or no shell → \`preview_url\`, then \`open <url>\` in the system browser as a last resort, and say so plainly. The system browser is the fallback, never the default.+- **Claude Code Desktop — you have \`preview_*\` tools** (e.g. \`preview_start\` + \`preview_eval\`) → **First open of the session:** to land directly on a doc, arm it first with \`preview_url({ armPaneTarget: true, document })\` (or \`folder\`), then \`preview_start("open-knowledge-ui")\` — \`ok ui\` redirects the base-open straight to the armed route, so the pane opens on the doc, not root. Plain \`preview_start\` (no arm) opens at root. **Moving between docs once the pane is open: do it in one \`preview_eval\` step — set \`window.location.hash\` to the target's route fragment from the response \`previewUrl\`, the part from \`#\` on (e.g. \`window.location.hash = '#/specs/foo/SPEC'\`).** That drives the SPA router directly. Arm + \`preview_start\` only redirects a *fresh* open; it can't move an already-open pane (\`preview_start\` reuses the live process without reloading), so use \`preview_eval\` there. Don't read or edit \`.claude/launch.json\` — host-managed; the OK lock-collision proxy handles the UI-already-running case. If \`preview_start\` fails, report it; don't "fix" \`launch.json\`.+- **Cursor / Codex desktop — no \`preview_*\` tool, but you have an in-app / built-in browser tool** → call \`preview_url\` once for the **exact** target (\`document\` for a doc, \`folder\` for a folder) and navigate your **in-app browser** straight to the returned \`url\`. Open that deep URL directly — never the root then navigate; omit both args only for the root. Drive the tool your host gives you:+ - **Cursor** → its built-in **Browser** tool, the **\`Navigate\`** action (\`browser_navigate\`, via Cursor's own \`cursor-ide-browser\`). Navigate it to the \`url\` yourself — don't print the URL or shell out to the system browser. (A *surfaced* link in Cursor follows its "Browser Tab" vs "Google Chrome" picker and may open the system browser; you calling \`Navigate\` avoids that. A third-party MCP like OK cannot push a URL into the pane — only the agent's own \`Navigate\` can.)+ - **Codex desktop app** → its in-app **Browser** plugin (\`@Browser\`); drive it to the \`url\` (Codex navigates via \`tab.goto\`).+ - **Any other host** with a URL-navigation tool (\`browser\`, \`view_url\`, \`open_url\`, \`web.browse\`, …) → navigate it to the \`url\`. **This is also the fallback when a named tool above isn't present under that exact name** (hosts rename tools): match on the capability, not the name. If no URL-navigation tool exists at all, drop to the Claude Code CLI track below.- **Honor \`autoOpen\`** (on \`preview_url\`, or on \`warning\` for write tools). If \`false\`, do not open or refresh any preview UI; surface the URL only if asked.+**Claude Code CLI — a separate track (no browser).** The CLI is pure stdio: don't open or fake a browser. For an "open \`<doc>\`/\`<folder>\`" request, run **\`ok open <doc>\`** (\`--folder\` for a folder) — it deep-links the doc into OK Desktop (folders open in the browser); an action you run, not a URL to print. Any other pure-stdio host with **no** URL-navigation tool is on this track too — but if you *do* have a tool that navigates to a URL, use the in-app branch above, not this track. The Codex **CLI**, **IDE extension**, and **Cloud** also live here (web search only, no localhost browser). No \`ok\` on PATH or no shell → \`preview_url\`, then \`open <url>\` in the system browser as a last resort, and say so plainly. The system browser is the fallback, never the default.+**Opening or reading a file IS a preview navigation.** On any "open \`<file>\`" / "read \`<file>\`" request, navigate the browser to that doc's \`previewUrl\` route from the tool response — not a separate fetch, not a fresh system-browser launch.**Four signals to check if the preview is already attached** (read these from each write response):diff --git a/packages/server/src/mcp/tools/preview-url.ts b/packages/server/src/mcp/tools/preview-url.tsindex 693440652..012918f1a 100644--- a/packages/server/src/mcp/tools/preview-url.ts+++ b/packages/server/src/mcp/tools/preview-url.ts@@ -45,7 +45,7 @@ type PreviewAttachWarning =const START_UI_MESSAGE ='No UI is running for this project. Start one to see the preview: `ok ui` (terminal), `preview_start("open-knowledge-ui")` (Claude Code Desktop), or open the project in OK Electron.';const ATTACH_PREVIEW_ONCE_MESSAGE =- 'No browser is attached to the preview. Open it with preview_start, or call preview_url for the URL.';+ "No browser is attached to the preview. Open it in your host's surface: `preview_start` (Claude Code Desktop pane), or `preview_url` then navigate your in-app browser to the url (Cursor's `Navigate` / Codex desktop `@Browser`); on the Claude Code CLI, `ok open <doc>`.";export function buildPreviewAttachWarning(preview: { url: string } | null,