@appsoftwareltd/etherpk-mcp 0.4.3 → 0.6.0

package/dist/main.js

@@ -1,31 +1,31 @@
 import { createRequire } from "node:module";
 import { createInterface } from "node:readline/promises";
 import { availableParallelism, homedir, hostname } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
 import { parseArgs } from "node:util";
-import { chmod, mkdir, readFile, readdir, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
+import { access, chmod, mkdir, readFile, readdir, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { x25519 } from "@noble/curves/ed25519.js";
 import "@noble/hashes/argon2.js";
-import { dirname, join } from "node:path";
 import { spawn } from "node:child_process";
 import { createHash } from "node:crypto";
-import { createWriteStream } from "node:fs";
+import { createWriteStream, statSync, watch } from "node:fs";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { pathToFileURL } from "node:url";
 import { Tokenizer } from "@huggingface/tokenizers";
 import { deserialize, serialize } from "node:v8";
 import { parser } from "@lezer/markdown";
-import "fake-indexeddb/auto";
 import * as Y from "yjs";
 import { z } from "zod";
 import { Awareness, applyAwarenessUpdate, encodeAwarenessUpdate, removeAwarenessStates } from "y-protocols/awareness";
 import * as encoding from "lib0/encoding";
 import { parse, stringify } from "yaml";
+import "fake-indexeddb/auto";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 var package_default = {
 	name: "@appsoftwareltd/etherpk-mcp",
-	version: "0.4.3",
+	version: "0.6.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",
@@ -485,6 +485,70 @@ async function openVault(envelope, key) {
 	};
 	throw new EnvelopeError(`unexpected vault envelope kind ${envelope[1] ?? "none"}`);
 }
+var PAD_TO = 64;
+var LENGTH_PREFIX = 2;
+function graphNameAad(graphId) {
+	return contextAad("graph-name", `graph:${graphId}`);
+}
+/** Seal a name into an envelope under the keyring's current epoch. */
+async function sealGraphName(keyring, graphId, name) {
+	const trimmed = name.trim();
+	if (trimmed === "") throw new Error("graph name is empty");
+	const utf8 = new TextEncoder().encode(trimmed);
+	if (utf8.byteLength > 512) throw new Error(`graph name is too long for the envelope (${utf8.byteLength} bytes)`);
+	const padded = new Uint8Array(Math.ceil((LENGTH_PREFIX + utf8.byteLength) / PAD_TO) * PAD_TO);
+	new DataView(padded.buffer).setUint16(0, utf8.byteLength, false);
+	padded.set(utf8, LENGTH_PREFIX);
+	const epoch = currentEpoch(keyring);
+	return sealSymmetric({
+		key: epoch.key,
+		epochId: epoch.epochId,
+		plaintext: padded,
+		aad: graphNameAad(graphId)
+	});
+}
+/**
+* Read the name from an envelope, or null when this keyring cannot: a missing epoch, another graph's
+* envelope, tampered or malformed bytes. Callers treat null as "no label", never as an error,
+* because the envelope is only ever a convenience.
+*/
+async function openGraphName(keyring, graphId, envelope) {
+	try {
+		const { plaintext } = await openSymmetric({
+			keyForEpoch: (epochId) => keyForEpoch(keyring, epochId),
+			envelope,
+			aad: graphNameAad(graphId)
+		});
+		if (plaintext.byteLength < LENGTH_PREFIX) return null;
+		const length = new DataView(plaintext.buffer, plaintext.byteOffset).getUint16(0, false);
+		if (length === 0 || LENGTH_PREFIX + length > plaintext.byteLength) return null;
+		return new TextDecoder().decode(plaintext.subarray(LENGTH_PREFIX, LENGTH_PREFIX + length));
+	} catch {
+		return null;
+	}
+}
+/**
+* The write side of the envelope, for `GraphSyncDeps.publishName`. Sends are chained so two
+* renames in quick succession cannot land on the server out of order, and a failure (offline,
+* an older server without the route) is reported and does not stop the next one.
+*/
+function createGraphNamePublisher(deps) {
+	const report = deps.onError ?? ((error) => console.warn("[sync] could not publish the graph name envelope", error));
+	let chain = Promise.resolve();
+	return {
+		publish(name) {
+			chain = chain.then(async () => {
+				try {
+					const envelope = await sealGraphName(deps.keyring, deps.graphId, name);
+					await deps.api.setGraphName(deps.graphId, toBase64Url(envelope));
+				} catch (err) {
+					report(err instanceof Error ? err : new Error(String(err)));
+				}
+			});
+		},
+		settled: () => chain
+	};
+}
 //#endregion
 //#region ../client/src/lib/sync/sync-api.ts
 var SyncApiError = class extends Error {
@@ -520,6 +584,12 @@ function createSyncApi(deps) {
 		listGraphs: () => call("/api/v1/sync/graphs").then((r) => r.graphs),
 		graphsOverview: () => call("/api/v1/sync/graphs"),
 		graphStorage: (graphId) => call(`/api/v1/sync/graphs/${graphId}/storage`),
+		setGraphName: async (graphId, envelope) => {
+			await call(`/api/v1/sync/graphs/${graphId}/name`, {
+				method: "PUT",
+				body: JSON.stringify({ envelope })
+			});
+		},
 		mintSyncToken: (graphId) => call("/api/v1/sync/token", {
 			method: "POST",
 			body: JSON.stringify({ graphId })
@@ -871,7 +941,7 @@ function normalise(vector) {
 //#endregion
 //#region ../client/src/lib/document/wikilink/model.ts
 /** The concept for a matched `[[…]]` text: strip exactly the outer `[[` and `]]`. */
-function conceptOf$1(text) {
+function conceptOf$2(text) {
 	return text.slice(2, -2);
 }
 //#endregion
@@ -902,7 +972,7 @@ function parseWikilinks(input) {
 				const text = input.slice(start, end + 1);
 				links.push({
 					text,
-					concept: conceptOf$1(text),
+					concept: conceptOf$2(text),
 					start,
 					end
 				});
@@ -916,6 +986,68 @@ function parseWikilinks(input) {
 	return links;
 }
 //#endregion
+//#region ../client/src/lib/document/wikilink/derive.ts
+/**
+* The two derivations from a concept (the link's identity yields neither itself —
+* see ADR 0011). `onDiskName` is a storage convenience; `publishSlug` is the URL
+* name. Both are pure.
+*/
+/** Characters illegal in a file name on common filesystems (the AS Notes set). */
+var INVALID_FILE_CHARS = /[/?<>\\:*|"]/g;
+/**
+* The on-disk file name for a concept (sans extension). Scoped concepts keep their
+* inner `[ ]` brackets; only filesystem-illegal characters are replaced with `_`.
+* A derived convenience only — frontmatter is authoritative for identity (ADR 0007).
+*/
+function onDiskName(concept) {
+	return concept.replace(INVALID_FILE_CHARS, "_");
+}
+/** Control characters: illegal or meaningless in a file name, and invisible if kept. */
+var CONTROL_CHARS = /[\u0000-\u001f\u007f]/g;
+/** Names Windows reserves for devices, with or without an extension (case-insensitive). */
+var RESERVED_DEVICE_NAME = /^(con|prn|aux|nul|com[0-9]|lpt[0-9])$/i;
+/**
+* Longest stem written, in UTF-8 bytes. Common filesystems cap a name at 255 bytes, and the
+* mirror may add a ` (10).md` suffix to it, so this leaves room for both.
+*/
+var MAX_STEM_BYTES = 200;
+/** `value` cut to at most `maxBytes` of UTF-8, never splitting a code point. */
+function truncateToBytes(value, maxBytes) {
+	if (value.length <= maxBytes / 4) return value;
+	const encoder = new TextEncoder();
+	if (encoder.encode(value).length <= maxBytes) return value;
+	let out = "";
+	let bytes = 0;
+	for (const codePoint of value) {
+		const size = encoder.encode(codePoint).length;
+		if (bytes + size > maxBytes) break;
+		out += codePoint;
+		bytes += size;
+	}
+	return out;
+}
+/**
+* {@link onDiskName} hardened for a directory that may be carried between operating systems by
+* the user's own sync tool or version control - which is the [[Local Mirror]]'s whole purpose,
+* and true of an exported Filesystem Backend folder too.
+*
+* Beyond the illegal-character set: control characters go, Windows silently drops trailing dots
+* and spaces (so a name written here would not be the name read back), its reserved device names
+* cannot be files at all, and a very long concept would exceed the byte cap every common
+* filesystem enforces. A concept that empties out, or lands on another concept's stem (`etc` and
+* `etc.`, `A/B` and `A_B`, two titles that truncate alike), is not a loss: identity is the
+* frontmatter `title` (ADR 0007, ADR 0061), and the file name is disambiguated by the allocators -
+* `allocateFileName` in `storage/fs/filesystem-store.ts` for the Filesystem Backend and
+* `planMirrorNames` in `storage/server/mirror-names.ts` for the Local Mirror - which suffix it
+* ` (2)`, ` (3)`, ... by the rule in `storage/file-names.ts`. Never write a stem from here to
+* disk without one of them.
+*/
+function portableFileStem(concept) {
+	const trimmed = truncateToBytes(onDiskName(concept).replace(CONTROL_CHARS, "_"), MAX_STEM_BYTES).replace(/[. ]+$/, "").replace(/^\./, "_");
+	if (trimmed === "") return "_";
+	return RESERVED_DEVICE_NAME.test(trimmed) ? `${trimmed}_` : trimmed;
+}
+//#endregion
 //#region ../client/src/lib/document/wikilink/code-ranges.ts
 /**
 * Code-region detection for wikilink suppression. Rather than hand-roll a fence
@@ -3309,6 +3441,21 @@ var CACHE_STORES = [
 function graphCacheDir(env, serverBaseUrl, graphId) {
 	return join(env.ETHERPK_MCP_CACHE_DIR?.trim() || join(env.XDG_CACHE_HOME?.trim() || join(homedir(), ".cache"), "etherpk", "mcp"), new URL(serverBaseUrl).host.replace(/[^A-Za-z0-9.-]/g, "_"), graphId);
 }
+/**
+* A local folder's identity for its cache directory and its index: the folder's basename for a
+* person reading the cache root, plus a hash of the absolute path so two folders of the same
+* name stay apart. A folder carries no graph id of its own (only settings live in its
+* `etherpk/`), so the path is the identity, and moving the folder means a re-derive
+* ([[2026-09-18 Headless Client Serves A Local Folder]]).
+*/
+function folderKey(folderPath) {
+	const absolute = resolve(folderPath);
+	return `${basename(absolute).replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 40) || "folder"}-${createHash("sha256").update(absolute).digest("hex").slice(0, 12)}`;
+}
+/** Where a local folder's index and embedding store live: `local/` is its "host" under the root. */
+function folderCacheDir(env, folderPath) {
+	return join(cacheRoot(env), "local", folderKey(folderPath));
+}
 /** The root every graph's cache dir sits under, for `logout` to remove. */
 function cacheRoot(env) {
 	return env.ETHERPK_MCP_CACHE_DIR?.trim() || join(env.XDG_CACHE_HOME?.trim() || join(homedir(), ".cache"), "etherpk", "mcp");
@@ -3938,6 +4085,92 @@ async function loadEmbeddingModel(env, options = {}) {
 	};
 }
 //#endregion
+//#region src/folder-watch.ts
+/**
+* The folder watcher for `serve --folder`: `fs.watch` over the whole graph directory, feeding
+* the folder backend's reconcile pass so the index follows an edit made in an editor or by the
+* agent writing markdown directly, without waiting for the next tool call. Best-effort by
+* design: a filesystem that cannot be watched (some network mounts) is reported once and the
+* per-call reconcile carries on alone, and the debounce and coalescing live in the backend, so
+* this is only the event source ([[2026-09-18 Headless Client Serves A Local Folder]]).
+*/
+/** A `HeadlessFolderDeps.watch` over `folder`; `onError` hears a watcher that could not start or died. */
+function watchFolder(folder, onError) {
+	return (trigger) => {
+		let watcher;
+		try {
+			if (!statSync(folder, { throwIfNoEntry: false })?.isDirectory()) throw new Error(`${folder} is not a directory that can be watched`);
+			watcher = watch(folder, { recursive: true }, () => trigger());
+			watcher.on("error", (error) => {
+				onError(error instanceof Error ? error : new Error(String(error)));
+				watcher?.close();
+				watcher = void 0;
+			});
+		} catch (error) {
+			onError(error instanceof Error ? error : new Error(String(error)));
+			return () => {};
+		}
+		return () => {
+			watcher?.close();
+			watcher = void 0;
+		};
+	};
+}
+//#endregion
+//#region src/graph-labels.ts
+/**
+* Labels for the `graphs` and `serve` commands, read from the Sync Server's name envelopes
+* (ADR 0031, amended 2026-09-17) with the keyrings the account vault holds. One list call
+* labels every graph with an envelope and nothing is opened. A graph with no envelope yet - not
+* opened by any member since envelopes existed - is read from its root document once through
+* the caller's `MetaNameReader` (graph-names.ts), which publishes what it finds, so the next
+* listing needs no connection for it either. "Unnamed" therefore means the root document has
+* no name at all, or the relay could not be reached to ask.
+*/
+var NO_KEY_LABEL = "(no key on this account yet - open it in EtherPK first)";
+var NO_NAME_LABEL = "(unnamed)";
+async function graphLabel(record, vault) {
+	const keyring = vault.keyrings.find((entry) => entry.graphId === record.id);
+	if (!keyring) return { kind: "no-key" };
+	if (!record.nameEnvelope) return { kind: "unnamed" };
+	const name = await openGraphName(keyring, record.id, fromBase64Url(record.nameEnvelope));
+	return name ? {
+		kind: "named",
+		name
+	} : { kind: "unnamed" };
+}
+/** The envelope first; for a graph without one, one read of the root document (which publishes it). */
+async function resolveGraphLabel(record, vault, readMeta) {
+	const label = await graphLabel(record, vault);
+	if (label.kind !== "unnamed") return label;
+	const keyring = vault.keyrings.find((entry) => entry.graphId === record.id);
+	if (!keyring) return { kind: "no-key" };
+	const name = await readMeta(record, keyring);
+	return name ? {
+		kind: "named",
+		name
+	} : { kind: "unnamed" };
+}
+function describeGraphLabel(label) {
+	switch (label.kind) {
+		case "named": return label.name;
+		case "unnamed": return NO_NAME_LABEL;
+		case "no-key": return NO_KEY_LABEL;
+	}
+}
+/** The graph named `wanted`, compared case-insensitively, envelope or root document; null when none. */
+async function findGraphByName(records, vault, wanted, readMeta) {
+	const target = wanted.trim().toLowerCase();
+	for (const record of records) {
+		const label = await resolveGraphLabel(record, vault, readMeta);
+		if (label.kind === "named" && label.name.toLowerCase() === target) return {
+			record,
+			name: label.name
+		};
+	}
+	return null;
+}
+//#endregion
 //#region ../client/src/lib/diagnostics/performance.ts
 function assertSafeName(name) {
 	if (!/^[a-z0-9][a-z0-9._-]*$/u.test(name)) throw new Error("Performance metric names may contain only lower-case stable identifiers");
@@ -5333,6 +5566,34 @@ function createPresenceSession(identity, options = {}) {
 	};
 }
 //#endregion
+//#region ../client/src/lib/document/quick-notes.ts
+/** A hard ceiling, so a corrupt or hostile list cannot swamp the View or the root doc. */
+var MAX_QUICK_NOTES = 1e4;
+/**
+* Keep only well-formed notes, deduped by id (first seen wins) - tolerant of a hand-edited
+* `quick-notes.json`, an import from a newer client, or a peer's malformed element.
+*/
+function sanitizeQuickNotes(raw) {
+	if (!Array.isArray(raw)) return [];
+	const seen = /* @__PURE__ */ new Set();
+	const out = [];
+	for (const entry of raw) {
+		if (typeof entry !== "object" || entry === null) continue;
+		const { id, text, createdAt } = entry;
+		if (typeof id !== "string" || id.trim() === "" || seen.has(id)) continue;
+		if (typeof text !== "string" || text.trim() === "") continue;
+		if (typeof createdAt !== "number" || !Number.isFinite(createdAt)) continue;
+		seen.add(id);
+		out.push({
+			id,
+			text: text.trim(),
+			createdAt
+		});
+		if (out.length >= MAX_QUICK_NOTES) break;
+	}
+	return out;
+}
+//#endregion
 //#region ../client/src/lib/sync/graph-sync.ts
 /**
 * Graph-level sync (plan Phase 3 Task 5): one WebSocket per open graph, multiplexing all
@@ -5580,6 +5841,26 @@ function createGraphSync(deps) {
 	const registryMap = root.doc.getMap("registry");
 	if (deps.onRegistryChange) registryMap.observe(() => deps.onRegistryChange?.());
 	const metaMap = root.doc.getMap("meta");
+	const quickNotesArray = root.doc.getArray("quickNotes");
+	let publishedName;
+	let rootCaughtUpOnce = false;
+	const publishName = (name) => {
+		if (disposed || !deps.publishName) return;
+		if (typeof name !== "string" || name === "" || name === publishedName) return;
+		publishedName = name;
+		deps.publishName(name);
+	};
+	const publishNameOnceCaughtUp = () => {
+		if (rootCaughtUpOnce) publishName(metaMap.get("name"));
+	};
+	if (deps.publishName) {
+		metaMap.observe(publishNameOnceCaughtUp);
+		root.caughtUp().then(() => {
+			if (disposed) return;
+			rootCaughtUpOnce = true;
+			publishNameOnceCaughtUp();
+		}, () => {});
+	}
 	function handleMessage(raw) {
 		const message = parseServerMessage(raw);
 		if (!message) return;
@@ -5743,6 +6024,7 @@ function createGraphSync(deps) {
 		},
 		setMetaName(name) {
 			metaMap.set("name", name);
+			publishName(name);
 		},
 		setMetaSettings(settings) {
 			metaMap.set("settings", settings);
@@ -5751,6 +6033,31 @@ function createGraphSync(deps) {
 			metaMap.observe(listener);
 			return () => metaMap.unobserve(listener);
 		},
+		quickNotes: () => ({
+			list: () => sanitizeQuickNotes(quickNotesArray.toArray()),
+			add(note) {
+				quickNotesArray.push([{
+					id: note.id,
+					text: note.text,
+					createdAt: note.createdAt
+				}]);
+			},
+			remove(ids) {
+				const gone = new Set(ids);
+				root.doc.transact(() => {
+					const items = quickNotesArray.toArray();
+					for (let i = items.length - 1; i >= 0; i--) {
+						const item = items[i];
+						const id = typeof item === "object" && item !== null ? item.id : void 0;
+						if (typeof id === "string" && gone.has(id)) quickNotesArray.delete(i, 1);
+					}
+				});
+			},
+			observe(listener) {
+				quickNotesArray.observe(listener);
+				return () => quickNotesArray.unobserve(listener);
+			}
+		}),
 		connected: () => firstOpen,
 		rootCaughtUp: () => root.caughtUp(),
 		onDocUpdate(listener) {
@@ -6356,7 +6663,7 @@ function nodeTransport(url) {
 }
 //#endregion
 //#region src/graph-names.ts
-/** The graph's name, or null when it has none yet or the relay could not be reached in time. */
+/** The name in the root document's meta map, or null when it has none or the relay did not answer in time. */
 async function readGraphName(deps) {
 	const cache = await openGraphCache(`${deps.graphId}-name`);
 	const sync = createGraphSync({
@@ -6366,7 +6673,8 @@ async function readGraphName(deps) {
 		relayUrl: deps.relayUrl,
 		token: deps.token,
 		cache,
-		connect: deps.connect ?? nodeTransport
+		connect: deps.connect ?? nodeTransport,
+		publishName: deps.publishName
 	});
 	try {
 		const timeout = new Promise((resolve) => setTimeout(() => resolve("timeout"), deps.timeoutMs ?? 1e4));
@@ -7581,129 +7889,6 @@ function inlineTransport(host = memoryDbHost()) {
 		}
 	};
 }
-function createSemanticIndex(options) {
-	const { index, model } = options;
-	const floor = options.floor ?? .25;
-	const settleMs = options.settleMs ?? 1500;
-	const pauseMs = options.pauseMs ?? 100;
-	let disposed = false;
-	let running;
-	let again = false;
-	let timer;
-	let unsubscribe;
-	async function runBuild() {
-		for (;;) {
-			if (disposed) return;
-			const pending = await index.semantic.pending(model.id, 128);
-			if (pending.length === 0) break;
-			const sorted = [...pending].sort((a, b) => a.text.length - b.text.length);
-			const rows = [];
-			for (let at = 0; at < sorted.length; at += 32) {
-				const slice = sorted.slice(at, at + 32);
-				const vectors = await model.embed(slice.map((passage) => passage.text));
-				if (disposed) return;
-				slice.forEach((passage, n) => rows.push({
-					hash: passage.hash,
-					...quantise(vectors[n])
-				}));
-				if (pauseMs > 0) await new Promise((resolve) => setTimeout(resolve, pauseMs));
-			}
-			await index.semantic.put(model.id, model.dims, rows);
-			if (options.onProgress) options.onProgress(await index.semantic.status(model.id));
-		}
-		await index.semantic.sweep(model.id);
-	}
-	function build() {
-		if (running) {
-			again = true;
-			return running;
-		}
-		running = runBuild().catch((error) => options.onError?.(error instanceof Error ? error : new Error(String(error)))).finally(() => {
-			running = void 0;
-			if (again && !disposed) {
-				again = false;
-				build();
-			}
-		});
-		return running;
-	}
-	function scheduleBuild() {
-		if (disposed) return;
-		clearTimeout(timer);
-		timer = setTimeout(() => void build(), settleMs);
-	}
-	return {
-		model,
-		status: () => index.semantic.status(model.id),
-		async search(query, offset, limit) {
-			const [vector] = await model.embed([query]);
-			return index.semantic.search(model.id, vector, offset, limit, floor);
-		},
-		build,
-		follow() {
-			if (unsubscribe || disposed) return;
-			unsubscribe = index.onUpdated(scheduleBuild);
-			build();
-		},
-		dispose() {
-			disposed = true;
-			clearTimeout(timer);
-			unsubscribe?.();
-			unsubscribe = void 0;
-		}
-	};
-}
-//#endregion
-//#region ../client/src/lib/document/calendar/month-grid-core.ts
-/** `YYYY-MM-DD` for a local date — the journal file-name format (fs/identity.ts). */
-function formatISODate(date) {
-	return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}-${String(date.getDate()).padStart(2, "0")}`;
-}
-/** Today, as the ISO day the user is living in. The app's single definition of "today". */
-function todayISO(now = /* @__PURE__ */ new Date()) {
-	return formatISODate(now);
-}
-var ISO_SHAPE = /^(\d{4})-(\d{2})-(\d{2})$/;
-/**
-* The local `Date` a `YYYY-MM-DD` string names, or `null` when it names no day that exists.
-*
-* The shape test alone is not enough: `2026-02-30` and `2026-13-01` match it and are not days.
-* Round-tripping through `Date` catches both, because JS silently rolls an out-of-range field
-* forward (31 February becomes 3 March) and the re-format then disagrees with the input.
-*/
-function parseISODate(value) {
-	const match = ISO_SHAPE.exec(value.trim());
-	if (!match) return null;
-	const [, y, m, d] = match;
-	const date = new Date(Number(y), Number(m) - 1, Number(d));
-	return formatISODate(date) === value.trim() ? date : null;
-}
-/** True when `value` names a calendar day that actually exists. */
-function isCalendarDay(value) {
-	return parseISODate(value) !== null;
-}
-//#endregion
-//#region ../client/src/lib/document/journal-concept.ts
-/**
-* What makes a [[Concept]] a [[Journal Concept]] — the one predicate that decides where a
-* promoting [[Draft]] writes, and which concepts refuse to be renamed (ADR 0056).
-*
-* It is deliberately **not** the `\d{4}-\d{2}-\d{2}` shape it grew out of. While the shape only
-* guarded rename, letting `2026-13-45` through cost nothing; now that the same answer decides
-* whether a file lands in `journals/` or `pages/`, a loose test would mint a journal entry for a
-* day no calendar can display or reach again.
-*
-* Pure; no DOM, no I/O.
-*/
-/**
-* True when `concept` names a calendar day that exists — a [[Journal Entry]]'s identity.
-*
-* Journal identity is the day itself, so this is case- and alias-free: there is nothing to
-* normalise beyond surrounding whitespace.
-*/
-function isJournalConcept(concept) {
-	return isCalendarDay(concept);
-}
 //#endregion
 //#region ../client/src/lib/storage/fs/frontmatter.ts
 /**
@@ -7741,10 +7926,30 @@ function parseFrontmatter(text) {
 }
 //#endregion
 //#region ../client/src/lib/storage/fs/identity.ts
+/** The kind a content subdir holds, or `null` for non-document subdirs. */
+function documentKindOf(subdir) {
+	if (subdir === "journals") return "journal";
+	if (subdir === "pages") return "page";
+	return null;
+}
+/** Strip a single trailing `.md` extension. */
+function fileStem(fileName) {
+	return fileName.replace(/\.md$/i, "");
+}
 /** The case-insensitive identity key for a concept (display casing is preserved elsewhere). */
 function conceptKey(concept) {
 	return concept.toLowerCase();
 }
+/** The display concept name for a page: frontmatter `title` if a non-empty string, else the filename stem. */
+function conceptOf$1(fm, fileNameStem) {
+	const title = fm.data.title;
+	if (typeof title === "string" && title.trim() !== "") return title;
+	return fileNameStem;
+}
+/** The concept (ISO date) of a journal entry, derived from its filename. */
+function journalConceptOf(fileName) {
+	return fileStem(fileName);
+}
 /** The aliases declared in frontmatter (`aliases:`), as a string array; `[]` when absent/invalid. */
 function aliasesOf(fm) {
 	const aliases = fm.data.aliases;
@@ -7850,54 +8055,55 @@ function serialise(data) {
 	return Object.keys(data).length === 0 ? "" : stringify(data);
 }
 //#endregion
-//#region ../client/src/lib/document/types.ts
-var DocumentNotFoundError = class extends Error {
-	constructor(target) {
-		super(`No document for "${target}"`);
-		this.target = target;
-		this.name = "DocumentNotFoundError";
-	}
-};
-var DocumentSyncDegradedError = class extends Error {
-	constructor(target, status) {
-		super(`Document "${target}" is sync-degraded: ${status}`);
-		this.target = target;
-		this.status = status;
-		this.name = "DocumentSyncDegradedError";
-	}
-};
-//#endregion
-//#region ../client/src/lib/activity/breathe.ts
+//#region ../client/src/lib/document/calendar/month-grid-core.ts
+/** `YYYY-MM-DD` for a local date — the journal file-name format (fs/identity.ts). */
+function formatISODate(date) {
+	return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}-${String(date.getDate()).padStart(2, "0")}`;
+}
+/** Today, as the ISO day the user is living in. The app's single definition of "today". */
+function todayISO(now = /* @__PURE__ */ new Date()) {
+	return formatISODate(now);
+}
+var ISO_SHAPE = /^(\d{4})-(\d{2})-(\d{2})$/;
 /**
-* The yield-and-cancel checkpoint (plan: 2026-07-27 Import Progress And Activities).
-*
-* A long synchronous loop starves the main thread: Svelte cannot repaint, so a status
-* line jumps from nothing straight to its final value, possibly via the browser's
-* "page unresponsive" prompt. `breathe` hands control back to the event loop.
-*
-* It yields on **elapsed time, not item count**. A graph of one-line journals and a graph
-* of 5000-line pages want wildly different batch sizes, and the thing we actually care
-* about is how long a frame has been blocked - so measure that directly.
+* The local `Date` a `YYYY-MM-DD` string names, or `null` when it names no day that exists.
 *
-* The yield point is also the natural cancel checkpoint, so cancellation rides along at
-* no extra cost (ADR 0035 §3): callers thread one `AbortSignal` and get both.
-*/
-/** Longest a loop may hold the thread before yielding. ~3 frames: smooth enough to repaint, coarse enough not to dominate. */
-var SLICE_MS = 50;
-/**
-* Create a breather. Call `await breathe(signal)` inside a loop: it returns immediately
-* while the current slice has budget left, and yields when it does not. It throws the
-* signal's reason as soon as the signal aborts, whether or not it yields.
+* The shape test alone is not enough: `2026-02-30` and `2026-13-01` match it and are not days.
+* Round-tripping through `Date` catches both, because JS silently rolls an out-of-range field
+* forward (31 February becomes 3 March) and the re-format then disagrees with the input.
 */
-function createBreather(now = () => performance.now()) {
-	let lastYield = now();
-	return async (signal) => {
-		signal?.throwIfAborted();
-		if (now() - lastYield < SLICE_MS) return;
-		await new Promise((resolve) => setTimeout(resolve));
-		lastYield = now();
-		signal?.throwIfAborted();
-	};
+function parseISODate(value) {
+	const match = ISO_SHAPE.exec(value.trim());
+	if (!match) return null;
+	const [, y, m, d] = match;
+	const date = new Date(Number(y), Number(m) - 1, Number(d));
+	return formatISODate(date) === value.trim() ? date : null;
+}
+/** True when `value` names a calendar day that actually exists. */
+function isCalendarDay(value) {
+	return parseISODate(value) !== null;
+}
+//#endregion
+//#region ../client/src/lib/document/journal-concept.ts
+/**
+* What makes a [[Concept]] a [[Journal Concept]] — the one predicate that decides where a
+* promoting [[Draft]] writes, and which concepts refuse to be renamed (ADR 0056).
+*
+* It is deliberately **not** the `\d{4}-\d{2}-\d{2}` shape it grew out of. While the shape only
+* guarded rename, letting `2026-13-45` through cost nothing; now that the same answer decides
+* whether a file lands in `journals/` or `pages/`, a loose test would mint a journal entry for a
+* day no calendar can display or reach again.
+*
+* Pure; no DOM, no I/O.
+*/
+/**
+* True when `concept` names a calendar day that exists — a [[Journal Entry]]'s identity.
+*
+* Journal identity is the day itself, so this is case- and alias-free: there is nothing to
+* normalise beyond surrounding whitespace.
+*/
+function isJournalConcept(concept) {
+	return isCalendarDay(concept);
 }
 //#endregion
 //#region ../client/src/lib/document/wikilink/rename.ts
@@ -8056,6 +8262,23 @@ function cascadeFor(concepts, from, to) {
 	return out;
 }
 //#endregion
+//#region ../client/src/lib/document/types.ts
+var DocumentNotFoundError = class extends Error {
+	constructor(target) {
+		super(`No document for "${target}"`);
+		this.target = target;
+		this.name = "DocumentNotFoundError";
+	}
+};
+var DocumentSyncDegradedError = class extends Error {
+	constructor(target, status) {
+		super(`Document "${target}" is sync-degraded: ${status}`);
+		this.target = target;
+		this.status = status;
+		this.name = "DocumentSyncDegradedError";
+	}
+};
+//#endregion
 //#region ../client/src/lib/document/protection/cipher-fence.ts
 /**
 * The `etherpk-cipher` fence as it appears in document *text* — finding one, reading what it holds
@@ -8138,6 +8361,32 @@ function lastNonBlank(lines) {
 	return -1;
 }
 //#endregion
+//#region ../client/src/lib/storage/file-names.ts
+/**
+* How a document is named on disk, shared by every backend that writes a folder: the
+* [[Filesystem Backend]] (`fs/filesystem-store.ts`, `allocateFileName`) and the [[Local Mirror]]
+* (`server/mirror-names.ts`, `planMirrorNames`). One rule, the one the Logseq and Obsidian
+* converters already follow: **suffix the file name, keep the title**.
+*
+* A document's file is `<portable stem of its concept>.md`. The stem is lossy - `etc` and `etc.`,
+* `A/B` and `A_B`, `CON` and `CON_` are distinct concepts on one stem - so a second document
+* wanting a name already taken gets ` (2)`, ` (3)` and so on. The title inside is never touched:
+* identity is the frontmatter `title` (ADR 0007, ADR 0061), so a suffixed file invents no concept,
+* which is what keeps this clear of ADR 0038's refusal of `(2)` suffixes for *concept* collisions.
+* A folder either backend wrote is read back the same way by the other, and by [[Import]].
+*
+* Pure: strings only.
+*/
+/** The unsuffixed file name for a concept: its portable stem plus the markdown extension. */
+function portableFileName(concept) {
+	return `${portableFileStem(concept)}.md`;
+}
+/** `Foo.md` at index 1, `Foo (2).md` at 2, and so on. */
+function suffixedFileName(base, index) {
+	if (index <= 1) return base;
+	return `${fileStem(base)} (${index}).md`;
+}
+//#endregion
 //#region ../client/src/lib/storage/merge.ts
 /**
 * [[Merge]] (CONTEXT.md): combining two [[Document]]s that have come to share one
@@ -8269,58 +8518,910 @@ function planRename(input) {
 * used to hold only ciphertext. Refused, not worked around: there is no join that keeps both
 * documents' guarantees.
 *
-* Both stores call this after planning, with their own way of reading a concept's stored text.
-* Only the endpoints of merging steps are asked about, so a plan with no collision - the common
-* case, and the one previewed on every keystroke in the dialog - reads nothing.
+* Both stores call this after planning, with their own way of reading a concept's stored text.
+* Only the endpoints of merging steps are asked about, so a plan with no collision - the common
+* case, and the one previewed on every keystroke in the dialog - reads nothing.
+*/
+async function refuseProtectedMerges(plan, isProtected) {
+	if (plan.refusal) return plan;
+	for (const step of renameSteps(plan)) {
+		if (!step.merges) continue;
+		if (await isProtected(step.into)) return {
+			...plan,
+			refusal: `“${step.into}” is a protected document, so nothing can be merged into it. Choose a different name.`
+		};
+		if (await isProtected(step.from)) return {
+			...plan,
+			refusal: `“${step.from}” is a protected document, so it cannot be merged into “${step.to}”. Choose a name that is not already taken.`
+		};
+	}
+	return plan;
+}
+/**
+* A step merges when a DIFFERENT document already answers to the target name - by title or by
+* alias - and the source has a document to join to it. Renaming onto yourself (a pure
+* re-casing, or onto one of your own aliases) is neither. A source with no document landing
+* on a taken name redirects: its links come to point at the page that already answers to it
+* (ADR 0064 §2). `into` is that page's own title.
+*/
+function stepFor(from, to, hasDocument, existing) {
+	const holder = existing.get(conceptKey(to));
+	const taken = holder !== void 0 && conceptKey(holder) !== conceptKey(from);
+	return {
+		from,
+		to,
+		hasDocument,
+		merges: taken && hasDocument,
+		redirects: taken && !hasDocument,
+		into: taken ? holder : to
+	};
+}
+/** Nesting depth of a concept - `[[[[A]] B]] C` is deeper than `[[A]] B`. */
+function depthOf(concept) {
+	let depth = 0;
+	let max = 0;
+	for (let i = 0; i < concept.length - 1; i++) if (concept[i] === "[" && concept[i + 1] === "[") {
+		depth += 1;
+		max = Math.max(max, depth);
+		i += 1;
+	} else if (concept[i] === "]" && concept[i + 1] === "]") {
+		depth -= 1;
+		i += 1;
+	}
+	return max;
+}
+//#endregion
+//#region ../client/src/lib/storage/fs/debounce.ts
+function debounce(fn, ms) {
+	let timer;
+	let pending;
+	function clear() {
+		if (timer !== void 0) {
+			clearTimeout(timer);
+			timer = void 0;
+		}
+		pending = void 0;
+	}
+	return {
+		call(...args) {
+			pending = args;
+			if (timer !== void 0) clearTimeout(timer);
+			timer = setTimeout(() => {
+				const args = pending;
+				clear();
+				fn(...args);
+			}, ms);
+		},
+		flush() {
+			if (pending === void 0) return;
+			const args = pending;
+			clear();
+			fn(...args);
+		},
+		cancel() {
+			clear();
+		}
+	};
+}
+//#endregion
+//#region ../client/src/lib/storage/fs/reconcile.ts
+function reconcileDecision({ dirty, baseText, diskText }) {
+	if (diskText === baseText) return "noop";
+	if (!dirty) return "reload";
+	return "conflict";
+}
+//#endregion
+//#region ../client/src/lib/storage/fs/scan.ts
+var SCANNED_SUBDIRS = ["journals", "pages"];
+function isMarkdown(name) {
+	return /\.md$/i.test(name);
+}
+async function scanGraph(adapter) {
+	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;
+			const { text } = await adapter.read(subdir, name);
+			const fm = parseFrontmatter(text);
+			const concept = kind === "journal" ? journalConceptOf(name) : conceptOf$1(fm, fileStem(name));
+			const entry = {
+				kind,
+				concept,
+				key: conceptKey(concept),
+				subdir,
+				fileName: name,
+				aliases: aliasesOf(fm),
+				lastModified,
+				size
+			};
+			(kind === "journal" ? journals : pages).push(entry);
+		}
+	}
+	journals.sort((a, b) => b.concept.localeCompare(a.concept));
+	pages.sort((a, b) => a.key.localeCompare(b.key));
+	return [...journals, ...pages];
+}
+//#endregion
+//#region ../client/src/lib/storage/fs/filesystem-store.ts
+/**
+* A {@link DocumentStore} over a real directory (via a {@link DirectoryAdapter}):
+* the Filesystem Backend. The files *are* the state — this holds only a live
+* buffer per open document plus a derived registry, and reconciles external
+* changes (git checkout, Syncthing) the way DESIGN.md → The git workflow requires.
+*
+* Assembled entirely from the pure pieces (scan, identity, reconcileDecision,
+* 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
+* `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
+* because DocumentView registers its `subscribe` listener in the same synchronous
+* onMount tick as its `getText()` seed, before the read resolves.
+*/
+function applyTextChange(text, change) {
+	return text.slice(0, change.from) + change.insert + text.slice(change.to);
+}
+/** A signature of the registry's membership + (mtime, size) stamps, to fire change events only on real change. */
+function registrySignature(entries) {
+	return entries.map((e) => `${e.key}@${e.lastModified}:${e.size}`).join("|");
+}
+function createFilesystemDocumentStore(adapter, options = {}) {
+	const { autosaveMs = 400, onConflict } = options;
+	const registry = /* @__PURE__ */ new Map();
+	let registrySig = "";
+	const open = /* @__PURE__ */ new Map();
+	const documentsChanged = /* @__PURE__ */ new Set();
+	const documentRemoved = /* @__PURE__ */ new Set();
+	const documentRenamed = /* @__PURE__ */ new Set();
+	const changed = /* @__PURE__ */ new Set();
+	function snapshotEntries() {
+		return [...registry.values()];
+	}
+	/** Named when this store knows which document moved; unnamed means re-verify everything. */
+	function emitChange(change) {
+		for (const listener of changed) listener(change);
+	}
+	/** The concept an open document answers to, as the registry spells it. */
+	function conceptOf(doc) {
+		return registry.get(doc.key)?.concept ?? doc.target;
+	}
+	function emitDocumentsChanged() {
+		for (const listener of documentsChanged) listener();
+		emitChange();
+	}
+	function emitDocumentRemoved(target) {
+		for (const listener of documentRemoved) listener(target);
+	}
+	/**
+	* The registry listing changed but no content did - aliases patched from a save. The
+	* listing's consumers are told; the [[Derived Index]] is not asked to re-verify the graph,
+	* because the named change the save emits already covers the one document that moved.
+	*/
+	function emitRegistryOnly() {
+		for (const listener of documentsChanged) listener();
+	}
+	/**
+	* The buffer as it should rest on disk (ADR 0061): the REGISTRY's title, whatever the buffer
+	* says, and the buffer's everything else. A title typed into the block is a proposal until the
+	* rename dialog confirms it, and a file that already said the new name would be re-keyed by
+	* the next rescan underneath the open document - which then found no entry for its old key
+	* and was declared removed. Aliases are the file's to say, so they go as typed. A block is
+	* only put back when the file name alone would not name the document.
+	*/
+	function proposedToStored(doc, buffer) {
+		const entry = registry.get(doc.key);
+		if (!entry || entry.kind !== "page") return buffer;
+		return withFrontmatterIdentity(buffer, { title: entry.concept }, { addBlock: fileStem(entry.fileName) !== entry.concept });
+	}
+	/** Aliases are the file's to say: keep the entry in step without waiting for the next scan. */
+	function adoptAliases(entry, text) {
+		const aliases = aliasesOf(parseFrontmatter(text));
+		if (sameAliases(aliases, entry.aliases)) return;
+		entry.aliases = aliases;
+		emitRegistryOnly();
+	}
+	/**
+	* A file whose `title` was edited outside the app is a rename that already happened
+	* (ADR 0061). The rescan has re-keyed it; the open document is re-keyed to match and its
+	* consumers told, so the tab follows the file - instead of the document being declared
+	* removed, and then resurrected over the external edit by its next keystroke.
+	*/
+	function followFile(doc) {
+		const entry = [...registry.values()].find((e) => e.subdir === doc.subdir && e.fileName === doc.fileName);
+		if (!entry) return;
+		const from = doc.target;
+		open.delete(doc.key);
+		doc.key = entry.key;
+		doc.target = entry.concept;
+		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. */
+	async function refreshRegistry() {
+		const entries = await scanGraph(adapter);
+		registry.clear();
+		for (const entry of entries) registry.set(entry.key, entry);
+		const sig = registrySignature(entries);
+		if (sig !== registrySig) {
+			registrySig = sig;
+			emitDocumentsChanged();
+		}
+		return entries;
+	}
+	function notify(doc, text) {
+		for (const listener of doc.listeners) listener(text);
+	}
+	/** The frontmatter block of `text`, given its parsed body (`''` when there is none). */
+	function headOf(text, body) {
+		return body === text ? "" : text.slice(0, text.length - body.length);
+	}
+	/** Documents whose BODY references `concept` at the top level. */
+	async function countReferencing(concept) {
+		let total = 0;
+		for (const entry of registry.values()) {
+			const { text } = await adapter.read(entry.subdir, entry.fileName);
+			if (countWikilinkTargets(parseFrontmatter(text).body, concept) > 0) total += 1;
+		}
+		return total;
+	}
+	/**
+	* The file a document is written to under `concept` - this backend's half of the naming
+	* rule in `storage/file-names.ts`. The portable stem is lossy (`etc` and `etc.`, `A/B` and
+	* `A_B`, two titles that truncate alike), so the bare name may already be another
+	* document's: the file took whichever was listed last and the other's bytes were gone. The
+	* first free candidate of `Title.md`, `Title (2).md`, ... is taken instead, the title
+	* untouched, so no concept is invented.
+	*
+	* Taken means held by another registry entry in the subdir, compared case-insensitively
+	* because a Windows or macOS folder would, or present on disk without being scanned yet (a
+	* file added behind the store's back). `own` is the document being renamed: its current file
+	* is not in its own way, and a candidate that IS that file in another case keeps the file
+	* as it is - on NTFS and APFS `foo.md` and `Foo.md` are one file, so writing the new casing
+	* and then removing the old would delete the document. A single user's directory, so the
+	* registry plus `exists` is enough; nothing coordinates with a concurrent creator.
+	*/
+	async function allocateFileName(subdir, concept, own) {
+		const base = portableFileName(concept);
+		const taken = /* @__PURE__ */ new Set();
+		for (const entry of registry.values()) if (entry.subdir === subdir && entry.key !== own?.key) taken.add(entry.fileName.toLowerCase());
+		for (let index = 1;; index++) {
+			const candidate = suffixedFileName(base, index);
+			const lower = candidate.toLowerCase();
+			if (own && lower === own.fileName.toLowerCase()) return own.fileName;
+			if (taken.has(lower)) continue;
+			if (await adapter.exists(subdir, candidate)) continue;
+			return candidate;
+		}
+	}
+	/**
+	* One step of a rename plan: retitle the document, and if the target name is already
+	* taken, [[Merge]] into it instead.
+	*
+	* The document's own file is written before the old one is removed - a crash between the
+	* two leaves a duplicate, which is recoverable, where the reverse order loses the
+	* document.
+	*/
+	async function applyStep(step, strategy) {
+		const entry = registry.get(conceptKey(step.from));
+		if (!entry) return;
+		if (conceptKey(step.from) === conceptKey(step.to) && step.from === step.to) return;
+		const openDoc = open.get(entry.key);
+		if (openDoc) {
+			openDoc.save.cancel();
+			await settled(openDoc);
+		}
+		const { text } = await adapter.read(entry.subdir, entry.fileName);
+		const fm = parseFrontmatter(text);
+		let aliases = aliasesOf(fm);
+		let body = fm.body;
+		let data = { ...fm.data };
+		if (strategy === "alias") {
+			if (!aliases.some((a) => conceptKey(a) === conceptKey(step.from))) aliases = [...aliases, step.from];
+		}
+		const targetEntry = step.merges ? registry.get(conceptKey(step.into)) : void 0;
+		const survivor = targetEntry && targetEntry.key !== entry.key ? targetEntry : void 0;
+		if (survivor) {
+			const existingFm = parseFrontmatter((await adapter.read(survivor.subdir, survivor.fileName)).text);
+			const merged = mergeDocuments({
+				body: existingFm.body,
+				aliases: aliasesOf(existingFm)
+			}, {
+				body,
+				aliases
+			});
+			body = merged.body;
+			aliases = merged.aliases;
+			data = { ...existingFm.data };
+		}
+		aliases = normaliseAliases(aliases, step.into);
+		data.title = step.into;
+		if (aliases.length > 0) data.aliases = aliases;
+		else delete data.aliases;
+		const subdir = survivor?.subdir ?? entry.subdir;
+		const fileName = survivor?.fileName ?? await allocateFileName(subdir, step.into, entry);
+		const written = await adapter.write(subdir, fileName, `---\n${stringify(data)}---\n${body}`);
+		if (!(subdir === entry.subdir && fileName === entry.fileName)) await adapter.remove(entry.subdir, entry.fileName);
+		registry.delete(entry.key);
+		if (survivor) registry.delete(survivor.key);
+		registry.set(conceptKey(step.into), {
+			kind: survivor?.kind ?? entry.kind,
+			concept: step.into,
+			key: conceptKey(step.into),
+			subdir,
+			fileName,
+			aliases,
+			lastModified: written.lastModified,
+			size: written.size
+		});
+		if (openDoc) open.delete(entry.key);
+	}
+	/**
+	* Start the document's save if none is in flight, else note that one is wanted. One writable
+	* per file at a time: each `createWritable()` gets its own swap file, made visible at
+	* `close()`, and nothing orders two of them - so of two overlapping writes the older text
+	* could land last, and the first to settle nulled the pointer while the other was still
+	* open, which let a reconcile pass read the app's own write as an external edit and raise a
+	* conflict. A write wanted mid-flight runs when the current one settles, with the buffer as
+	* it is then, so a burst of keystrokes costs two writes at most.
+	*
+	* The chain never rejects. An autosave has no caller to reject to, so a failed write (a full
+	* disk, a lapsed folder permission, a file locked by another program) was an unhandled
+	* rejection with `dirty` left true, the debounce spent and nothing to retry it. Now the
+	* failure is recorded and reported (`onSaveError`), the buffer stays dirty - dirty work is
+	* the source of truth - and `flushDocument`, the next keystroke's autosave and `dispose`
+	* retry it. Never a timer: a full disk should not be hammered.
+	*/
+	function runSave(doc) {
+		if (doc.conflict || doc.removed) {
+			doc.queued = false;
+			return;
+		}
+		if (!doc.loaded) {
+			doc.queued = false;
+			if (doc.loadError !== null) options.onSaveError?.(conceptOf(doc), doc.loadError);
+			return;
+		}
+		if (doc.saving) {
+			doc.queued = true;
+			return;
+		}
+		doc.queued = false;
+		const snapshot = doc.buffer;
+		const written = proposedToStored(doc, snapshot);
+		doc.saving = adapter.write(doc.subdir, doc.fileName, written).then((res) => {
+			doc.saveError = null;
+			doc.baseText = written;
+			doc.lastModified = res.lastModified;
+			doc.size = res.size;
+			doc.dirty = doc.buffer !== snapshot;
+			const entry = registry.get(doc.key);
+			if (entry) {
+				entry.lastModified = res.lastModified;
+				entry.size = res.size;
+				adoptAliases(entry, written);
+			} else refreshRegistry();
+			emitChange({ concept: conceptOf(doc) });
+		}, (error) => {
+			doc.saveError = error;
+			options.onSaveError?.(conceptOf(doc), error);
+		}).finally(() => {
+			doc.saving = null;
+			if (doc.queued && doc.dirty) runSave(doc);
+		});
+	}
+	/** Resolves once no write is in flight for `doc`, including any that were queued behind it. */
+	async function settled(doc) {
+		while (doc.saving) await doc.saving;
+	}
+	/**
+	* Write the buffer now if it is dirty, and wait for every write in flight. The pending
+	* debounce is superseded rather than flushed: `dirty` is what says there is work, and it
+	* outlives a spent debounce - which is what lets a failed autosave be retried here. A
+	* document that could not be read at open is read again first: a retry is the user asking,
+	* and reconcile either reloads the buffer or, if something was typed, raises a conflict.
+	*/
+	async function saveNow(doc) {
+		doc.save.cancel();
+		if (!doc.loaded && doc.loadError !== null) try {
+			await reconcileDoc(doc);
+		} catch (error) {
+			doc.loadError = error;
+		}
+		if (doc.dirty) runSave(doc);
+		await settled(doc);
+	}
+	function makeOpenDoc(target, entry) {
+		const doc = {
+			key: entry.key,
+			target,
+			subdir: entry.subdir,
+			fileName: entry.fileName,
+			buffer: "",
+			baseText: "",
+			lastModified: 0,
+			size: 0,
+			dirty: false,
+			loaded: false,
+			loadError: null,
+			ready: Promise.resolve(),
+			removed: false,
+			conflict: null,
+			listeners: /* @__PURE__ */ new Set(),
+			save: void 0,
+			saving: null,
+			queued: false,
+			saveError: null,
+			handle: void 0
+		};
+		doc.save = debounce(() => runSave(doc), autosaveMs);
+		doc.handle = {
+			get id() {
+				return doc.target;
+			},
+			getText: () => doc.buffer,
+			applyChange(change, origin = "editor") {
+				doc.buffer = applyTextChange(doc.buffer, change);
+				doc.dirty = true;
+				if (doc.removed) {
+					doc.removed = false;
+					options.onResurrected?.(doc.target);
+				}
+				doc.save.call();
+				if (origin === "external") notify(doc, doc.buffer);
+			},
+			subscribe(listener) {
+				doc.listeners.add(listener);
+				return () => doc.listeners.delete(listener);
+			}
+		};
+		doc.ready = adapter.read(doc.subdir, doc.fileName).then((content) => {
+			doc.buffer = content.text;
+			doc.baseText = content.text;
+			doc.lastModified = content.lastModified;
+			doc.size = content.size;
+			doc.loaded = true;
+			notify(doc, content.text);
+		}).catch(async (error) => {
+			if (await adapter.exists(doc.subdir, doc.fileName).catch(() => true)) doc.loadError = error;
+			else doc.loaded = true;
+		});
+		return doc;
+	}
+	async function reconcileDoc(doc) {
+		if (doc.removed) return;
+		await settled(doc);
+		const entry = registry.get(doc.key);
+		if (!entry) {
+			doc.removed = true;
+			doc.save.cancel();
+			emitDocumentRemoved(doc.target);
+			return;
+		}
+		if (doc.loaded && entry.lastModified === doc.lastModified && entry.size === doc.size) return;
+		const { text: diskText, lastModified, size } = await adapter.read(doc.subdir, doc.fileName);
+		const decision = reconcileDecision({
+			dirty: doc.dirty,
+			baseText: doc.baseText,
+			diskText
+		});
+		if (decision === "noop") {
+			doc.lastModified = lastModified;
+			doc.size = size;
+			doc.loaded = true;
+			doc.loadError = null;
+			return;
+		}
+		if (decision === "reload") {
+			doc.buffer = diskText;
+			doc.baseText = diskText;
+			doc.lastModified = lastModified;
+			doc.size = size;
+			doc.loaded = true;
+			doc.loadError = null;
+			doc.dirty = false;
+			notify(doc, diskText);
+			emitChange({ concept: conceptOf(doc) });
+			return;
+		}
+		doc.conflict = {
+			target: doc.target,
+			diskText,
+			bufferText: doc.buffer
+		};
+		doc.save.cancel();
+		onConflict?.(doc.conflict);
+	}
+	return {
+		open(target) {
+			const key = conceptKey(target);
+			const existing = open.get(key);
+			if (existing) return existing.handle;
+			const entry = registry.get(key);
+			if (!entry) throw new DocumentNotFoundError(target);
+			const doc = makeOpenDoc(target, entry);
+			open.set(key, doc);
+			return doc.handle;
+		},
+		async whenReady(target) {
+			await (open.get(conceptKey(target)) ?? (this.open(target), open.get(conceptKey(target))))?.ready;
+		},
+		async scan() {
+			await adapter.ensureSkeleton();
+			await refreshRegistry();
+		},
+		listDocuments() {
+			return snapshotEntries();
+		},
+		onDocumentsChanged(listener) {
+			documentsChanged.add(listener);
+			return () => documentsChanged.delete(listener);
+		},
+		onDocumentRemoved(listener) {
+			documentRemoved.add(listener);
+			return () => documentRemoved.delete(listener);
+		},
+		onDocumentRenamed(listener) {
+			documentRenamed.add(listener);
+			return () => documentRenamed.delete(listener);
+		},
+		async setAliases(target, aliases) {
+			const entry = registry.get(conceptKey(target));
+			if (!entry) throw new DocumentNotFoundError(target);
+			const next = normaliseAliases(aliases, entry.concept);
+			const doc = open.get(entry.key);
+			if (doc) {
+				await doc.ready;
+				const text = withFrontmatterIdentity(doc.buffer, { aliases: next }, { addBlock: next.length > 0 });
+				if (text !== doc.buffer) doc.handle.applyChange({
+					from: 0,
+					to: doc.buffer.length,
+					insert: text
+				}, "external");
+			} else {
+				const { text } = await adapter.read(entry.subdir, entry.fileName);
+				const rewritten = withFrontmatterIdentity(text, { aliases: next }, { addBlock: next.length > 0 });
+				if (rewritten !== text) {
+					const res = await adapter.write(entry.subdir, entry.fileName, rewritten);
+					entry.lastModified = res.lastModified;
+					entry.size = res.size;
+					emitChange({ concept: entry.concept });
+				}
+			}
+			if (!sameAliases(entry.aliases, next)) {
+				entry.aliases = next;
+				emitRegistryOnly();
+			}
+		},
+		onChange(listener) {
+			changed.add(listener);
+			return () => changed.delete(listener);
+		},
+		async snapshotForIndex() {
+			const out = [];
+			const stream = await this.streamForIndex();
+			for await (const batch of stream.batches) out.push(...batch);
+			return out;
+		},
+		async streamForIndex() {
+			const entries = [...registry.values()];
+			return {
+				total: entries.length,
+				batches: (async function* () {
+					const batch = [];
+					for (const entry of entries) {
+						const read = await adapter.read(entry.subdir, entry.fileName).catch(() => null);
+						if (!read) continue;
+						const fm = parseFrontmatter(read.text);
+						batch.push({
+							concept: entry.concept,
+							kind: entry.kind,
+							aliases: aliasesOf(fm),
+							text: fm.body
+						});
+						if (batch.length === 100) yield batch.splice(0);
+					}
+					if (batch.length > 0) yield batch;
+				})()
+			};
+		},
+		async snapshotDocument(concept) {
+			const entry = registry.get(conceptKey(concept));
+			if (!entry) return null;
+			const doc = open.get(entry.key);
+			let text;
+			if (doc) {
+				await doc.ready;
+				text = doc.buffer;
+			} else {
+				const read = await adapter.read(entry.subdir, entry.fileName).catch(() => null);
+				if (!read) return null;
+				text = read.text;
+			}
+			const fm = parseFrontmatter(text);
+			return {
+				concept: entry.concept,
+				kind: entry.kind,
+				aliases: aliasesOf(fm),
+				text: fm.body
+			};
+		},
+		async reconcile() {
+			await refreshRegistry();
+			for (const doc of [...open.values()]) {
+				if (!registry.has(doc.key)) followFile(doc);
+				await reconcileDoc(doc);
+			}
+		},
+		async resolveConflict(target, choice) {
+			const doc = open.get(conceptKey(target));
+			if (!doc || !doc.conflict) return;
+			doc.loaded = true;
+			doc.loadError = null;
+			if (choice === "take-disk") {
+				const { text, lastModified, size } = await adapter.read(doc.subdir, doc.fileName);
+				doc.buffer = text;
+				doc.baseText = text;
+				doc.lastModified = lastModified;
+				doc.size = size;
+				doc.dirty = false;
+				doc.conflict = null;
+				notify(doc, text);
+			} else {
+				const res = await adapter.write(doc.subdir, doc.fileName, doc.buffer);
+				doc.baseText = doc.buffer;
+				doc.lastModified = res.lastModified;
+				doc.size = res.size;
+				doc.dirty = false;
+				doc.conflict = null;
+				const entry = registry.get(doc.key);
+				if (entry) {
+					entry.lastModified = res.lastModified;
+					entry.size = res.size;
+				}
+			}
+			emitChange({ concept: conceptOf(doc) });
+		},
+		async createJournal(date, body = "") {
+			const concept = date.trim();
+			if (!isJournalConcept(concept)) throw new Error(`"${date}" is not a calendar day.`);
+			if (registry.get(conceptKey(concept))) throw new Error(`A document for "${concept}" already exists.`);
+			await adapter.ensureSkeleton();
+			await adapter.write("journals", `${concept}.md`, body);
+			await refreshRegistry();
+			return concept;
+		},
+		async createPage(title, body = "") {
+			const concept = title.trim();
+			if (concept === "") throw new Error("A page needs a non-empty title.");
+			const key = conceptKey(concept);
+			if (registry.get(key)) throw new Error(`A document for "${concept}" already exists.`);
+			await adapter.ensureSkeleton();
+			const fileName = await allocateFileName("pages", concept);
+			const content = `---\n${stringify({ title: concept })}---\n${body}`;
+			await adapter.write("pages", fileName, content);
+			await refreshRegistry();
+			return concept;
+		},
+		async planRename(from, to, referencingDocuments) {
+			return refuseProtectedMerges(planRename({
+				from,
+				to,
+				kind: registry.get(conceptKey(from))?.kind ?? null,
+				concepts: [...registry.values()].map((e) => e.concept),
+				aliases: [...registry.values()].flatMap((e) => (e.aliases ?? []).map((name) => ({
+					name,
+					concept: e.concept
+				}))),
+				referencingDocuments: referencingDocuments ?? await countReferencing(from)
+			}), async (concept) => {
+				const other = registry.get(conceptKey(concept));
+				if (!other) return false;
+				return documentProtection(open.get(other.key)?.buffer ?? (await adapter.read(other.subdir, other.fileName)).text).kind === "document";
+			});
+		},
+		async renamePage(from, to, options) {
+			const plan = await this.planRename(from, to, 0);
+			if (plan.refusal) throw new Error(plan.refusal);
+			for (const step of renameSteps(plan)) await applyStep(step, options.strategy);
+			let rewritten = 0;
+			if (options.strategy === "rewrite") for (const other of [...registry.values()]) {
+				const openDoc = open.get(other.key);
+				if (openDoc) {
+					await openDoc.ready;
+					const prefix = frontmatterSpan(openDoc.buffer)?.end ?? 0;
+					const splices = wikilinkScopeSplices(openDoc.buffer.slice(prefix), plan.direct.from, plan.direct.to);
+					if (splices.length === 0) continue;
+					for (let i = splices.length - 1; i >= 0; i--) {
+						const splice = splices[i];
+						openDoc.handle.applyChange({
+							from: splice.from + prefix,
+							to: splice.to + prefix,
+							insert: splice.insert
+						}, "external");
+					}
+					rewritten += 1;
+					continue;
+				}
+				const doc = await adapter.read(other.subdir, other.fileName);
+				const parsed = parseFrontmatter(doc.text);
+				const result = rewriteWikilinkScope(parsed.body, plan.direct.from, plan.direct.to);
+				if (result.count === 0) continue;
+				await adapter.write(other.subdir, other.fileName, `${headOf(doc.text, parsed.body)}${result.text}`);
+				rewritten += 1;
+			}
+			await refreshRegistry();
+			return {
+				concept: plan.direct.into,
+				rewritten,
+				cascaded: plan.cascade.length,
+				merged: mergeCount(plan)
+			};
+		},
+		async deleteDocument(concept) {
+			const entry = registry.get(conceptKey(concept));
+			if (!entry) return;
+			const doc = open.get(entry.key);
+			if (doc) {
+				doc.save.cancel();
+				doc.removed = true;
+				await settled(doc);
+			}
+			await adapter.remove(entry.subdir, entry.fileName);
+			await refreshRegistry();
+			emitDocumentRemoved(entry.concept);
+		},
+		async flushDocument(target) {
+			const doc = open.get(conceptKey(target));
+			if (!doc) return;
+			await saveNow(doc);
+		},
+		async dispose() {
+			await Promise.all([...open.values()].map(saveNow));
+			open.clear();
+			documentsChanged.clear();
+			documentRemoved.clear();
+			changed.clear();
+		}
+	};
+}
+//#endregion
+//#region ../client/src/lib/storage/fs/save-error-copy.ts
+/**
+* Turn a failed write to the graph folder into a sentence the user can act on (AGENTS.md rule 6:
+* what happened, why, what next). The File System Access API reports faults as DOMExceptions
+* whose `name` is the only stable signal. The sync path's `describeSyncFailure` reads those as
+* IndexedDB or network faults and falls back to "the sync server could not be reached", which
+* is wrong for a folder on disk - so the [[Filesystem Backend]] has its own map.
+*
+* Every sentence ends by saying the edits are kept: the buffer stays dirty until a retry
+* succeeds (`FilesystemDocumentStoreOptions.onSaveError`), and the user should know that closing
+* the tab is what loses them.
+*
+* Pure, so the mapping is unit tested rather than inferred from a screenshot.
+*/
+var KEPT = "Your edits are kept in this tab until a save succeeds.";
+function describeFilesystemSaveFailure(error, concept) {
+	const opening = `Could not save “${concept}”.`;
+	switch (error instanceof Error ? error.name : "") {
+		case "QuotaExceededError": return `${opening} The disk this folder is on is full. Free up some space, then retry. ${KEPT}`;
+		case "NotAllowedError":
+		case "SecurityError": return `${opening} Permission to write to the folder has lapsed. Grant access again when the browser asks, then retry. ${KEPT}`;
+		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}`;
+		default: return `${opening}${error instanceof Error && error.message ? ` The browser reported: ${error.message}.` : ""} Retry in a moment. ${KEPT}`;
+	}
+}
+function createSemanticIndex(options) {
+	const { index, model } = options;
+	const floor = options.floor ?? .25;
+	const settleMs = options.settleMs ?? 1500;
+	const pauseMs = options.pauseMs ?? 100;
+	let disposed = false;
+	let running;
+	let again = false;
+	let timer;
+	let unsubscribe;
+	async function runBuild() {
+		for (;;) {
+			if (disposed) return;
+			const pending = await index.semantic.pending(model.id, 128);
+			if (pending.length === 0) break;
+			const sorted = [...pending].sort((a, b) => a.text.length - b.text.length);
+			const rows = [];
+			for (let at = 0; at < sorted.length; at += 32) {
+				const slice = sorted.slice(at, at + 32);
+				const vectors = await model.embed(slice.map((passage) => passage.text));
+				if (disposed) return;
+				slice.forEach((passage, n) => rows.push({
+					hash: passage.hash,
+					...quantise(vectors[n])
+				}));
+				if (pauseMs > 0) await new Promise((resolve) => setTimeout(resolve, pauseMs));
+			}
+			await index.semantic.put(model.id, model.dims, rows);
+			if (options.onProgress) options.onProgress(await index.semantic.status(model.id));
+		}
+		await index.semantic.sweep(model.id);
+	}
+	function build() {
+		if (running) {
+			again = true;
+			return running;
+		}
+		running = runBuild().catch((error) => options.onError?.(error instanceof Error ? error : new Error(String(error)))).finally(() => {
+			running = void 0;
+			if (again && !disposed) {
+				again = false;
+				build();
+			}
+		});
+		return running;
+	}
+	function scheduleBuild() {
+		if (disposed) return;
+		clearTimeout(timer);
+		timer = setTimeout(() => void build(), settleMs);
+	}
+	return {
+		model,
+		status: () => index.semantic.status(model.id),
+		async search(query, offset, limit) {
+			const [vector] = await model.embed([query]);
+			return index.semantic.search(model.id, vector, offset, limit, floor);
+		},
+		build,
+		follow() {
+			if (unsubscribe || disposed) return;
+			unsubscribe = index.onUpdated(scheduleBuild);
+			build();
+		},
+		dispose() {
+			disposed = true;
+			clearTimeout(timer);
+			unsubscribe?.();
+			unsubscribe = void 0;
+		}
+	};
+}
+//#endregion
+//#region ../client/src/lib/activity/breathe.ts
+/**
+* The yield-and-cancel checkpoint (plan: 2026-07-27 Import Progress And Activities).
+*
+* A long synchronous loop starves the main thread: Svelte cannot repaint, so a status
+* line jumps from nothing straight to its final value, possibly via the browser's
+* "page unresponsive" prompt. `breathe` hands control back to the event loop.
+*
+* It yields on **elapsed time, not item count**. A graph of one-line journals and a graph
+* of 5000-line pages want wildly different batch sizes, and the thing we actually care
+* about is how long a frame has been blocked - so measure that directly.
+*
+* The yield point is also the natural cancel checkpoint, so cancellation rides along at
+* no extra cost (ADR 0035 §3): callers thread one `AbortSignal` and get both.
 */
-async function refuseProtectedMerges(plan, isProtected) {
-	if (plan.refusal) return plan;
-	for (const step of renameSteps(plan)) {
-		if (!step.merges) continue;
-		if (await isProtected(step.into)) return {
-			...plan,
-			refusal: `“${step.into}” is a protected document, so nothing can be merged into it. Choose a different name.`
-		};
-		if (await isProtected(step.from)) return {
-			...plan,
-			refusal: `“${step.from}” is a protected document, so it cannot be merged into “${step.to}”. Choose a name that is not already taken.`
-		};
-	}
-	return plan;
-}
+/** Longest a loop may hold the thread before yielding. ~3 frames: smooth enough to repaint, coarse enough not to dominate. */
+var SLICE_MS = 50;
 /**
-* A step merges when a DIFFERENT document already answers to the target name - by title or by
-* alias - and the source has a document to join to it. Renaming onto yourself (a pure
-* re-casing, or onto one of your own aliases) is neither. A source with no document landing
-* on a taken name redirects: its links come to point at the page that already answers to it
-* (ADR 0064 §2). `into` is that page's own title.
+* Create a breather. Call `await breathe(signal)` inside a loop: it returns immediately
+* while the current slice has budget left, and yields when it does not. It throws the
+* signal's reason as soon as the signal aborts, whether or not it yields.
 */
-function stepFor(from, to, hasDocument, existing) {
-	const holder = existing.get(conceptKey(to));
-	const taken = holder !== void 0 && conceptKey(holder) !== conceptKey(from);
-	return {
-		from,
-		to,
-		hasDocument,
-		merges: taken && hasDocument,
-		redirects: taken && !hasDocument,
-		into: taken ? holder : to
+function createBreather(now = () => performance.now()) {
+	let lastYield = now();
+	return async (signal) => {
+		signal?.throwIfAborted();
+		if (now() - lastYield < SLICE_MS) return;
+		await new Promise((resolve) => setTimeout(resolve));
+		lastYield = now();
+		signal?.throwIfAborted();
 	};
 }
-/** Nesting depth of a concept - `[[[[A]] B]] C` is deeper than `[[A]] B`. */
-function depthOf(concept) {
-	let depth = 0;
-	let max = 0;
-	for (let i = 0; i < concept.length - 1; i++) if (concept[i] === "[" && concept[i + 1] === "[") {
-		depth += 1;
-		max = Math.max(max, depth);
-		i += 1;
-	} else if (concept[i] === "]" && concept[i + 1] === "]") {
-		depth -= 1;
-		i += 1;
-	}
-	return max;
-}
 //#endregion
 //#region ../client/src/lib/storage/server/server-document-store.ts
 /**
@@ -9010,7 +10111,114 @@ function createServerDocumentStore(graph, options) {
 * mid-way would lose every vector of the run. Throttled exports bound the loss to this window.
 */
 var BUILD_PERSIST_EVERY_MS = 3e4;
-/** Open the graph, scan its registry and build the index; resolves once tools can answer. */
+/** How long a read waits for the relay before answering with what it has. */
+var CATCH_UP_TIMEOUT_MS = 15e3;
+/** How long `refresh()` waits for the index to absorb a change before answering from what it has. */
+var INDEX_FOLLOW_MS = 5e3;
+/**
+* Whether the index has yet to absorb the source's latest change. A tool that searches right
+* after a write - its own, or one found on disk - would otherwise race the index's debounce and
+* answer from the moment before; `refresh()` on either backend waits here first. The wait is
+* bounded: an index that is rebuilding a large graph should not stall every tool behind it.
+*/
+function followIndex(index, source, followMs = INDEX_FOLLOW_MS) {
+	let pending = false;
+	let waiters = [];
+	const stopSource = source.onChange(() => {
+		pending = true;
+	});
+	const stopIndex = index.onUpdated(() => {
+		pending = false;
+		const resolved = waiters;
+		waiters = [];
+		for (const resolve of resolved) resolve();
+	});
+	return {
+		settled() {
+			if (!pending) return Promise.resolve();
+			return new Promise((resolve) => {
+				waiters.push(resolve);
+				setTimeout(resolve, followMs).unref?.();
+			});
+		},
+		dispose() {
+			stopSource();
+			stopIndex();
+		}
+	};
+}
+/**
+* The part of a headless graph that does not care where its documents come from: snapshots of
+* the index (and whatever the backend keeps beside it) off the tool's critical path, semantic
+* search opened on demand, and a dispose that takes a last snapshot.
+*/
+function assembleHeadlessGraph(parts) {
+	const { index, indexHost } = parts;
+	let persisting = Promise.resolve();
+	let timer;
+	const persist = () => {
+		if (!parts.persistDir || !indexHost) return persisting;
+		persisting = persisting.then(() => parts.persistBackend?.()).then(() => indexHost.export()).catch((error) => parts.onError?.(error instanceof Error ? error : new Error(String(error))));
+		return persisting;
+	};
+	const schedulePersist = () => {
+		if (!parts.persistDir) return;
+		clearTimeout(timer);
+		timer = setTimeout(() => void persist(), parts.persistDebounceMs ?? 5e3);
+	};
+	const unsubscribe = parts.onChange(schedulePersist);
+	let lastBuildPersist = 0;
+	const persistDuringBuild = () => {
+		if (Date.now() - lastBuildPersist >= BUILD_PERSIST_EVERY_MS) {
+			lastBuildPersist = Date.now();
+			persist();
+		} else schedulePersist();
+	};
+	let semanticOpening;
+	let semanticModel;
+	const semantic = () => {
+		if (semanticOpening) return semanticOpening;
+		semanticOpening = (async () => {
+			if (!parts.embeddingModel) throw new Error("Semantic search is not available in this process: no embedding model was configured.");
+			const model = await parts.embeddingModel();
+			semanticModel = model;
+			const created = createSemanticIndex({
+				index,
+				model,
+				onError: parts.onError,
+				onProgress: (status) => {
+					persistDuringBuild();
+					parts.onSemanticProgress?.(status);
+				}
+			});
+			created.follow();
+			return created;
+		})();
+		semanticOpening.catch(() => {
+			semanticOpening = void 0;
+		});
+		return semanticOpening;
+	};
+	return {
+		graphId: parts.graphId,
+		name: parts.name,
+		store: parts.store,
+		index,
+		settle: () => parts.settle(schedulePersist),
+		persist,
+		semantic,
+		async dispose() {
+			clearTimeout(timer);
+			unsubscribe();
+			if (semanticOpening) await semanticOpening.then((s) => s.dispose()).catch(() => {});
+			await persist();
+			index.dispose();
+			await parts.disposeBackend();
+			await semanticModel?.dispose?.();
+		}
+	};
+}
+/** Open a synced graph, scan its registry and build the index; resolves once tools can answer. */
 async function openHeadlessGraph(deps) {
 	const cache = await openGraphCache(deps.graphId);
 	if (deps.persistDir) await loadLocalCache(deps.persistDir, deps.graphId);
@@ -9029,7 +10237,8 @@ async function openHeadlessGraph(deps) {
 			name: deps.presenceName,
 			...PRESENCE_PALETTE[0]
 		},
-		onError: deps.onError
+		onError: deps.onError,
+		publishName: deps.publishName
 	});
 	const store = createServerDocumentStore(sync, { readyTimeoutMs: deps.readyTimeoutMs });
 	try {
@@ -9037,76 +10246,54 @@ async function openHeadlessGraph(deps) {
 		const index = createRemoteGraphIndex(store, inlineTransport(indexHost ?? memoryDbHost()), { graphId: deps.graphId });
 		await index.prepare();
 		await index.refresh();
-		let persisting = Promise.resolve();
-		let timer;
-		const persist = () => {
-			if (!deps.persistDir || !indexHost) return persisting;
-			const dir = deps.persistDir;
-			persisting = persisting.then(() => persistLocalCache(dir, deps.graphId)).then(() => indexHost.export()).catch((error) => deps.onError?.(error instanceof Error ? error : new Error(String(error))));
-			return persisting;
-		};
-		const schedulePersist = () => {
-			if (!deps.persistDir) return;
-			clearTimeout(timer);
-			timer = setTimeout(() => void persist(), deps.persistDebounceMs ?? 5e3);
-		};
-		const unsubscribe = sync.onDocUpdate(schedulePersist);
-		let lastBuildPersist = 0;
-		const persistDuringBuild = () => {
-			if (Date.now() - lastBuildPersist >= BUILD_PERSIST_EVERY_MS) {
-				lastBuildPersist = Date.now();
-				persist();
-			} else schedulePersist();
-		};
-		let semanticOpening;
-		let semanticModel;
-		const semantic = () => {
-			if (semanticOpening) return semanticOpening;
-			semanticOpening = (async () => {
-				if (!deps.embeddingModel) throw new Error("Semantic search is not available in this process: no embedding model was configured.");
-				const model = await deps.embeddingModel();
-				semanticModel = model;
-				const created = createSemanticIndex({
-					index,
-					model,
-					onError: deps.onError,
-					onProgress: (status) => {
-						persistDuringBuild();
-						deps.onSemanticProgress?.(status);
-					}
-				});
-				created.follow();
-				return created;
-			})();
-			semanticOpening.catch(() => {
-				semanticOpening = void 0;
-			});
-			return semanticOpening;
-		};
-		return {
+		const follower = followIndex(index, store);
+		return assembleHeadlessGraph({
 			graphId: deps.graphId,
-			sync,
-			store,
+			name: sync.getMeta().name ?? deps.graphId,
+			store: {
+				refresh: () => follower.settled(),
+				listDocuments: () => store.listDocuments(),
+				async whenReady(concept) {
+					await store.whenReady(concept);
+					const wanted = conceptKey(concept);
+					const identity = store.listIdentities().find((candidate) => conceptKey(candidate.concept) === wanted);
+					if (!identity) return;
+					const caughtUp = sync.caughtUpDoc(identity.docId).then(() => "ok");
+					const timeout = new Promise((resolve) => setTimeout(() => resolve("timeout"), CATCH_UP_TIMEOUT_MS));
+					await Promise.race([caughtUp, timeout]);
+				},
+				open: (concept) => store.open(concept),
+				createJournal: (date, body) => store.createJournal(date, body),
+				createPage: (title, body) => store.createPage(title, body),
+				setAliases: (target, aliases) => store.setAliases(target, aliases),
+				deleteDocument: (concept) => store.deleteDocument(concept)
+			},
 			index,
-			async settle() {
+			indexHost,
+			persistDir: deps.persistDir,
+			persistDebounceMs: deps.persistDebounceMs,
+			embeddingModel: deps.embeddingModel,
+			onSemanticProgress: deps.onSemanticProgress,
+			onError: deps.onError,
+			persistBackend: deps.persistDir ? () => persistLocalCache(deps.persistDir, deps.graphId) : void 0,
+			onChange: (schedule) => sync.onDocUpdate(schedule),
+			async settle(schedulePersist) {
 				await sync.flushAll();
 				const result = await sync.awaitAcked({ stallMs: 1e4 });
 				schedulePersist();
-				return result;
+				if (result.settled) return { settled: true };
+				return {
+					settled: false,
+					outstanding: result.outstanding,
+					message: `The edit is saved locally but the Sync Server has not acknowledged it (${result.outstanding} outstanding). It will be delivered when the connection recovers.`
+				};
 			},
-			persist,
-			semantic,
-			async dispose() {
-				clearTimeout(timer);
-				unsubscribe();
-				if (semanticOpening) await semanticOpening.then((s) => s.dispose()).catch(() => {});
-				await persist();
-				index.dispose();
-				await semanticModel?.dispose?.();
+			async disposeBackend() {
+				follower.dispose();
 				await store.dispose();
 				cache.dispose();
 			}
-		};
+		});
 	} catch (error) {
 		await store.dispose().catch(() => {});
 		cache.dispose();
@@ -9114,6 +10301,211 @@ async function openHeadlessGraph(deps) {
 	}
 }
 //#endregion
+//#region src/headless-folder.ts
+/**
+* A local graph folder, open in a process with no editor: the client's filesystem store over a
+* directory adapter, with the same derived index, persistence and semantic search a synced
+* graph gets from `assembleHeadlessGraph` ([[2026-09-18 Headless Client Serves A Local Folder]]).
+*
+* A folder has no relay, so the two things the relay gave the synced backend for free are done
+* here instead:
+*
+* - **Edits made outside this process.** `refresh()` runs the store's `reconcile()` - re-list
+*   the folder, re-read files whose stamp moved, follow renames - and then waits, bounded, for
+*   the index to absorb what it found, so a search right after an external edit sees it. Every
+*   tool calls it first; a watcher the caller supplies (`fs.watch` in the CLI) feeds the same
+*   pass between calls so the index does not go stale while the agent thinks.
+* - **Knowing a write is done.** The store autosaves on a debounce and reports a failed write
+*   through a callback rather than a rejection. `settle()` flushes every document a tool touched
+*   and turns a failure into the message the agent gets; the buffer keeps the edit, the store
+*   retries it on the next flush and at shutdown, and a read meanwhile shows the pending text.
+*   If the file then changes on disk before the retry succeeds, the disk copy wins and the lost
+*   edit is logged: it was already reported as not written.
+*
+* A local document's file opens with a frontmatter block that carries its identity (ADR 0061);
+* a synced document's text never does, because identity lives in the encrypted registry. The
+* tools get the same shape on both: `open()` here is a view of the body alone, with edit
+* offsets translated past the block, so a read shows the note and never its identity, an edit
+* cannot reach the `title`, and the line numbers the index reports (it strips the block too)
+* match the text the agent was given. The store rewrites the title on every save anyway.
+*
+* Nothing is written into the folder except the documents a tool writes. The index and the
+* embedding store live under `persistDir`, a directory the CLI keys by the folder's path.
+*/
+var WATCH_DEBOUNCE_MS = 250;
+/** The document's text after its frontmatter block, and where that block ends. */
+function body(text) {
+	const head = frontmatterSpan(text)?.end ?? 0;
+	return {
+		head,
+		body: text.slice(head)
+	};
+}
+function bodyView(handle) {
+	return {
+		id: handle.id,
+		getText: () => body(handle.getText()).body,
+		applyChange(change, origin) {
+			const { head } = body(handle.getText());
+			handle.applyChange({
+				from: change.from + head,
+				to: change.to + head,
+				insert: change.insert
+			}, origin);
+		},
+		subscribe: (listener) => handle.subscribe((text) => listener(body(text).body))
+	};
+}
+/** Open the folder, scan it and build the index; resolves once tools can answer. */
+async function openHeadlessFolder(deps) {
+	const warn = deps.onWarning ?? ((line) => console.error(`etherpk-mcp: ${line}`));
+	/** The last failed write per document, until a flush of it is attempted again. */
+	const saveErrors = /* @__PURE__ */ new Map();
+	/** Conflicts raised during the reconcile pass in flight, resolved as soon as it returns. */
+	let conflicts = [];
+	const store = createFilesystemDocumentStore(deps.adapter, {
+		onConflict: (conflict) => conflicts.push(conflict),
+		onSaveError: (concept, error) => saveErrors.set(conceptKey(concept), error)
+	});
+	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
+	* 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}`);
+		return parts.sort().join("|");
+	};
+	let lastListing;
+	let stopWatching;
+	try {
+		lastListing = await listingSignature();
+		await store.scan();
+		const index = createRemoteGraphIndex(store, inlineTransport(indexHost ?? memoryDbHost()), { graphId: deps.graphId });
+		await index.prepare();
+		await index.refresh();
+		const follower = followIndex(index, store, deps.indexFollowMs);
+		/**
+		* One reconcile pass: the store's own, then the conflicts it raised. A conflict here can
+		* only be a dirty buffer whose write already failed and was reported, so the disk copy
+		* wins and the person is told what was dropped. Passes never overlap: a request during
+		* one runs another after it.
+		*/
+		let reconciling;
+		let rerun = false;
+		const reconcileNow = () => {
+			if (reconciling) {
+				rerun = true;
+				return reconciling;
+			}
+			reconciling = (async () => {
+				const listing = await listingSignature();
+				if (listing === lastListing) return;
+				lastListing = listing;
+				await store.reconcile();
+				const raised = conflicts;
+				conflicts = [];
+				for (const conflict of raised) {
+					await store.resolveConflict(conflict.target, "take-disk");
+					saveErrors.delete(conceptKey(conflict.target));
+					warn(`"${conflict.target}" changed on disk while an edit to it could not be written; took the file on disk and discarded the edit.`);
+				}
+			})();
+			const pass = reconciling;
+			pass.finally(() => {
+				reconciling = void 0;
+				if (rerun) {
+					rerun = false;
+					reconcileNow();
+				}
+			});
+			return pass;
+		};
+		if (deps.watch) {
+			let timer;
+			stopWatching = deps.watch(() => {
+				clearTimeout(timer);
+				timer = setTimeout(() => void reconcileNow(), deps.watchDebounceMs ?? WATCH_DEBOUNCE_MS);
+			});
+			const stop = stopWatching;
+			stopWatching = () => {
+				clearTimeout(timer);
+				stop();
+			};
+		}
+		/** Documents a tool has opened since the last clean settle: the ones a flush must cover. */
+		const touched = /* @__PURE__ */ new Map();
+		return assembleHeadlessGraph({
+			graphId: deps.graphId,
+			name: deps.name,
+			store: {
+				async refresh() {
+					await reconcileNow();
+					await follower.settled();
+				},
+				listDocuments: () => store.listDocuments(),
+				whenReady: (concept) => store.whenReady(concept),
+				open(concept) {
+					touched.set(conceptKey(concept), concept);
+					return bodyView(store.open(concept));
+				},
+				createJournal: (date, body) => store.createJournal(date, body),
+				createPage: (title, body) => store.createPage(title, body),
+				async setAliases(target, aliases) {
+					await store.setAliases(target, aliases);
+					await store.flushDocument(target);
+				},
+				deleteDocument: (concept) => store.deleteDocument(concept)
+			},
+			index,
+			indexHost,
+			persistDir: deps.persistDir,
+			persistDebounceMs: deps.persistDebounceMs,
+			embeddingModel: deps.embeddingModel,
+			onSemanticProgress: deps.onSemanticProgress,
+			onError: deps.onError,
+			onChange: (schedule) => store.onChange(() => schedule()),
+			async settle(schedulePersist) {
+				const failures = [];
+				for (const [key, concept] of touched) {
+					saveErrors.delete(key);
+					await store.flushDocument(concept);
+					const error = saveErrors.get(key);
+					if (error === void 0) {
+						touched.delete(key);
+						continue;
+					}
+					failures.push(describeFilesystemSaveFailure(error, concept));
+				}
+				schedulePersist();
+				if (failures.length === 0) return { settled: true };
+				const message = `${failures.join(" ")} The edit is kept in memory, shows in a read of the document, and is retried on the next write and at shutdown.`;
+				warn(message);
+				return {
+					settled: false,
+					outstanding: failures.length,
+					message
+				};
+			},
+			async disposeBackend() {
+				stopWatching?.();
+				follower.dispose();
+				await store.dispose();
+			}
+		});
+	} catch (error) {
+		stopWatching?.();
+		await store.dispose().catch(() => {});
+		throw error;
+	}
+}
+//#endregion
 //#region ../client/src/lib/sync/device-approval.ts
 /**
 * Device approval (ADR 0026 flows): unlock a NEW device from an already-unlocked one, so
@@ -9228,11 +10620,11 @@ var ToolError = class extends Error {
 		this.name = "ToolError";
 	}
 };
-/** How `concept`, `today` and aliases resolve to one registry entry, case-insensitively. */
+/** How `concept`, `today` and aliases resolve to one document, case-insensitively. */
 function resolveIdentity(graph, target) {
 	const wanted = conceptKey(target === "today" ? todayISO() : target.trim());
-	for (const identity of graph.store.listIdentities()) {
-		if (conceptKey(identity.concept) === wanted) return identity;
+	for (const identity of graph.store.listDocuments()) {
+		if (identity.key === wanted) return identity;
 		if (identity.aliases.some((alias) => conceptKey(alias) === wanted)) return identity;
 	}
 	return null;
@@ -9243,19 +10635,14 @@ function requireIdentity(graph, target) {
 	return identity;
 }
 /**
-* The document's current text from a live handle, after its relay catch-up has reached its
-* terminal page. A fresh process has an empty Local Cache, so a cache-seeded read answers ""
-* for every document until the relay has spoken; a tool must never believe that emptiness.
+* The document's current text from a live handle, once the backend says it can be trusted:
+* caught up with the relay, or read from disk (`HeadlessDocuments.whenReady`). A fresh process
+* seeds every document empty until then, and a tool must never believe that emptiness.
 */
 async function liveText(graph, identity) {
 	await graph.store.whenReady(identity.concept);
-	const caughtUp = graph.sync.caughtUpDoc(identity.docId).then(() => "ok");
-	const timeout = new Promise((resolve) => setTimeout(() => resolve("timeout"), CATCH_UP_TIMEOUT_MS));
-	await Promise.race([caughtUp, timeout]);
 	return graph.store.open(identity.concept).getText();
 }
-/** How long a read waits for the relay before answering with what it has. */
-var CATCH_UP_TIMEOUT_MS = 15e3;
 function refuseIfProtected(concept, text) {
 	if (documentProtection(text).kind === "document") throw new ToolError("protected_document", `"${concept}" is a protected document. Its content is encrypted under a key this client never holds, so it cannot be read or changed here; the user can unlock it in EtherPK.`);
 }
@@ -9270,12 +10657,16 @@ function bounded(value, fallback, max) {
 	if (!Number.isInteger(value) || value < 0) throw new ToolError("invalid_argument", "offset and limit must be non-negative integers.");
 	return Math.min(value, max);
 }
-/** After a write: push it and wait for the relay, so the agent's next read anywhere sees it. */
+/**
+* After a write: make it durable - acknowledged by the relay, or on disk - so the agent's next
+* read anywhere sees it, and refuse in the backend's own words when that did not happen.
+*/
 async function settle(graph) {
 	const result = await graph.settle();
-	if (!result.settled) throw new ToolError("not_settled", `The edit is saved locally but the Sync Server has not acknowledged it (${result.outstanding} outstanding). It will be delivered when the connection recovers.`);
+	if (!result.settled) throw new ToolError("not_settled", result.message);
 }
-function listDocuments(graph, args = {}) {
+async function listDocuments(graph, args = {}) {
+	await graph.store.refresh();
 	const offset = bounded(args.offset, 0, Number.MAX_SAFE_INTEGER);
 	const limit = bounded(args.limit, 200, 200);
 	const protectedKeys = new Set(graph.index.allConcepts().filter((candidate) => candidate.protected && (candidate.kind === "page" || candidate.kind === "journal")).map((candidate) => candidate.key));
@@ -9293,6 +10684,7 @@ function listDocuments(graph, args = {}) {
 	};
 }
 async function readDocument(graph, concept) {
+	await graph.store.refresh();
 	const identity = requireIdentity(graph, concept);
 	const text = await liveText(graph, identity);
 	refuseIfProtected(identity.concept, text);
@@ -9307,6 +10699,7 @@ async function readDocument(graph, concept) {
 async function search(graph, args) {
 	const query = args.query.trim();
 	if (query === "") throw new ToolError("invalid_argument", "query must not be empty.");
+	await graph.store.refresh();
 	const offset = bounded(args.offset, 0, Number.MAX_SAFE_INTEGER);
 	const limit = bounded(args.limit, 20, 50);
 	const mode = args.mode ?? "text";
@@ -9377,6 +10770,7 @@ async function searchText(graph, query, offset, limit) {
 async function backlinks(graph, concept) {
 	const target = concept.trim() === "today" ? todayISO() : concept.trim();
 	if (target === "") throw new ToolError("invalid_argument", "concept must not be empty.");
+	await graph.store.refresh();
 	return {
 		concept: target,
 		sources: (await graph.index.backlinks(target)).map((group) => ({
@@ -9396,6 +10790,7 @@ async function tasks(graph, args = {}) {
 	const statuses = args.statuses ?? OPEN_TASK_STATUSES;
 	for (const status of statuses) if (!TASK_STATUSES.includes(status)) throw new ToolError("invalid_argument", `Unknown task status "${status}".`);
 	const priorities = args.priorities ? args.priorities.map((priority) => priority === "none" ? null : priority) : [...TASK_PRIORITY_FILTERS];
+	await graph.store.refresh();
 	const result = await graph.index.tasks({
 		concept: args.concept?.trim() ? args.concept.trim() === "today" ? todayISO() : args.concept.trim() : null,
 		statuses,
@@ -9426,6 +10821,7 @@ async function tasks(graph, args = {}) {
 }
 async function editDocument(graph, args) {
 	if (args.old === "") throw new ToolError("invalid_argument", "old must not be empty.");
+	await graph.store.refresh();
 	const identity = requireIdentity(graph, args.concept);
 	const text = await liveText(graph, identity);
 	refuseIfProtected(identity.concept, text);
@@ -9449,6 +10845,7 @@ async function appendDocument(graph, args) {
 	const text = normaliseIndentUnit(args.text);
 	if (text.trim() === "") throw new ToolError("invalid_argument", "text must not be empty.");
 	const target = args.concept.trim() === "today" ? todayISO() : args.concept.trim();
+	await graph.store.refresh();
 	const existing = resolveIdentity(graph, target);
 	if (!existing) {
 		if (!isJournalConcept(target)) throw new ToolError("not_found", `No document is named "${target}". Use create_page to start a new page.`);
@@ -9477,6 +10874,7 @@ async function createPage(graph, args) {
 	const title = args.title.trim();
 	if (title === "") throw new ToolError("invalid_argument", "title must not be empty.");
 	if (isJournalConcept(title)) throw new ToolError("invalid_argument", `"${title}" is a calendar day, so it names a journal entry; use append_document to write to it.`);
+	await graph.store.refresh();
 	if (resolveIdentity(graph, title)) throw new ToolError("already_exists", `A document already answers to "${title}". Use edit_document or append_document instead.`);
 	await graph.store.createPage(title, normaliseIndentUnit(args.text ?? ""));
 	await settle(graph);
@@ -9598,7 +10996,7 @@ function createMcpServer(graph, info) {
 	}, async (args) => run(() => tasks(graph, args)));
 	server.registerTool("edit_document", {
 		title: "Edit a document",
-		description: "Replace one exact occurrence of \"old\" with \"new\" in a document. \"old\" must appear exactly once (include surrounding lines to disambiguate); the change is applied as one edit so it merges with anyone typing elsewhere in the page. Refused on a protected document.",
+		description: "Replace one exact occurrence of \"old\" with \"new\" in a document. \"old\" must appear exactly once (include surrounding lines to disambiguate); the change is applied as one edit, so on a synced graph it merges with anyone typing elsewhere in the page, and on a folder it is in the file when this returns. Refused on a protected document.",
 		inputSchema: {
 			concept,
 			old: z.string().min(1).describe("The exact text to replace, as read_document returned it."),
@@ -9624,6 +11022,147 @@ function createMcpServer(graph, info) {
 	return server;
 }
 //#endregion
+//#region ../client/src/lib/storage/fs/directory-adapter.ts
+/** All four, in skeleton-creation order. */
+var SUBDIRS = [
+	"journals",
+	"pages",
+	"assets",
+	"etherpk"
+];
+//#endregion
+//#region src/node-directory-adapter.ts
+/**
+* A {@link DirectoryAdapter} over a real directory through `node:fs`: the third adapter behind
+* the seam the filesystem store reads and writes through (the browser's `web-fs-adapter.ts`
+* and the tests' `memory-adapter.ts` are the other two), so `createFilesystemDocumentStore`
+* runs unchanged in the [[Headless Client]] over a local graph folder.
+*
+* The contract it keeps, because the store's external-change detection depends on it: a
+* listing reports each file's mtime in epoch milliseconds and its size in bytes, a write
+* answers with the same pair the next listing will show, listings hold files only, and a
+* root-file read answers `null` for "absent" and rejects for anything else, so a permission
+* problem is never mistaken for an empty slot and written over (see `directory-adapter.ts`).
+*/
+function isMissing(error) {
+	return error?.code === "ENOENT";
+}
+/** `bytes` as an ArrayBuffer-backed view of exactly its own length, as the contract promises. */
+function standalone(bytes) {
+	const copy = new Uint8Array(new ArrayBuffer(bytes.byteLength));
+	copy.set(bytes);
+	return copy;
+}
+function createNodeDirectoryAdapter(root) {
+	const dir = resolve(root);
+	const path = (subdir, name) => join(dir, subdir, name);
+	async function stamped(file) {
+		const info = await stat(file);
+		return {
+			lastModified: info.mtimeMs,
+			size: info.size
+		};
+	}
+	return {
+		async list(subdir) {
+			const entries = await readdir(join(dir, subdir), { withFileTypes: true }).catch((error) => {
+				if (isMissing(error)) return [];
+				throw error;
+			});
+			const out = [];
+			for (const entry of entries) {
+				if (!entry.isFile()) continue;
+				const { lastModified, size } = await stamped(path(subdir, entry.name));
+				out.push({
+					name: entry.name,
+					lastModified,
+					size
+				});
+			}
+			return out;
+		},
+		async read(subdir, name) {
+			const file = path(subdir, name);
+			return {
+				text: await readFile(file, "utf8"),
+				...await stamped(file)
+			};
+		},
+		async write(subdir, name, text) {
+			const file = path(subdir, name);
+			await mkdir(join(dir, subdir), { recursive: true });
+			await writeFile(file, text, "utf8");
+			return {
+				text,
+				...await stamped(file)
+			};
+		},
+		async readBinary(subdir, name) {
+			const file = path(subdir, name);
+			return {
+				bytes: standalone(await readFile(file)),
+				lastModified: (await stamped(file)).lastModified
+			};
+		},
+		async writeBinary(subdir, name, bytes) {
+			const file = path(subdir, name);
+			await mkdir(join(dir, subdir), { recursive: true });
+			await writeFile(file, bytes);
+			return {
+				bytes,
+				lastModified: (await stamped(file)).lastModified
+			};
+		},
+		async exists(subdir, name) {
+			try {
+				await access(path(subdir, name));
+				return true;
+			} catch (error) {
+				if (isMissing(error)) return false;
+				throw error;
+			}
+		},
+		async remove(subdir, name) {
+			await rm(path(subdir, name), { force: true });
+		},
+		async ensureSkeleton() {
+			for (const subdir of SUBDIRS) await mkdir(join(dir, subdir), { recursive: true });
+		},
+		async readRootFile(name) {
+			const file = join(dir, name);
+			let text;
+			try {
+				text = await readFile(file, "utf8");
+			} catch (error) {
+				if (isMissing(error)) return null;
+				throw error;
+			}
+			return {
+				text,
+				...await stamped(file)
+			};
+		},
+		async writeRootFile(name, text) {
+			const file = join(dir, name);
+			await writeFile(file, text, "utf8");
+			return {
+				text,
+				...await stamped(file)
+			};
+		}
+	};
+}
+/**
+* Whether `root` looks like a graph folder: a directory holding the `pages` and `journals`
+* subdirectories the skeleton creates. The Headless Client refuses anything else rather than
+* creating a skeleton in whatever directory was mistyped; opening the folder in EtherPK once is
+* what makes a graph.
+*/
+async function isGraphFolder(root) {
+	for (const subdir of ["pages", "journals"]) if (!(await stat(join(root, subdir)).catch(() => null))?.isDirectory()) return false;
+	return true;
+}
+//#endregion
 //#region src/main.ts
 /**
 * `etherpk-mcp`: the [[Headless Client]]'s command line (ADR 0072).
@@ -9631,6 +11170,7 @@ function createMcpServer(graph, info) {
 *   etherpk-mcp login  --sync-server <url> [--pat <token>] [--recovery-code]
 *   etherpk-mcp graphs [--sync-server <url>]
 *   etherpk-mcp serve  --graph <id or name> [--sync-server <url>] [--no-semantic]
+*   etherpk-mcp serve  --folder <path> [--no-semantic]
 *   etherpk-mcp logout [--sync-server <url> | --all]
 *   etherpk-mcp semantic setup | status | remove
 *
@@ -9660,11 +11200,17 @@ var USAGE = `etherpk-mcp - EtherPK Headless Client (an MCP server over one synce
   ${CMD} graphs [--sync-server <url>]
       List the synced graphs each signed-in account can reach, by name and id.
   ${CMD} serve --graph <id or name> [--sync-server <url>] [--no-semantic]
-      Serve one graph to an agent over stdio. For Claude Code:
+      Serve one synced graph to an agent over stdio. For Claude Code:
         claude mcp add etherpk -- npx @appsoftwareltd/etherpk-mcp serve --sync-server <url> --graph <id>
       Once "semantic setup" has run on this computer, serve also keeps a search-by-meaning
       store of the graph current (the agent's search tool gains mode: semantic); pass
       --no-semantic to leave it off for this registration.
+  ${CMD} serve --folder <path> [--no-semantic]
+      Serve a local graph folder the same way: no sign-in, no server. The agent gets search,
+      backlinks, tasks and format-safe edits over the folder's markdown, alongside the files
+      themselves. Edits made in an editor or by the agent directly are picked up as they land.
+      The folder must already be a graph (open it in EtherPK once); its index is kept under
+      the cache directory, never in the folder.
   ${CMD} logout [--sync-server <url> | --all]
       Forget that server's token, keys and cached graphs on this machine.
   ${CMD} semantic setup
@@ -9826,6 +11372,32 @@ async function graphsCommand(args) {
 	if (logins.length === 0) fail(`Not logged in on this machine. Run: ${CMD} login --sync-server <url>`);
 	for (const login of logins) await listGraphs(login, logins.length > 1);
 }
+/**
+* The fallback for a graph the server carries no name envelope for: read its root document once
+* and publish the name, so no later listing has to. The publish is awaited because these
+* commands exit as soon as they have printed, and a request still in flight would be lost.
+*/
+function metaNameReader(account) {
+	return async (record, keyring) => {
+		const publisher = createGraphNamePublisher({
+			api: account.api,
+			keyring,
+			graphId: record.id
+		});
+		try {
+			return await readGraphName({
+				graphId: record.id,
+				rootDocId: record.rootDocId,
+				keyring,
+				relayUrl: account.relayUrl,
+				token: account.tokenFor(record.id),
+				publishName: publisher.publish
+			});
+		} finally {
+			await publisher.settled();
+		}
+	};
+}
 async function listGraphs(login, several) {
 	if (!login.vaultKey) fail(`Keys are not unlocked on this machine for ${login.syncServer}. Run: ${CMD} login --sync-server ${login.syncServer}`);
 	const account = await connectAccount(login);
@@ -9837,18 +11409,8 @@ async function listGraphs(login, several) {
 		return;
 	}
 	console.log(several ? `Synced graphs on ${login.syncServer}:` : "Synced graphs:");
-	for (const record of graphs) {
-		const keyring = vault.keyrings.find((entry) => entry.graphId === record.id);
-		const name = keyring ? await readGraphName({
-			graphId: record.id,
-			rootDocId: record.rootDocId,
-			keyring,
-			relayUrl: account.relayUrl,
-			token: account.tokenFor(record.id)
-		}) : null;
-		const label = keyring ? name ?? "(unnamed)" : "(no key on this account yet - open it in EtherPK first)";
-		console.log(`  ${record.id}  ${label}  [${record.role}]`);
-	}
+	const readMeta = metaNameReader(account);
+	for (const record of graphs) console.log(`  ${record.id}  ${describeGraphLabel(await resolveGraphLabel(record, vault, readMeta))}  [${record.role}]`);
 	console.log("");
 	console.log(`Serve one to an agent with:  ${CMD} serve${serverFlag} --graph <id>`);
 	console.log(`For Claude Code:             claude mcp add etherpk -- ${CMD} serve${serverFlag} --graph <id>`);
@@ -9904,9 +11466,49 @@ function memoryNote() {
 	return ` [rss ${mb(m.rss)} MB, heap ${mb(m.heapUsed)} MB, external ${mb(m.external)} MB, arrayBuffers ${mb(m.arrayBuffers)} MB]`;
 }
 if (debugMemory) setInterval(() => console.error(`etherpk-mcp: memory${memoryNote()}`), 1e4).unref();
+/**
+* The embedding model for a serve, whichever backend: refused with the reason when the agent's
+* registration turned it off, else loaded on first semantic use. Always wired, so a semantic
+* search on a machine without setup is refused with the command to run - and once it has run,
+* the next search loads the model with no restart.
+*/
+function embeddingModelFor(args) {
+	return args["no-semantic"] ? () => Promise.reject(new SemanticUnavailable("Semantic search is off for this agent: serve was started with --no-semantic.")) : () => loadEmbeddingModel(process.env);
+}
 async function serve(args) {
+	const folder = args.folder?.trim();
 	const wanted = args.graph?.trim();
-	if (!wanted) fail("serve needs --graph <id or name>.");
+	if (folder && (wanted || args["sync-server"])) fail("serve takes either --folder <path> or --graph <id or name> (with an optional --sync-server), not both.");
+	if (!folder && !wanted) fail("serve needs --graph <id or name>, or --folder <path> for a local graph folder.");
+	const { graph, graphName } = folder ? await openFolderForServe(folder, args) : await openSyncedForServe(wanted, args);
+	await serveGraph(graph, graphName, args);
+}
+/**
+* A local graph folder: no sign-in and no server ([[2026-09-18 Headless Client Serves A Local
+* Folder]]). The folder is what it is; the CLI never creates a skeleton in whatever directory
+* was mistyped. The index lives under the cache root, keyed by the folder's path.
+*/
+async function openFolderForServe(folder, args) {
+	const path = resolve(folder);
+	if (!await isGraphFolder(path)) fail(`${path} is not an EtherPK graph folder: it has no pages/ and journals/ directories. Open the folder in EtherPK once to make it one, then serve it.`);
+	const name = basename(path);
+	console.error(`etherpk-mcp: opening folder ${path}…`);
+	return {
+		graph: await openHeadlessFolder({
+			adapter: createNodeDirectoryAdapter(path),
+			name,
+			graphId: folderKey(path),
+			persistDir: folderCacheDir(process.env, path),
+			embeddingModel: embeddingModelFor(args),
+			onSemanticProgress: reportSemanticProgress,
+			onError: (error) => console.error(`etherpk-mcp: ${error.message}`),
+			onWarning: (line) => console.error(`etherpk-mcp: ${line}`),
+			watch: watchFolder(path, (error) => console.error(`etherpk-mcp: not watching the folder for changes (${error.message}); edits made outside are still picked up before each tool call.`))
+		}),
+		graphName: name
+	};
+}
+async function openSyncedForServe(wanted, args) {
 	const login = requireServer(await loadConfig(defaultConfigPath()), args["sync-server"]);
 	if (!login.vaultKey) fail(`Keys are not unlocked on this machine for ${login.syncServer}. Run: ${CMD} login --sync-server ${login.syncServer}`);
 	const account = await connectAccount(login);
@@ -9914,26 +11516,15 @@ async function serve(args) {
 	const graphs = await account.api.listGraphs();
 	let graphId = graphs.find((graph) => graph.id === wanted)?.id;
 	let graphName = null;
-	if (!graphId) for (const record of graphs) {
-		const keyring = vault.keyrings.find((entry) => entry.graphId === record.id);
-		if (!keyring) continue;
-		const name = await readGraphName({
-			graphId: record.id,
-			rootDocId: record.rootDocId,
-			keyring,
-			relayUrl: account.relayUrl,
-			token: account.tokenFor(record.id)
-		});
-		if (name && name.toLowerCase() === wanted.toLowerCase()) {
-			graphId = record.id;
-			graphName = name;
-			break;
+	if (!graphId) {
+		const match = await findGraphByName(graphs, vault, wanted, metaNameReader(account));
+		if (match) {
+			graphId = match.record.id;
+			graphName = match.name;
 		}
 	}
 	if (!graphId) fail(`No synced graph on ${login.syncServer} is named or identified by "${wanted}". Run: ${CMD} graphs`);
 	const { record, keyring } = resolveGraphById(graphs, vault, graphId);
-	const semanticReady = await semanticSetupStatus(process.env);
-	const semanticOn = !args["no-semantic"] && semanticReady.runtime && semanticReady.model;
 	console.error(`etherpk-mcp: opening graph ${graphId} on ${account.serverBaseUrl}…`);
 	const graph = await openHeadlessGraph({
 		graphId,
@@ -9944,11 +11535,24 @@ async function serve(args) {
 		presenceName: `Agent on ${hostname()}`,
 		readyTimeoutMs: 2e4,
 		persistDir: graphCacheDir(process.env, account.serverBaseUrl, graphId),
-		embeddingModel: args["no-semantic"] ? () => Promise.reject(new SemanticUnavailable("Semantic search is off for this agent: serve was started with --no-semantic.")) : () => loadEmbeddingModel(process.env),
+		embeddingModel: embeddingModelFor(args),
 		onSemanticProgress: reportSemanticProgress,
-		onError: (error) => console.error(`etherpk-mcp: ${error.message}`)
+		onError: (error) => console.error(`etherpk-mcp: ${error.message}`),
+		publishName: createGraphNamePublisher({
+			api: account.api,
+			keyring,
+			graphId
+		}).publish
 	});
-	graphName ??= graph.sync.getMeta().name ?? graphId;
+	return {
+		graph,
+		graphName: graphName ?? graph.name
+	};
+}
+/** Speak MCP over stdio for an open graph until the transport closes or a signal arrives. */
+async function serveGraph(graph, graphName, args) {
+	const semanticReady = await semanticSetupStatus(process.env);
+	const semanticOn = !args["no-semantic"] && semanticReady.runtime && semanticReady.model;
 	const server = createMcpServer(graph, {
 		graphName,
 		version: VERSION
@@ -10008,6 +11612,7 @@ async function main() {
 			pat: { type: "string" },
 			"recovery-code": { type: "boolean" },
 			graph: { type: "string" },
+			folder: { type: "string" },
 			"no-semantic": { type: "boolean" },
 			all: { type: "boolean" },
 			help: {