Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

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.md
new file mode 100644
index 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.json
index 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.ts
index 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.md
index 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.ts
deleted file mode 100644
index 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.ts
deleted file mode 100644
index 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.ts
index 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.ts
index 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.ts
deleted file mode 100644
index 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.ts
deleted file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.sh
index 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.sh
deleted file mode 100755
index 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 --check
diff --git a/scripts/check-no-major-changeset.sh b/scripts/check-no-major-changeset.sh
index 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.