Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
Drop the OK MCP instructions handshake (PRD-7115) (#1940)
tim-inkeep15dfda2d4200
diff --git a/.changeset/drop-mcp-instructions-handshake.md b/.changeset/drop-mcp-instructions-handshake.mdnew file mode 100644index 000000000..1ace5fc08--- /dev/null+++ b/.changeset/drop-mcp-instructions-handshake.md@@ -0,0 +1,5 @@+---+"@inkeep/open-knowledge": patch+---++The Open Knowledge MCP server no longer emits a handshake `instructions` block. That block was injected into every project the (globally-registered) server connected to — including non-Open-Knowledge projects — which steered agents toward OK tools they could not use there. Agent guidance for OK projects is delivered by the installed `open-knowledge` project skill, which is the single source of that contract.diff --git a/package.json b/package.jsonindex a41e8d74f..075b7273c 100644--- a/package.json+++ b/package.json@@ -21,7 +21,7 @@"build:desktop:dir": "turbo run build:desktop:dir","check:desktop": "turbo run lint typecheck test --filter=@inkeep/open-knowledge-desktop","check:fast": "bun run typecheck",- "check:drift": "bash scripts/check-husky-prepare-guard.sh && bash scripts/check-knip-clean.sh && bash scripts/check-notices-clean.sh && bash scripts/check-schema-snapshot-clean.sh && bash scripts/check-instructions-drift.sh && bash scripts/check-i18n-drift.sh && bash scripts/check-no-major-changeset.sh && bun test scripts/",+ "check:drift": "bash scripts/check-husky-prepare-guard.sh && bash scripts/check-knip-clean.sh && bash scripts/check-notices-clean.sh && bash scripts/check-schema-snapshot-clean.sh && bash scripts/check-i18n-drift.sh && bash scripts/check-no-major-changeset.sh && bun test scripts/","typecheck": "turbo run typecheck","test": "turbo run test","lint": "bun lint:biome && bun lint:oxlint",@@ -29,7 +29,7 @@"lint:oxlint": "oxlint --max-warnings 0 .","format": "bun run lint:biome --write --unsafe","check": "bun run lint && turbo run build typecheck test",- "check:full:parallel": "bash scripts/check-husky-prepare-guard.sh && bash scripts/check-knip-clean.sh && bash scripts/check-notices-clean.sh && bash scripts/check-schema-snapshot-clean.sh && bash scripts/check-instructions-drift.sh && bash scripts/check-i18n-drift.sh && bash scripts/check-no-major-changeset.sh && bun run lint && bun test scripts/ && bun test --cwd .github/scripts && turbo run build typecheck test test:dom test:integration test:conversion test:fidelity test:perf:regression:unit test:health:unit test:health test:e2e test:visual test:perf test:a11y --concurrency=100% --output-logs=errors-only",+ "check:full:parallel": "bash scripts/check-husky-prepare-guard.sh && bash scripts/check-knip-clean.sh && bash scripts/check-notices-clean.sh && bash scripts/check-schema-snapshot-clean.sh && bash scripts/check-i18n-drift.sh && bash scripts/check-no-major-changeset.sh && bun run lint && bun test scripts/ && bun test --cwd .github/scripts && turbo run build typecheck test test:dom test:integration test:conversion test:fidelity test:perf:regression:unit test:health:unit test:health test:e2e test:visual test:perf test:a11y --concurrency=100% --output-logs=errors-only","tier1": "bun run check","tier2": "bun run tier1 && turbo run test:perf:regression:unit test:health:unit test:health test:e2e","tier3": "STRESS_FIDELITY=1 bun run tier2",diff --git a/packages/cli/src/mcp/server.ts b/packages/cli/src/mcp/server.tsindex fcc1c190c..de37ddf5d 100644--- a/packages/cli/src/mcp/server.ts+++ b/packages/cli/src/mcp/server.ts@@ -8,7 +8,6 @@ import { OK_PROJECT_MARKER } from '@inkeep/open-knowledge-core';import { type KeepaliveHandle, startKeepalive } from '@inkeep/open-knowledge-core/keepalive';import {type AgentIdentity,- buildInstructions,type Config,getLocalDir,installPrettyZodErrors,@@ -156,15 +155,10 @@ export async function startGlobalMcpServer(startupConfig: opts.startupConfig,});- const server = new McpServer(- {- name: MCP_SERVER_NAME,- version: RUNTIME_VERSION,- },- {- instructions: buildInstructions({ dir: '.' }),- },- );+ const server = new McpServer({+ name: MCP_SERVER_NAME,+ version: RUNTIME_VERSION,+ });installPrettyZodErrors(server);const connectionId = randomUUID();diff --git a/packages/server/assets/skills/project/SKILL.md b/packages/server/assets/skills/project/SKILL.mdindex 175e4be4f..cb6ae09d8 100644--- a/packages/server/assets/skills/project/SKILL.md+++ b/packages/server/assets/skills/project/SKILL.md@@ -1,6 +1,6 @@---name: open-knowledge-description: "MUST invoke before reading or editing any `.md` / `.mdx` file, and before any `mcp__open-knowledge__*` tool call (`exec`, `search`, `write`, `edit`, and the rest). This skill is installed into the repository by `ok init`, so its presence alone means this is an Open Knowledge project — its runtime contract governs every markdown file here, with no need to probe for a `.ok/` directory. Authoritative agent-runtime contract; supersedes the overlapping MCP server `instructions` echo."+description: "MUST invoke before reading or editing any `.md` / `.mdx` file, and before any `mcp__open-knowledge__*` tool call (`exec`, `search`, `write`, `edit`, and the rest). This skill is installed into the repository by `ok init`, so its presence alone means this is an Open Knowledge project — its runtime contract governs every markdown file here, with no need to probe for a `.ok/` directory. Authoritative agent-runtime contract for working inside this Open Knowledge project."compatibility: "Claude Code, Claude Desktop, Claude Cowork, Claude.ai web. Requires Open Knowledge MCP server + code execution."metadata:version: "0.14.0"@@ -11,7 +11,7 @@ metadata:Open Knowledge (OK) is a markdown-CRDT collaboration platform exposed via MCP. This skill carries the behavioral rules agents need to use it fluently. Every section is a MUST unless marked otherwise.-> **Authoritative source.** Where the MCP server's `instructions` echo overlaps with this skill, this skill wins — the full attach rule, grounding rule, media rules, dead-link verification, and failure-mode guidance live only here.+> **Authoritative source.** This skill is the single source of Open Knowledge agent guidance — the full attach rule, grounding rule, media rules, dead-link verification, and failure-mode guidance live only here.> Skill version: tracks `@inkeep/open-knowledge-server` package version. Check `cat ~/.ok/skill-state.yml` to see what's installed locally. **Version floor:** `ok seed` (referenced below) requires `@inkeep/open-knowledge` >= 0.4.0. If `ok seed` errors with `unknown command`, upgrade: `npm install -g @inkeep/open-knowledge`.diff --git a/packages/server/scripts/generate-instructions.test.ts b/packages/server/scripts/generate-instructions.test.tsdeleted file mode 100644index 5739af12a..000000000--- a/packages/server/scripts/generate-instructions.test.ts+++ /dev/null@@ -1,137 +0,0 @@-import { describe, expect, test } from 'bun:test';-import { readFileSync } from 'node:fs';-import { dirname, resolve } from 'node:path';-import { fileURLToPath } from 'node:url';-import {- type GenerateResult,- generateInstructions,- renderInstructionsFile,-} from './generate-instructions.ts';--const __dirname = dirname(fileURLToPath(import.meta.url));-const PKG_ROOT = resolve(__dirname, '..');-const SKILL_PATH = resolve(PKG_ROOT, 'assets/skills/project/SKILL.md');-const INSTRUCTIONS_PATH = resolve(PKG_ROOT, 'src/mcp/instructions.ts');--describe('generateInstructions — extraction + round-trip', () => {- test('round-trips: generated body matches the committed instructions.ts (idempotency gate)', () => {- const skill = readFileSync(SKILL_PATH, 'utf8');- const result = generateInstructions(skill);- const rendered = renderInstructionsFile(result.body);- const committed = readFileSync(INSTRUCTIONS_PATH, 'utf8');- expect(rendered).toBe(committed);- });-- test('extracts all 4 target H2 sections from real SKILL.md', () => {- const skill = readFileSync(SKILL_PATH, 'utf8');- const result = generateInstructions(skill);- expect(result.body).toContain('## STOP — native tools on in-scope `.md` / `.mdx`');- expect(result.body).toContain('## Reads — examples');- expect(result.body).toContain('## Preview — open the browser at session start');- expect(result.body).toContain('## Scope recap');- });-- test('generated body routes preview by browser-tool capability, not host name (PRD-6761)', () => {- const skill = readFileSync(SKILL_PATH, 'utf8');- const result = generateInstructions(skill);- expect(result.body).not.toContain('Codex CLI, which has no embedded browser');- expect(result.body).toContain('built-in browser');- expect(result.body).toContain('navigate to a URL');- expect(result.body).toContain('use the in-app branch above');- });-- test('generated body documents both Claude-pane preview modes, not arm-then-start alone (PRD-6900)', () => {- const skill = readFileSync(SKILL_PATH, 'utf8');- const result = generateInstructions(skill);- expect(result.body).toContain('armPaneTarget');- expect(result.body).toContain('redirects the base-open');- expect(result.body).toContain('preview_eval');- expect(result.body).toContain('window.location.hash');- expect(result.body).toContain('reuses the live process without reloading');- });-- test('emits identity prefix at the head', () => {- const skill = readFileSync(SKILL_PATH, 'utf8');- const result = generateInstructions(skill);- expect(- result.body.startsWith('Open Knowledge is a markdown-CRDT knowledge base exposed via MCP.'),- ).toBe(true);- });-- test('emits pointer suffix at the tail', () => {- const skill = readFileSync(SKILL_PATH, 'utf8');- const result = generateInstructions(skill);- expect(result.body).toContain(- 'Full guidance lives in the bundled `open-knowledge` skill at `~/.ok/skills/open-knowledge/SKILL.md`.',- );- });-});--describe('generateInstructions — missing-section detection', () => {- test('throws with a clear error naming the renamed heading + listing actual H2 headings', () => {- const skill = readFileSync(SKILL_PATH, 'utf8');- const tampered = skill.replace(- '## STOP — native tools on in-scope `.md` / `.mdx`',- '## STOP — native tools (renamed)',- );- let thrown: Error | undefined;- try {- generateInstructions(tampered);- } catch (err) {- thrown = err as Error;- }- expect(thrown).toBeDefined();- const msg = thrown?.message ?? '';- expect(msg).toContain('missing required H2 section');- expect(msg).toContain('## STOP — native tools on in-scope `.md` / `.mdx`');- expect(msg).toContain('H2 headings actually found:');- expect(msg).toContain('## STOP — native tools (renamed)');- });-- test('lists all missing sections when multiple are renamed', () => {- const skill = readFileSync(SKILL_PATH, 'utf8');- const tampered = skill- .replace('## Reads — examples', '## Reads (renamed)')- .replace('## Scope recap', '## Scope (renamed)');- let thrown: Error | undefined;- try {- generateInstructions(tampered);- } catch (err) {- thrown = err as Error;- }- expect(thrown).toBeDefined();- const msg = thrown?.message ?? '';- expect(msg).toContain('## Reads — examples');- expect(msg).toContain('## Scope recap');- });-});--describe('generateInstructions — byte budget', () => {- test('emits an over-budget warning naming the heaviest section when body > 2 KB', () => {- const skill = readFileSync(SKILL_PATH, 'utf8');- const result = generateInstructions(skill);- if (result.byteLength > 2048) {- expect(result.warnings.length).toBeGreaterThan(0);- const w = result.warnings.join('\n');- expect(w).toContain('over Claude Code');- expect(w).toContain('Heaviest section');- } else {- expect(result.warnings).toEqual([]);- }- });-- test('stays within the structural ceiling (truncation / cache-cost guard)', () => {- const skill = readFileSync(SKILL_PATH, 'utf8');- const result = generateInstructions(skill);- expect(result.byteLength).toBeLessThan(13776);- });-- test('reports per-section byte lengths so maintainers can spot the heaviest', () => {- const skill = readFileSync(SKILL_PATH, 'utf8');- const result: GenerateResult = generateInstructions(skill);- expect(Object.keys(result.sectionByteLengths)).toHaveLength(4);- for (const bytes of Object.values(result.sectionByteLengths)) {- expect(bytes).toBeGreaterThan(0);- }- });-});diff --git a/packages/server/scripts/generate-instructions.ts b/packages/server/scripts/generate-instructions.tsdeleted file mode 100644index 3de755168..000000000--- a/packages/server/scripts/generate-instructions.ts+++ /dev/null@@ -1,165 +0,0 @@-#!/usr/bin/env bun--import { readFileSync, writeFileSync } from 'node:fs';-import { dirname, resolve } from 'node:path';-import { fileURLToPath } from 'node:url';--const __dirname = dirname(fileURLToPath(import.meta.url));-const PKG_ROOT = resolve(__dirname, '..');-const SKILL_PATH = resolve(PKG_ROOT, 'assets/skills/project/SKILL.md');-const INSTRUCTIONS_PATH = resolve(PKG_ROOT, 'src/mcp/instructions.ts');--const IDENTITY_PREFIX = 'Open Knowledge is a markdown-CRDT knowledge base exposed via MCP.';-const POINTER_SUFFIX =- 'Full guidance lives in the bundled `open-knowledge` skill at `~/.ok/skills/open-knowledge/SKILL.md`.';--const TARGET_HEADINGS = [- '## STOP — native tools on in-scope `.md` / `.mdx`',- '## Reads — examples',- '## Preview — open the browser at session start',- '## Scope recap',-] as const;--const CLAUDE_CODE_INSTRUCTIONS_CAP_BYTES = 2048;--export interface GenerateResult {- body: string;- byteLength: number;- sectionByteLengths: Record<string, number>;- warnings: string[];-}--function extractSection(lines: string[], heading: string): string | null {- let start = -1;- for (let i = 0; i < lines.length; i++) {- if (lines[i] === heading) {- start = i;- break;- }- }- if (start === -1) return null;- let end = lines.length;- for (let i = start + 1; i < lines.length; i++) {- if (lines[i].startsWith('## ')) {- end = i;- break;- }- }- return lines.slice(start + 1, end).join('\n');-}--function listH2Headings(lines: string[]): string[] {- return lines.filter((l) => l.startsWith('## '));-}--export function generateInstructions(skillMarkdown: string): GenerateResult {- const lines = skillMarkdown.split('\n');- const sections: string[] = [];- const sectionByteLengths: Record<string, number> = {};- const missing: string[] = [];-- for (const heading of TARGET_HEADINGS) {- const content = extractSection(lines, heading);- if (content === null) {- missing.push(heading);- continue;- }- sections.push(`${heading}\n${content}`);- sectionByteLengths[heading] = Buffer.byteLength(content, 'utf8');- }-- if (missing.length > 0) {- const found = listH2Headings(lines);- const lines_out = [- 'generate-instructions: missing required H2 section(s) in SKILL.md:',- ...missing.map((m) => ` - ${m}`),- '',- 'H2 headings actually found:',- ...found.map((f) => ` - ${f}`),- ];- throw new Error(lines_out.join('\n'));- }-- const body = [IDENTITY_PREFIX, '', ...sections, '', POINTER_SUFFIX, ''].join('\n');- const byteLength = Buffer.byteLength(body, 'utf8');-- const warnings: string[] = [];- if (byteLength > CLAUDE_CODE_INSTRUCTIONS_CAP_BYTES) {- const heaviest = Object.entries(sectionByteLengths).sort(([, a], [, b]) => b - a)[0];- warnings.push(- `generate-instructions: body is ${byteLength} bytes, over Claude Code's ${CLAUDE_CODE_INSTRUCTIONS_CAP_BYTES}-byte instructions cap. Heaviest section: ${heaviest[0]} (${heaviest[1]} bytes). Tighten SKILL.md or split the section.`,- );- }-- return { body, byteLength, sectionByteLengths, warnings };-}--export function renderInstructionsFile(body: string): string {- const escaped = body.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${');- return `/**- * MCP \`instructions\` handshake string — emitted on \`initialize\`.- *- * GENERATED FILE — do not edit by hand. Canonical source is- * \`packages/server/assets/skills/project/SKILL.md\`. Regenerate via:- *- * bun run packages/server/scripts/generate-instructions.ts- *- * CI gate (\`bun run check\`) runs the same script with \`--check\` and fails- * on drift. See \`packages/server/scripts/generate-instructions.ts\` for the- * extraction contract (4 H2 sections by exact-match heading text).- *- * The generated body intentionally exceeds Claude's 2 KB per-server cap —- * that cap fires a warning, not an error. The body carries the cross-host- * STOP / Reads / Preview / Scope-recap contract by design; its structural- * ceiling is pinned by generate-instructions.test.ts. Shrink only by tightening- * those SKILL.md sections, never by dropping load-bearing rules.- */-import type { Config } from '../config/schema.ts';--export function buildInstructions(_content: Config['content']): string {- return \`${escaped}\`;-}-`;-}--function runCli(): void {- const args = process.argv.slice(2);- const checkMode = args.includes('--check');-- const skill = readFileSync(SKILL_PATH, 'utf8');- let result: GenerateResult;- try {- result = generateInstructions(skill);- } catch (err) {- console.error((err as Error).message);- process.exit(1);- }-- for (const w of result.warnings) {- console.warn(w);- }-- const rendered = renderInstructionsFile(result.body);-- if (checkMode) {- const existing = readFileSync(INSTRUCTIONS_PATH, 'utf8');- if (existing !== rendered) {- console.error(- `generate-instructions --check: ${INSTRUCTIONS_PATH} is out of sync with SKILL.md.\n` +- `Regenerate via: bun run packages/server/scripts/generate-instructions.ts`,- );- process.exit(1);- }- console.log(- `generate-instructions --check: instructions.ts in sync (${result.byteLength} bytes).`,- );- return;- }-- writeFileSync(INSTRUCTIONS_PATH, rendered);- console.log(`generate-instructions: wrote ${INSTRUCTIONS_PATH} (${result.byteLength} bytes).`);-}--if (import.meta.main) {- runCli();-}diff --git a/packages/server/src/index.ts b/packages/server/src/index.tsindex 6fa98154c..e226979f4 100644--- a/packages/server/src/index.ts+++ b/packages/server/src/index.ts@@ -259,7 +259,6 @@ export {MCP_CONNECTION_ID_HEADER,sanitizeClientName,} from './mcp/agent-identity.ts';-export { buildInstructions } from './mcp/instructions.ts';export { getCurrentMcpLogger, McpLogger, runWithMcpLogger } from './mcp/logger.ts';export { installPrettyZodErrors } from './mcp/pretty-zod-errors.ts';export { buildExecResult, type ExecStructuredResult } from './mcp/tools/exec.ts';diff --git a/packages/server/src/mcp-http.ts b/packages/server/src/mcp-http.tsindex 61603e7fa..53c657cf8 100644--- a/packages/server/src/mcp-http.ts+++ b/packages/server/src/mcp-http.ts@@ -11,7 +11,6 @@ import {MCP_CONNECTION_ID_HEADER,sanitizeClientName,} from './mcp/agent-identity.ts';-import { buildInstructions } from './mcp/instructions.ts';import { installPrettyZodErrors } from './mcp/pretty-zod-errors.ts';import { registerAllTools } from './mcp/tools/index.ts';import { resolveWithinRoot } from './mcp/tools/path-safety.ts';@@ -59,15 +58,10 @@ function createSessionServer(forwardedConnectionId: string | undefined,): McpHttpSession {const config = opts.config;- const server = new McpServer(- {- name: MCP_SERVER_NAME,- version: RUNTIME_VERSION,- },- {- instructions: buildInstructions(config.content),- },- );+ const server = new McpServer({+ name: MCP_SERVER_NAME,+ version: RUNTIME_VERSION,+ });installPrettyZodErrors(server);const connectionId = forwardedConnectionId ?? randomUUID();diff --git a/packages/server/src/mcp/instructions.test.ts b/packages/server/src/mcp/instructions.test.tsdeleted file mode 100644index cf265ee10..000000000--- a/packages/server/src/mcp/instructions.test.ts+++ /dev/null@@ -1,87 +0,0 @@-import { test as _bunTest, expect } from 'bun:test';--const test = process.env.CI ? _bunTest.skip : _bunTest;--import { type Config, ConfigSchema } from '../config/schema.ts';-import { buildInstructions } from './instructions.ts';--function defaultContent(): Config['content'] {- return ConfigSchema.parse({}).content;-}--test('buildInstructions carries the STOP rule on native tools for in-scope markdown', () => {- const text = buildInstructions(defaultContent());- expect(text).toContain('STOP');- expect(text).toContain('Open Knowledge MCP configured');- expect(text).toContain('write');- expect(text).toContain('edit');-});--test('buildInstructions carries the preview-attach rule', () => {- const text = buildInstructions(defaultContent());- expect(text).toContain('Preview');- expect(text).toContain('attach-preview-once');- expect(text).toContain('previewUrl');-});--test('buildInstructions carries the autoOpen directional bullet', () => {- const text = buildInstructions(defaultContent());- expect(text).toContain('Honor `autoOpen`** (on `preview_url`, or on `warning` for write tools)');- expect(text).toContain('do not open or refresh any preview UI');-});--test('buildInstructions carries the end-of-turn deliverable-navigation rule', () => {- const text = buildInstructions(defaultContent());- expect(text).toContain('End a turn on the deliverable');- expect(text).toContain('navigate the preview to the primary deliverable');-});--test('buildInstructions routes by browser-tool capability, not by host name (PRD-6761)', () => {- const text = buildInstructions(defaultContent());- expect(text).not.toContain('Codex CLI, which has no embedded browser');- expect(text).toContain('built-in browser');- expect(text).toContain('navigate to a URL');- expect(text).toContain('use the in-app branch above');-});--test('buildInstructions points readers at the bundled open-knowledge skill for full guidance', () => {- const text = buildInstructions(defaultContent());- expect(text).toContain('open-knowledge');- expect(text).toContain('skill');- expect(text).toContain('~/.ok/skills/open-knowledge/SKILL.md');-});--test('buildInstructions documents the read tool routing (exec / search)', () => {- const text = buildInstructions(defaultContent());- expect(text).toContain('## Reads');- expect(text).toContain('exec(');- expect(text).toContain('search');- expect(text).toContain('grep'); // still mentioned via `exec("grep -rn …")` example-});--test('buildInstructions surfaces an explicit native-tool escape hatch', () => {- const text = buildInstructions(defaultContent());- expect(text).toContain('Escape hatch');- expect(text).toContain('Open Knowledge MCP unavailable:');-});--test('buildInstructions surfaces the scope-recap section pointing at .okignore', () => {- const text = buildInstructions(defaultContent());- expect(text).toContain('## Scope recap');- expect(text).toContain('.okignore');- expect(text).toContain('content.dir');-});--test('buildInstructions leads with the identity prefix', () => {- const text = buildInstructions(defaultContent());- expect(text.startsWith('Open Knowledge is a markdown-CRDT knowledge base exposed via MCP.')).toBe(- true,- );-});--test('buildInstructions exceeds the legacy 2 KB Claude Code cap (generator emits a warning; see generate-instructions.test.ts)', () => {- const text = buildInstructions(defaultContent());- const bytes = Buffer.byteLength(text, 'utf8');- expect(bytes).toBeGreaterThan(2048);- expect(bytes).toBeLessThan(13776);-});diff --git a/packages/server/src/mcp/instructions.ts b/packages/server/src/mcp/instructions.tsdeleted file mode 100644index 044d33f6f..000000000--- a/packages/server/src/mcp/instructions.ts+++ /dev/null@@ -1,86 +0,0 @@-import type { Config } from '../config/schema.ts';--export function buildInstructions(_content: Config['content']): string {- return `Open Knowledge is a markdown-CRDT knowledge base exposed via MCP.--## STOP — native tools on in-scope \`.md\` / \`.mdx\`--When this workspace has Open Knowledge MCP configured, do **not** use your host's native file tools on markdown paths inside the content directory. The ban covers every common rationalization:--- **Native \`Read\` / \`Grep\` / \`Glob\` on in-scope \`.md\` / \`.mdx\`** — the original case.-- **\`Bash ls\` / \`Bash find\` / \`Bash cat\` on dirs containing in-scope markdown** — use \`exec("ls -A …")\` / \`exec("find … -name '*.md'")\` / \`exec("cat …")\` instead. Native returns bare names; \`exec\` returns frontmatter, backlink counts, and recent activity per child. \`-A\` shows hidden entries (\`.ok/\`, \`.okignore\`) which OK projects carry; omit \`.\` and \`..\` rows that \`-a\` would add.-- **Glob patterns that target markdown** (\`**/*.md\`, any dir known to be markdown-heavy like \`specs/**\`, \`reports/**\`, \`docs/**\`) — use \`exec\` with \`find\`, or \`exec("ls -A <dir>")\`.-- **Dispatching the Explore / general-purpose subagent for markdown-heavy exploration** — subagents use native \`Read\` / \`Grep\` / \`Glob\` internally and bypass Open Knowledge entirely. Do markdown exploration yourself via \`exec\` / \`search\`. Subagents remain appropriate for **source-code** exploration.-- **Native \`Read\` / \`Grep\` on any in-scope markdown inside \`.ok/\`** — the \`.ok/\` directory is in-scope; if it carries \`.md\` / \`.mdx\`, treat those the same as any other knowledge-base file.--Why: native tools skip frontmatter, backlinks, shadow-repo activity, and project git history that OK's tools return for every matched knowledge-base file. \`exec\` is the primary read surface; it runs read-only bash (\`cat\`, \`ls\`, \`grep\`, \`find\`, \`head\`, \`tail\`, \`wc\`, \`sort\`, \`uniq\`, \`cut\`) and returns raw stdout plus enriched metadata per file. One command or a pipe (\`|\`) per call — it is NOT a shell, so \`&&\` / \`;\` / redirects are rejected; list several dirs with \`ls -A a b c\` or make separate calls.--**MCP tool visibility — not seeing \`exec\` is NOT the escape hatch.** MCP wiring varies by client. Claude Code, Cursor, Codex, Windsurf, VS Code — each surfaces MCP differently. Server labels are user-defined; tools may not appear as top-level symbols named \`exec\` in your specific UI. If Open Knowledge is registered as an MCP server in this workspace, route markdown reads through its \`exec\` / \`search\` via your client's documented MCP invocation (including any generic "call MCP tool" flow). Registration is the test, not top-level-symbol visibility.--**Escape hatch.** Native \`Read\` / \`Grep\` / \`Glob\` on \`.md\` / \`.mdx\` is allowed **only** when no Open Knowledge MCP server is registered for this project, **or** immediately after you tried an MCP call and it failed — then begin a user-visible sentence with \`Open Knowledge MCP unavailable:\`. Never use the hatch because you skipped your client's MCP path, didn't see \`exec\` as a top-level tool, or rationalized the skill wasn't necessary.--**Source code and non-markdown files** (\`.ts\`, \`.py\`, \`package.json\`, …): native \`Read\` / \`Grep\` / \`Glob\` always.--## Reads — examples--- Read a file: \`exec("cat <path>.md")\` — contents + full rich enrichment.-- List a directory: \`exec("ls -A <dir>")\` — per-child frontmatter, recursive markdown counts, most-recently-updated doc per subdir, the folder's own \`title\`/\`description\`/\`tags\` + \`templates_available\`. Prefer \`-A\` over plain \`ls\` to surface dot-prefixed entries (\`.ok/\`, \`.okignore\`) without the noisy \`.\`/\`..\` rows that \`-a\` adds.-- Literal search: \`exec("grep -rn <term> <dir> | head -5")\` — matches + enrichment on matched files.-- Ranked search: \`search({ query })\` — cmd-K parity (title boost + body BM25 + recency); use when picking the best doc, not when listing every occurrence.--## Preview — open the browser at session start--The user watches your edits land in a live browser preview. Open it once at session start, then keep working. Re-navigate only when the user asks to open a different doc, or to land them on a finished deliverable (see below) — not to re-check your own edits.--**End a turn on the deliverable, not your scratch space.** Keep the preview steady *during* a multi-doc task — don't yank it around to re-check your own edits. But when a turn created or substantially changed user-facing docs, navigate the preview to the primary deliverable before you hand back: the hub / overview / index page when you created several docs, or the changed doc when you changed one. Don't step the user through every supporting source card — the user is watching, so leave them on the result.--**\`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:--- **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):--1. You opened/navigated earlier this session → don't reopen.-2. Write response has \`previewUrl\` (non-null route) and NO \`warning\` → a browser is attached somewhere; do nothing.-3. \`warning: { action: "attach-preview-once", previewUrl, message }\` → UI reachable, no browser attached; navigate one-shot (\`preview_start\`, or \`preview_url\` → in-app browser).-4. \`warning: { action: "start-ui", previewUrl: null, message }\` → no UI running anywhere. Surface the message verbatim — recovery options are in the in-band copy. Don't loop on retries.--Warnings fire at most once per session in the fresh-start case.--**Re-point at the end of a multi-doc workflow; don't claim a doc is on screen unless you put it there.** The one-shot attach (signal 3) opens the preview *once* — later writes do NOT move the pane; it stays on the doc you last navigated to. When a turn touches several docs, finish by navigating the preview to the doc the user should land on, using your host's move mechanism (\`preview_eval\` setting \`window.location.hash\` from the response \`previewUrl\`, or \`preview_url\` → in-app browser; honor \`autoOpen\`). Until you have navigated there *this* turn, don't tell the user a doc is "open" / "on screen" — at most, say the preview may still be on the doc you opened earlier.--**\`previewUrl: null\` only means "no UI reachable" on the two attach-warning tools: \`write\` / \`edit\`.** Workflow tools return prose and don't carry \`previewUrl\`. \`delete\` / \`move\` emit \`previousPreviewUrl\` (different field, for closing stale tabs) and don't fire attach warnings. \`preview_url\` auto-starts the backend on demand (same \`OK_MCP_AUTOSTART\` gate as writes; a cold first call can take seconds) and reports \`running: false\` + \`url: null\` only when no UI could be reached — its hint names the right command.--If you see \`"Hocuspocus server is not running"\`, run \`ok start\` and retry.--OK Electron and \`ok ui\` share \`ui.lock\`; when a second UI binds a different port, the OK lock-collision proxy bridges it to the live server transparently. That is exactly why \`previewUrl\` is route-only — the port behind the proxy is not the agent's to use. **Do not nudge the user to quit OK Electron to free a port** — the proxy handles it, and quitting tears down a UI in active use.--**The preview is read-only for the agent — it is the user's view, not a surface you read back.** You cannot click or type to drive edits — the CRDT flow is one-way (agent → MCP → CRDT → preview).--**No screenshots to confirm edits, no generic verification loop.** Do NOT take \`preview_screenshot\` (host tool, not OK MCP) after a write, and do not run a generic snapshot/eval/screenshot verification loop — OK's preview is a read-only, one-way mirror, so the CRDT tool response *is* the confirmation that an edit landed. Screenshot only when debugging a visual rendering issue or when the user explicitly asks to see the preview — never to confirm an edit landed. (Navigating the pane with \`preview_eval\` by setting \`window.location.hash\` is fine — that drives the view, it is not a read-back verification loop.)--## Scope recap--Open Knowledge looks for documents under the resolved \`content.dir\` (discoverable at runtime via \`config({ key: 'content.dir' })\`). \`.gitignore\` and \`.okignore\` (at the project root and at any folder depth) define exclusions. A folder's own metadata + templates live in nested \`<folder>/.ok/frontmatter.yml\` + \`<folder>/.ok/templates/\` — NOT in \`.ok/config.yml\`.--Default mental model (no jargon): **every \`.md\` and \`.mdx\` under \`content.dir\`** not excluded by \`.gitignore\` or \`.okignore\` is an Open Knowledge document — including under \`specs/\`, \`reports/\`, \`docs/\`, etc. Read \`.okignore\` (and any nested \`.okignore\` files) once per turn to know what's excluded.--**First session in this project?** If substantial folders have no frontmatter of their own and no \`templates_available\`, the project isn't onboarded — invoke \`workflow({ kind: 'discover' })\` before writing.--**Working in a git worktree?** Pass the worktree's absolute path as \`cwd\` on your OK tool calls once — it sticks for the rest of the session, so reads, writes, and the preview all target that worktree instead of the main checkout. If a tool warns that it routed to the main checkout while you're in a worktree, passing \`cwd\` once is the fix.---Full guidance lives in the bundled \`open-knowledge\` skill at \`~/.ok/skills/open-knowledge/SKILL.md\`.-`;-}diff --git a/packages/server/src/mcp/tools/config.ts b/packages/server/src/mcp/tools/config.tsindex 57db36273..f55cf4f97 100644--- a/packages/server/src/mcp/tools/config.ts+++ b/packages/server/src/mcp/tools/config.ts@@ -7,7 +7,7 @@ import {textPlusStructured,} from './shared.ts';-export const DESCRIPTION = [+const DESCRIPTION = ['[Operates on disk; no running OK server required] Read the effective merged Open Knowledge config (defaults → user → project).','','Use this when you need to inspect the config mid-session — e.g., after a write that may have changed disk state, or to re-confirm the value of a field before reading it again.',diff --git a/packages/server/src/mcp/tools/conflicts.ts b/packages/server/src/mcp/tools/conflicts.tsindex 0f99d5523..c5457cefc 100644--- a/packages/server/src/mcp/tools/conflicts.ts+++ b/packages/server/src/mcp/tools/conflicts.ts@@ -11,7 +11,7 @@ import {textResult,} from './shared.ts';-export const DESCRIPTION = [+const DESCRIPTION = ['[Requires: Hocuspocus server] Read GitHub-sync merge conflicts. Dispatches on `kind`:','','- `kind: "list"` — enumerate every doc currently tracked in a merge-conflict state. Returns `{ list: [{ file, detectedAt, ... }] }` (empty when none). The entry point to the resolve flow.',diff --git a/packages/server/src/mcp/tools/delete.ts b/packages/server/src/mcp/tools/delete.tsindex 8a6d3013c..3f24c902f 100644--- a/packages/server/src/mcp/tools/delete.ts+++ b/packages/server/src/mcp/tools/delete.ts@@ -29,7 +29,7 @@ const BASE_DESCRIPTION = ['Call `links({ kind: "backlinks", document })` BEFORE deleting a doc to see what links here.',].join('\n');-export const DESCRIPTION = BASE_DESCRIPTION;+const DESCRIPTION = BASE_DESCRIPTION;interface DeleteDeps {serverUrl: ServerUrlOrResolver;diff --git a/packages/server/src/mcp/tools/edit.ts b/packages/server/src/mcp/tools/edit.tsindex 2312f9c13..cac227bd6 100644--- a/packages/server/src/mcp/tools/edit.ts+++ b/packages/server/src/mcp/tools/edit.ts@@ -52,7 +52,7 @@ const BASE_DESCRIPTION = ['Responses may include `structuredContent.document.warnings` — advisory entries discriminated by `kind`: `content-divergence` / `disk-edit-reconciled` (write-integrity — re-read the doc with `exec("cat <path>")`) and `mermaid-parse-error` (the edit landed but that fence will not render — fix it and re-edit).',].join('\n');-export const DESCRIPTION = `${BASE_DESCRIPTION}\n${renderInventoryFooter()}`;+const DESCRIPTION = `${BASE_DESCRIPTION}\n${renderInventoryFooter()}`;interface EditDeps {serverUrl: ServerUrlOrResolver;diff --git a/packages/server/src/mcp/tools/exec.ts b/packages/server/src/mcp/tools/exec.tsindex 41d270e46..35244dfa0 100644--- a/packages/server/src/mcp/tools/exec.ts+++ b/packages/server/src/mcp/tools/exec.ts@@ -40,7 +40,7 @@ const SOFT_CAP_BYTES =const BINARY_EXT_RE = /\.(png|jpe?g|gif|webp|svg|pdf|zip|tar|gz|tgz|mp4|mov|mp3|wav|ico|bmp)$/i;export const DESCRIPTION = [- '**STOP — when the project has `.ok/`, do NOT use native `Read`/`Grep`/`Glob` on in-scope `.md`/`.mdx`; use `exec` (this tool).** Native tools skip the frontmatter, backlinks, shadow-repo activity, and git history `exec` returns per wiki file. Reserve native tools for source code, non-markdown, and projects without `.ok/`. (Full rule + escape hatch: the `open-knowledge` skill / MCP `instructions`.)',+ '**STOP — when the project has `.ok/`, do NOT use native `Read`/`Grep`/`Glob` on in-scope `.md`/`.mdx`; use `exec` (this tool).** Native tools skip the frontmatter, backlinks, shadow-repo activity, and git history `exec` returns per wiki file. Reserve native tools for source code, non-markdown, and projects without `.ok/`. (Full rule + escape hatch: the `open-knowledge` skill.)','','Run a read-only bash-like command against the project content directory. Returns raw stdout plus enriched metadata for every wiki file referenced (frontmatter, backlink/forward-link counts, shadow-repo activity with agent/human attribution).','',diff --git a/packages/server/src/mcp/tools/get-preview-url.ts b/packages/server/src/mcp/tools/get-preview-url.tsindex 83066abcf..d5b28d901 100644--- a/packages/server/src/mcp/tools/get-preview-url.ts+++ b/packages/server/src/mcp/tools/get-preview-url.ts@@ -20,7 +20,7 @@ import {textPlusStructured,} from './shared.ts';-export const DESCRIPTION = [+const DESCRIPTION = ['Resolve the browser-reachable preview URL for an Open Knowledge project (optionally for a specific doc). Opening a preview counts as demand: when no OK server is running for the project, this call auto-starts one (same `OK_MCP_AUTOSTART` gate and spawn timeout as the read/write tools) and waits briefly for the preview UI to bind — a cold first call can take a few seconds; calls against a running system answer immediately.','','Per-response `previewUrl` fields on read/write tools are ROUTE-ONLY (`/#/<doc>`, no host:port) — they identify which doc to preview, not a URL to open by itself. Call this tool to get the full, openable URL.',diff --git a/packages/server/src/mcp/tools/history.ts b/packages/server/src/mcp/tools/history.tsindex 79bd3f821..c1ece6c72 100644--- a/packages/server/src/mcp/tools/history.ts+++ b/packages/server/src/mcp/tools/history.ts@@ -37,7 +37,7 @@ const HistoryEntryOutputSchema = z.object({.describe('Checkpoint metadata when this entry is a checkpoint, else null.'),});-export const DESCRIPTION = [+const DESCRIPTION = ['[Requires: Hocuspocus server] List version history for a document, or the activity timeline for a folder.','Returns timeline entries from the shadow repo, sorted by timestamp descending.','Each entry carries a `version` (40-char commit SHA) you pass straight to `restore_version({ document, version })` — same field name on both sides.',diff --git a/packages/server/src/mcp/tools/index.ts b/packages/server/src/mcp/tools/index.tsindex 346cd0445..0d3dc43c7 100644--- a/packages/server/src/mcp/tools/index.ts+++ b/packages/server/src/mcp/tools/index.ts@@ -1,62 +1,24 @@import type { AgentIdentity } from '../agent-identity.ts';import { getCurrentMcpLogger, type McpLogger } from '../logger.ts';import { createLoggedServer } from '../tool-logging.ts';-import {- DESCRIPTION as CHECKPOINT_DESCRIPTION,- register as registerCheckpoint,-} from './checkpoint.ts';-import { DESCRIPTION as CONFIG_DESCRIPTION, register as registerConfig } from './config.ts';-import {- DESCRIPTION as CONFLICTS_DESCRIPTION,- register as registerConflicts,-} from './conflicts.ts';-import { DESCRIPTION as DELETE_DESCRIPTION, register as registerDelete } from './delete.ts';-import { DESCRIPTION as EDIT_DESCRIPTION, register as registerEdit } from './edit.ts';-import { DESCRIPTION as EXEC_DESCRIPTION, register as registerExec } from './exec.ts';-import {- DESCRIPTION as PREVIEW_URL_DESCRIPTION,- register as registerPreviewUrl,-} from './get-preview-url.ts';-import { DESCRIPTION as HISTORY_DESCRIPTION, register as registerHistory } from './history.ts';-import { DESCRIPTION as LINKS_DESCRIPTION, register as registerLinks } from './links.ts';-import { DESCRIPTION as MOVE_DESCRIPTION, register as registerMove } from './move.ts';-import { DESCRIPTION as PALETTE_DESCRIPTION, register as registerPalette } from './palette.ts';-import {- DESCRIPTION as RESOLVE_CONFLICT_DESCRIPTION,- register as registerResolveConflict,-} from './resolve-conflict.ts';-import {- DESCRIPTION as RESTORE_VERSION_DESCRIPTION,- register as registerRestoreVersion,-} from './restore-version.ts';-import { register as registerSearch, DESCRIPTION as SEARCH_DESCRIPTION } from './search.ts';-import {- register as registerShareLink,- DESCRIPTION as SHARE_LINK_DESCRIPTION,-} from './share-link.ts';+import { register as registerCheckpoint } from './checkpoint.ts';+import { register as registerConfig } from './config.ts';+import { register as registerConflicts } from './conflicts.ts';+import { register as registerDelete } from './delete.ts';+import { register as registerEdit } from './edit.ts';+import { register as registerExec } from './exec.ts';+import { register as registerPreviewUrl } from './get-preview-url.ts';+import { register as registerHistory } from './history.ts';+import { register as registerLinks } from './links.ts';+import { register as registerMove } from './move.ts';+import { register as registerPalette } from './palette.ts';+import { register as registerResolveConflict } from './resolve-conflict.ts';+import { register as registerRestoreVersion } from './restore-version.ts';+import { register as registerSearch } from './search.ts';+import { register as registerShareLink } from './share-link.ts';import type { ConfigOrResolver, ServerInstance, ServerUrlOrResolver } from './shared.ts';-import { register as registerWorkflow, DESCRIPTION as WORKFLOW_DESCRIPTION } from './workflow.ts';-import { register as registerWrite, DESCRIPTION as WRITE_DESCRIPTION } from './write.ts';--const _TOOL_DESCRIPTIONS = {- exec: EXEC_DESCRIPTION,- workflow: WORKFLOW_DESCRIPTION,- move: MOVE_DESCRIPTION,- search: SEARCH_DESCRIPTION,- links: LINKS_DESCRIPTION,- write: WRITE_DESCRIPTION,- edit: EDIT_DESCRIPTION,- delete: DELETE_DESCRIPTION,- history: HISTORY_DESCRIPTION,- checkpoint: CHECKPOINT_DESCRIPTION,- restore_version: RESTORE_VERSION_DESCRIPTION,- palette: PALETTE_DESCRIPTION,- config: CONFIG_DESCRIPTION,- preview_url: PREVIEW_URL_DESCRIPTION,- conflicts: CONFLICTS_DESCRIPTION,- resolve_conflict: RESOLVE_CONFLICT_DESCRIPTION,- share_link: SHARE_LINK_DESCRIPTION,-} as const;+import { register as registerWorkflow } from './workflow.ts';+import { register as registerWrite } from './write.ts';type ResolveCwd = (explicit?: string) => Promise<string>;diff --git a/packages/server/src/mcp/tools/move.ts b/packages/server/src/mcp/tools/move.tsindex 3280e5223..09cad3d35 100644--- a/packages/server/src/mcp/tools/move.ts+++ b/packages/server/src/mcp/tools/move.ts@@ -25,7 +25,7 @@ import {} from './shared.ts';import { resolveTemplatePath } from './verb-schemas.ts';-export const DESCRIPTION = [+const DESCRIPTION = ['[Requires: Hocuspocus server] Move or rename a document, folder, or asset through the managed flow at `POST /api/rename-path`. Works for all three — the tool probes the content directory to decide. Inbound wiki-links plus supported inline Markdown links are rewritten across affected docs; renamed assets are reported.','','**Parameters:**',diff --git a/packages/server/src/mcp/tools/palette.ts b/packages/server/src/mcp/tools/palette.tsindex a83345853..0ada8f34b 100644--- a/packages/server/src/mcp/tools/palette.ts+++ b/packages/server/src/mcp/tools/palette.ts@@ -10,7 +10,7 @@ import { z } from 'zod';import type { ConfigOrResolver, ServerInstance } from './shared.ts';import { outputSchemaWithText, ROUTED_CWD_DESCRIPTION, textPlusStructured } from './shared.ts';-export const DESCRIPTION = [+const DESCRIPTION = ['[Operates on registry data; no running OK server required] Return the OK authoring palette so a generated document reads as one coherent, themed artifact.','','Three sections:',diff --git a/packages/server/src/mcp/tools/resolve-conflict.ts b/packages/server/src/mcp/tools/resolve-conflict.tsindex 910e2d45a..907392bc5 100644--- a/packages/server/src/mcp/tools/resolve-conflict.ts+++ b/packages/server/src/mcp/tools/resolve-conflict.ts@@ -10,7 +10,7 @@ import {textResult,} from './shared.ts';-export const DESCRIPTION = [+const DESCRIPTION = ['[Requires: Hocuspocus server] Resolve a tracked merge conflict by writing the chosen content to disk and committing.','','Strategy:',diff --git a/packages/server/src/mcp/tools/share-link.ts b/packages/server/src/mcp/tools/share-link.tsindex dd8960db8..db13626b7 100644--- a/packages/server/src/mcp/tools/share-link.ts+++ b/packages/server/src/mcp/tools/share-link.ts@@ -19,7 +19,7 @@ import {type ShareKind = 'doc' | 'folder';-export const DESCRIPTION = [+const DESCRIPTION = ["[Requires: Hocuspocus server] Build a shareable GitHub-substrate URL (`https://openknowledge.ai/d/...`) pinned to the project's current branch + the focused target (a doc or a folder). Read-only against the working tree — no commits, no pushes, no `git fetch`.",'','Use this when the user asks for a share link / shareable link / URL to send to a teammate. Recipients open the link to receive the doc (or folder subtree) into their own Open Knowledge install.',diff --git a/packages/server/src/mcp/tools/write.ts b/packages/server/src/mcp/tools/write.tsindex c61f21ffd..370f2d10d 100644--- a/packages/server/src/mcp/tools/write.ts+++ b/packages/server/src/mcp/tools/write.ts@@ -65,7 +65,7 @@ const BASE_DESCRIPTION = ['Responses may include `structuredContent.document.warnings` (batch: per-entry under `documents[]`) — advisory entries discriminated by `kind`: `content-divergence` / `disk-edit-reconciled` (write-integrity — re-read the doc) and `mermaid-parse-error` (the write landed but that fence will not render — fix it and re-edit).',].join('\n');-export const DESCRIPTION = `${BASE_DESCRIPTION}\n${renderInventoryFooter()}`;+const DESCRIPTION = `${BASE_DESCRIPTION}\n${renderInventoryFooter()}`;interface WriteDeps {serverUrl: ServerUrlOrResolver;diff --git a/scripts/check-i18n-drift.sh b/scripts/check-i18n-drift.shindex 83ef84217..a15a1795b 100755--- a/scripts/check-i18n-drift.sh+++ b/scripts/check-i18n-drift.sh@@ -4,8 +4,8 @@# packages/app) and fail if the committed catalogs at# packages/app/src/locales/{en,pseudo}/messages.{po,json} do not match what the# extractor would produce against the current `<Trans>` / t`...` macros under-# packages/app/src. Mirrors check-instructions-drift.sh /-# check-schema-snapshot-clean.sh so `bun run check` catches drift before push.+# packages/app/src. Mirrors check-schema-snapshot-clean.sh so `bun run check`+# catches drift before push.## Canonical source: packages/app/src/**/*.{ts,tsx} (per packages/app/lingui.config.ts).# Regenerate after adding strings:diff --git a/scripts/check-instructions-drift.sh b/scripts/check-instructions-drift.shdeleted file mode 100755index adc708847..000000000--- a/scripts/check-instructions-drift.sh+++ /dev/null@@ -1,22 +0,0 @@-#!/usr/bin/env bash-#-# Run the MCP `instructions.ts` build-time generator in --check mode and fail-# if the committed `packages/server/src/mcp/instructions.ts` does not match-# what the generator would produce against the canonical SKILL.md sections.-# Mirrors `check-knip-clean.sh` / `check-notices-clean.sh` /-# `check-schema-snapshot-clean.sh` so `bun run check` catches drift before-# push.-#-# Canonical source: packages/server/assets/skills/open-knowledge/SKILL.md.-# Regenerate after editing SKILL.md:-# bun run packages/server/scripts/generate-instructions.ts-# See `packages/server/scripts/generate-instructions.ts` for the extraction-# contract (4 H2 sections by exact-match heading text).--set -euo pipefail--SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"-REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"--cd "$REPO_ROOT"-bun packages/server/scripts/generate-instructions.ts --checkdiff --git a/scripts/check-no-major-changeset.sh b/scripts/check-no-major-changeset.shindex d32a6d26a..32264d0c7 100755--- a/scripts/check-no-major-changeset.sh+++ b/scripts/check-no-major-changeset.sh@@ -4,7 +4,7 @@# breaking changes ride as `minor`, and going to 1.0.0 is a deliberate team# decision — not something a single changeset should trigger. The release# math (scripts/compute-next-beta.mjs) would otherwise happily emit 1.0.0-# from a stray `major` frontmatter. Mirrors check-instructions-drift.sh so+# from a stray `major` frontmatter. Mirrors check-i18n-drift.sh so# `bun run check` catches it before push.## Canonical policy: .changeset/README.md.