@appsoftwareltd/etherpk-mcp 0.7.0 → 0.8.0

package/dist/main.js

@@ -23,15 +23,15 @@ import * as encoding from "lib0/encoding";
 import { parse, stringify } from "yaml";
 import "fake-indexeddb/auto";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import "@codemirror/language";
-import { languages } from "@codemirror/language-data";
 import { classHighlighter, highlightTree } from "@lezer/highlight";
+import { LanguageDescription } from "@codemirror/language";
+import { languages } from "@codemirror/language-data";
 import MarkdownIt from "markdown-it";
 import katex from "katex";
 import Mustache from "mustache";
 var package_default = {
 	name: "@appsoftwareltd/etherpk-mcp",
-	version: "0.7.0",
+	version: "0.8.0",
 	license: "Elastic-2.0",
 	description: "EtherPK Headless Client: an MCP server over a synced knowledge graph, run beside the agent on the user's own machine.",
 	type: "module",
@@ -39,10 +39,11 @@ var package_default = {
 	bin: { "etherpk-mcp": "./bin/etherpk-mcp.js" },
 	files: ["bin", "dist"],
 	scripts: {
-		"build": "vite build",
+		"client-tsconfig": "pnpm --dir ../client exec svelte-kit sync",
+		"build": "pnpm client-tsconfig && vite build",
 		"check": "tsc -p tsconfig.json --noEmit",
-		"test": "vitest run",
-		"test:watch": "vitest",
+		"test": "pnpm client-tsconfig && vitest run",
+		"test:watch": "pnpm client-tsconfig && vitest",
 		"prepack": "pnpm build"
 	},
 	dependencies: {
@@ -80,7 +81,7 @@ var package_default = {
 	homepage: "https://docs.etherpk.com/using-ai-agents-with-your-notes",
 	repository: {
 		"type": "git",
-		"url": "https://github.com/appsoftwareltd/etherpk",
+		"url": "https://github.com/appsoftwareltd/etherpk-client",
 		"directory": "apps/mcp"
 	},
 	keywords: [
@@ -1393,50 +1394,6 @@ function wrapOo1Db(db) {
 	};
 }
 //#endregion
-//#region ../client/src/lib/storage/fs/frontmatter-span.ts
-/** A line that is exactly a `---` delimiter (trailing spaces and tabs allowed). */
-var DELIMITER = /^---[ \t]*\r?$/;
-/** The Frontmatter of `text`, or `null` when it has none — including an unterminated opener. */
-function frontmatterSpan(text) {
-	const firstBreak = text.indexOf("\n");
-	if (firstBreak === -1 || !DELIMITER.test(text.slice(0, firstBreak))) return null;
-	const bodyFrom = firstBreak + 1;
-	let lineStart = bodyFrom;
-	let lines = 1;
-	while (lineStart <= text.length) {
-		const nextBreak = text.indexOf("\n", lineStart);
-		const lineEnd = nextBreak === -1 ? text.length : nextBreak;
-		lines += 1;
-		if (DELIMITER.test(text.slice(lineStart, lineEnd))) {
-			let bodyTo = Math.max(bodyFrom, lineStart - 1);
-			if (bodyTo > bodyFrom && text[bodyTo - 1] === "\r") bodyTo -= 1;
-			return {
-				end: nextBreak === -1 ? text.length : nextBreak + 1,
-				lines,
-				body: text.slice(bodyFrom, bodyTo),
-				bodyFrom,
-				bodyTo
-			};
-		}
-		if (nextBreak === -1) break;
-		lineStart = nextBreak + 1;
-	}
-	return null;
-}
-/**
-* How many lines a document's [[Frontmatter]] occupies - opener and closer included - given the
-* document already split into lines, or 0 when it has none. The same rule as {@link frontmatterSpan}
-* (a lone `---` is not a block; an unterminated one is not a block), for the line-shaped consumers
-* in the editor that treat the block as opaque: the outliner's scans, the bullet dots, the guides,
-* the clamp. Those already hold `lines`, and re-joining them per keystroke to ask the text form
-* would be the only O(n) step in an otherwise line-local pass.
-*/
-function frontmatterLines(lines) {
-	if (lines.length < 2 || !DELIMITER.test(lines[0])) return 0;
-	for (let i = 1; i < lines.length; i++) if (DELIMITER.test(lines[i])) return i + 1;
-	return 0;
-}
-//#endregion
 //#region ../client/src/lib/document/fenced-code.ts
 /** A backtick fence line, tolerant of a leading plain-bullet marker (`- `) so `- ``` ` is a fence.
 *  Backticks only (this slice) — tildes are left untouched, so they are not auto-completed. */
@@ -1518,6 +1475,57 @@ function fencedBlocks(lines, closerTolerance = 0) {
 	}
 	return blocks;
 }
+/**
+* A line of a fenced block as code: the indentation up to the fence's column is structure (the
+* block's place in the outline) and goes; whatever lies past it is the code's own and stays.
+*/
+function codeLineText(line, fenceColumn) {
+	return line.length - line.trimStart().length >= fenceColumn ? line.slice(fenceColumn) : line.trimStart();
+}
+//#endregion
+//#region ../client/src/lib/storage/fs/frontmatter-span.ts
+/** A line that is exactly a `---` delimiter (trailing spaces and tabs allowed). */
+var DELIMITER = /^---[ \t]*\r?$/;
+/** The Frontmatter of `text`, or `null` when it has none — including an unterminated opener. */
+function frontmatterSpan(text) {
+	const firstBreak = text.indexOf("\n");
+	if (firstBreak === -1 || !DELIMITER.test(text.slice(0, firstBreak))) return null;
+	const bodyFrom = firstBreak + 1;
+	let lineStart = bodyFrom;
+	let lines = 1;
+	while (lineStart <= text.length) {
+		const nextBreak = text.indexOf("\n", lineStart);
+		const lineEnd = nextBreak === -1 ? text.length : nextBreak;
+		lines += 1;
+		if (DELIMITER.test(text.slice(lineStart, lineEnd))) {
+			let bodyTo = Math.max(bodyFrom, lineStart - 1);
+			if (bodyTo > bodyFrom && text[bodyTo - 1] === "\r") bodyTo -= 1;
+			return {
+				end: nextBreak === -1 ? text.length : nextBreak + 1,
+				lines,
+				body: text.slice(bodyFrom, bodyTo),
+				bodyFrom,
+				bodyTo
+			};
+		}
+		if (nextBreak === -1) break;
+		lineStart = nextBreak + 1;
+	}
+	return null;
+}
+/**
+* How many lines a document's [[Frontmatter]] occupies - opener and closer included - given the
+* document already split into lines, or 0 when it has none. The same rule as {@link frontmatterSpan}
+* (a lone `---` is not a block; an unterminated one is not a block), for the line-shaped consumers
+* in the editor that treat the block as opaque: the outliner's scans, the bullet dots, the guides,
+* the clamp. Those already hold `lines`, and re-joining them per keystroke to ask the text form
+* would be the only O(n) step in an otherwise line-local pass.
+*/
+function frontmatterLines(lines) {
+	if (lines.length < 2 || !DELIMITER.test(lines[0])) return 0;
+	for (let i = 1; i < lines.length; i++) if (DELIMITER.test(lines[i])) return i + 1;
+	return 0;
+}
 " ".repeat(2);
 /** Width of the `- ` marker, which sets a bullet's content column (`indent + MARKER_WIDTH`). */
 var MARKER_WIDTH = 2;
@@ -1729,11 +1737,17 @@ function normaliseIndentUnit(text) {
 *  3. **Continuation lines** — non-bullet lines indented to a bullet's content
 *     column belong to the *same* block (the soft-newline-within-a-block).
 *
+* A complete [[Fenced Code Block]] is opaque to all three: it belongs whole to the block its
+* opener sits in, so a blank line, a `# comment` or a `- item` inside it is code, never a block
+* boundary, a heading or a bullet. "Complete" is the editor's pairing (`fencedBlocks`), the same
+* one the outline walk (`indent-unit.ts`) takes fences whole by.
+*
 * A block has a kind (heading / paragraph / bullet / task). Blocks have no
 * persistent identity: a block is its source range in the current parse.
 *
-* Pure and DOM-free; the editor (keyboard ops, fold) and the derived index consume
-* it. See Dual Mode Editor.md.
+* Pure and DOM-free; the derived index (`index-derive.ts`) and the publisher's navigation
+* (`publish/nav.ts`) consume it. The editor reads the same outline through `indent-unit.ts`.
+* See Dual Mode Editor.md.
 */
 function indentOf(line) {
 	return line.length - line.trimStart().length;
@@ -1762,7 +1776,21 @@ function taskDone(line) {
 */
 function parseBlocks(markdown) {
 	const lines = markdown.split("\n");
-	const outline = outlineLines(lines);
+	const fences = fencedBlocks(lines);
+	const outline = outlineLines(lines, fences);
+	const fenceAt = new Map(fences.map((f) => [f.start, f]));
+	/**
+	* Add line `k` to a block's `buf` and return the line after it. A line that opens a complete
+	* fenced block brings the whole block with it, so nothing inside the fence is read as structure.
+	* A fence nested inside it starts within the range taken, so only outermost fences reach here.
+	*/
+	const take = (k, buf) => {
+		buf.push(lines[k].trimStart());
+		const fence = fenceAt.get(k);
+		if (!fence) return k + 1;
+		for (let n = k + 1; n <= fence.end; n++) buf.push(codeLineText(lines[n], fence.fenceColumn));
+		return fence.end + 1;
+	};
 	const flat = [];
 	let i = 0;
 	while (i < lines.length) {
@@ -1788,12 +1816,9 @@ function parseBlocks(markdown) {
 			const contentCol = indentOf(lines[i]) + 2;
 			const done = taskDone(lines[i]);
 			const start = i;
-			const buf = [lines[i].trimStart()];
-			i++;
-			while (i < lines.length && lines[i].trim() !== "" && headingLevel(lines[i]) === void 0 && !isBullet(lines[i]) && indentOf(lines[i]) >= contentCol) {
-				buf.push(lines[i].trimStart());
-				i++;
-			}
+			const buf = [];
+			i = take(i, buf);
+			while (i < lines.length && lines[i].trim() !== "" && headingLevel(lines[i]) === void 0 && !isBullet(lines[i]) && indentOf(lines[i]) >= contentCol) i = take(i, buf);
 			flat.push({
 				type: done === void 0 ? "bullet" : "task",
 				depth,
@@ -1805,12 +1830,9 @@ function parseBlocks(markdown) {
 			continue;
 		}
 		const start = i;
-		const buf = [lines[i].trimStart()];
-		i++;
-		while (i < lines.length && lines[i].trim() !== "" && headingLevel(lines[i]) === void 0 && !isBullet(lines[i]) && indentOf(lines[i]) === indentOf(lines[start])) {
-			buf.push(lines[i].trimStart());
-			i++;
-		}
+		const buf = [];
+		i = take(i, buf);
+		while (i < lines.length && lines[i].trim() !== "" && headingLevel(lines[i]) === void 0 && !isBullet(lines[i]) && indentOf(lines[i]) === indentOf(lines[start])) i = take(i, buf);
 		flat.push({
 			type: "paragraph",
 			depth,
@@ -1997,14 +2019,12 @@ function serialiseTags(tags) {
 /**
 * A predicate over source line numbers: is this line inside a [[Fenced Code Block]]?
 *
-* The [[Block]] model does not treat fences as opaque, so `- [ ] x` written inside a fence
-* parses as a [[Task]] like any other bullet. That was invisible while nothing listed tasks;
-* the [[Tasks View]] makes it visible, as phantom tasks lifted out of code examples. Two
-* things follow from excluding them here rather than in the block model: the editor's outliner
-* behaviour is untouched (a fence's lines still belong to their block, which is what the
-* keyboard layer expects), and a [[Protected Document]] - an `etherpk-cipher` fence - can never
-* contribute a task, whatever it holds. That last one is a rule, not an optimisation: the
-* [[Derived Index]] is plaintext at rest and outlives the session.
+* A `- [ ] x` written inside a fence must not become a [[Task]]: the [[Tasks View]] would list
+* phantom tasks lifted out of code examples. The [[Block]] model now takes a complete fence
+* whole (block-model.ts), so no task starts inside one; this scan stays for what the block model
+* cannot know, that a [[Protected Document]] - an `etherpk-cipher` fence - never contributes a
+* task, whatever it holds. That is a rule, not an optimisation: the [[Derived Index]] is
+* plaintext at rest and outlives the session.
 *
 * "Inside a fence" is the EDITOR's answer, not a second one: the column-scoped pairing of
 * `fencedBlocks` (Editor Content Rules → "Inside a block"), so a task is indexed exactly when
@@ -2040,6 +2060,15 @@ function blockLabel(block) {
 	return bulletLabel(first);
 }
 /**
+* A block as a reader sees it: the marker stripped as in its {@link blockLabel}, and every line
+* after the first kept - continuation lines and fenced code, which a label drops. What a
+* references [[View]] quotes and a semantic passage embeds.
+*/
+function blockContent(block) {
+	const newline = block.text.indexOf("\n");
+	return newline === -1 ? block.label : block.label + block.text.slice(newline);
+}
+/**
 * The label of a bullet or [[Task]] line — its marker and checkbox stripped, indentation
 * ignored. Exported because the [[Tasks View]]'s write-back guard has to ask "is the line in
 * the document still the task the index recorded?", and the only honest way to answer is with
@@ -2225,9 +2254,7 @@ var OVERLAP_MAX_CHARS = Math.floor(PASSAGE_BUDGET_CHARS / 4);
 var CRUMB = " > ";
 /** A block's text with its bullet / task / heading marker gone, continuation lines kept. */
 function blockBody(block) {
-	const newline = block.text.indexOf("\n");
-	const rest = newline === -1 ? "" : block.text.slice(newline);
-	return stripWikilinkBrackets(block.label + rest);
+	return stripWikilinkBrackets(blockContent(block));
 }
 /** `[[Physics]]` embeds as `Physics`: the brackets are syntax, not meaning. */
 function stripWikilinkBrackets(text) {
@@ -2545,7 +2572,7 @@ function createSchema(db) {
 	db.exec(SCHEMA$1);
 	db.run("INSERT OR IGNORE INTO index_metadata (key, value) VALUES ('active_generation', 1)");
 	db.run("INSERT OR IGNORE INTO index_metadata (key, value) VALUES ('revision', 0)");
-	db.exec(`PRAGMA user_version = 11`);
+	db.exec(`PRAGMA user_version = 12`);
 }
 function activeIndexGeneration(db) {
 	return db.all("SELECT value FROM index_metadata WHERE key = 'active_generation'")[0]?.value ?? 1;
@@ -2566,7 +2593,7 @@ function advanceIndexRevision(db) {
 */
 function isUsableIndex(db) {
 	try {
-		return db.all("PRAGMA user_version")[0]?.user_version === 11;
+		return db.all("PRAGMA user_version")[0]?.user_version === 12;
 	} catch {
 		return false;
 	}
@@ -3077,16 +3104,40 @@ function collectSubtree(blocks, rootId) {
 		const b = blocks[id];
 		if (!b) return;
 		out.push({
-			label: b.label,
+			text: blockContent(b),
 			depth,
-			isMatch: id === rootId
+			isMatch: id === rootId,
+			...b.kind === "task" ? { done: b.done === true } : {}
 		});
 		for (const child of childrenByParent.get(id) ?? []) walk(child.localId, depth + 1);
 	};
 	walk(rootId, 0);
 	return out;
 }
-/** Truncate `text` to MAX_CONTEXT chars centred on the match, with ellipses. */
+/**
+* Widen `[start, end)` so that neither end falls inside a complete fenced code block. Half a code
+* block is no excerpt at all, and an opener cut from its closer would render as raw backticks.
+*/
+function widenToFences(text, start, end) {
+	const lines = text.split("\n");
+	const lineStarts = [];
+	let offset = 0;
+	for (const line of lines) {
+		lineStarts.push(offset);
+		offset += line.length + 1;
+	}
+	for (const fence of fencedBlocks(lines)) {
+		const from = lineStarts[fence.start];
+		const to = lineStarts[fence.end] + lines[fence.end].length;
+		if (start > from && start < to) start = from;
+		if (end > from && end < to) end = to;
+	}
+	return [start, end];
+}
+/**
+* Truncate `text` to MAX_CONTEXT chars centred on the match, with ellipses. The window grows past
+* MAX_CONTEXT rather than cut a fenced code block in two ({@link widenToFences}).
+*/
 function truncateContext(text, matchStart, matchEnd) {
 	if (text.length <= MAX_CONTEXT) return {
 		text,
@@ -3095,17 +3146,17 @@ function truncateContext(text, matchStart, matchEnd) {
 		truncated: false
 	};
 	const mid = Math.floor((matchStart + matchEnd) / 2);
-	let start = Math.max(0, mid - Math.floor(MAX_CONTEXT / 2));
-	const end = Math.min(text.length, start + MAX_CONTEXT);
-	start = Math.max(0, end - MAX_CONTEXT);
-	const prefix = start > 0 ? "…" : "";
-	const suffix = end < text.length ? "…" : "";
+	const windowStart = Math.max(0, mid - Math.floor(MAX_CONTEXT / 2));
+	const windowEnd = Math.min(text.length, windowStart + MAX_CONTEXT);
+	const [start, end] = widenToFences(text, Math.max(0, windowEnd - MAX_CONTEXT), windowEnd);
+	const prefix = start === 0 ? "" : text[start - 1] === "\n" ? "…\n" : "…";
+	const suffix = end === text.length ? "" : text[end] === "\n" ? "\n…" : "…";
 	const shift = prefix.length - start;
 	return {
 		text: prefix + text.slice(start, end) + suffix,
 		matchStart: Math.max(0, matchStart + shift),
 		matchEnd: Math.max(0, matchEnd + shift),
-		truncated: true
+		truncated: prefix !== "" || suffix !== ""
 	};
 }
 /** Build a reference: a block subtree for bullets/tasks, prose context otherwise. */
@@ -3167,7 +3218,7 @@ function backlinksFor(db, concept) {
          WHERE p.generation=? AND l.concept_key IN (${placeholders})`, [generation, ...names]);
 	const blocksByPage = /* @__PURE__ */ new Map();
 	for (const pid of new Set(hits.map((h) => h.page_id))) {
-		const rows = db.all("SELECT local_id, parent_local_id, ord, kind, depth, label, text FROM blocks WHERE page_id=? ORDER BY local_id", [pid]);
+		const rows = db.all("SELECT local_id, parent_local_id, ord, kind, depth, done, label, text FROM blocks WHERE page_id=? ORDER BY local_id", [pid]);
 		const blocks = [];
 		for (const r of rows) blocks[r.local_id] = {
 			localId: r.local_id,
@@ -3175,6 +3226,7 @@ function backlinksFor(db, concept) {
 			ord: r.ord,
 			kind: r.kind,
 			depth: r.depth,
+			...r.done === null ? {} : { done: r.done === 1 },
 			startLine: 0,
 			endLine: 0,
 			text: r.text,
@@ -3854,19 +3906,25 @@ function folderCacheDir(env, folderPath) {
 function cacheRoot(env) {
 	return env.ETHERPK_MCP_CACHE_DIR?.trim() || join(env.XDG_CACHE_HOME?.trim() || join(homedir(), ".cache"), "etherpk", "mcp");
 }
+/**
+* The files this build reads and writes in a graph's directory, by name: the cache, the index,
+* and the [[Embedding]] store beside the index with a stamp of its own (ADR 0076) - an index
+* schema bump discards `index.v<N>` and leaves the vectors alone, because their rows cost
+* minutes to re-derive where the index's cost a second. `removeStaleFiles` keeps exactly these
+* names, so they are declared once here and joined to a directory below; a name is never
+* recovered from a joined path (see there).
+*/
+var CACHE_FILE_NAME = `local-cache.v${CACHE_DB_VERSION}.bin`;
+var INDEX_FILE_NAME = `index.v12.sqlite`;
+var VECTORS_FILE_NAME = `vectors.v1.sqlite`;
 function cacheFile(dir) {
-	return join(dir, `local-cache.v${CACHE_DB_VERSION}.bin`);
+	return join(dir, CACHE_FILE_NAME);
 }
 function indexFile(dir) {
-	return join(dir, `index.v11.sqlite`);
+	return join(dir, INDEX_FILE_NAME);
 }
-/**
-* The [[Embedding]] store, beside the index but with its own stamp (ADR 0076): an index
-* schema bump discards `index.v<N>` and leaves this file alone, because its rows cost minutes
-* to re-derive where the index's cost a second.
-*/
 function vectorsFile(dir) {
-	return join(dir, `vectors.v1.sqlite`);
+	return join(dir, VECTORS_FILE_NAME);
 }
 function request(req) {
 	return new Promise((resolve, reject) => {
@@ -3997,10 +4055,10 @@ var ABANDONED_TMP_AFTER_MS = 10 * 6e4;
 */
 async function removeStaleFiles(dir, now = Date.now()) {
 	const keep = new Set([
-		cacheFile(dir),
-		indexFile(dir),
-		vectorsFile(dir)
-	].map((f) => f.split("/").pop()));
+		CACHE_FILE_NAME,
+		INDEX_FILE_NAME,
+		VECTORS_FILE_NAME
+	]);
 	const removed = [];
 	for (const name of await readdir(dir).catch(() => [])) {
 		const stale = /^(index|vectors)\.v\d+\.sqlite$/.test(name) && !keep.has(name);
@@ -4643,13 +4701,8 @@ var performanceRecorder = createPerformanceRecorder({ enabled: typeof window !==
 var ENTITLEMENT_AUDIENCE = "urn:etherpk:sync-entitlements";
 var ENTITLEMENT_SERVICE = "managed-sync";
 /**
-* Version-agnostic, like `isUuid` on the Server. The subject was matched by four different
-* hand-rolled patterns that happened to agree only because billing account ids are v4 today:
-* one accepted v1 to v5, another v1 to v8, another any 36 characters of hex and dashes
-* (quality audit B4). If an id ever became a uuidv7 - which is what better-auth already mints
-* - the strictest of them would have silently stopped matching, and the Stripe webhook's
-* metadata fallback would have answered 409 "Unknown Stripe customer" for a real subscription.
-* One pattern, here, next to the claim it belongs to.
+* Version-agnostic, like `isUuid` on the Server: any UUID version matches, so an id minted as a
+* uuidv7 is recognised as readily as a v4. One pattern, here, next to the claim it belongs to.
 */
 var ENTITLEMENT_SUBJECT_PATTERN = /^billing-account:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 var httpsUrl = z.url().refine((value) => {
@@ -5087,7 +5140,7 @@ function createSyncProtocol(overrides = {}) {
 }
 var defaultProtocol = createSyncProtocol();
 defaultProtocol.parseClientMessage;
-var parseServerMessage$1 = defaultProtocol.parseServerMessage;
+var parseServerMessage = defaultProtocol.parseServerMessage;
 var serializeClientMessage$1 = defaultProtocol.serializeClientMessage;
 defaultProtocol.serializeServerMessage;
 //#endregion
@@ -5096,13 +5149,10 @@ defaultProtocol.serializeServerMessage;
 * The asset chunking contract, shared by the Client that uploads and the Sync Server that
 * signs the upload URLs.
 *
-* These constants used to live only in the Client, which made the declared `size` on
-* `POST /api/v1/sync/assets` a number the server had to take on trust: it counted the
-* declared figure against the storage entitlement and then handed back presigned PUT URLs
-* that bound nothing, so `size: 1024` bought unlimited bytes in the bucket (quality audit
-* S2). With the contract stated here the server can derive exactly how many chunks an asset
-* of a given size has, and exactly how long each chunk's ciphertext must be, and sign that
-* length into the URL.
+* Shared so that the declared `size` on `POST /api/v1/sync/assets` is not taken on trust: from
+* the contract stated here the server derives exactly how many chunks an asset of a given size
+* has, and exactly how long each chunk's ciphertext must be, and signs that length into each
+* presigned PUT URL.
 *
 * Changing either constant is a protocol change: the Client's chunking and the Server's
 * signed lengths must move together, or every upload fails with an opaque 403.
@@ -5846,13 +5896,41 @@ function createDocSync(deps) {
 * added and checked only at the serialisation boundary so the document engine does not repeat
 * a transport constant on every operation.
 */
-/** Returns null for anything malformed, oversized or from an unsupported protocol version. */
-function parseServerMessage(raw) {
-	const result = parseServerMessage$1(raw);
-	if (!result.ok) return null;
-	const { v: _version, ...message } = result.value;
-	return message;
+function readServerMessage(raw) {
+	const result = parseServerMessage(raw);
+	if (result.ok) {
+		const { v: _version, ...message } = result.value;
+		return {
+			kind: "message",
+			message
+		};
+	}
+	if (result.code === "unsupported_version") {
+		const { v } = JSON.parse(raw);
+		if (typeof v === "number" && Number.isInteger(v)) return {
+			kind: "protocol_mismatch",
+			serverVersion: v
+		};
+	}
+	return { kind: "malformed" };
 }
+/**
+* The Sync Server speaks another sync protocol version, so nothing it sends can be read and
+* nothing this Client sends will be accepted. Retrying cannot fix it; one side has to be
+* upgraded. The message is for logs and the Headless Client; the browser maps the error to
+* its own copy in `sync-error-copy.ts`.
+*/
+var SyncProtocolMismatchError = class extends Error {
+	name = "SyncProtocolMismatchError";
+	constructor(serverVersion, clientVersion = 2) {
+		super(serverVersion < clientVersion ? `The Sync Server speaks sync protocol ${serverVersion} and this Client speaks ${clientVersion}: the server is older, and its operator needs to upgrade it.` : `The Sync Server speaks sync protocol ${serverVersion} and this Client speaks ${clientVersion}: this Client is older and needs upgrading.`);
+		this.serverVersion = serverVersion;
+		this.clientVersion = clientVersion;
+	}
+	get serverIsOlder() {
+		return this.serverVersion < this.clientVersion;
+	}
+};
 function serializeClientMessage(message) {
 	return serializeClientMessage$1({
 		v: 2,
@@ -6013,6 +6091,39 @@ function sanitizeQuickNotes(raw) {
 	}
 	return out;
 }
+new Intl.Segmenter(void 0, { granularity: "word" });
+/**
+* The spelling a dictionary is asked about: a curly apostrophe (`’`), which keyboards and
+* pastes produce, straightened, since Hunspell dictionaries spell contractions with `'`.
+*/
+function spellingForm(word) {
+	return word.replace(/’/g, "'");
+}
+/** Longer than any real word; a line this long is not one. */
+var MAX_WORD_LENGTH = 100;
+/**
+* The word as the dictionary keeps it, or null when it cannot be one entry. A curly apostrophe is
+* straightened, the form the checker compares (`spelling/words.ts` → `spellingForm`), so a word
+* added from `don’t` also accepts `don't`.
+*/
+function normaliseDictionaryWord(raw) {
+	const word = spellingForm(raw.trim().normalize("NFC"));
+	if (word === "" || /\s/u.test(word) || word.length > MAX_WORD_LENGTH) return null;
+	return word;
+}
+/** Well-formed words, deduped (first seen wins), capped: tolerant of a peer's or a newer client's list. */
+function sanitizeDictionaryWords(raw) {
+	if (!Array.isArray(raw)) return [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const entry of raw) {
+		if (typeof entry !== "string") continue;
+		const word = normaliseDictionaryWord(entry);
+		if (word === null || seen.has(word)) continue;
+		seen.add(word);
+		if (seen.size >= 5e4) break;
+	}
+	return [...seen];
+}
 //#endregion
 //#region ../client/src/lib/storage/fs/frontmatter.ts
 /**
@@ -6385,6 +6496,12 @@ function createGraphSync(deps) {
 	let socket;
 	let open = false;
 	let disposed = false;
+	/**
+	* Set when the Sync Server turned out to speak another protocol version. The session then
+	* stops for good: every reconnect would meet the same server, and nothing either side
+	* sends can be read by the other. Pending appends stay in the cache for a later session.
+	*/
+	let protocolMismatch;
 	const reportError = (error) => {
 		if (!disposed) deps.onError?.(error instanceof Error ? error : new Error(String(error)));
 	};
@@ -6406,6 +6523,7 @@ function createGraphSync(deps) {
 	function waitForCurrentConnection() {
 		if (open && socket) return Promise.resolve();
 		if (disposed) return Promise.reject(/* @__PURE__ */ new Error("the graph sync session was disposed"));
+		if (protocolMismatch) return Promise.reject(protocolMismatch);
 		return new Promise((resolve, reject) => {
 			connectionWaiters.add({
 				resolve,
@@ -6445,7 +6563,7 @@ function createGraphSync(deps) {
 	}
 	/**
 	* Documents the CURRENT socket has subscribed to. The relay keeps and forwards presence
-	* only for a subscribed document (ASTRA F11), and this mirrors that rule at the source:
+	* only for a subscribed document, and this mirrors that rule at the source:
 	* y-protocols renews every engine's awareness state every fifteen seconds, and an engine
 	* created for a background walk starts with an empty `{}` state, so without the gate every
 	* unretained engine encrypted and sent presence the relay would only drop. Cleared with
@@ -6463,9 +6581,9 @@ function createGraphSync(deps) {
 	}
 	/**
 	* Subscribe to every retained document on a freshly opened socket, in batches the relay
-	* accepts. One message used to carry the whole set, and above the protocol's per-message
-	* limit the relay rejects it as invalid, which left a tab with many open views silently
-	* without live updates for anything after a reconnect (ASTRA F11).
+	* accepts. Above the protocol's per-message limit the relay rejects a subscribe as invalid,
+	* which would leave a tab with many open views silently without live updates after a
+	* reconnect.
 	*/
 	function subscribeRetained() {
 		const docIds = [...retained.keys()];
@@ -6603,6 +6721,7 @@ function createGraphSync(deps) {
 	if (deps.onRegistryChange) registryMap.observe(() => deps.onRegistryChange?.());
 	const metaMap = root.doc.getMap("meta");
 	const quickNotesArray = root.doc.getArray("quickNotes");
+	const dictionaryMap = root.doc.getMap("spellingDictionary");
 	const themesMap = root.doc.getMap("themes");
 	/** A stored theme as a plain object, or null when the entry is not one. */
 	function readTheme(id) {
@@ -6656,9 +6775,23 @@ function createGraphSync(deps) {
 			publishNameOnceCaughtUp();
 		}, () => {});
 	}
+	/** Report once, fail everything waiting for a connection, and close without reconnecting. */
+	function stopForProtocolMismatch(serverVersion) {
+		if (protocolMismatch) return;
+		protocolMismatch = new SyncProtocolMismatchError(serverVersion);
+		reportError(protocolMismatch);
+		for (const waiter of connectionWaiters) waiter.reject(protocolMismatch);
+		connectionWaiters.clear();
+		socket?.close();
+	}
 	function handleMessage(raw) {
-		const message = parseServerMessage(raw);
-		if (!message) return;
+		const read = readServerMessage(raw);
+		if (read.kind === "protocol_mismatch") {
+			stopForProtocolMismatch(read.serverVersion);
+			return;
+		}
+		if (read.kind === "malformed") return;
+		const message = read.message;
 		if (message.type === "catchup_batch") performanceRecorder.mark("sync.catchup.batch", {
 			rows: message.updates.length,
 			bytes: new TextEncoder().encode(raw).byteLength,
@@ -6704,7 +6837,7 @@ function createGraphSync(deps) {
 	* on open. Only rebuildable snapshot uploads use a volatile queue.
 	*/
 	function connect() {
-		if (disposed) return;
+		if (disposed || protocolMismatch) return;
 		deps.token().then((token) => {
 			if (disposed) return;
 			const s = deps.connect(`${deps.relayUrl}?token=${encodeURIComponent(token)}`);
@@ -6746,7 +6879,7 @@ function createGraphSync(deps) {
 					pending.reject(new WatermarkConnectionInterruptedError());
 				}
 				watermarkRequests.clear();
-				if (!disposed) setTimeout(connect, RECONNECT_MS);
+				if (!disposed && !protocolMismatch) setTimeout(connect, RECONNECT_MS);
 			});
 		}, () => {
 			if (!disposed) setTimeout(connect, TOKEN_RETRY_MS);
@@ -6853,6 +6986,21 @@ function createGraphSync(deps) {
 				return () => quickNotesArray.unobserve(listener);
 			}
 		}),
+		spellingDictionary: () => ({
+			list: () => sanitizeDictionaryWords([...dictionaryMap.keys()]),
+			add(word) {
+				dictionaryMap.set(word, true);
+			},
+			remove(words) {
+				root.doc.transact(() => {
+					for (const word of words) dictionaryMap.delete(word);
+				});
+			},
+			observe(listener) {
+				dictionaryMap.observe(listener);
+				return () => dictionaryMap.unobserve(listener);
+			}
+		}),
 		themes: () => ({
 			list() {
 				const out = [];
@@ -9449,6 +9597,16 @@ function isCalendarDay(value) {
 function isJournalConcept(concept) {
 	return isCalendarDay(concept);
 }
+/**
+* Why a [[Page]] cannot be called `day`: a day is the name of that day's [[Journal Entry]].
+*
+* A page given one sits in `pages/` answering to the day, which is what an older version left
+* behind when a Draft for a date promoted to a page. Creating a page and renaming one both
+* refuse with this, on both backends, so the copy is the same wherever the user meets it.
+*/
+function dayIsNotAPageName(day) {
+	return `“${day.trim()}” is a date, and a date is the name of that day's journal entry, so a page cannot be called that. Choose a different name.`;
+}
 //#endregion
 //#region ../client/src/lib/document/wikilink/rename.ts
 /**
@@ -9730,11 +9888,17 @@ var RenameUnconfirmedError = class extends Error {
 * journal-shaped [[Pageless Concept]] (a day nobody has written yet) is refused for the same
 * reason: its name is its day whether or not the entry exists.
 *
+* The same holds in the other direction: a page renamed TO a day is refused, rather than left
+* in `pages/` answering to the day or merged into its journal entry with a `title` block the
+* entry never carries (ADR 0056).
+*
 * A collision is NOT a refusal (ADR 0038 §4): it is a [[Merge]], confirmed in the dialog.
 */
 function renameRefusal(options) {
-	if (options.to.trim() === "") return "A page needs a non-empty name.";
+	const to = options.to.trim();
+	if (to === "") return "A page needs a non-empty name.";
 	if (options.kind === "journal" || options.kind === null && isJournalConcept(options.from)) return "A journal entry cannot be renamed - its name is its date, and there is exactly one per day.";
+	if (options.kind === "page" && isJournalConcept(to)) return dayIsNotAPageName(to);
 	return null;
 }
 /** Every step, direct first - what an applier iterates. */
@@ -9890,17 +10054,29 @@ function reconcileDecision({ dirty, baseText, diskText }) {
 //#endregion
 //#region ../client/src/lib/storage/fs/scan.ts
 var SCANNED_SUBDIRS = ["journals", "pages"];
-function isMarkdown(name) {
+/** Whether a listed name is a document file: `.md`, in any case. A `.crswap` swap file is not. */
+function isDocumentFile(name) {
 	return /\.md$/i.test(name);
 }
-async function scanGraph(adapter) {
+function fileKey(subdir, fileName) {
+	return `${subdir}/${fileName}`;
+}
+async function scanGraph(adapter, options = {}) {
+	const previous = /* @__PURE__ */ new Map();
+	for (const entry of options.previous ?? []) previous.set(fileKey(entry.subdir, entry.fileName), entry);
+	const writeInFlight = options.writeInFlight ?? (() => false);
 	const journals = [];
 	const pages = [];
 	for (const subdir of SCANNED_SUBDIRS) {
 		const kind = documentKindOf(subdir);
 		if (!kind) continue;
 		for (const { name, lastModified, size } of await adapter.list(subdir)) {
-			if (!isMarkdown(name)) continue;
+			if (!isDocumentFile(name)) continue;
+			const known = previous.get(fileKey(subdir, name));
+			if (known !== void 0 && (known.lastModified === lastModified && known.size === size || writeInFlight(subdir, name))) {
+				(kind === "journal" ? journals : pages).push(known);
+				continue;
+			}
 			const { text } = await adapter.read(subdir, name);
 			const fm = parseFrontmatter(text);
 			const concept = kind === "journal" ? journalConceptOf(name) : conceptOf$1(fm, fileStem(name));
@@ -9933,7 +10109,7 @@ async function scanGraph(adapter) {
 * debounce) so it is exercised in Node over createMemoryDirectoryAdapter before
 * any browser code exists.
 *
-* Async-seam note (see docs/docs/technical/Document Editor.md): the seam's
+* Async-seam note: the seam's
 * `getText()` is synchronous but disk reads are async, so `open()` returns a
 * handle whose buffer is empty on first open and is hydrated by an internal
 * awaited read that then notifies subscribers the *external* way — which is safe
@@ -10039,9 +10215,22 @@ function createFilesystemDocumentStore(adapter, options = {}) {
 		open.set(doc.key, doc);
 		for (const listener of documentRenamed) listener(from, entry.concept);
 	}
-	/** Replace the registry from a fresh scan; fire onDocumentsChanged iff it changed. */
+	/**
+	* Replace the registry from a fresh scan; fire onDocumentsChanged iff it changed. The scan
+	* is given the entries it has and reuses each whose file has not moved, so a pass over an
+	* unchanged graph reads nothing, and it is told which files have a write in flight so it
+	* never opens one the store is saving - on Windows that read handle would make the
+	* browser's rename of its swap file over the target fail. A fresh store has no entries, so
+	* graph open reads every file and learns every identity.
+	*/
 	async function refreshRegistry() {
-		const entries = await scanGraph(adapter);
+		const entries = await scanGraph(adapter, {
+			previous: registry.values(),
+			writeInFlight: (subdir, fileName) => {
+				for (const doc of open.values()) if (doc.saving && doc.subdir === subdir && doc.fileName === fileName) return true;
+				return false;
+			}
+		});
 		registry.clear();
 		for (const entry of entries) registry.set(entry.key, entry);
 		const sig = registrySignature(entries);
@@ -10484,6 +10673,7 @@ function createFilesystemDocumentStore(adapter, options = {}) {
 		async createPage(title, body = "") {
 			const concept = title.trim();
 			if (concept === "") throw new Error("A page needs a non-empty title.");
+			if (isJournalConcept(concept)) throw new Error(dayIsNotAPageName(concept));
 			const key = conceptKey(concept);
 			if (registry.get(key)) throw new Error(`A document for "${concept}" already exists.`);
 			await adapter.ensureSkeleton();
@@ -10604,6 +10794,7 @@ function describeFilesystemSaveFailure(error, concept) {
 		case "NoModificationAllowedError": return `${opening} The file is locked by another program - a sync tool, or an editor holding it open. Close that, then retry. ${KEPT}`;
 		case "NotFoundError": return `${opening} The folder is no longer where it was - a drive unplugged, or the folder moved. Make it available again, then retry. ${KEPT}`;
 		case "NotReadableError": return `${opening} The file could not be read when it was opened, so nothing is written over it. Once it can be read the app reloads it, or asks you to choose if you have typed since. ${KEPT}`;
+		case "InvalidStateError": return `${opening} Another program was using the file at the same time. Retry in a moment. If it keeps happening, check what else is using this folder. ${KEPT}`;
 		default: return `${opening}${error instanceof Error && error.message ? ` The browser reported: ${error.message}.` : ""} Retry in a moment. ${KEPT}`;
 	}
 }
@@ -11340,6 +11531,7 @@ function createServerDocumentStore(graph, options) {
 			return day;
 		},
 		async createPage(title, body = "") {
+			if (isJournalConcept(title)) throw new Error(dayIsNotAPageName(title));
 			if (docIdFor(title)) throw new Error(`A page for "${title}" already exists`);
 			const docId = crypto.randomUUID();
 			registry.set(docId, {
@@ -12221,17 +12413,22 @@ async function openHeadlessFolder(deps) {
 	});
 	const indexHost = deps.persistDir ? nodeIndexHost(deps.persistDir) : void 0;
 	/**
-	* The folder's listing as one string: every document file's name, mtime and size. The
-	* store's own reconcile re-reads every file to learn titles and aliases, which is right
-	* for the browser's poll but too much for a pass before every tool call on a large
-	* graph, so a pass first lists the two document subdirectories - a stat per file, no
-	* reads - and runs the full reconcile only when this differs from the last pass. An
-	* edit that keeps both mtime and size (an mtime-preserving copy) is missed until
+	* The folder's listing as one string: every document file's name, mtime and size. A pass
+	* first lists the two document subdirectories - a stat per file, no reads - and runs the
+	* store's reconcile only when this differs from the last pass, so a pass before every
+	* tool call on a large graph costs nothing when nothing moved. Only document files count:
+	* a browser saving into the same folder writes a `.crswap` swap file first and renames it
+	* over the document when the save lands, and a pass started by the swap file would read
+	* the documents while that rename is due, which on Windows makes the browser's save fail.
+	* An edit that keeps both mtime and size (an mtime-preserving copy) is missed until
 	* something else changes, the same blind spot the store's own fast path accepts.
 	*/
 	const listingSignature = async () => {
 		const parts = [];
-		for (const subdir of ["journals", "pages"]) for (const entry of await deps.adapter.list(subdir)) parts.push(`${subdir}/${entry.name}@${entry.lastModified}:${entry.size}`);
+		for (const subdir of ["journals", "pages"]) for (const entry of await deps.adapter.list(subdir)) {
+			if (!isDocumentFile(entry.name)) continue;
+			parts.push(`${subdir}/${entry.name}@${entry.lastModified}:${entry.size}`);
+		}
 		return parts.sort().join("|");
 	};
 	let lastListing;
@@ -13312,31 +13509,48 @@ function archiveHtml(journals) {
 	return `<ul class="journal-archive">${journals.map((j) => `<li><time datetime="${escapeHtml$6(j.date ?? "")}">${escapeHtml$6(j.date ?? "")}</time> <a href="${escapeHtml$6(j.url)}">${escapeHtml$6(j.title)}</a>${j.excerpt ? `<p>${escapeHtml$6(j.excerpt)}</p>` : ""}</li>`).join("")}</ul>`;
 }
 //#endregion
-//#region ../client/src/lib/document/publish/highlight.ts
-function escapeHtml$5(text) {
-	return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
-}
+//#region ../client/src/lib/document/code-languages.ts
+/**
+* The grammar for a [[Fenced Code Block]]'s info-string, from the registry the editor nests inside
+* fences (`@codemirror/language-data`, see `view/augmentations/code-highlight.ts`). Every surface
+* that highlights code outside an editor - the publisher (`publish/highlight.ts`) and the
+* read-only quotes (`code-tokens.ts`) - resolves a language here, so each knows the languages
+* the editor knows, by the same names and aliases.
+*
+* The match is exact: a language's name or one of its aliases, in any case. The editor's own
+* lookup (`@codemirror/lang-markdown`) also matches an alias found inside the info-string, which
+* reads `text`, `plaintext` and `context` as LaTeX (alias `tex`), so a plain-text block turned
+* into a LaTeX one, `%` starting a comment. That fuzzy step is not repeated here.
+*/
 var loaded = /* @__PURE__ */ new Map();
-function describe(lang) {
-	const byName = languages.find((d) => d.name.toLowerCase() === lang.toLowerCase());
-	if (byName) return byName;
-	return languages.find((d) => d.alias.some((a) => a.toLowerCase() === lang.toLowerCase())) ?? null;
-}
 /** The grammar for an info-string, loaded once; null for a language the editor does not know either. */
-async function loadLanguage(lang) {
+async function loadCodeLanguage(lang) {
 	const key = lang.toLowerCase();
 	let pending = loaded.get(key);
 	if (!pending) {
-		const description = describe(key);
+		const description = LanguageDescription.matchLanguageName(languages, key, false);
 		pending = description ? description.load().catch(() => null) : Promise.resolve(null);
 		loaded.set(key, pending);
 	}
 	return pending;
 }
+//#endregion
+//#region ../client/src/lib/document/publish/highlight.ts
+/**
+* Code highlighting for the site with the grammars the editor already ships: the same
+* `@codemirror/language-data` registry `code-highlight.ts` nests inside fences, resolved by
+* `code-languages.ts`, run headless over the fence's text and emitted as `<span class="tok-…">`
+* (the `classHighlighter` names), so a site knows exactly the languages the editor knows and needs
+* no script for it. A theme colours the `tok-*` classes. Unknown languages come back as null and
+* render escaped.
+*/
+function escapeHtml$5(text) {
+	return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
 /** The fence's code as highlighted HTML (the `<code>` element's inner HTML), or null when the language is unknown. */
 async function highlightCode(lang, code) {
 	if (lang === "") return null;
-	const support = await loadLanguage(lang);
+	const support = await loadCodeLanguage(lang);
 	if (!support) return null;
 	const tree = support.language.parser.parse(code);
 	let out = "";
@@ -15510,7 +15724,7 @@ async function backlinks(graph, concept) {
 				kind: ref.kind,
 				line: ref.line,
 				breadcrumb: ref.breadcrumb,
-				text: ref.kind === "block" ? ref.subtree.map((node) => node.label).join("\n") : ref.context?.text ?? ""
+				text: ref.kind === "block" ? ref.subtree.map((node) => node.text).join("\n") : ref.context?.text ?? ""
 			}))
 		}))
 	};
@@ -17363,6 +17577,24 @@ async function isGraphFolder(root) {
 	return true;
 }
 //#endregion
+//#region src/serve-lifetime.ts
+/** Bind every end to one single-flight shutdown; returns it, for an end the caller finds itself. */
+function bindServeLifetime(deps) {
+	let ending;
+	const shutdown = (end) => ending ??= deps.shutdown(end);
+	let spoken = false;
+	deps.stdin.once("data", () => {
+		spoken = true;
+	});
+	deps.stdin.once("end", () => {
+		if (spoken) shutdown("the client closed stdin");
+	});
+	deps.signals.on("SIGINT", () => void shutdown("SIGINT"));
+	deps.signals.on("SIGTERM", () => void shutdown("SIGTERM"));
+	deps.transportClosed(() => void shutdown("the transport closed"));
+	return shutdown;
+}
+//#endregion
 //#region src/main.ts
 /**
 * `etherpk-mcp`: the [[Headless Client]]'s command line (ADR 0072).
@@ -17830,14 +18062,19 @@ async function serveGraph(graph, graphName, args) {
 		cmd: CMD
 	});
 	const transport = new StdioServerTransport();
-	const shutdown = async () => {
-		await graph.settle().catch(() => {});
-		await graph.dispose().catch(() => {});
-		process.exit(0);
-	};
-	process.on("SIGINT", () => void shutdown());
-	process.on("SIGTERM", () => void shutdown());
-	transport.onclose = () => void shutdown();
+	bindServeLifetime({
+		signals: process,
+		stdin: process.stdin,
+		transportClosed: (listener) => {
+			transport.onclose = listener;
+		},
+		async shutdown(end) {
+			console.error(`etherpk-mcp: ${end}; flushing and exiting.`);
+			await graph.settle().catch(() => {});
+			await graph.dispose().catch(() => {});
+			process.exit(0);
+		}
+	});
 	await server.connect(transport);
 	console.error(`etherpk-mcp: serving "${graphName}" over stdio as "Agent on ${hostname()}".`);
 	chromiumStatus(process.env, CMD).then((chromium) => {