@appsoftwareltd/etherpk-mcp 0.8.54 → 0.8.60

package/dist/main.js

@@ -36,7 +36,7 @@ import { UndirectedGraph } from "graphology";
 import louvain from "graphology-communities-louvain";
 var package_default = {
 	name: "@appsoftwareltd/etherpk-mcp",
-	version: "0.8.54",
+	version: "0.8.60",
 	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",
@@ -2673,9 +2673,14 @@ function withoutRanges(input, ranges) {
 * it. A rename's "N documents link to X and will be updated" counts the documents whose text
 * the rewrite touches; a page that merely carries the scope in its title is retitled by the
 * cascade and reported there, so counting it here would describe it twice (ADR 0083).
+*
+* Given `name`, only links that say that name count. The rewrite changes `[[name]]` and no
+* other name the page answers to, so a rename asks by the name it renames (ADR 0065, amended
+* 2026-10-04): the page's title and its aliases share one group of backlinks.
 */
-function referencedInBody(group) {
-	return group.refs.some((ref) => ref.kind !== "title");
+function referencedInBody(group, name) {
+	if (name === void 0) return group.refs.some((ref) => ref.kind !== "title");
+	return group.bodyNames.includes(conceptKey$1(name));
 }
 var MAX_CONTEXT = 1e3;
 var SCHEMA$1 = `
@@ -2810,8 +2815,39 @@ function isUsableIndex(db) {
 		return false;
 	}
 }
-function documentHash(db, key) {
-	return db.all("SELECT text_hash FROM pages WHERE generation = ? AND concept_key = ? LIMIT 1", [activeIndexGeneration(db), key])[0]?.text_hash;
+/**
+* The page the live generation holds under `key`, as an ingest compares a document with it: its
+* hash, and the title and kind it is shown under, which a title changed only in case moves while
+* its key and its text stay the same.
+*/
+function indexedPage(db, key) {
+	const row = db.all("SELECT text_hash, concept, kind FROM pages WHERE generation = ? AND concept_key = ? LIMIT 1", [activeIndexGeneration(db), key])[0];
+	return row ? {
+		hash: row.text_hash,
+		concept: row.concept,
+		kind: row.kind
+	} : void 0;
+}
+/**
+* Every document the live generation holds, by its names: what a change to the graph's names is
+* reconciled against (`reconcileNames`). Read from the tables, not the concept candidates, which
+* hold one row per name and so lose a page whose title is another page's alias.
+*/
+function indexedNames(db) {
+	const generation = activeIndexGeneration(db);
+	const pages = db.all("SELECT id, concept, kind FROM pages WHERE generation = ?", [generation]);
+	const aliases = db.all("SELECT a.page_id, a.display FROM aliases a JOIN pages p ON p.id = a.page_id WHERE p.generation = ? ORDER BY a.rowid", [generation]);
+	const byPage = /* @__PURE__ */ new Map();
+	for (const alias of aliases) {
+		const list = byPage.get(alias.page_id);
+		if (list) list.push(alias.display);
+		else byPage.set(alias.page_id, [alias.display]);
+	}
+	return pages.map((page) => ({
+		concept: page.concept,
+		kind: page.kind,
+		aliases: byPage.get(page.id) ?? []
+	}));
 }
 /**
 * cyrb53 — a fast, non-cryptographic 53-bit string hash. Not a security boundary: it decides
@@ -2826,10 +2862,11 @@ function documentHash(db, key) {
 function indexDocHash(doc) {
 	const includes = doc.includes ?? [];
 	const properties = doc.properties ?? [];
-	if (includes.length === 0 && properties.length === 0) return hashText(doc.text);
+	const aliases = doc.aliases ?? [];
+	if (includes.length === 0 && properties.length === 0 && aliases.length === 0) return hashText(doc.text);
 	const includeText = includes.map((i) => `${i.publication}\u0001${i.slot}\u0001${i.concept}`).join("\0");
 	const propertyText = properties.map((p) => `${p.key}\u0001${p.value ?? ""}`).join("\0");
-	return hashText(`${doc.text}\u0000${includeText}\u0003${propertyText}`);
+	return hashText(`${doc.text}\u0000${includeText}\u0003${propertyText}\u0004${aliases.join("\0")}`);
 }
 function hashText(text) {
 	let h1 = 3735928559;
@@ -3147,16 +3184,7 @@ function ingestOne(db, doc) {
 		const leaving = found.length > 0 && protectedFlag(doc) === 1 ? db.all("SELECT text FROM block_fts WHERE rowid >= ? AND rowid < ?", blockFtsRange(found[0].id)).map((row) => row.text) : [];
 		if (found.length > 0) {
 			pageId = found[0].id;
-			db.run("DELETE FROM aliases WHERE page_id = ?", [pageId]);
-			db.run("DELETE FROM publication_includes WHERE page_id = ?", [pageId]);
-			const [ftsFrom, ftsTo] = blockFtsRange(pageId);
-			db.run("DELETE FROM block_fts WHERE rowid >= ? AND rowid < ?", [ftsFrom, ftsTo]);
-			db.run("DELETE FROM blocks WHERE page_id = ?", [pageId]);
-			db.run("DELETE FROM links WHERE page_id = ?", [pageId]);
-			db.run("DELETE FROM tasks WHERE page_id = ?", [pageId]);
-			db.run("DELETE FROM task_concepts WHERE page_id = ?", [pageId]);
-			db.run("DELETE FROM passages WHERE page_id = ?", [pageId]);
-			db.run("DELETE FROM properties WHERE page_id = ?", [pageId]);
+			deleteDerivedRows(db, pageId);
 			db.run("UPDATE pages SET concept = ?, kind = ?, text_hash = ?, protected = ? WHERE id = ?", [
 				doc.concept,
 				doc.kind,
@@ -3180,6 +3208,40 @@ function ingestOne(db, doc) {
 		if (leaving.some((text) => !written.has(text))) purgeDeletedText(db);
 	});
 }
+/**
+* Every row derived from page `pageId`, the page row itself aside: what an ingest replaces and a
+* removal drops. One list, so a table added to the schema is cleared by both.
+*/
+function deleteDerivedRows(db, pageId) {
+	db.run("DELETE FROM aliases WHERE page_id = ?", [pageId]);
+	db.run("DELETE FROM publication_includes WHERE page_id = ?", [pageId]);
+	const [ftsFrom, ftsTo] = blockFtsRange(pageId);
+	db.run("DELETE FROM block_fts WHERE rowid >= ? AND rowid < ?", [ftsFrom, ftsTo]);
+	db.run("DELETE FROM blocks WHERE page_id = ?", [pageId]);
+	db.run("DELETE FROM links WHERE page_id = ?", [pageId]);
+	db.run("DELETE FROM tasks WHERE page_id = ?", [pageId]);
+	db.run("DELETE FROM task_concepts WHERE page_id = ?", [pageId]);
+	db.run("DELETE FROM passages WHERE page_id = ?", [pageId]);
+	db.run("DELETE FROM properties WHERE page_id = ?", [pageId]);
+}
+/**
+* Drop the document with key `key` from the live generation: its page row and every row derived
+* from it. A rename, a delete, or a title becoming another page's alias leaves rows under a name
+* no document has any more, and this takes them out one document at a time, where a whole
+* replacement would re-read the graph. Links other documents hold to the name are theirs and stay,
+* so a name still linked to lives on as a [[Pageless Concept]]. Returns whether there was one.
+*/
+function removeDocument(db, key) {
+	let removed = false;
+	inTransaction(db, () => {
+		const found = db.all("SELECT id FROM pages WHERE generation = ? AND concept_key = ?", [activeIndexGeneration(db), key]);
+		if (found.length === 0) return;
+		deleteDerivedRows(db, found[0].id);
+		db.run("DELETE FROM pages WHERE id = ?", [found[0].id]);
+		removed = true;
+	});
+	return removed;
+}
 /** Every concept key that resolves to a real document (canonical name or alias). */
 function existingConceptKeys(db) {
 	const generation = activeIndexGeneration(db);
@@ -3505,7 +3567,7 @@ function backlinksFor(db, concept) {
 	if (names.length === 0) return [];
 	const placeholders = names.map(() => "?").join(",");
 	const generation = activeIndexGeneration(db);
-	const hits = db.all(`SELECT l.page_id, p.concept AS sourceConcept, p.kind AS sourceKind, l.line, l.line_text,
+	const hits = db.all(`SELECT l.page_id, l.concept_key, p.concept AS sourceConcept, p.kind AS sourceKind, l.line, l.line_text,
                 l.match_start, l.match_end, l.block_local_id, l.in_title
          FROM links l JOIN pages p ON p.id = l.page_id
          WHERE p.generation=? AND l.concept_key IN (${placeholders})
@@ -3531,18 +3593,20 @@ function backlinksFor(db, concept) {
 	const groups = /* @__PURE__ */ new Map();
 	const places = /* @__PURE__ */ new Set();
 	for (const h of hits) {
-		const place = h.in_title ? `${h.page_id}:title` : h.block_local_id != null ? `${h.page_id}:block:${h.block_local_id}` : `${h.page_id}:line:${h.line}`;
-		if (places.has(place)) continue;
-		places.add(place);
 		let group = groups.get(h.sourceConcept);
 		if (!group) {
 			group = {
 				sourceConcept: h.sourceConcept,
 				sourceKind: h.sourceKind,
-				refs: []
+				refs: [],
+				bodyNames: []
 			};
 			groups.set(h.sourceConcept, group);
 		}
+		if (!h.in_title && !group.bodyNames.includes(h.concept_key)) group.bodyNames.push(h.concept_key);
+		const place = h.in_title ? `${h.page_id}:title` : h.block_local_id != null ? `${h.page_id}:block:${h.block_local_id}` : `${h.page_id}:line:${h.line}`;
+		if (places.has(place)) continue;
+		places.add(place);
 		group.refs.push(buildRef(h, blocksByPage.get(h.page_id) ?? []));
 	}
 	const rank = (ref) => ref.kind === "title" ? 0 : 1;
@@ -8835,6 +8899,44 @@ function lastNonBlank(lines) {
 	return -1;
 }
 //#endregion
+//#region ../client/src/lib/document/index-worker/name-reconcile.ts
+/**
+* Which documents' names differ between the [[Derived Index]] and the store, so a change to the
+* graph's names (a create, a rename, an alias change, a delete) re-reads only those documents
+* rather than every document in the graph.
+*
+* Both sides are documents by their names, without their text: the index's are its own page and
+* alias rows (the worker's \`names\` answer), the store's its listing. A document whose title, kind
+* or aliases differ is \`changed\` and read again; a title the index has and the store does not is
+* \`removed\`. Matched by title key, so a page whose title another page has as an alias is still a
+* document of its own. A name only links hold (a [[Pageless Concept]]) has no page row, so it is
+* never removed here: the linking documents keep it.
+*
+* Pure, so the rule is unit-tested without a worker or a store.
+*/
+function reconcileNames(indexed, listed) {
+	const held = new Map(indexed.map((document) => [conceptKey$1(document.concept), document]));
+	const changed = [];
+	for (const document of listed) {
+		const key = conceptKey$1(document.concept);
+		const known = held.get(key);
+		held.delete(key);
+		if (!known || known.concept !== document.concept || known.kind !== document.kind || !sameNames(known.aliases ?? [], document.aliases ?? [])) changed.push(document.concept);
+	}
+	return {
+		changed,
+		removed: [...held.values()].map((document) => document.concept)
+	};
+}
+/** Whether two alias lists name the same names, as the index keys them: order and case aside. */
+function sameNames(a, b) {
+	const keys = new Set(a.map(conceptKey$1));
+	const other = new Set(b.map(conceptKey$1));
+	if (keys.size !== other.size) return false;
+	for (const key of keys) if (!other.has(key)) return false;
+	return true;
+}
+//#endregion
 //#region ../client/src/lib/document/index-link-graph.ts
 /**
 * The [[Graph View]]'s query over the [[Derived Index]]: every [[Concept]] and every pair of
@@ -9133,10 +9235,27 @@ function createIndexCore(host) {
 			case "ingest": {
 				if (!db) throw new Error("index not open");
 				const changed = [];
-				for (const doc of request.docs) if (documentHash(db, conceptKey$1(doc.concept)) !== indexDocHash(doc)) changed.push(doc);
-				if (changed.length === 0) return [];
+				for (const doc of request.docs) {
+					const stored = indexedPage(db, conceptKey$1(doc.concept));
+					if (!(stored !== void 0 && stored.hash === indexDocHash(doc) && stored.concept === doc.concept && stored.kind === doc.kind)) changed.push(doc);
+				}
+				const taken = new Set(request.docs.map((doc) => conceptKey$1(doc.concept)));
+				const removed = [...new Set((request.removed ?? []).map(conceptKey$1))].filter((key) => !taken.has(key) && indexedPage(db, key) !== void 0);
+				if (changed.length === 0 && removed.length === 0) return [];
 				const affected = /* @__PURE__ */ new Set();
 				const backlinkTargetsChanged = /* @__PURE__ */ new Set();
+				for (const key of removed) {
+					const before = indexedDocumentFacts(db, key);
+					for (const name of [key, ...before.aliases]) {
+						affected.add(name);
+						backlinkTargetsChanged.add(name);
+					}
+					for (const target of before.includeTargets) for (const family of conceptFamilyKeys(db, target)) affected.add(family);
+					for (const target of before.linkTargets) {
+						affected.add(target);
+						backlinkTargetsChanged.add(target);
+					}
+				}
 				for (const doc of changed) {
 					const key = conceptKey$1(doc.concept);
 					const before = indexedDocumentFacts(db, key);
@@ -9152,6 +9271,7 @@ function createIndexCore(host) {
 				const before = conceptCandidatesForKeys(db, affected);
 				const previousSnapshot = visibleSnapshot;
 				visibleSnapshot = void 0;
+				for (const key of removed) removeDocument(db, key);
 				for (const doc of changed) ingestOne(db, doc);
 				const after = conceptCandidatesForKeys(db, affected);
 				const delta = deltaFor(advanceIndexRevision(db), before, after, backlinkTargetsChanged);
@@ -9237,6 +9357,11 @@ function createIndexCore(host) {
 					usage
 				}];
 			}
+			case "names": return [{
+				type: "names",
+				id: request.id,
+				documents: db ? indexedNames(db) : []
+			}];
 			case "link-graph": {
 				const graph = db ? linkGraph(db) : {
 					concepts: [],
@@ -9394,6 +9519,10 @@ function createRemoteGraphIndex(source, transport, options) {
 	let workerReplaced = false;
 	/** Set while refresh()'s initial full derivation runs; cleared by its snapshot. */
 	let building = false;
+	/** Rebuilds queued or running, catch-ups and cold builds not yet finished: what `isBusy` reads. */
+	let workInFlight = 0;
+	let busyReported = false;
+	const busyChanged = /* @__PURE__ */ new Set();
 	const updated = /* @__PURE__ */ new Set();
 	let timer;
 	let rebuildTail = Promise.resolve();
@@ -9411,6 +9540,20 @@ function createRemoteGraphIndex(source, transport, options) {
 	let coldCatchUpPending = false;
 	/** Concepts whose content changed, or `null` for "the document set moved — replace all". */
 	let dirty = /* @__PURE__ */ new Set();
+	/**
+	* The graph's names moved since the last rebuild (a create, rename, alias change or delete):
+	* the next one reconciles them against the source's listing (`reconcileNames`) and re-reads
+	* only the documents they changed, where it used to replace the whole index.
+	*/
+	let namesMoved = false;
+	/**
+	* Source changes observed so far, and how many of them a completed rebuild had taken when it
+	* started: what `settled` waits on, so it waits for the changes seen when it was asked only.
+	*/
+	let observedChanges = 0;
+	let ingestedThrough = 0;
+	/** Rebuilds queued on the tail and not finished: whether a `settled` wait can still end. */
+	let queuedRuns = 0;
 	let nextId = 1;
 	let nextOpenId = 1;
 	const pending = /* @__PURE__ */ new Map();
@@ -9777,8 +9920,33 @@ function createRemoteGraphIndex(source, transport, options) {
 			return response;
 		}
 	}
+	/** Tell `onBusyChanged` listeners when `isBusy()` has changed. */
+	function reportBusy() {
+		const busy = workInFlight > 0;
+		if (busy === busyReported) return;
+		busyReported = busy;
+		for (const listener of busyChanged) listener(busy);
+	}
+	/**
+	* Count `work` towards `isBusy()` until it settles, whichever way. Started at once, not a
+	* microtask later: `runRebuild` chains the next run onto the tail it reads synchronously.
+	*/
+	function busyWhile(work) {
+		workInFlight++;
+		reportBusy();
+		let started;
+		try {
+			started = work();
+		} catch (error) {
+			started = Promise.reject(error);
+		}
+		return started.finally(() => {
+			workInFlight--;
+			reportBusy();
+		});
+	}
 	function catchUpWarmIndex({ verifyExternalSource = true } = {}) {
-		Promise.resolve().then(() => withCatchUpLock(async () => {
+		busyWhile(() => Promise.resolve().then(() => withCatchUpLock(async () => {
 			if (source.catchUpPersistedIndex) {
 				await source.catchUpPersistedIndex();
 				if (timer !== void 0) {
@@ -9791,7 +9959,7 @@ function createRemoteGraphIndex(source, transport, options) {
 			if (!verifyExternalSource) return;
 			dirty = null;
 			await runRebuild();
-		})).catch((error) => options.onBackgroundError?.(error instanceof Error ? error : new Error(String(error))));
+		}))).catch((error) => options.onBackgroundError?.(error instanceof Error ? error : new Error(String(error))));
 	}
 	/** Hand the worker every document. Used when nothing usable is persisted. */
 	async function rebuildAll(checkpointStream) {
@@ -9865,40 +10033,87 @@ function createRemoteGraphIndex(source, transport, options) {
 		const checkpointDocuments = new Map((checkpoint?.documents ?? []).map((document) => [conceptKey$1(document.concept), document]));
 		if (checkpoint?.changes === null) dirty = null;
 		else if (checkpoint && dirty !== null) for (const change of checkpoint.changes) dirty.add(change.concept);
+		const listing = checkpoint?.names ?? source.listDocuments?.();
+		if (checkpoint?.namesMoved) if (listing) namesMoved = true;
+		else dirty = null;
+		const through = observedChanges;
 		const changed = dirty;
+		const reconcile = namesMoved;
 		dirty = /* @__PURE__ */ new Set();
+		namesMoved = false;
+		/** Titles the source no longer has, found by reconciling names; read nothing to drop. */
+		let removed = [];
 		try {
+			if (changed !== null && reconcile && listing) {
+				const names = reconcileNames(await indexedNames(), listing);
+				for (const concept of names.changed) changed.add(concept);
+				removed = names.removed;
+			}
 			const checkpointCoversChanged = changed !== null && [...changed].every((concept) => checkpointDocuments.has(conceptKey$1(concept)));
-			if (changed === null || changed.size > INCREMENTAL_LIMIT && !checkpointCoversChanged) await rebuildAll(checkpoint?.streamForIndex);
-			else if (changed.size > 0) {
-				const docs = [];
-				for (const concept of changed) {
-					const doc = checkpointDocuments.get(conceptKey$1(concept)) ?? await source.snapshotDocument?.(concept);
-					if (doc) docs.push(doc);
-				}
-				if (docs.length !== changed.size) await rebuildAll(checkpoint?.streamForIndex);
-				else {
-					for (let start = 0; start < docs.length; start += REBUILD_SEND_CHUNK) transport.send({
-						type: "ingest",
-						docs: docs.slice(start, start + REBUILD_SEND_CHUNK)
-					});
-					await request((id) => ({
-						type: "barrier",
-						id
-					}));
-				}
+			const targeted = changed !== null && (changed.size + removed.length <= INCREMENTAL_LIMIT || checkpointCoversChanged) ? await targetedChanges(changed, removed, checkpointDocuments, listing) : null;
+			if (targeted === null) await rebuildAll(checkpoint?.streamForIndex);
+			else if (targeted.docs.length > 0 || targeted.removed.length > 0) {
+				const { docs } = targeted;
+				for (let start = 0; start < Math.max(docs.length, 1); start += REBUILD_SEND_CHUNK) transport.send({
+					type: "ingest",
+					docs: docs.slice(start, start + REBUILD_SEND_CHUNK),
+					...start === 0 && targeted.removed.length > 0 ? { removed: targeted.removed } : {}
+				});
+				await request((id) => ({
+					type: "barrier",
+					id
+				}));
 			}
 			await checkpoint?.acknowledge();
+			ingestedThrough = Math.max(ingestedThrough, through);
 		} catch (error) {
 			if (changed === null) dirty = null;
-			else if (dirty !== null) for (const concept of changed) dirty.add(concept);
+			else if (dirty !== null) for (const concept of [...changed, ...removed]) dirty.add(concept);
+			if (reconcile) namesMoved = true;
 			throw error;
 		}
 	}
-	/** Source events and the terminal catch-up flush share one ordered main-thread pipeline. */
+	/** Every document the index holds, by its names: the worker's own rows (`indexedNames`). */
+	async function indexedNames() {
+		return (await request((id) => ({
+			type: "names",
+			id
+		}))).documents;
+	}
+	/**
+	* What a targeted ingest takes for `changed` and `removed`: each changed name read again, and
+	* dropped when it reads back as nothing (gone) or as a document under another title (now that
+	* document's alias, or retitled). Null when a name might only have failed to read: one the
+	* source still lists as a title, or any, from a source that cannot list its documents.
+	*/
+	async function targetedChanges(changed, removed, checkpointDocuments, listing) {
+		const listed = listing ? new Set(listing.map((document) => conceptKey$1(document.concept))) : null;
+		const docs = /* @__PURE__ */ new Map();
+		const gone = new Set(removed);
+		for (const concept of changed) {
+			const doc = checkpointDocuments.get(conceptKey$1(concept)) ?? await source.snapshotDocument?.(concept);
+			if (!doc) {
+				if (!listed || listed.has(conceptKey$1(concept))) return null;
+				gone.add(concept);
+				continue;
+			}
+			if (conceptKey$1(doc.concept) !== conceptKey$1(concept)) gone.add(concept);
+			docs.set(conceptKey$1(doc.concept), doc);
+		}
+		return {
+			docs: [...docs.values()],
+			removed: [...gone]
+		};
+	}
+	/**
+	* Source events and the terminal catch-up flush share one ordered main-thread pipeline. A run
+	* counts as busy from the moment it is queued, so runs waiting on one another read as one spell.
+	*/
 	function runRebuild() {
-		const next = rebuildTail.then(() => rebuild());
+		queuedRuns++;
+		const next = busyWhile(() => rebuildTail.then(() => rebuild()));
 		rebuildTail = next.catch(() => void 0).then(() => {
+			queuedRuns--;
 			const woken = drainWaiters;
 			drainWaiters = [];
 			for (const wake of woken) wake();
@@ -9909,12 +10124,19 @@ function createRemoteGraphIndex(source, transport, options) {
 		if (timer !== void 0) clearTimeout(timer);
 		timer = setTimeout(() => {
 			timer = void 0;
-			runRebuild().catch((error) => options.onBackgroundError?.(error instanceof Error ? error : new Error(String(error))));
+			runRebuild().catch(reportBackgroundError);
 		}, debounceMs);
 	}
+	/** A rebuild nobody awaits failed: said, without failing anything that is waiting. */
+	function reportBackgroundError(error) {
+		options.onBackgroundError?.(error instanceof Error ? error : new Error(String(error)));
+	}
 	function scheduleRebuild(change) {
-		if (!change || !source.snapshotDocument) dirty = null;
-		else if (dirty !== null) dirty.add(change.concept);
+		observedChanges++;
+		if (change && source.snapshotDocument) {
+			if (dirty !== null) dirty.add(change.concept);
+		} else if (!change && source.snapshotDocument && source.listDocuments) namesMoved = true;
+		else dirty = null;
 		if (activeRebuildId) {
 			rebuildInvalidated = true;
 			return;
@@ -10068,6 +10290,11 @@ function createRemoteGraphIndex(source, transport, options) {
 			return () => persistenceChanged.delete(listener);
 		},
 		isBuilding: () => building,
+		isBusy: () => busyReported,
+		onBusyChanged(listener) {
+			busyChanged.add(listener);
+			return () => busyChanged.delete(listener);
+		},
 		async refresh() {
 			if ((await preparedOpenResponse(true)).indexedDocuments > 0) {
 				backgroundRebuildsEnabled = true;
@@ -10075,7 +10302,7 @@ function createRemoteGraphIndex(source, transport, options) {
 				return;
 			}
 			building = true;
-			await withRebuildLock(async () => {
+			await busyWhile(() => withRebuildLock(async () => {
 				if ((await openIndex()).indexedDocuments > 0) {
 					building = false;
 					backgroundRebuildsEnabled = true;
@@ -10086,7 +10313,7 @@ function createRemoteGraphIndex(source, transport, options) {
 				coldCatchUpPending = true;
 				await runRebuild();
 				backgroundRebuildsEnabled = true;
-			});
+			}));
 		},
 		async rebuild() {
 			if (disposed) return;
@@ -10104,13 +10331,17 @@ function createRemoteGraphIndex(source, transport, options) {
 			return () => updated.delete(listener);
 		},
 		settled() {
+			const target = observedChanges;
 			return new Promise((resolve) => {
 				const look = () => {
-					if (timer !== void 0 && !disposed) {
-						drainWaiters.push(look);
-						return;
+					if (disposed || ingestedThrough >= target) return resolve();
+					if (timer !== void 0 && backgroundRebuildsEnabled) {
+						clearTimeout(timer);
+						timer = void 0;
+						runRebuild().catch(reportBackgroundError);
 					}
-					rebuildTail.then(resolve, resolve);
+					if (queuedRuns === 0) return resolve();
+					drainWaiters.push(look);
 				};
 				look();
 			});
@@ -10125,6 +10356,7 @@ function createRemoteGraphIndex(source, transport, options) {
 			unsubscribe();
 			updated.clear();
 			persistenceChanged.clear();
+			busyChanged.clear();
 			transport.send({ type: "close" });
 			transport.close();
 		}
@@ -10777,7 +11009,7 @@ function normaliseAliases(aliases, concept) {
 	return out;
 }
 /** Set equality by identity key: order and case carry no meaning. */
-function sameAliases(a, b) {
+function sameAliases$1(a, b) {
 	const left = new Set(a.map(conceptKey));
 	const right = new Set(b.map(conceptKey));
 	return left.size === right.size && [...left].every((key) => right.has(key));
@@ -10796,7 +11028,7 @@ function withFrontmatterIdentity(text, patch, options = {}) {
 		if (data === null) return text;
 		const wantTitle = patch.title === void 0 ? titleOf(data) : patch.title;
 		const wantAliases = patch.aliases === void 0 ? aliasesOf({ data }) : patch.aliases;
-		if (wantTitle === titleOf(data) && sameAliases(wantAliases, aliasesOf({ data }))) return text;
+		if (wantTitle === titleOf(data) && sameAliases$1(wantAliases, aliasesOf({ data }))) return text;
 	}
 	return editFrontmatter(text, (block) => {
 		if (patch.title !== void 0) if (patch.title === null || patch.title.trim() === "") block.delete("title");
@@ -10810,7 +11042,8 @@ function withFrontmatterIdentity(text, patch, options = {}) {
 * the rewrite added. A writer that gives a document its first block, as Publish does when it adds
 * `public:`, must not make the document claim fewer aliases than it has: a block with no
 * `aliases:` line claims none, and the next edit to it would clear them (ADR 0061). Only a Server
-* Backend has aliases without a block; on a Filesystem Backend they are read from the saved file,
+* Backend has aliases without a block, on a document aliased before they were always shown and not
+* yet repaired (amended 2026-10-03). On a Filesystem Backend they are read from the saved file,
 * so `aliases` is empty there provided the caller wrote pending edits before reading them
 * (`rewriteFrontmatter` flushes first). A block `before` already had is left as the writer left it.
 */
@@ -11151,6 +11384,18 @@ var DocumentSyncDegradedError = class extends Error {
 		this.name = "DocumentSyncDegradedError";
 	}
 };
+/**
+* A synced document this device could not bring current in time, so a write that has to see its
+* whole text was refused rather than made blind: a block added to text that has not arrived would
+* sit above the document's own block once it does.
+*/
+var DocumentUnconfirmedError = class extends Error {
+	constructor(target) {
+		super(`"${target}" has not finished syncing to this device. Nothing was changed - try again once sync has caught up.`);
+		this.target = target;
+		this.name = "DocumentUnconfirmedError";
+	}
+};
 //#endregion
 //#region ../client/src/lib/storage/file-names.ts
 /**
@@ -11276,6 +11521,15 @@ function renameRefusal(options) {
 function renameSteps(plan) {
 	return [plan.direct, ...plan.cascade];
 }
+/**
+* The name a document called `concept` before the rename goes by after it: where a title step
+* lands it (its `into`, a merge's survivor included), or the same name when no step moves it.
+* How a holder of an alias the rename rewrites is found, and named in what the rename reports.
+*/
+function landedName(plan, concept) {
+	const key = conceptKey(concept);
+	return renameSteps(plan).find((step) => step.hasDocument && conceptKey(step.from) === key)?.into ?? concept;
+}
 /** How many steps merge - what the dialog warns about. */
 function mergeCount(plan) {
 	return renameSteps(plan).filter((s) => s.merges).length;
@@ -11292,10 +11546,12 @@ function mergeCount(plan) {
 function planRename$1(input) {
 	const from = input.from.trim();
 	const to = input.to.trim();
+	const renamedAlias = input.kind === null ? (input.aliases ?? []).find((alias) => conceptKey(alias.name) === conceptKey(from)) : void 0;
+	const aliasOf = renamedAlias?.concept ?? null;
 	const refusal = renameRefusal({
 		from,
 		to,
-		kind: input.kind
+		kind: renamedAlias ? "page" : input.kind
 	});
 	const hasDocument = input.kind !== null;
 	const direct = {
@@ -11309,18 +11565,110 @@ function planRename$1(input) {
 	if (refusal) return {
 		direct,
 		cascade: [],
+		aliases: [],
+		aliasOf,
 		referencingDocuments: input.referencingDocuments,
 		refusal
 	};
 	const existing = new Map(input.concepts.map((c) => [conceptKey(c), c]));
 	for (const alias of input.aliases ?? []) if (!existing.has(conceptKey(alias.name))) existing.set(conceptKey(alias.name), alias.concept);
 	const cascade = cascadeFor(input.concepts, from, to).sort((a, b) => depthOf(b.from) - depthOf(a.from)).map((step) => stepFor(step.from, step.to, true, existing));
-	return {
-		direct: stepFor(from, to, hasDocument, existing),
+	const plan = {
+		direct: renamedAlias ? direct : stepFor(from, to, hasDocument, existing),
 		cascade,
+		aliases: [],
+		aliasOf,
 		referencingDocuments: input.referencingDocuments,
 		refusal: null
 	};
+	const rewrites = aliasRewrites(plan, renamedAlias, input.aliases ?? [], existing);
+	return "refusal" in rewrites ? {
+		...plan,
+		refusal: rewrites.refusal
+	} : {
+		...plan,
+		aliases: rewrites.aliases
+	};
+}
+/**
+* The aliases the rename rewrites: the alias it names, when it names one (ADR 0065, amended
+* 2026-10-04), then every alias that names `from` as a scope, by the cascade's own rule, on
+* whatever document holds it (ADR 0038, amended 2026-10-03). A new form that a different document
+* will answer to refuses the rename: one another document already has, by title or alias; one a
+* title step of this same rename gives; or one another alias of this rename also becomes. Sharing
+* an alias does not make two documents one concept, and the name would go to whichever document a
+* lookup reached first.
+*
+* "Different" is judged on where each document ends up: a merge in the same rename makes two
+* documents one, so a parallel hierarchy merging into another, each page with its scoped alias,
+* is no collision. Nor is a re-casing (the name stays the same name), a form the holder itself
+* already has (the applier drops the duplicate), or one alias two documents already shared (the
+* rename carries that over rather than creating it).
+*/
+function aliasRewrites(plan, renamed, aliases, existing) {
+	const steps = renameSteps(plan).filter((step) => step.hasDocument);
+	const landed = new Map(steps.map((step) => [conceptKey(step.from), step.into]));
+	const endsIn = (concept) => conceptKey(landed.get(conceptKey(concept)) ?? concept);
+	const given = new Map(steps.map((step) => [conceptKey(step.to), step.from]));
+	const planned = /* @__PURE__ */ new Map();
+	const refuse = (alias, to, why) => ({ refusal: `“${alias.concept}” has the alias “${alias.name}”, which the rename would make “${to}”, but ${why}. Change one of the two names, then rename again.` });
+	const candidates = renamed ? [{
+		alias: renamed,
+		to: plan.direct.to
+	}] : [];
+	for (const alias of aliases) {
+		const rewritten = rewriteWikilinkScope(alias.name, plan.direct.from, plan.direct.to);
+		if (rewritten.count > 0) candidates.push({
+			alias,
+			to: rewritten.text
+		});
+	}
+	const out = [];
+	for (const { alias, to } of candidates) {
+		const key = conceptKey(to);
+		if (key !== conceptKey(alias.name)) {
+			const holder = endsIn(alias.concept);
+			const owner = existing.get(key);
+			if (owner !== void 0 && endsIn(owner) !== holder) {
+				if (alias === renamed) return { refusal: renamedAliasTaken(alias, to, owner) };
+				return refuse(alias, to, `that is already a name of “${owner}”`);
+			}
+			const receiver = given.get(key);
+			if (receiver !== void 0 && endsIn(receiver) !== holder) return refuse(alias, to, `the rename gives that name to “${receiver}”`);
+			const earlier = planned.get(key);
+			if (earlier && endsIn(earlier.concept) !== holder && conceptKey(earlier.name) !== conceptKey(alias.name)) return refuse(alias, to, `it would also make “${earlier.concept}”'s alias “${earlier.name}” that name`);
+			planned.set(key, alias);
+		}
+		out.push({
+			holder: alias.concept,
+			from: alias.name,
+			to
+		});
+	}
+	return { aliases: out };
+}
+/**
+* Why an alias cannot be renamed to a name another document answers to. Not a merge, as a page's
+* rename onto a taken name is: the alias belongs to one page, and the other page keeps its name.
+*/
+function renamedAliasTaken(alias, to, owner) {
+	return `${conceptKey(owner) === conceptKey(to) ? `“${to}” is another page's name` : `“${to}” is already an alias of “${owner}”`}, so “${alias.concept}”'s alias “${alias.name}” cannot be renamed to it. Choose another name, or keep the link as typed.`;
+}
+/**
+* A holder's alias list after the rename (ADR 0038, amended 2026-10-03): under the rewrite arm
+* each rewritten alias is replaced in place, as the links that used it are rewritten; under the
+* alias arm the old form stays, since untouched links still say it, and the new form is added
+* after it. The caller normalises the result, which drops a new form the document already has.
+*/
+function aliasesAfterRename(current, rewrites, strategy) {
+	const next = [];
+	for (const alias of current) {
+		const rewrite = rewrites.find((r) => conceptKey(r.from) === conceptKey(alias));
+		if (!rewrite) next.push(alias);
+		else if (strategy === "rewrite") next.push(rewrite.to);
+		else next.push(alias, rewrite.to);
+	}
+	return next;
 }
 /**
 * A [[Protected Document]] never merges (ADR 0062): not into another document, and nothing into
@@ -11353,13 +11701,16 @@ async function refuseProtectedMerges(plan, isProtected) {
 * Refuse a plan whose steps would rewrite a [[Frontmatter]] block that does not parse. A
 * Filesystem Backend rebuilds each renamed document's block, and a merge survivor's, from its
 * parsed data, which is empty for such a block, so every key it holds would be lost from the file:
-* the only copy. `textOf` gives a document's current text (an open buffer, else its file), or
-* null for a name with no document behind it.
+* the only copy. `textOf` gives the text a step rewrites, or null for a name with no document
+* behind it. A document whose alias the rename rewrites has its block rewritten too, and
+* `holderTextOf` gives the text that write starts from (an open buffer, where a step's is the
+* file), defaulting to `textOf`.
 */
-async function refuseUnreadableBlocks(plan, textOf) {
+async function refuseUnreadableBlocks(plan, textOf, holderTextOf = textOf) {
 	if (plan.refusal) return plan;
-	for (const step of renameSteps(plan)) for (const concept of step.merges ? [step.from, step.into] : [step.from]) {
-		const text = await textOf(concept);
+	const checks = [...renameSteps(plan).flatMap((step) => step.merges ? [step.from, step.into] : [step.from]).map((concept) => [concept, textOf]), ...plan.aliases.map((alias) => [alias.holder, holderTextOf])];
+	for (const [concept, read] of checks) {
+		const text = await read(concept);
 		if (text === null || frontmatterIdentity(text).readable) continue;
 		return {
 			...plan,
@@ -11494,6 +11845,48 @@ async function scanGraph(adapter, options = {}) {
 	return [...journals, ...pages];
 }
 //#endregion
+//#region ../client/src/lib/storage/fs/registry-changes.ts
+/**
+* What a rescan of a graph folder changed, as the [[Derived Index]] needs to hear it: the
+* documents whose files changed on disk, each by name, and whether any name changed (a document
+* added, removed, retitled or re-cased, or given other aliases). The two are separate because they
+* cost differently: a changed file is one document to re-read, while moved names are reconciled
+* against the index's own names (`reconcileNames`) and re-read only the documents they touch.
+*
+* The store keeps an entry's file stamps in step with its own writes, so a save it made is never
+* reported here a second time: what is left is an edit made outside the app.
+*
+* A document new under its name, or held by another file than before, is named as well as moving
+* the names. Names alone cannot tell it from the document the index last saw under that name: a
+* page renamed away and another created under its old title, both before the index caught up,
+* left the index holding the first page's rows for the second.
+*
+* Pure, so the rule is unit-tested without a folder.
+*/
+function registryChanges(previous, next) {
+	let namesMoved = previous.size !== next.length;
+	const contentChanged = [];
+	for (const entry of next) {
+		const before = previous.get(entry.key);
+		if (!before) {
+			namesMoved = true;
+			contentChanged.push(entry.concept);
+			continue;
+		}
+		if (before.concept !== entry.concept || before.kind !== entry.kind || !sameAliases(before.aliases, entry.aliases)) namesMoved = true;
+		if (before.subdir !== entry.subdir || before.fileName !== entry.fileName || before.lastModified !== entry.lastModified || before.size !== entry.size) contentChanged.push(entry.concept);
+	}
+	return {
+		namesMoved,
+		contentChanged
+	};
+}
+function sameAliases(a, b) {
+	if (a.length !== b.length) return false;
+	const keys = new Set(a.map(conceptKey));
+	return b.every((alias) => keys.has(conceptKey(alias)));
+}
+//#endregion
 //#region ../client/src/lib/storage/fs/filesystem-store.ts
 /**
 * The snapshot for one document's full text: identity from the registry, aliases and include
@@ -11529,6 +11922,13 @@ function createFilesystemDocumentStore(adapter, options = {}) {
 	const { autosaveMs = 400, onConflict } = options;
 	const registry = /* @__PURE__ */ new Map();
 	let registrySig = "";
+	/**
+	* The registry as the last rescan announced it, what the next one's changes are measured
+	* against. Not `registry` itself: a rename's steps patch that in place before the closing
+	* rescan, which would then find nothing moved. The same entry objects, so a save's stamps,
+	* kept in step on its entry, are never mistaken for an edit made outside the app.
+	*/
+	let announced = /* @__PURE__ */ new Map();
 	const open = /* @__PURE__ */ new Map();
 	const documentsChanged = /* @__PURE__ */ new Set();
 	const documentRemoved = /* @__PURE__ */ new Set();
@@ -11545,9 +11945,16 @@ function createFilesystemDocumentStore(adapter, options = {}) {
 	function conceptOf(doc) {
 		return registry.get(doc.key)?.concept ?? doc.target;
 	}
-	function emitDocumentsChanged() {
+	/**
+	* Tell listeners what a rescan changed. The document-set listeners hear whenever the listing
+	* moved; the index hears it precisely (`registryChanges`): each file changed outside the app,
+	* by name, and the names, once, when they moved. Unnamed for every listing change, it re-read
+	* every document after each save, since a save's new file stamp moves the listing too.
+	*/
+	function emitRegistryChanged(changes) {
 		for (const listener of documentsChanged) listener();
-		emitChange();
+		for (const concept of changes.contentChanged) emitChange({ concept });
+		if (changes.namesMoved) emitChange();
 	}
 	function emitDocumentRemoved(target) {
 		for (const listener of documentRemoved) listener(target);
@@ -11576,7 +11983,7 @@ function createFilesystemDocumentStore(adapter, options = {}) {
 	/** 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;
+		if (sameAliases$1(aliases, entry.aliases)) return;
 		entry.aliases = aliases;
 		emitRegistryOnly();
 	}
@@ -11614,10 +12021,13 @@ function createFilesystemDocumentStore(adapter, options = {}) {
 		});
 		registry.clear();
 		for (const entry of entries) registry.set(entry.key, entry);
+		for (const doc of [...open.values()]) if (doc.removed && registry.has(doc.key)) await takeUpFileAgain(doc);
 		const sig = registrySignature(entries);
 		if (sig !== registrySig) {
 			registrySig = sig;
-			emitDocumentsChanged();
+			const changes = registryChanges(announced, entries);
+			announced = new Map(registry);
+			emitRegistryChanged(changes);
 		}
 		return entries;
 	}
@@ -11668,6 +12078,34 @@ function createFilesystemDocumentStore(adapter, options = {}) {
 		}
 	}
 	/**
+	* The aliases a rename carries along (ADR 0038, amended 2026-10-03), after its title steps,
+	* on both arms: each holder's list with its rewrites applied, handed to `write` (the store's
+	* `setAliases`, which goes through the open buffer or the file and patches the registry).
+	* Never through `applyStep`, which retitles and moves files and would give a journal a
+	* title. A holder a step retitled, or merged into another document, is found under the name
+	* it landed on. Its aliases are read from the open buffer where there is one, so an alias
+	* typed but not yet saved is kept. Returns the holders, by their names now.
+	*/
+	async function rewriteScopedAliases(plan, strategy, write) {
+		const byHolder = /* @__PURE__ */ new Map();
+		for (const rewrite of plan.aliases) {
+			const key = conceptKey(landedName(plan, rewrite.holder));
+			byHolder.set(key, [...byHolder.get(key) ?? [], rewrite]);
+		}
+		const holders = [];
+		for (const [key, rewrites] of byHolder) {
+			const entry = registry.get(key);
+			if (!entry) continue;
+			const openDoc = open.get(entry.key);
+			if (openDoc) await openDoc.ready;
+			const text = openDoc?.loaded ? openDoc.buffer : (await adapter.read(entry.subdir, entry.fileName)).text;
+			if (!frontmatterIdentity(text).readable) throw new Error(unreadableBlockRefusal(plan.direct.from, entry.concept));
+			await write(entry.concept, aliasesAfterRename(aliasesOf(parseFrontmatter(text)), rewrites, strategy));
+			holders.push(entry.concept);
+		}
+		return holders;
+	}
+	/**
 	* One step of a rename plan: retitle the document, and if the target name is already
 	* taken, [[Merge]] into it instead.
 	*
@@ -11695,8 +12133,15 @@ function createFilesystemDocumentStore(adapter, options = {}) {
 		}
 		const targetEntry = step.merges ? registry.get(conceptKey(step.into)) : void 0;
 		const survivor = targetEntry && targetEntry.key !== entry.key ? targetEntry : void 0;
+		const survivorDoc = survivor ? open.get(survivor.key) : void 0;
+		if (survivorDoc) {
+			survivorDoc.save.cancel();
+			await settled(survivorDoc);
+			await survivorDoc.ready;
+		}
+		const throughBuffer = survivorDoc?.loaded === true;
 		if (survivor) {
-			const existing = await adapter.read(survivor.subdir, survivor.fileName);
+			const existing = { text: throughBuffer ? survivorDoc.buffer : (await adapter.read(survivor.subdir, survivor.fileName)).text };
 			if (!frontmatterIdentity(existing.text).readable) throw new Error(unreadableBlockRefusal(step.from, survivor.concept));
 			const existingFm = parseFrontmatter(existing.text);
 			const merged = mergeDocuments({
@@ -11718,7 +12163,19 @@ function createFilesystemDocumentStore(adapter, options = {}) {
 		}, { addBlock: true });
 		const subdir = survivor?.subdir ?? entry.subdir;
 		const fileName = survivor?.fileName ?? await allocateFileName(subdir, step.into, entry);
-		const written = await adapter.write(subdir, fileName, content);
+		let written;
+		if (throughBuffer && survivorDoc) {
+			survivorDoc.handle.applyChange({
+				from: 0,
+				to: survivorDoc.buffer.length,
+				insert: content
+			}, "external");
+			await saveNow(survivorDoc);
+			written = {
+				lastModified: survivorDoc.lastModified,
+				size: survivorDoc.size
+			};
+		} else written = await adapter.write(subdir, fileName, content);
 		if (!(subdir === entry.subdir && fileName === entry.fileName)) await adapter.remove(entry.subdir, entry.fileName);
 		registry.delete(entry.key);
 		if (survivor) registry.delete(survivor.key);
@@ -11733,6 +12190,8 @@ function createFilesystemDocumentStore(adapter, options = {}) {
 			size: written.size
 		});
 		if (openDoc) open.delete(entry.key);
+		const stale = open.get(conceptKey(step.into));
+		if (stale?.removed) await takeUpFileAgain(stale);
 	}
 	/**
 	* Start the document's save if none is in flight, else note that one is wanted. One writable
@@ -11823,7 +12282,7 @@ function createFilesystemDocumentStore(adapter, options = {}) {
 	/** The open document `target` names, opening it if it is not; throws when nothing has that name. */
 	function openDocNamed(target) {
 		const existing = open.get(conceptKey(target));
-		if (existing) return existing;
+		if (existing && !(existing.removed && existing.deletedHere)) return existing;
 		const entry = entryNamed(target);
 		if (!entry) throw new DocumentNotFoundError(target);
 		const opened = open.get(entry.key);
@@ -11847,6 +12306,7 @@ function createFilesystemDocumentStore(adapter, options = {}) {
 			loadError: null,
 			ready: Promise.resolve(),
 			removed: false,
+			deletedHere: false,
 			conflict: null,
 			listeners: /* @__PURE__ */ new Set(),
 			save: void 0,
@@ -11866,6 +12326,7 @@ function createFilesystemDocumentStore(adapter, options = {}) {
 				doc.dirty = true;
 				if (doc.removed) {
 					doc.removed = false;
+					doc.deletedHere = false;
 					options.onResurrected?.(doc.target);
 				}
 				doc.save.call();
@@ -11941,6 +12402,27 @@ function createFilesystemDocumentStore(adapter, options = {}) {
 		doc.save.cancel();
 		onConflict?.(doc.conflict);
 	}
+	/**
+	* A document removed while open keeps its buffer, so its tab still shows it and an edit there
+	* brings it back (ADR 0039 §4). It answers to its name only until a file does again: a page
+	* created under the name, in the app or by another program. Then it takes that file up as an
+	* opened document would. A buffer with no unsaved edits reloads from the file, and one with
+	* unsaved edits raises a conflict rather than being written over it. Before, it kept the name
+	* for the session: the name opened the deleted text, the index read it, and the first
+	* keystroke saved it over the new file.
+	*/
+	async function takeUpFileAgain(doc) {
+		const entry = registry.get(doc.key);
+		if (!doc.removed || !entry) return;
+		const read = await readIfPresent(entry.subdir, entry.fileName);
+		if (!read) return;
+		doc.removed = false;
+		doc.deletedHere = false;
+		doc.subdir = entry.subdir;
+		doc.fileName = entry.fileName;
+		doc.target = entry.concept;
+		followDisk(doc, read);
+	}
 	/** A file's content, or null when it does not exist; any other failure rejects. */
 	async function readIfPresent(subdir, fileName) {
 		try {
@@ -12019,8 +12501,8 @@ function createFilesystemDocumentStore(adapter, options = {}) {
 			if (!entry) throw new DocumentNotFoundError(target);
 			const next = normaliseAliases(aliases, entry.concept);
 			const doc = open.get(entry.key);
-			if (doc) {
-				await doc.ready;
+			if (doc) await doc.ready;
+			if (doc?.loaded) {
 				const text = withFrontmatterIdentity(doc.buffer, { aliases: next }, { addBlock: next.length > 0 });
 				if (text !== doc.buffer) doc.handle.applyChange({
 					from: 0,
@@ -12037,7 +12519,7 @@ function createFilesystemDocumentStore(adapter, options = {}) {
 					emitChange({ concept: entry.concept });
 				}
 			}
-			if (!sameAliases(entry.aliases, next)) {
+			if (!sameAliases$1(entry.aliases, next)) {
 				entry.aliases = next;
 				emitRegistryOnly();
 			}
@@ -12100,8 +12582,10 @@ function createFilesystemDocumentStore(adapter, options = {}) {
 			return indexSnapshotOf(entry, text);
 		},
 		async reconcile() {
+			const wasRemoved = new Set([...open.values()].filter((doc) => doc.removed));
 			await refreshRegistry();
 			for (const doc of [...open.values()]) {
+				if (wasRemoved.has(doc) && !doc.removed) continue;
 				if (!registry.has(doc.key)) followFile(doc);
 				await reconcileDoc(doc);
 			}
@@ -12178,12 +12662,19 @@ function createFilesystemDocumentStore(adapter, options = {}) {
 				const openDoc = open.get(other.key);
 				if (openDoc) await settled(openDoc);
 				return (await adapter.read(other.subdir, other.fileName)).text;
+			}, async (concept) => {
+				const other = registry.get(conceptKey(concept));
+				if (!other) return null;
+				const openDoc = open.get(other.key);
+				if (openDoc) await openDoc.ready;
+				return openDoc?.loaded ? openDoc.buffer : (await adapter.read(other.subdir, other.fileName)).text;
 			});
 		},
 		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);
+			const aliasesRewritten = await rewriteScopedAliases(plan, options.strategy, (target, aliases) => this.setAliases(target, aliases));
 			let rewritten = 0;
 			const rewrittenDocuments = [];
 			if (options.strategy === "rewrite") for (const other of [...registry.values()]) {
@@ -12214,12 +12705,16 @@ function createFilesystemDocumentStore(adapter, options = {}) {
 				rewrittenDocuments.push(other.concept);
 			}
 			await refreshRegistry();
+			const wrote = [...renameSteps(plan).filter((step) => step.hasDocument).map((step) => step.into), ...rewrittenDocuments];
+			for (const concept of new Set(wrote)) emitChange({ concept });
 			return {
 				concept: plan.direct.into,
+				aliasOf: plan.aliasOf === null ? null : landedName(plan, plan.aliasOf),
 				rewritten,
 				rewrittenDocuments,
 				cascaded: plan.cascade.length,
-				merged: mergeCount(plan)
+				merged: mergeCount(plan),
+				aliasesRewritten
 			};
 		},
 		async deleteDocument(concept) {
@@ -12229,6 +12724,8 @@ function createFilesystemDocumentStore(adapter, options = {}) {
 			if (doc) {
 				doc.save.cancel();
 				doc.removed = true;
+				doc.deletedHere = true;
+				doc.dirty = false;
 				await settled(doc);
 			}
 			await adapter.remove(entry.subdir, entry.fileName);
@@ -12242,7 +12739,7 @@ function createFilesystemDocumentStore(adapter, options = {}) {
 		},
 		async flushAll() {
 			await Promise.all([...open.values()].map(saveNow));
-			const unwritten = [...open.values()].filter((doc) => doc.dirty).map((doc) => doc.target);
+			const unwritten = [...open.values()].filter((doc) => doc.dirty && !doc.removed).map((doc) => doc.target);
 			if (unwritten.length > 0) throw new Error(`Edits to ${unwritten.join(", ")} could not be written to the folder yet, so it does not hold them. Try again once they are saved.`);
 		},
 		async dispose() {
@@ -12313,6 +12810,23 @@ function bodyView(handle) {
 		subscribe: (listener) => handle.subscribe((text) => listener(bodyOf$1(text).body))
 	};
 }
+//#endregion
+//#region ../client/src/lib/reached-within.ts
+/**
+* Whether `promise` settled within `timeoutMs`. A milestone that never arrives (offline, a silent
+* server, an index that keeps being handed changes) is a bounded wait and a `false`, never a hang
+* and never an unhandled rejection: the caller decides what an unreached milestone means.
+*/
+async function reachedWithin(promise, timeoutMs) {
+	let timer;
+	try {
+		return await Promise.race([promise.then(() => true, () => false), new Promise((resolve) => {
+			timer = setTimeout(() => resolve(false), timeoutMs);
+		})]);
+	} finally {
+		if (timer) clearTimeout(timer);
+	}
+}
 function createSemanticIndex(options) {
 	const { index, model } = options;
 	const floor = options.floor ?? .25;
@@ -12430,21 +12944,6 @@ function createBreather(now = () => performance.now()) {
 function conceptOf(entry) {
 	return entry.kind === "journal" ? entry.date ?? "" : entry.title ?? "";
 }
-/**
-* Whether `promise` settled within `timeoutMs`. A sync milestone that never arrives (offline, a
-* silent server) is a bounded wait and a `false`, never a hang and never an unhandled rejection:
-* the caller decides what an unreached milestone means.
-*/
-async function reachedWithin(promise, timeoutMs) {
-	let timer;
-	try {
-		return await Promise.race([promise.then(() => true, () => false), new Promise((resolve) => {
-			timer = setTimeout(() => resolve(false), timeoutMs);
-		})]);
-	} finally {
-		if (timer) clearTimeout(timer);
-	}
-}
 function createServerDocumentStore(graph, options) {
 	const registry = graph.registry();
 	/** Engines created between yields while snapshotting — small enough to keep frames free. */
@@ -12566,9 +13065,11 @@ function createServerDocumentStore(graph, options) {
 			const additions = [];
 			const renames = [];
 			let additionsOnly = true;
+			const named = /* @__PURE__ */ new Map();
 			for (const docId of changedDocIds) {
 				const before = knownRegistry.get(docId);
 				const after = nextRegistry.get(docId);
+				for (const entry of [before, after]) if (entry) named.set(conceptKey(entry.concept), entry.concept);
 				if (fromElsewhere && before && after && before.concept !== after.concept) renames.push({
 					docId,
 					from: before.concept,
@@ -12588,7 +13089,10 @@ function createServerDocumentStore(graph, options) {
 			knownRegistry = nextRegistry;
 			docsChangedListeners.forEach((l) => l());
 			if (!restored) if (additionsOnly) for (const concept of additions) changeListeners.forEach((listener) => listener({ concept }));
-			else changeListeners.forEach((listener) => listener());
+			else {
+				for (const concept of named.values()) changeListeners.forEach((listener) => listener({ concept }));
+				changeListeners.forEach((listener) => listener());
+			}
 			for (const { docId, from, to } of renames) {
 				const first = renamesFromElsewhere.get(docId)?.from ?? from;
 				if (first === to) renamesFromElsewhere.delete(docId);
@@ -12659,18 +13163,31 @@ function createServerDocumentStore(graph, options) {
 	* Bring a block the text carries in line with the registry (ADR 0061). Part of the action that
 	* changed the registry - a rename, an alias change - and never a reaction to one arriving: if
 	* every member's device rewrote the block on seeing the registry move, the CRDT would merge N
-	* identical concurrent edits into duplicated text. Adds no block to a document without one. A
-	* journal's title is its date, so only its aliases are mirrored.
+	* identical concurrent edits into duplicated text. A journal's title is its date, so only its
+	* aliases are mirrored.
+	*
+	* A document with aliases and no block is given one (amended 2026-10-03): an alias is never
+	* invisible, so a page that answers to another name says so in its text. Without aliases a
+	* document without a block keeps none. The caller has brought the text current first, or the
+	* block would be written above a block still on its way.
 	*/
 	function writeBackIdentity(docId) {
 		const entry = registry.get(docId);
 		if (!entry) return;
 		const ytext = graph.docSync(docId).doc.getText("content");
 		const text = ytext.toString();
-		const next = withFrontmatterIdentity(text, {
+		const aliases = entry.aliases ?? [];
+		replaceBlock(ytext, text, withFrontmatterIdentity(text, {
 			...entry.kind === "page" ? { title: conceptOf(entry) } : {},
-			aliases: entry.aliases ?? []
-		});
+			aliases
+		}, { addBlock: aliases.length > 0 }));
+	}
+	/**
+	* Write `next`'s block over `text`'s. Only the block is replaced: the body is verbatim in
+	* `next`, and a whole-document rewrite would be a whole-document edit for every other member
+	* to receive.
+	*/
+	function replaceBlock(ytext, text, next) {
 		if (next === text) return;
 		const before = frontmatterSpan(text)?.end ?? 0;
 		const after = frontmatterSpan(next)?.end ?? 0;
@@ -12899,12 +13416,7 @@ function createServerDocumentStore(graph, options) {
 				if (timer) clearTimeout(timer);
 			}
 		},
-		async confirmRegistry(timeoutMs = 5e3) {
-			if (registryConfirmed) return true;
-			if (!graph.isConnected()) return false;
-			if (await reachedWithin(graph.rootCaughtUp(), timeoutMs)) registryConfirmed = true;
-			return registryConfirmed;
-		},
+		confirmRegistry,
 		onDocumentsChanged(listener) {
 			docsChangedListeners.add(listener);
 			return () => docsChangedListeners.delete(listener);
@@ -13015,19 +13527,25 @@ function createServerDocumentStore(graph, options) {
 			});
 			const concepts = /* @__PURE__ */ new Map();
 			const documents = [];
-			let requiresFullReplacement = false;
+			let namesMoved = false;
 			for (const docId of checkpoint.docIds) {
 				const entry = entriesByDocId.get(docId);
 				if (!entry) {
-					requiresFullReplacement = true;
-					break;
+					namesMoved = true;
+					continue;
 				}
 				const concept = conceptOf(entry);
 				concepts.set(conceptKey(concept), concept);
 				documents.push(await snapshot(docId, entry));
 			}
 			return {
-				changes: requiresFullReplacement ? null : [...concepts.values()].map((concept) => ({ concept })),
+				changes: [...concepts.values()].map((concept) => ({ concept })),
+				namesMoved,
+				...namesMoved ? { names: entries.map(([, entry]) => ({
+					concept: conceptOf(entry),
+					kind: entry.kind,
+					aliases: entry.aliases ?? []
+				})) } : {},
 				documents,
 				streamForIndex: checkpointStream,
 				acknowledge: checkpoint.acknowledge
@@ -13054,14 +13572,64 @@ function createServerDocumentStore(graph, options) {
 		},
 		async setAliases(target, aliases) {
 			const docId = docIdFor(target);
-			const entry = docId ? registry.get(docId) : void 0;
-			if (!docId || !entry) throw new DocumentNotFoundError(target);
-			const next = normaliseAliases(aliases, conceptOf(entry));
-			const updated = { ...entry };
-			if (next.length > 0) updated.aliases = next;
-			else delete updated.aliases;
-			registry.set(docId, updated);
-			writeBackIdentity(docId);
+			const known = docId ? registry.get(docId) : void 0;
+			if (!docId || !known) throw new DocumentNotFoundError(target);
+			if (!givesFirstBlock(docId, known, aliases)) {
+				writeAliases(docId, known, aliases);
+				return;
+			}
+			const materialised = await materialise([docId], COLD_CONTENT_TIMEOUT_MS);
+			try {
+				const entry = registry.get(docId);
+				if (!entry) throw new DocumentNotFoundError(target);
+				if (materialised.unconfirmed.length > 0) throw new DocumentUnconfirmedError(target);
+				writeAliases(docId, entry, aliases);
+			} finally {
+				materialised.release();
+			}
+		},
+		async revealHiddenAliases() {
+			if (!graph.isConnected() || !await confirmRegistry()) throw new Error("This graph has not finished syncing to this device, so nothing was changed.");
+			const report = {
+				revealed: [],
+				unreadable: [],
+				unconfirmed: []
+			};
+			const holders = [];
+			registry.forEach((entry, docId) => {
+				if ((entry.aliases ?? []).length > 0) holders.push(docId);
+			});
+			if (holders.length === 0) return report;
+			const materialised = await materialise(holders, COLD_CONTENT_TIMEOUT_MS);
+			try {
+				const unconfirmed = new Set(materialised.unconfirmed);
+				for (const docId of holders) {
+					const entry = registry.get(docId);
+					const aliases = entry?.aliases ?? [];
+					if (!entry || aliases.length === 0) continue;
+					const name = conceptOf(entry);
+					if (unconfirmed.has(docId)) {
+						report.unconfirmed.push(name);
+						continue;
+					}
+					const ytext = graph.docSync(docId).doc.getText("content");
+					const text = ytext.toString();
+					const claim = frontmatterIdentity(text);
+					if (claim.hasBlock && !claim.readable) {
+						report.unreadable.push(name);
+						continue;
+					}
+					if (claim.hasAliasesKey) continue;
+					replaceBlock(ytext, text, claim.hasBlock ? withFrontmatterIdentity(text, { aliases }) : withFrontmatterIdentity(text, {
+						...entry.kind === "page" ? { title: name } : {},
+						aliases
+					}, { addBlock: true }));
+					report.revealed.push(name);
+				}
+			} finally {
+				materialised.release();
+			}
+			return report;
 		},
 		async spliceIfUnchanged(docId, expected, splices, spliceOptions) {
 			if (!registry.has(docId)) return "gone";
@@ -13118,7 +13686,8 @@ function createServerDocumentStore(graph, options) {
 		},
 		async planRename(from, to, referencingDocuments) {
 			const docId = docIdFor(from);
-			const entry = docId ? registry.get(docId) : void 0;
+			const resolved = docId ? registry.get(docId) : void 0;
+			const entry = resolved && conceptKey(conceptOf(resolved)) === conceptKey(from) ? resolved : void 0;
 			let counted = 0;
 			const concepts = [];
 			const aliases = [];
@@ -13152,6 +13721,10 @@ function createServerDocumentStore(graph, options) {
 				const id = docIdFor(concept);
 				if (id) wanted.add(id);
 			}
+			for (const alias of plan.aliases) {
+				const id = docIdFor(alias.holder);
+				if (id) wanted.add(id);
+			}
 			if (options.strategy === "rewrite") if (options.referencing) for (const concept of options.referencing) {
 				const id = docIdFor(concept);
 				if (id) wanted.add(id);
@@ -13184,12 +13757,55 @@ function createServerDocumentStore(graph, options) {
 			graph.dispose();
 		}
 	};
+	async function confirmRegistry(timeoutMs = 5e3) {
+		if (registryConfirmed) return true;
+		if (!graph.isConnected()) return false;
+		if (await reachedWithin(graph.rootCaughtUp(), timeoutMs)) registryConfirmed = true;
+		return registryConfirmed;
+	}
+	/** Whether writing `aliases` back would give the document its first block (amended 2026-10-03). */
+	function givesFirstBlock(docId, entry, aliases) {
+		if (normaliseAliases(aliases, conceptOf(entry)).length === 0) return false;
+		return frontmatterSpan(graph.docSync(docId).doc.getText("content").toString()) === null;
+	}
+	/** Write a document's aliases to the registry, the authority, and show them in its block, added if need be. */
+	function writeAliases(docId, entry, aliases) {
+		const next = normaliseAliases(aliases, conceptOf(entry));
+		const updated = { ...entry };
+		if (next.length > 0) updated.aliases = next;
+		else delete updated.aliases;
+		registry.set(docId, updated);
+		writeBackIdentity(docId);
+	}
+	/**
+	* The aliases a rename carries along (ADR 0038, amended 2026-10-03), after its title steps,
+	* on both arms: each holder's registry list with its rewrites applied. A holder a step
+	* retitled, or merged into another document, is found under the name it landed on. Returns
+	* the holders, by their names now.
+	*/
+	function rewriteScopedAliases(plan, options) {
+		const byHolder = /* @__PURE__ */ new Map();
+		for (const rewrite of plan.aliases) {
+			const docId = docIdFor(landedName(plan, rewrite.holder));
+			if (docId) byHolder.set(docId, [...byHolder.get(docId) ?? [], rewrite]);
+		}
+		const holders = [];
+		for (const [docId, rewrites] of byHolder) {
+			const entry = registry.get(docId);
+			if (!entry) continue;
+			writeAliases(docId, entry, aliasesAfterRename(entry.aliases ?? [], rewrites, options.strategy));
+			holders.push(conceptOf(entry));
+		}
+		return holders;
+	}
 	/**
 	* The writes of a rename, over documents `renamePage` has already brought current and
-	* holds live: the registry steps, then the body pass over `readable` (ADR 0038).
+	* holds live: the registry steps, the scoped aliases, then the body pass over `readable`
+	* (ADR 0038).
 	*/
 	function applyRename(plan, options, readable) {
 		for (const step of renameSteps(plan)) {
+			if (!step.hasDocument) continue;
 			const docId = docIdFor(step.from);
 			if (!docId) continue;
 			const entry = registry.get(docId);
@@ -13233,6 +13849,7 @@ function createServerDocumentStore(graph, options) {
 			registry.set(docId, next);
 			writeBackIdentity(docId);
 		}
+		const aliasesRewritten = rewriteScopedAliases(plan, options);
 		let rewritten = 0;
 		const rewrittenDocuments = [];
 		if (options.strategy === "rewrite") {
@@ -13267,10 +13884,12 @@ function createServerDocumentStore(graph, options) {
 		}
 		return {
 			concept: plan.direct.into,
+			aliasOf: plan.aliasOf === null ? null : landedName(plan, plan.aliasOf),
 			rewritten,
 			rewrittenDocuments,
 			cascaded: plan.cascade.length,
-			merged: mergeCount(plan)
+			merged: mergeCount(plan),
+			aliasesRewritten
 		};
 	}
 }
@@ -13726,6 +14345,12 @@ var INDEX_FOLLOW_MS = 5e3;
 * stays for an index without `settled`.
 */
 function followIndex(index, source, followMs = INDEX_FOLLOW_MS) {
+	if (index.settled) return {
+		async settled() {
+			await reachedWithin(index.settled(), followMs);
+		},
+		dispose() {}
+	};
 	let pending = false;
 	let waiters = [];
 	const stopSource = source.onChange(() => {
@@ -13742,13 +14367,7 @@ function followIndex(index, source, followMs = INDEX_FOLLOW_MS) {
 			if (!pending) return Promise.resolve();
 			return new Promise((resolve) => {
 				waiters.push(resolve);
-				const timer = setTimeout(resolve, followMs);
-				timer.unref?.();
-				if (index.settled) index.settled().then(() => {
-					pending = false;
-					clearTimeout(timer);
-					resolve();
-				});
+				setTimeout(resolve, followMs).unref?.();
 			});
 		},
 		dispose() {
@@ -14153,7 +14772,11 @@ async function openHeadlessFolder(deps) {
 				planRename: (from, to, referencingDocuments) => store.planRename(from, to, referencingDocuments),
 				async renamePage(from, to, options) {
 					const result = await store.renamePage(from, to, options);
-					for (const concept of [result.concept, ...result.rewrittenDocuments]) await store.flushDocument(concept);
+					for (const concept of [
+						result.concept,
+						...result.rewrittenDocuments,
+						...result.aliasesRewritten
+					]) await store.flushDocument(concept);
 					return result;
 				},
 				async readBodies() {
@@ -15751,8 +16374,8 @@ function createDocumentRenderer(options) {
 *
 * Ten places used to spell this out, and each spelled the destination `[^)\s]+`, which stops at
 * the FIRST closing parenthesis. That is wrong the moment a file name contains one, and imported
-* attachments contain them all the time - `Estimate_320_from_B_Sprake_ltd_(1)_1706517395516_0.pdf`
-* is a real example. Every reader then saw the same truncated target, so the link styling and the
+* attachments contain them all the time - `Quote_320_from_Garden_Fencing_ltd_(1)_1700000000000_0.pdf`
+* has the shape they take. Every reader then saw the same truncated target, so the link styling and the
 * download and delete controls landed in the middle of the text, and the [[Local Mirror]] reported
 * the stub as a document link to an attachment the graph plainly had (2026-09-10).
 *
@@ -18580,9 +19203,13 @@ function conceptExists(graph, concept) {
 	if (resolveIdentity(graph, concept)) return true;
 	return graph.index.candidate(concept) !== void 0;
 }
-/** The documents whose BODIES link to the concept, by name - what a rewrite has to read (ADR 0083: a title reference is the cascade's). */
+/**
+* The documents whose BODIES link to the concept by that very name - what a rewrite has to read
+* (ADR 0083: a title reference is the cascade's). The page's other names share its backlinks, and
+* the rewrite leaves links that say them alone.
+*/
 async function referencingDocuments(graph, concept) {
-	return (await graph.index.backlinks(concept)).filter(referencedInBody).map((group) => group.sourceConcept);
+	return (await graph.index.backlinks(concept)).filter((group) => referencedInBody(group, concept)).map((group) => group.sourceConcept);
 }
 /** Protected documents in the graph: their references can be neither seen nor rewritten. */
 function protectedDocumentCount(graph) {
@@ -18611,11 +19238,12 @@ async function planRename(graph, args) {
 	if (!conceptExists(graph, from)) throw new ToolError("not_found", `Nothing in the graph is named "${from}".`);
 	const identity = resolveIdentity(graph, from);
 	if (identity) refuseIfProtected(identity.concept, await liveText(graph, identity));
-	const referencing = await referencingDocuments(graph, from);
-	const plan = await graph.store.planRename(identity?.concept ?? from, to, referencing.length);
+	const subject = identity?.concept ?? from;
+	const referencing = await referencingDocuments(graph, subject);
+	const plan = await graph.store.planRename(subject, to, referencing.length);
 	const steps = renameSteps(plan);
 	return {
-		from: identity?.concept ?? from,
+		from: subject,
 		to,
 		refusal: plan.refusal,
 		direct: renameStepView(plan.direct),
@@ -18625,6 +19253,11 @@ async function planRename(graph, args) {
 			from: step.from,
 			into: step.into
 		})),
+		aliases: plan.aliases.map((alias) => ({
+			document: alias.holder,
+			from: alias.from,
+			to: alias.to
+		})),
 		protectedDocuments: protectedDocumentCount(graph)
 	};
 }
@@ -18670,7 +19303,8 @@ async function rename$1(graph, args) {
 			from: step.from,
 			to: step.into
 		})),
-		merged: result.merged
+		merged: result.merged,
+		aliasesRewritten: result.aliasesRewritten
 	};
 }
 /**
@@ -18691,7 +19325,12 @@ async function setAliases(graph, args) {
 		if (holder && holder.key !== identity.key) throw new ToolError("name_taken", `"${alias}" is already a name of "${holder.concept}", so it cannot be an alias of "${identity.concept}".`);
 		aliases.push(alias);
 	}
-	await graph.store.setAliases(identity.concept, aliases);
+	try {
+		await graph.store.setAliases(identity.concept, aliases);
+	} catch (error) {
+		if (error instanceof DocumentUnconfirmedError) throw new ToolError("unconfirmed_documents", error.message);
+		throw error;
+	}
 	await settle$2(graph);
 	await graph.store.refresh();
 	return {
@@ -20206,7 +20845,7 @@ function createMcpServer(graph, info) {
 	}, async (args) => run(() => createPage(graph, args)));
 	server.registerTool("plan_rename", {
 		title: "Plan a rename",
-		description: "What renaming a page or concept would do, before anything changes: the scoped concepts carried along (cascade), the documents whose links would be rewritten (referencingDocuments, by name - read or backlinks any of them), any merge (the new name is already a document's name or alias, so the two would be joined), a refusal if the rename is not allowed, and how many protected documents exist whose references cannot be seen. Journal entries cannot be renamed.",
+		description: "What renaming a page or concept would do, before anything changes: the scoped concepts carried along (cascade), the documents whose links would be rewritten (referencingDocuments, by name - read or backlinks any of them), any merge (the new name is already a document's name or alias, so the two would be joined), the aliases that name it as a scope and would be rewritten with it (aliases: the document, the alias and its new form), a refusal if the rename is not allowed, and how many protected documents exist whose references cannot be seen. Journal entries cannot be renamed.",
 		inputSchema: {
 			from: z.string().min(1).describe("The current name: a page title or a concept that only links name."),
 			to: z.string().min(1).describe("The new name.")
@@ -20214,7 +20853,7 @@ function createMcpServer(graph, info) {
 	}, async (args) => run(() => planRename(graph, args)));
 	server.registerTool("rename", {
 		title: "Rename",
-		description: "Rename a page or concept. Its page (if any) and every scoped concept beneath it (\"[[Old]] Notes\" becomes \"[[New]] Notes\") move with it. strategy \"rewrite\" (default) rewrites every [[Old]] link in the graph to the new name. \"alias\" keeps the old name as an alias so existing links keep resolving. If the new name is already taken the two documents would merge, which is irreversible: refused with error \"merge_requires_confirmation\" unless confirm_merge is true. Refused with \"unconfirmed_documents\" if a document it must read has not finished syncing to this device (nothing changes - try again). Call plan_rename first to see what will happen.",
+		description: "Rename a page or concept. Its page (if any) and every scoped concept beneath it (\"[[Old]] Notes\" becomes \"[[New]] Notes\") move with it, and so does any alias that names it as a scope (\"[[Old]] lab\" on another page becomes \"[[New]] lab\"; with strategy \"alias\" the old alias is kept and the new form added). Refused if such an alias would become a name another document already has. strategy \"rewrite\" (default) rewrites every [[Old]] link in the graph to the new name. \"alias\" keeps the old name as an alias so existing links keep resolving. If the new name is already taken the two documents would merge, which is irreversible: refused with error \"merge_requires_confirmation\" unless confirm_merge is true. Refused with \"unconfirmed_documents\" if a document it must read has not finished syncing to this device (nothing changes - try again). Call plan_rename first to see what will happen.",
 		inputSchema: {
 			from: z.string().min(1),
 			to: z.string().min(1),
@@ -20224,7 +20863,7 @@ function createMcpServer(graph, info) {
 	}, async (args) => run(() => rename$1(graph, args)));
 	server.registerTool("set_aliases", {
 		title: "Set aliases",
-		description: "Replace a document's aliases: other names it answers to in [[wikilinks]], Quick Find and on a published site. The list you pass is the complete list. A name that is already another document's title or alias is refused with error \"name_taken\".",
+		description: "Replace a document's aliases: other names it answers to in [[wikilinks]], Quick Find and on a published site. The list you pass is the complete list, and it is shown in the document's frontmatter, in a block added if there is none. A name that is already another document's title or alias is refused with error \"name_taken\".",
 		inputSchema: {
 			concept,
 			aliases: z.array(z.string()).describe("Every alias the document should have - an empty list removes them all.")