Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
feat: agent ability to focus a page in the editor (PRD-7183) (#2269)
tim-inkeep8996d69eaf1d
diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.tsindex 45bb0a102..ec48e1e12 100644--- a/packages/cli/src/cli.ts+++ b/packages/cli/src/cli.ts@@ -9,7 +9,6 @@ if (process.argv.includes('--no-color')) {}import { spawn } from 'node:child_process';-import { existsSync } from 'node:fs';import { resolve } from 'node:path';import type { Config } from '@inkeep/open-knowledge-server';import { Command } from 'commander';@@ -35,7 +34,7 @@ import { shareCommand } from './commands/share/index.ts';import { sharingCommand } from './commands/sharing/index.ts';import {decideSingleFileTarget,- hasMarkdownExtension,+ isFileishTarget,scanRootArgv,} from './commands/single-file-dispatch.ts';import { createRealSingleFileOpenDeps, runSingleFileOpen } from './commands/single-file-open.ts';@@ -186,7 +185,7 @@ Examples:const knownSubcommands = new Set(program.commands.map((c) => c.name()));const target = decideSingleFileTarget(scanned.operands, {knownSubcommands,- isFileish: (t) => hasMarkdownExtension(t) || existsSync(resolve(baseDir, t)),+ isFileish: (t) => isFileishTarget(resolve(baseDir, t), t),});if (target !== null) {const code = await runSingleFileOpen(diff --git a/packages/cli/src/commands/open.test.ts b/packages/cli/src/commands/open.test.tsindex 4c7991fdf..1600f9be7 100644--- a/packages/cli/src/commands/open.test.ts+++ b/packages/cli/src/commands/open.test.ts@@ -13,6 +13,7 @@ function makeDeps(overrides: Partial<OpenDeps> = {}): {const deps: OpenDeps = {detectBundlePath: () => null,resolveBaseUrl: () => null,+ classifyName: () => 'doc',openTarget: (t) => opened.push(t),log: (m) => logs.push(m),error: (m) => errors.push(m),@@ -49,26 +50,95 @@ describe('runOpen', () => {expect(errors).toHaveLength(1);});- test('folder takes the browser route even when a desktop bundle is present', () => {+ test('folder with a desktop bundle → folder= deep link, exit 0', () => {const { deps, opened } = makeDeps({detectBundlePath: () => '/Applications/OpenKnowledge.app',+ });+ const code = runOpen('specs/foo/', { project: '/p' }, deps);+ expect(code).toBe(0);+ expect(opened).toEqual(['openknowledge://open?project=%2Fp&folder=specs%2Ffoo']);+ });++ test('folder, no bundle but UI running → browser folder route, exit 0', () => {+ const { deps, opened } = makeDeps({+ detectBundlePath: () => null,resolveBaseUrl: () => 'http://localhost:5173',});- const code = runOpen('specs/foo', { folder: true, project: '/p' }, deps);+ const code = runOpen('specs/foo/', { project: '/p' }, deps);expect(code).toBe(0);expect(opened).toEqual(['http://localhost:5173/#/specs/foo/']);});- test('trailing slash infers folder intent without --folder', () => {- const { deps, opened } = makeDeps({ resolveBaseUrl: () => 'http://localhost:5173' });+ test('auto-detects a folder from disk (no trailing slash needed)', () => {+ const { deps, opened } = makeDeps({+ detectBundlePath: () => '/Applications/OpenKnowledge.app',+ classifyName: () => 'folder',+ });+ const code = runOpen('specs/foo', { project: '/p' }, deps);+ expect(code).toBe(0);+ expect(opened).toEqual(['openknowledge://open?project=%2Fp&folder=specs%2Ffoo']);+ });++ test('trailing slash infers folder intent even when disk classify says doc', () => {+ const { deps, opened } = makeDeps({+ resolveBaseUrl: () => 'http://localhost:5173',+ classifyName: () => 'doc',+ });const code = runOpen('specs/foo/', {}, deps);expect(code).toBe(0);expect(opened).toEqual(['http://localhost:5173/#/specs/foo/']);});+ test('skill with a desktop bundle → rides doc=__skill__/<scope>/<name> deep link', () => {+ const { deps, opened } = makeDeps({+ detectBundlePath: () => '/Applications/OpenKnowledge.app',+ });+ const code = runOpen('trip-log', { skill: true, project: '/p' }, deps);+ expect(code).toBe(0);+ expect(opened).toEqual([+ 'openknowledge://open?project=%2Fp&doc=__skill__%2Fproject%2Ftrip-log',+ ]);+ });++ test('skill --scope global, no bundle but UI running → browser skill route', () => {+ const { deps, opened } = makeDeps({ resolveBaseUrl: () => 'http://localhost:5173' });+ const code = runOpen('trip-log', { skill: true, scope: 'global', project: '/p' }, deps);+ expect(code).toBe(0);+ expect(opened).toEqual(['http://localhost:5173/#/__skill__/global/trip-log']);+ });++ test('skill with an invalid --scope → error, exit 1', () => {+ const { deps, errors } = makeDeps({+ detectBundlePath: () => '/Applications/OpenKnowledge.app',+ });+ const code = runOpen('trip-log', { skill: true, scope: 'nonsense', project: '/p' }, deps);+ expect(code).toBe(1);+ expect(errors).toHaveLength(1);+ });++ test('skill, neither desktop nor UI → error, exit 1, nothing opened', () => {+ const { deps, opened, errors } = makeDeps();+ const code = runOpen('trip-log', { skill: true, project: '/p' }, deps);+ expect(code).toBe(1);+ expect(opened).toEqual([]);+ expect(errors).toHaveLength(1);+ });++ test('skill name with a traversal/unsafe segment → error before any open', () => {+ const { deps, opened, errors } = makeDeps({+ detectBundlePath: () => '/Applications/OpenKnowledge.app',+ });+ for (const bad of ['../../etc', '/abs', 'a\\b']) {+ const code = runOpen(bad, { skill: true, project: '/p' }, deps);+ expect(code).toBe(1);+ }+ expect(opened).toEqual([]);+ expect(errors.length).toBeGreaterThanOrEqual(3);+ });+test('folder with no UI running → error, exit 1', () => {const { deps, errors } = makeDeps({ resolveBaseUrl: () => null });- const code = runOpen('specs/foo', { folder: true, project: '/p' }, deps);+ const code = runOpen('specs/foo/', { project: '/p' }, deps);expect(code).toBe(1);expect(errors).toHaveLength(1);});@@ -97,7 +167,7 @@ describe('runOpen', () => {test('rejects unsafe folder names too', () => {const { deps, opened, errors } = makeDeps({ resolveBaseUrl: () => 'http://localhost:5173' });- const code = runOpen('specs/..', { folder: true, project: '/p' }, deps);+ const code = runOpen('specs/..', { project: '/p' }, deps);expect(code).toBe(1);expect(opened).toEqual([]);expect(errors).toHaveLength(1);diff --git a/packages/cli/src/commands/open.ts b/packages/cli/src/commands/open.tsindex b1945382a..0eb656552 100644--- a/packages/cli/src/commands/open.ts+++ b/packages/cli/src/commands/open.ts@@ -1,8 +1,11 @@import { spawn as nodeSpawn } from 'node:child_process';-import { resolve } from 'node:path';+import { statSync } from 'node:fs';+import { join, resolve } from 'node:path';+import { MANAGED_ARTIFACT_SCOPES, type SkillScope } from '@inkeep/open-knowledge-core';import {encodeDocName,encodeFolderRoute,+ encodeSkillRoute,resolveLockDir,resolveUiInfo,} from '@inkeep/open-knowledge-server';@@ -10,13 +13,15 @@ import { Command } from 'commander';import { createRealDetectDeps, type DetectResult, detectDesktop } from './desktop-dispatch.ts';export interface OpenOptions {- folder?: boolean;+ skill?: boolean;+ scope?: string;project?: string;}export interface OpenDeps {detectBundlePath: () => string | null;resolveBaseUrl: (projectDir: string) => string | null;+ classifyName: (projectDir: string, name: string) => 'doc' | 'folder';openTarget: (target: string) => void;log: (message: string) => void;error: (message: string) => void;@@ -34,6 +39,20 @@ export function createRealOpenDeps(return {detectBundlePath: () => detect().bundlePath ?? null,resolveBaseUrl: (projectDir) => resolveUiInfo({ lockDir: resolveLockDir(projectDir) }).baseUrl,+ classifyName: (projectDir, name) => {+ const abs = join(projectDir, name);+ try {+ return statSync(abs).isDirectory() ? 'folder' : 'doc';+ } catch (err) {+ const code = (err as { code?: string } | null)?.code;+ if (code !== 'ENOENT' && code !== 'ENOTDIR') {+ process.stderr.write(+ `[ok open] statSync failed for ${abs} (${code ?? 'unknown'}); treating as a doc\n`,+ );+ }+ return 'doc';+ }+ },openTarget: (target) => {const child = nodeSpawn('open', [target], {detached: true,@@ -47,51 +66,96 @@ export function createRealOpenDeps(};}+function isUnsafeName(name: string): boolean {+ return name.startsWith('/') || name.includes('\\') || name.split('/').includes('..');+}++function noTargetError(deps: OpenDeps): number {+ deps.error(+ 'No OpenKnowledge desktop app found and no UI is running. ' ++ 'Install OK Desktop, or start a UI with `ok ui`, then retry.',+ );+ return 1;+}++function openDesktopDeepLink(+ projectDir: string,+ param: 'doc' | 'folder',+ target: string,+ deps: OpenDeps,+): void {+ const deepLink = `openknowledge://open?project=${encodeURIComponent(+ projectDir,+ )}&${param}=${encodeURIComponent(target)}`;+ deps.openTarget(deepLink);+}+export function runOpen(name: string, options: OpenOptions, deps: OpenDeps): number {const projectDir = resolve(options.project ?? process.cwd());- const isFolder = options.folder === true || /\/+$/.test(name);const cleanName = name.replace(/\/+$/, '');if (!cleanName) {- deps.error('Nothing to open: pass a doc path (e.g. `ok open specs/foo/SPEC`).');+ deps.error(+ 'Nothing to open: pass a doc, folder, or skill name (e.g. `ok open specs/foo/SPEC`).',+ );return 1;}- if (- cleanName.startsWith('/') ||- cleanName.includes('\\') ||- cleanName.split('/').includes('..')- ) {+ if (isUnsafeName(cleanName)) {deps.error(`Invalid name "${cleanName}": must be a relative path with no '..' segments, leading '/', or backslashes.`,);return 1;}- if (isFolder) {- const baseUrl = deps.resolveBaseUrl(projectDir);- if (!baseUrl) {+ if (options.skill === true) {+ const scope = (options.scope ?? 'project') as SkillScope;+ if (!(MANAGED_ARTIFACT_SCOPES as readonly string[]).includes(scope)) {deps.error(- `No OpenKnowledge UI is running for ${projectDir}. Folder preview requires a running UI — start one with \`ok ui\`, then retry.`,+ `Invalid --scope "${options.scope}": expected one of ${MANAGED_ARTIFACT_SCOPES.join(', ')}.`,);return 1;}- const url = `${baseUrl}/#/${encodeFolderRoute(cleanName)}`;- deps.openTarget(url);- deps.log(`Opening folder ${cleanName} in your browser: ${url}`);- return 0;+ const bundlePath = deps.detectBundlePath();+ if (bundlePath) {+ openDesktopDeepLink(projectDir, 'doc', `__skill__/${scope}/${cleanName}`, deps);+ deps.log(`Opening skill ${cleanName} (${scope}) in the OpenKnowledge desktop app.`);+ return 0;+ }+ const baseUrl = deps.resolveBaseUrl(projectDir);+ if (baseUrl) {+ const url = `${baseUrl}/#/${encodeSkillRoute(scope, cleanName)}`;+ deps.openTarget(url);+ deps.log(`Opening skill ${cleanName} (${scope}) in your browser: ${url}`);+ return 0;+ }+ return noTargetError(deps);}+ const isFolder = /\/+$/.test(name) || deps.classifyName(projectDir, cleanName) === 'folder';+const bundlePath = deps.detectBundlePath();+ if (isFolder) {+ if (bundlePath) {+ openDesktopDeepLink(projectDir, 'folder', cleanName, deps);+ deps.log(`Opening folder ${cleanName} in the OpenKnowledge desktop app.`);+ return 0;+ }+ const baseUrl = deps.resolveBaseUrl(projectDir);+ if (baseUrl) {+ const url = `${baseUrl}/#/${encodeFolderRoute(cleanName)}`;+ deps.openTarget(url);+ deps.log(`Opening folder ${cleanName} in your browser: ${url}`);+ return 0;+ }+ return noTargetError(deps);+ }+if (bundlePath) {- const deepLink = `openknowledge://open?project=${encodeURIComponent(- projectDir,- )}&doc=${encodeURIComponent(cleanName)}`;- deps.openTarget(deepLink);+ openDesktopDeepLink(projectDir, 'doc', cleanName, deps);deps.log(`Opening ${cleanName} in the OpenKnowledge desktop app.`);return 0;}-const baseUrl = deps.resolveBaseUrl(projectDir);if (baseUrl) {const url = `${baseUrl}/#/${encodeDocName(cleanName)}`;@@ -99,22 +163,25 @@ export function runOpen(name: string, options: OpenOptions, deps: OpenDeps): numdeps.log(`Opening ${cleanName} in your browser: ${url}`);return 0;}-- deps.error(- 'No OpenKnowledge desktop app found and no UI is running. ' +- 'Install OK Desktop, or start a UI with `ok ui`, then retry.',- );- return 1;+ return noTargetError(deps);}export function openCommand(): Command {return new Command('open')- .description('Open a doc in the OK Desktop app (folders open in the browser)')+ .description(+ 'Open a doc, folder, or skill in the OK Desktop app (falls back to the browser UI). ' ++ 'Docs and folders are auto-detected — no flag needed.',+ ).argument(- '<doc>',- 'Extension-less doc path (e.g. specs/foo/SPEC), or a folder path with --folder',+ '<name>',+ 'Doc path (specs/foo/SPEC), folder path (specs/foo or specs/foo/), or a skill name with --skill',+ )+ .option('--skill', 'Open <name> as a skill in the skill editor')+ .option(+ '--scope <scope>',+ `Skill scope when --skill is set: ${MANAGED_ARTIFACT_SCOPES.join(' | ')}`,+ 'project',)- .option('--folder', 'Treat <doc> as a folder and open the folder route in the browser').option('--project <dir>', 'Project root (defaults to the current directory)').action((name: string, options: OpenOptions) => {process.exitCode = runOpen(name, options, createRealOpenDeps());diff --git a/packages/cli/src/commands/single-file-dispatch.test.ts b/packages/cli/src/commands/single-file-dispatch.test.tsindex 45e3e05a4..b8995be91 100644--- a/packages/cli/src/commands/single-file-dispatch.test.ts+++ b/packages/cli/src/commands/single-file-dispatch.test.ts@@ -1,7 +1,11 @@-import { describe, expect, test } from 'bun:test';+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';import {decideSingleFileTarget,hasMarkdownExtension,+ isFileishTarget,scanRootArgv,} from './single-file-dispatch.ts';@@ -93,3 +97,31 @@ describe('hasMarkdownExtension', () => {expect(hasMarkdownExtension('a.md.txt')).toBe(false);});});++describe('isFileishTarget (fs-backed predicate)', () => {+ let dir: string;+ beforeAll(() => {+ dir = mkdtempSync(join(tmpdir(), 'ok-fileish-'));+ writeFileSync(join(dir, 'note.md'), '# note');+ writeFileSync(join(dir, 'data.json'), '{}');+ mkdirSync(join(dir, 'a-folder'));+ });+ afterAll(() => rmSync(dir, { recursive: true, force: true }));++ test('a markdown-extension token is fileish (even if it does not exist)', () => {+ expect(isFileishTarget(join(dir, 'missing.md'), 'missing.md')).toBe(true);+ });++ test('an existing regular file is fileish', () => {+ expect(isFileishTarget(join(dir, 'data.json'), 'data.json')).toBe(true);+ expect(isFileishTarget(join(dir, 'note.md'), 'note.md')).toBe(true);+ });++ test('an existing DIRECTORY is NOT fileish — so `ok open <folder>` falls through to the open command', () => {+ expect(isFileishTarget(join(dir, 'a-folder'), 'a-folder')).toBe(false);+ });++ test('a non-existent non-markdown token is not fileish', () => {+ expect(isFileishTarget(join(dir, 'nope'), 'nope')).toBe(false);+ });+});diff --git a/packages/cli/src/commands/single-file-dispatch.ts b/packages/cli/src/commands/single-file-dispatch.tsindex 084db8771..16bbf8f2e 100644--- a/packages/cli/src/commands/single-file-dispatch.ts+++ b/packages/cli/src/commands/single-file-dispatch.ts@@ -1,3 +1,5 @@+import { statSync } from 'node:fs';+const VALUE_TAKING_GLOBAL_FLAGS = new Set(['--cwd', '--log-level']);export interface ScannedRootArgv {@@ -61,7 +63,22 @@ export function decideSingleFileTarget(}/** Markdown-extension test mirroring `SUPPORTED_DOC_EXTENSIONS` — the cheap half- * of the fileish predicate (the other half is an existing-file `existsSync`). */+ * of the fileish predicate (the other half is an existing-regular-file stat). */export function hasMarkdownExtension(token: string): boolean {return /\.(md|mdx)$/i.test(token);}++export function isFileishTarget(absPath: string, token: string): boolean {+ if (hasMarkdownExtension(token)) return true;+ try {+ return statSync(absPath).isFile();+ } catch (err) {+ const code = (err as { code?: string } | null)?.code;+ if (code !== 'ENOENT' && code !== 'ENOTDIR') {+ process.stderr.write(+ `[ok] statSync failed for ${absPath} (${code ?? 'unknown'}); treating as non-fileish\n`,+ );+ }+ return false;+ }+}diff --git a/packages/cli/src/mcp/server.ts b/packages/cli/src/mcp/server.tsindex 52fdde026..706849c55 100644--- a/packages/cli/src/mcp/server.ts+++ b/packages/cli/src/mcp/server.ts@@ -258,6 +258,7 @@ export async function startGlobalMcpServer(resolveCwd,config: resolveConfigForCwd,identityRef,+ isDesktopTerminal: process.env.OK_DESKTOP_TERMINAL === '1',});const transport = new StdioServerTransport();diff --git a/packages/desktop/src/main/index.ts b/packages/desktop/src/main/index.tsindex ee53a24ba..db2ad3b67 100644--- a/packages/desktop/src/main/index.ts+++ b/packages/desktop/src/main/index.ts@@ -554,6 +554,9 @@ function ensureWindowManager() {);return win as unknown as BrowserWindowLike;},+ activateApp: () => {+ if (process.platform === 'darwin') app.focus({ steal: true });+ },forkUtility: (entry, args, opts) => {const child = utilityProcess.fork(entry, args, {...opts,diff --git a/packages/desktop/src/main/url-scheme.test.ts b/packages/desktop/src/main/url-scheme.test.tsindex 32b6d4566..a3accbbb5 100644--- a/packages/desktop/src/main/url-scheme.test.ts+++ b/packages/desktop/src/main/url-scheme.test.ts@@ -8,6 +8,7 @@ describe('parseOpenKnowledgeUrl — valid inputs', () => {expect(result).toEqual({host: 'open',project: '/abs/path',+ kind: 'doc',doc: 'foo.md',});});@@ -19,10 +20,33 @@ describe('parseOpenKnowledgeUrl — valid inputs', () => {expect(result).toEqual({host: 'open',project: '/abs/my path',+ kind: 'doc',doc: 'foo bar.md',});});+ test('parses a folder= deep link with kind folder', () => {+ expect(parseOpenKnowledgeUrl('openknowledge://open?project=/abs&folder=specs%2Ffoo')).toEqual({+ host: 'open',+ project: '/abs',+ kind: 'folder',+ doc: 'specs/foo',+ });+ });++ test('rejects when BOTH doc and folder are present (ambiguous)', () => {+ expect(parseOpenKnowledgeUrl('openknowledge://open?project=/abs&doc=a&folder=b')).toBeNull();+ });++ test('rejects when NEITHER doc nor folder is present', () => {+ expect(parseOpenKnowledgeUrl('openknowledge://open?project=/abs')).toBeNull();+ });++ test('applies the same traversal defense to folder= as doc=', () => {+ expect(parseOpenKnowledgeUrl('openknowledge://open?project=/abs&folder=a%2F..%2Fb')).toBeNull();+ expect(parseOpenKnowledgeUrl('openknowledge://open?project=/abs&folder=%2Fabs')).toBeNull();+ });+test('accepts flat doc-name', () => {expect(parseOpenKnowledgeUrl('openknowledge://open?project=/abs&doc=a_b-c.md')).toMatchObject({doc: 'a_b-c.md',diff --git a/packages/desktop/src/main/url-scheme.ts b/packages/desktop/src/main/url-scheme.tsindex 8a2c842ba..178ae3974 100644--- a/packages/desktop/src/main/url-scheme.ts+++ b/packages/desktop/src/main/url-scheme.ts@@ -20,6 +20,7 @@ function shareTargetPath(target: ShareTarget): string {interface ParsedOpenKnowledgeUrl {readonly host: 'open';readonly project: string;+ readonly kind: 'doc' | 'folder';readonly doc: string;}@@ -177,13 +178,17 @@ export function parseOpenKnowledgeUrl(input: string): ParsedOpenKnowledgeUrl | nconst rawProject = parsed.searchParams.get('project');const rawDoc = parsed.searchParams.get('doc');- if (!rawProject || !rawDoc) return null;+ const rawFolder = parsed.searchParams.get('folder');+ if (!rawProject) return null;+ if ((rawDoc == null) === (rawFolder == null)) return null;+ const kind: 'doc' | 'folder' = rawDoc != null ? 'doc' : 'folder';+ const rawTarget = (rawDoc ?? rawFolder) as string;let project: string;let doc: string;try {project = decodeURIComponent(rawProject);- doc = decodeURIComponent(rawDoc);+ doc = decodeURIComponent(rawTarget);} catch {return null;}@@ -202,6 +207,7 @@ export function parseOpenKnowledgeUrl(input: string): ParsedOpenKnowledgeUrl | nreturn {host: 'open',project: resolve(project),+ kind,doc,};}@@ -649,11 +655,13 @@ export function registerProtocolHandler(deps: ProtocolHandlerDeps): ProtocolHand}const existing = deps.focusWindowForProject(parsed.project);if (existing) {- deps.sendDeepLink(existing, { doc: parsed.doc, kind: 'doc' });+ deps.sendDeepLink(existing, { doc: parsed.doc, kind: parsed.kind });return;}void deps- .openProject(parsed.project, { pendingDeepLinkTarget: { kind: 'doc', path: parsed.doc } })+ .openProject(parsed.project, {+ pendingDeepLinkTarget: { kind: parsed.kind, path: parsed.doc },+ }).catch((err) => {deps.log?.warn({ err: (err as Error).message, project: parsed.project },diff --git a/packages/desktop/src/main/window-manager.ts b/packages/desktop/src/main/window-manager.tsindex b735ea1ca..994e6166a 100644--- a/packages/desktop/src/main/window-manager.ts+++ b/packages/desktop/src/main/window-manager.ts@@ -41,6 +41,8 @@ export interface BrowserWindowLike {isMinimized?(): boolean;isDestroyed?(): boolean;isVisible?(): boolean;+ moveTop?(): void;+ isFocused?(): boolean;close?(): void;destroy?(): void;on(event: 'closed', cb: () => void): void;@@ -145,6 +147,7 @@ export interface WindowManagerDeps {showGate: ShowGateRegistry;runClean?(opts: { lockDir: string }): Promise<void>;realpathSync?(p: string): string;+ activateApp?(): void;readServerLock?(lockDir: string): ServerLockMetadataLike | null;isProcessAlive?(pid: number): boolean;hostname?(): string;@@ -232,11 +235,17 @@ export class WindowManager {focusWindowForProject(projectPath: string): BrowserWindowLike | null {const ctx = this.windowsByPath.get(this.canonicalizeKey(projectPath));if (!ctx) return null;- const win = ctx.window;+ this.bringToFront(ctx.window);+ return ctx.window;+ }++ private bringToFront(win: BrowserWindowLike): void {if (win.isMinimized?.()) win.restore?.();win.show?.();+ const alreadyFrontmost = win.isFocused?.() === true;+ win.moveTop?.();win.focus();- return win;+ if (!alreadyFrontmost) this.deps.activateApp?.();}getContextForBrowserWindow(win: BrowserWindowLike): ProjectContext | undefined {@@ -463,7 +472,7 @@ export class WindowManager {const existing = this.windowsByPath.get(canonicalKey);if (existing) {if (existing.window.isDestroyed?.() !== true) {- existing.window.focus();+ this.bringToFront(existing.window);return existing;}this.deps.log?.warn(@@ -786,7 +795,7 @@ export class WindowManager {const existing = this.windowsByPath.get(canonicalKey);if (existing) {if (existing.window.isDestroyed?.() !== true) {- existing.window.focus();+ this.bringToFront(existing.window);return existing;}this.deps.log?.warn(@@ -800,7 +809,7 @@ export class WindowManager {if (inFlight) {const ctx = await inFlight;if (ctx.window.isDestroyed?.() !== true) {- ctx.window.focus();+ this.bringToFront(ctx.window);return ctx;}return this.createEphemeralWindow(opts);diff --git a/packages/desktop/src/utility/pty-host.ts b/packages/desktop/src/utility/pty-host.tsindex 4a9d5303c..6b38bacd3 100644--- a/packages/desktop/src/utility/pty-host.ts+++ b/packages/desktop/src/utility/pty-host.ts@@ -142,6 +142,7 @@ export function buildShellEnv(if (stripped.has(key)) continue;out[key] = value;}+ out.OK_DESKTOP_TERMINAL = '1';return out;}diff --git a/packages/desktop/tests/main/window-manager.test.ts b/packages/desktop/tests/main/window-manager.test.tsindex 4a0beb913..c05dca32a 100644--- a/packages/desktop/tests/main/window-manager.test.ts+++ b/packages/desktop/tests/main/window-manager.test.ts@@ -32,7 +32,7 @@ function makeUtility(pid: number): MockUtility {};}-function makeWindow(opts?: { minimized?: boolean }): BrowserWindowLike & {+function makeWindow(opts?: { minimized?: boolean; focused?: boolean }): BrowserWindowLike & {fireClose: () => void;fireDomReady: () => void;fireDidFinishLoad: () => void;@@ -56,6 +56,8 @@ function makeWindow(opts?: { minimized?: boolean }): BrowserWindowLike & {minimized = false;}),isMinimized: mock(() => minimized),+ moveTop: mock(() => {}),+ isFocused: mock(() => opts?.focused ?? false),isDestroyed: mock(() => destroyed),isVisible: mock(() => visible),on: mock((_event: 'closed', cb: () => void) => {@@ -101,6 +103,7 @@ interface TestEnv {forkUtilityArgs: string[][];timers: Array<{ cb: () => void; ms: number }>;killProbe: ReturnType<typeof mock>;+ activateApp: ReturnType<typeof mock>;showGateRegistrations: ShowGateRegistration[];deps: WindowManagerDeps;}@@ -112,6 +115,7 @@ function buildEnv(): TestEnv {const forkUtilityArgs: string[][] = [];const timers: Array<{ cb: () => void; ms: number }> = [];const killProbe = mock(() => {});+ const activateApp = mock(() => {});const showGateRegistrations: ShowGateRegistration[] = [];const showGate: ShowGateRegistry = {register: (window, opts) => {@@ -135,6 +139,7 @@ function buildEnv(): TestEnv {forkUtilityArgs,timers,killProbe,+ activateApp,showGateRegistrations,deps: {createWindow: (opts) => {@@ -157,6 +162,7 @@ function buildEnv(): TestEnv {return null;},killProbe,+ activateApp,showGate,},};@@ -1417,6 +1423,36 @@ describe('WindowManager.focusWindowForProject (M4 URL-scheme warm-start)', () =>expect(w.focus).toHaveBeenCalled();});+ test('brings a backgrounded window to the front: show + moveTop + focus + app steal', async () => {+ const wm = new WindowManager(env.deps);+ const p = wm.createProjectWindow({ projectPath: '/tmp/bg-proj' });+ env.utilities[0]?.fire({ type: 'ready', port: 51210, apiOrigin: 'http://localhost:51210' });+ const ctx = await p;++ wm.focusWindowForProject('/tmp/bg-proj');+ expect(ctx.window.show).toHaveBeenCalled();+ expect(ctx.window.moveTop).toHaveBeenCalled();+ expect(ctx.window.focus).toHaveBeenCalled();+ expect(env.activateApp).toHaveBeenCalled();+ });++ test('skips the app-level focus steal when the window is already frontmost', async () => {+ const w = makeWindow({ focused: true });+ env.deps.createWindow = () => {+ env.createWindowOpts.push({ additionalArguments: [], title: '' });+ env.windows.push(w);+ return w;+ };+ const wm = new WindowManager(env.deps);+ const p = wm.createProjectWindow({ projectPath: '/tmp/frontmost-proj' });+ env.utilities[0]?.fire({ type: 'ready', port: 51211, apiOrigin: 'http://localhost:51211' });+ await p;++ wm.focusWindowForProject('/tmp/frontmost-proj');+ expect(w.focus).toHaveBeenCalled();+ expect(env.activateApp).not.toHaveBeenCalled();+ });+test('canonicalizes project path before lookup (resolve equivalence)', async () => {const wm = new WindowManager(env.deps);const p = wm.createProjectWindow({ projectPath: '/tmp/canon' });diff --git a/packages/desktop/tests/utility/pty-host.test.ts b/packages/desktop/tests/utility/pty-host.test.tsindex 7fbcad66e..35919bb0b 100644--- a/packages/desktop/tests/utility/pty-host.test.ts+++ b/packages/desktop/tests/utility/pty-host.test.ts@@ -161,6 +161,13 @@ describe('setupPtyHost — create', () => {expect(env.OK_LOCK_KIND).toBeUndefined();expect(env.PATH).toBe('/usr/bin');});++ test('marks the shell as the OK Desktop terminal (OK_DESKTOP_TERMINAL=1)', () => {+ const h = makeHarness({ env: { SHELL: '/bin/zsh', OK_DESKTOP_TERMINAL: '' } });+ h.fire(CREATE());+ const env = h.spawnCalls[0]?.options.env ?? {};+ expect(env.OK_DESKTOP_TERMINAL).toBe('1');+ });});describe('setupPtyHost — streaming', () => {@@ -498,7 +505,7 @@ describe('setupPtyHost — incoming message validation (asIncomingMessage guard)});describe('buildShellEnv', () => {- test('strips markers, drops undefined, preserves the rest', () => {+ test('strips markers, drops undefined, preserves the rest, marks the desktop terminal', () => {const env = buildShellEnv({PATH: '/usr/bin',HOME: '/Users/x',@@ -506,7 +513,7 @@ describe('buildShellEnv', () => {OK_LOCK_KIND: 'interactive',MAYBE: undefined,});- expect(env).toEqual({ PATH: '/usr/bin', HOME: '/Users/x' });+ expect(env).toEqual({ PATH: '/usr/bin', HOME: '/Users/x', OK_DESKTOP_TERMINAL: '1' });});});diff --git a/packages/server/assets/skills/project/SKILL.md b/packages/server/assets/skills/project/SKILL.mdindex d0655c1a5..c06ada956 100644--- a/packages/server/assets/skills/project/SKILL.md+++ b/packages/server/assets/skills/project/SKILL.md@@ -19,7 +19,7 @@ OpenKnowledge (OK) is a markdown-CRDT collaboration platform exposed via MCP. Th1. **Reads:** `exec("cat …")` for one doc, `exec("ls -A …")` for a directory (folder defaults + template menu), `exec("grep …")` for literal, `search` for ranked retrieval. Native `Read` / `Grep` only on source code (`.ts` / `.py` / …), never on in-scope `.md` / `.mdx`.2. **Writes:** `write({ document: { path, content } })` for a new or full-replace doc; `edit({ document: { path, find, replace } })` for a body find/replace; `edit({ document: { path, frontmatter } })` for a frontmatter merge-patch (`null` deletes a key). `delete({ document })` removes, `move({ from, to })` moves/renames. Body find/replace is body-only. Pass a one-line `summary` (≤80 chars, user-facing outcome) on every content write.-3. **Preview:** every read/write response carries a route-only `previewUrl` (`/#/<doc>`, no host:port). Open the browser once at session start. Don't `preview_screenshot` to confirm edits — the tool response is the confirmation. Full multi-host contract: `references/preview.md`.+3. **Preview / open a doc — determine your ONE surface FIRST (once per session).** Before opening anything, pick where to focus, stop at first match: **`OK_DESKTOP_TERMINAL` set** (check your env — `echo "$OK_DESKTOP_TERMINAL"`) → OK Desktop's own terminal → `ok open <name>` (switches this window) · have `preview_*` → Claude Code Desktop pane · have a URL-navigation/browser tool → Cursor/Codex → `preview_url` then navigate it · else plain CLI → `ok open <name>`. `ok open <name>` opens a **doc or folder** (auto-detected — no `--folder`); add `--skill <name>` for a skill. The `previewUrl` field is a route id, **not** your open mechanism — don't hand it to a browser just because you saw it. Don't `preview_screenshot` to confirm edits. Full Step-0 procedure + per-surface how-to: `references/preview.md`.4. **Workflow guides:** `workflow({ kind: 'ingest' | 'research' | 'consolidate' | 'discover' })` returns a procedural guide, not data. Use it when the work fits the layer.5. **Direct questions:** a plain business question ("which customers…", "what did we decide about…") routes to `search` / `exec` + a cited chat answer — no "research" keyword needed. Persist only when durable + multi-doc + not already covered, and *offer* first. See `references/corpus-qa.md`.6. **Authoring or improving a skill** ("write/make a skill", "improve this skill", "turn this into a skill"): STOP and invoke the **`open-knowledge-write-skill`** skill — it owns scope choice (project vs global), the SKILL.md contract, evaluation, and install; don't improvise from this skill. Author through the `skill` target (`write({ skill })`), never a raw `.ok/skills/…` document. **Never read, diff, or edit the installed projections under `.claude/skills/` · `.cursor/skills/` · `.codex/skills/` · `.opencode/skills/` · `.agents/skills/`** — `install` generates them and overwrites them on the next sync; they are NOT source of truth.diff --git a/packages/server/assets/skills/project/references/anti-patterns.md b/packages/server/assets/skills/project/references/anti-patterns.mdindex d0e50cce9..13ad00033 100644--- a/packages/server/assets/skills/project/references/anti-patterns.md+++ b/packages/server/assets/skills/project/references/anti-patterns.md@@ -14,7 +14,7 @@| Wait for the server to tell you to open preview | Skip the session-start preview open and wait for the `attach-preview-once` hint | Open the preview browser at session start; the hint is a fallback when you didn't || Ignore the attach hint | Skip the `warning: { action: "attach-preview-once" }` hint in write-tool responses | Open the preview when the hint fires (`preview_start`, or `preview_url`); otherwise do nothing || Make the Claude Code Desktop preview work | Read / diagnose / edit `.claude/launch.json` (host-managed config) | Call `preview_start("open-knowledge-ui")` and nothing else; the OK lock-collision proxy bridges any port mismatch transparently |-| Open a doc in the app from the Claude Code CLI | Print the `previewUrl` / `openknowledge://` string for the user to click | Run `ok open <doc>` — it opens the OK Desktop app (folders open in the browser), with browser fallback |+| Open a doc/folder/skill in the app from a CLI | Print the `previewUrl` / `openknowledge://` string for the user to click | Run `ok open <name>` (doc or folder, auto-detected; `--skill <name>` for a skill) — deep-links into OK Desktop, browser fallback || Reference another doc | `` `[text](./page.md)` `` (backticked) or HTML `<a>` | `[text](./page.md)` (raw markdown) || Embed an image | `<img src="...">` (HTML), a `localhost:<port>` / `preview_url` server URL, or hot-linked external URL | Fetch + save locally + doc-relative `` || Write a factual claim in a KB doc | plausible prose without citation, OR inline `[source](https://URL)` | `ingest` the source first, then cite the local path per Grounding |diff --git a/packages/server/assets/skills/project/references/preview.md b/packages/server/assets/skills/project/references/preview.mdindex 4262d79d7..920e33250 100644--- a/packages/server/assets/skills/project/references/preview.md+++ b/packages/server/assets/skills/project/references/preview.md@@ -1,10 +1,11 @@# Preview — full multi-host contract## Contents+- **Step 0 — determine your ONE focus surface before opening anything (the load-bearing check)**- Re-navigation and end-of-turn discipline- `previewUrl` is a route, not a URL- The three first-class apps (Claude Code Desktop, Cursor, Codex desktop)-- Claude Code CLI track (no browser)+- Any-CLI track — Claude Code / Codex / Cursor CLI / OpenCode, no browser → `ok open`- Four attach signals- `previewUrl: null` semantics, server lifecycle, read-only mirror, no-screenshots@@ -16,7 +17,18 @@ 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.-**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:+### Step 0 — figure out your ONE focus surface BEFORE you open anything++Your host doesn't change mid-session, so determine this **once**, the first time you're asked to open/show/preview a doc, and use that one surface for the rest of the session. Run the checks **top-to-bottom and stop at the first match** — earlier rungs win:++1. **Is `OK_DESKTOP_TERMINAL` set in your environment?** You're a shell agent — actually check it (`echo "$OK_DESKTOP_TERMINAL"`, or read your env), don't assume. **Set → you're inside the OK Desktop app's own terminal.** Open a doc or folder with `ok open <name>` (auto-detected; `--skill <name>` for a skill) — it switches THIS window to the target. **Never resolve a preview URL here.** (This rung is the one agents miss most — check the env first, before anything else.)+2. **Do you have `preview_*` tools** (`preview_start` / `preview_eval`)? → **Claude Code Desktop** → drive its pane (rung details below).+3. **Do you have any URL-navigation / in-app browser tool** (Cursor `Navigate`, Codex `@Browser`, or `browser` / `open_url` / `view_url` / …)? → **Cursor / Codex desktop** → `preview_url` once, then navigate that browser to the `url`.+4. **None of the above** → you're a **plain CLI** (Claude Code CLI, Codex CLI, Cursor CLI, OpenCode, any shell agent) → `ok open <name>` for a doc or folder (auto-detected; `--skill <name>` for a skill); deep-links a separate OK Desktop window, system browser only if no desktop.++Decide once; then every "open / show / preview this doc" this session uses that surface's mechanism. **The `previewUrl` field in tool responses is a route id, not your open mechanism** — seeing it is not a reason to hand it to a browser. The rest of this section is the per-surface "how" for whichever rung you landed on.++**OK ships first-class preview support for three apps — Claude Code Desktop, Cursor, and the Codex desktop app — plus any CLI (Claude Code CLI, Codex CLI, Cursor CLI, OpenCode, …) on a separate `ok open` 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; if nothing can, you're a CLI → `ok open`. The three apps map to:- **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:@@ -25,7 +37,13 @@ The user watches your edits land in a live browser preview. Open it once at sess- **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.+**Any CLI — a separate track (no browser).** **Claude Code CLI, Codex CLI, Cursor CLI, OpenCode — any pure-stdio / shell agent with no in-app browser tool — uses `ok open`, never a preview URL.** The rule is capability, not vendor: no tool that navigates a URL → you're on this track.++- **`ok open <name>`** — opens a **doc or folder** in the OK Desktop app. The type is auto-detected (a directory on disk → folder, otherwise a doc), so **`--folder` is not needed** (it stays only as an explicit override for a folder that doesn't exist on disk yet). An action you run, not a URL to print.+- **`ok open <skill-name> --skill [--scope project|global]`** — opens a **skill** in the skill editor (skills are addressed by name + scope, not a content path, so they need the flag).+- All three deep-link into OK Desktop when a bundle is installed, and fall back to the browser UI (`ok ui`) otherwise. 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.++(The same vendors' *desktop apps* with a built-in browser — Cursor, Codex desktop — are NOT here; they navigate their own browser per the in-app branch above. Codex **IDE extension** / **Cloud** are web-search-only → they're on this CLI track too.) **Running inside the OK Desktop built-in terminal (the `OK_DESKTOP_TERMINAL` env var is set)? Same track — `ok open <name>` re-targets the window you're already in** (switches that window to the doc/folder; no second window, no need to raise it since it's already frontmost). Don't resolve preview URLs in that case; `ok open` is the whole answer.**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.diff --git a/packages/server/src/index.ts b/packages/server/src/index.tsindex e4676c284..61a31108e 100644--- a/packages/server/src/index.ts+++ b/packages/server/src/index.ts@@ -266,7 +266,12 @@ export { getCurrentMcpLogger, McpLogger, runWithMcpLogger } from './mcp/logger.texport { installPrettyZodErrors } from './mcp/pretty-zod-errors.ts';export { buildExecResult, type ExecStructuredResult } from './mcp/tools/exec.ts';export { registerAllTools } from './mcp/tools/index.ts';-export { encodeDocName, encodeFolderRoute, resolveUiInfo } from './mcp/tools/preview-url.ts';+export {+ encodeDocName,+ encodeFolderRoute,+ encodeSkillRoute,+ resolveUiInfo,+} from './mcp/tools/preview-url.ts';export {createMcpHttpHandler,type McpHttpHandler,diff --git a/packages/server/src/mcp/tools/get-preview-url.test.ts b/packages/server/src/mcp/tools/get-preview-url.test.tsindex f001308a2..7fe7b4038 100644--- a/packages/server/src/mcp/tools/get-preview-url.test.ts+++ b/packages/server/src/mcp/tools/get-preview-url.test.ts@@ -37,6 +37,7 @@ interface EnsureDeps {offCwdResolverDeps?: OffCwdResolverDeps;ensureSingleFileSession?: (absFile: string) => Promise<boolean>;resolveUserAutoOpen?: () => boolean;+ isDesktopTerminal?: boolean;}function captureRegistration(@@ -125,6 +126,100 @@ describe('preview_url tool — UI running', () => {expect(readArmedPaneTarget(resolveLockDir(cwd))).toBe('#/specs/foo/');});+ describe('isDesktopTerminal steer (OK Desktop built-in terminal)', () => {+ test('document: response leads with `ok open <doc>` and tells the agent not to navigate the URL', async () => {+ const cwd = mkdtempSync(join(tmpdir(), 'ok-get-preview-url-'));+ bindTestUiLock(cwd);+ const handler = captureRegistration(cwd, BASE_CONFIG, { isDesktopTerminal: true });+ const result = await handler({ document: 'specs/foo/SPEC' });+ const text = result.content[0]?.text ?? '';+ expect(text).toContain('ok open specs/foo/SPEC');+ expect(text).toMatch(/Don't navigate the URL|reference only/);+ expect(result.structuredContent?.running).toBe(true);+ expect(result.structuredContent?.okOpenCommand).toBe('ok open specs/foo/SPEC');+ });++ test('folder: steers to `ok open <folder>`', async () => {+ const cwd = mkdtempSync(join(tmpdir(), 'ok-get-preview-url-'));+ bindTestUiLock(cwd);+ const handler = captureRegistration(cwd, BASE_CONFIG, { isDesktopTerminal: true });+ const result = await handler({ folder: 'specs/foo' });+ expect(result.content[0]?.text ?? '').toContain('ok open specs/foo');+ expect(result.structuredContent?.okOpenCommand).toBe('ok open specs/foo');+ });++ test('skill default scope (project): steers to `ok open <name> --skill` (no --scope)', async () => {+ const cwd = mkdtempSync(join(tmpdir(), 'ok-get-preview-url-'));+ bindTestUiLock(cwd);+ const handler = captureRegistration(cwd, BASE_CONFIG, { isDesktopTerminal: true });+ const result = await handler({ skill: { name: 'trip-log' } });+ expect(result.content[0]?.text ?? '').toContain('ok open trip-log --skill');+ expect(result.content[0]?.text ?? '').not.toContain('--scope');+ expect(result.structuredContent?.okOpenCommand).toBe('ok open trip-log --skill');+ });++ test('skill --scope global: steers to `ok open <name> --skill --scope global`', async () => {+ const cwd = mkdtempSync(join(tmpdir(), 'ok-get-preview-url-'));+ bindTestUiLock(cwd);+ const handler = captureRegistration(cwd, BASE_CONFIG, { isDesktopTerminal: true });+ const result = await handler({ skill: { name: 'trip-log', scope: 'global' } });+ expect(result.content[0]?.text ?? '').toContain('ok open trip-log --skill --scope global');+ expect(result.structuredContent?.okOpenCommand).toBe(+ 'ok open trip-log --skill --scope global',+ );+ });++ test('no target (root): no steer — nothing to `ok open`', async () => {+ const cwd = mkdtempSync(join(tmpdir(), 'ok-get-preview-url-'));+ bindTestUiLock(cwd);+ const handler = captureRegistration(cwd, BASE_CONFIG, { isDesktopTerminal: true });+ const result = await handler({});+ expect(result.content[0]?.text ?? '').not.toContain('ok open');+ });++ test('NOT a desktop terminal (default): no steer — plain Preview URL', async () => {+ const cwd = mkdtempSync(join(tmpdir(), 'ok-get-preview-url-'));+ bindTestUiLock(cwd);+ const handler = captureRegistration(cwd);+ const result = await handler({ document: 'specs/foo/SPEC' });+ expect(result.content[0]?.text ?? '').not.toContain('ok open');+ expect(result.structuredContent?.okOpenCommand ?? null).toBeNull();+ });++ test('desktop terminal + no UI running: steer + okOpenCommand still fire (ok open does not need the UI)', async () => {+ const cwd = mkdtempSync(join(tmpdir(), 'ok-get-preview-url-'));+ const handler = captureRegistration(cwd, BASE_CONFIG, { isDesktopTerminal: true });+ const result = await handler({ document: 'specs/foo/SPEC' });+ expect(result.structuredContent?.running).toBe(false);+ expect(result.structuredContent?.okOpenCommand).toBe('ok open specs/foo/SPEC');+ expect(result.content[0]?.text ?? '').toContain('ok open specs/foo/SPEC');+ });++ test('document with a space: okOpenCommand shell-quotes the path', async () => {+ const cwd = mkdtempSync(join(tmpdir(), 'ok-get-preview-url-'));+ bindTestUiLock(cwd);+ const handler = captureRegistration(cwd, BASE_CONFIG, { isDesktopTerminal: true });+ const result = await handler({ document: 'notes/My Doc' });+ expect(result.structuredContent?.okOpenCommand).toBe("ok open 'notes/My Doc'");+ });++ test('document with an embedded single quote: okOpenCommand POSIX-escapes it', async () => {+ const cwd = mkdtempSync(join(tmpdir(), 'ok-get-preview-url-'));+ bindTestUiLock(cwd);+ const handler = captureRegistration(cwd, BASE_CONFIG, { isDesktopTerminal: true });+ const result = await handler({ document: "Q&A/what's new" });+ expect(result.structuredContent?.okOpenCommand).toBe("ok open 'Q&A/what'\\''s new'");+ });++ test('desktop terminal + no UI + folder: okOpenCommand still fires', async () => {+ const cwd = mkdtempSync(join(tmpdir(), 'ok-get-preview-url-'));+ const handler = captureRegistration(cwd, BASE_CONFIG, { isDesktopTerminal: true });+ const result = await handler({ folder: 'specs/foo' });+ expect(result.structuredContent?.running).toBe(false);+ expect(result.structuredContent?.okOpenCommand).toBe('ok open specs/foo');+ });+ });+test('docName + folder together is rejected (mutually exclusive)', async () => {const cwd = mkdtempSync(join(tmpdir(), 'ok-get-preview-url-'));bindTestUiLock(cwd);diff --git a/packages/server/src/mcp/tools/get-preview-url.ts b/packages/server/src/mcp/tools/get-preview-url.tsindex 5f09a01cc..3949eff0a 100644--- a/packages/server/src/mcp/tools/get-preview-url.ts+++ b/packages/server/src/mcp/tools/get-preview-url.ts@@ -52,6 +52,7 @@ const DESCRIPTION = [interface GetPreviewUrlDeps {config: ConfigOrResolver;resolveCwd: (explicit?: string) => Promise<string>;+ isDesktopTerminal?: boolean;serverUrl?: ServerUrlOrResolver;uiBindWait?: { timeoutMs?: number; pollIntervalMs?: number };offCwdResolverDeps?: OffCwdResolverDeps;@@ -126,6 +127,13 @@ const OutputSchema = outputSchemaWithText({.describe('User-scoped preview-auto-open preference (`appearance.preview.autoOpen`). When `true`, the agent should route the preview using capability-based routing (in-app browser if available, system browser as fallback). When `false`, the user is managing their own preview view (OK Desktop window, a browser tab they opened, etc.) — the agent must NOT open or refresh any preview UI, and should surface this URL only on direct user ask. Resolved fresh on every call; defaults to `true`.',),+ okOpenCommand: z+ .string()+ .nullable()+ .optional()+ .describe(+ 'Machine-readable form of the desktop-terminal steer: when this MCP server runs inside OK Desktop’s built-in terminal AND a doc/folder/skill target was given, the exact `ok open …` command to run to focus it in the OK Desktop window. Prefer running it over navigating `url`. `null`/absent in every other context (navigate `url` per your host instead).',+ ),});const NO_UI_SERVER_RUNNING_MESSAGE =@@ -165,6 +173,11 @@ function isServerLive(lockDir: string): boolean {}}+function shellQuoteArg(arg: string): string {+ if (/^[A-Za-z0-9._/@%+-]+$/.test(arg)) return arg;+ return `'${arg.replace(/'/g, "'\\''")}'`;+}+export function register(server: ServerInstance, deps: GetPreviewUrlDeps): void {server.registerTool('preview_url',@@ -257,6 +270,18 @@ export function register(server: ServerInstance, deps: GetPreviewUrlDeps): void? `#/${encodeSkillRoute(args.skill.scope ?? 'project', args.skill.name)}`: null;+ const okOpenCommand = args.document+ ? `ok open ${shellQuoteArg(args.document)}`+ : args.folder+ ? `ok open ${shellQuoteArg(args.folder)}`+ : args.skill+ ? `ok open ${args.skill.name} --skill${args.skill.scope === 'global' ? ' --scope global' : ''}`+ : null;+ const desktopTerminalSteer =+ deps.isDesktopTerminal && okOpenCommand+ ? `You're in the OK Desktop terminal — run \`${okOpenCommand}\` to focus this in the OK Desktop window. Don't navigate the URL below or open a browser; it's for reference only.\n\n`+ : '';+if (args.armPaneTarget && routeFragment) {try {armPaneTarget(lockDir, routeFragment);@@ -302,21 +327,23 @@ export function register(server: ServerInstance, deps: GetPreviewUrlDeps): voidconst hint = isServerLive(lockDir)? NO_UI_SERVER_RUNNING_MESSAGE: `${NO_SERVER_MESSAGE}${autoStartDisabled ? AUTOSTART_DISABLED_NOTE : ''}`;- return textPlusStructured(`${hint}${armNote}`, {+ return textPlusStructured(`${desktopTerminalSteer}${hint}${armNote}`, {url: null,baseUrl: null,running: false,autoOpen,+ okOpenCommand: deps.isDesktopTerminal ? okOpenCommand : null,});}const url = routeFragment ? `${baseUrl}/${routeFragment}` : baseUrl;- return textPlusStructured(`Preview URL: ${url}${armNote}`, {+ return textPlusStructured(`${desktopTerminalSteer}Preview URL: ${url}${armNote}`, {url,baseUrl,running: true,autoOpen,+ okOpenCommand: deps.isDesktopTerminal ? okOpenCommand : null,});},);diff --git a/packages/server/src/mcp/tools/index.ts b/packages/server/src/mcp/tools/index.tsindex 6b641118b..37293e17c 100644--- a/packages/server/src/mcp/tools/index.ts+++ b/packages/server/src/mcp/tools/index.ts@@ -31,6 +31,7 @@ interface RegisterAllToolsOptions {config: ConfigOrResolver;identityRef?: { current: AgentIdentity };logger?: McpLogger;+ isDesktopTerminal?: boolean;}export function registerAllTools(server: ServerInstance, opts: RegisterAllToolsOptions): void {@@ -142,6 +143,7 @@ export function registerAllTools(server: ServerInstance, opts: RegisterAllToolsOconfig: opts.config,resolveCwd: named('preview_url'),serverUrl: opts.serverUrl,+ isDesktopTerminal: opts.isDesktopTerminal,...(opts.serverUrl ? { ensureSingleFileSession: createEnsureSingleFileSession() } : {}),});registerConflicts(registrationServer, {