@appsoftwareltd/etherpk-mcp 0.8.4 → 0.8.5

package/dist/main.js

@@ -34,7 +34,7 @@ import { request } from "node:https";
 import { BlockList, isIP } from "node:net";
 var package_default = {
 	name: "@appsoftwareltd/etherpk-mcp",
-	version: "0.8.4",
+	version: "0.8.5",
 	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",
@@ -2149,19 +2149,31 @@ function flatten(roots) {
 	roots.forEach((root, i) => walk(root, null, i));
 	return rows;
 }
-/** Derive the index rows for a single document's text. Pure. */
-function deriveDoc(text) {
+/**
+* A document's blocks and links, each link tagged with the block holding it, and which block
+* each source line belongs to (the deepest whose own range covers it). The one reading of a
+* document's outline that the index rows and {@link blockConceptChain} share.
+*/
+function blocksAndLinks(text) {
 	const blocks = flatten(parseBlocks(text));
 	const lineToBlock = /* @__PURE__ */ new Map();
 	for (const b of blocks) for (let line = b.startLine; line <= b.endLine; line++) lineToBlock.set(line, b.localId);
-	const links = wikilinkOccurrencesInSource(text).map((occ) => ({
-		concept: occ.concept,
-		line: occ.line,
-		lineText: occ.lineText,
-		matchStart: occ.matchStart,
-		matchEnd: occ.matchEnd,
-		blockLocalId: lineToBlock.get(occ.line) ?? null
-	}));
+	return {
+		blocks,
+		links: wikilinkOccurrencesInSource(text).map((occ) => ({
+			concept: occ.concept,
+			line: occ.line,
+			lineText: occ.lineText,
+			matchStart: occ.matchStart,
+			matchEnd: occ.matchEnd,
+			blockLocalId: lineToBlock.get(occ.line) ?? null
+		})),
+		lineToBlock
+	};
+}
+/** Derive the index rows for a single document's text. Pure. */
+function deriveDoc(text) {
+	const { blocks, links } = blocksAndLinks(text);
 	const candidateTasks = blocks.filter((b) => b.kind === "task");
 	const fenced = candidateTasks.length === 0 ? () => false : fencedLines(text);
 	const taskBlocks = candidateTasks.filter((b) => !fenced(b.startLine));
@@ -2198,6 +2210,17 @@ function deriveDoc(text) {
 */
 function deriveTaskConcepts(blocks, links, taskBlocks) {
 	if (taskBlocks.length === 0) return [];
+	const byBlock = linksByBlock(links);
+	if (byBlock.size === 0) return [];
+	const rows = [];
+	for (const task of taskBlocks) for (const { concept } of conceptChain(blocks, byBlock, task.localId)) rows.push({
+		blockLocalId: task.localId,
+		concept
+	});
+	return rows;
+}
+/** The concepts linked on each block, in the order they are written, by block. */
+function linksByBlock(links) {
 	const byBlock = /* @__PURE__ */ new Map();
 	for (const link of links) {
 		if (link.blockLocalId === null) continue;
@@ -2205,21 +2228,26 @@ function deriveTaskConcepts(blocks, links, taskBlocks) {
 		if (existing) existing.push(link.concept);
 		else byBlock.set(link.blockLocalId, [link.concept]);
 	}
-	if (byBlock.size === 0) return [];
-	const rows = [];
-	for (const task of taskBlocks) {
-		const seen = /* @__PURE__ */ new Set();
-		for (let id = task.localId; id !== null; id = blocks[id]?.parentId ?? null) for (const concept of byBlock.get(id) ?? []) {
-			const key = conceptKey$1(concept);
-			if (seen.has(key)) continue;
-			seen.add(key);
-			rows.push({
-				blockLocalId: task.localId,
-				concept
-			});
-		}
+	return byBlock;
+}
+/**
+* The walk under a [[Task Concept]] (ADR 0051): the concepts linked on block `from`, then on each
+* ancestor up to the root, each named once where it is nearest, whatever its case.
+*/
+function conceptChain(blocks, byBlock, from) {
+	const out = [];
+	const seen = /* @__PURE__ */ new Set();
+	let depth = 0;
+	for (let id = from; id !== null; id = blocks[id]?.parentId ?? null, depth++) for (const concept of byBlock.get(id) ?? []) {
+		const key = conceptKey$1(concept);
+		if (seen.has(key)) continue;
+		seen.add(key);
+		out.push({
+			concept,
+			depth
+		});
 	}
-	return rows;
+	return out;
 }
 /**
 * The references a document makes BY ITS NAME: every wikilink nested in the concept string, at
@@ -2244,6 +2272,14 @@ function deriveTitleLinks(concept) {
 		matchEnd: occ.matchEnd
 	}));
 }
+/**
+* The [[Task Concept]]s every task in a document has, whatever its outline (ADR 0051): the
+* document's own concept, then the [[Scope]]s in its name, outermost first. The index writes these
+* for every task, and `/kanban` offers them after the block's own (ADR 0113).
+*/
+function documentTaskConcepts(concept) {
+	return [concept, ...deriveTitleLinks(concept).map((link) => link.concept)];
+}
 /** The ancestor labels of a block, root-first (the outline-chain breadcrumb). */
 function ancestorChain(blocks, localId) {
 	const chain = [];
@@ -2743,7 +2779,7 @@ function createSchema(db) {
 	db.exec(SCHEMA$1);
 	db.run("INSERT OR IGNORE INTO index_metadata (key, value) VALUES ('active_generation', 1)");
 	db.run("INSERT OR IGNORE INTO index_metadata (key, value) VALUES ('revision', 0)");
-	db.exec(`PRAGMA user_version = 14`);
+	db.exec(`PRAGMA user_version = 15`);
 }
 function activeIndexGeneration(db) {
 	return db.all("SELECT value FROM index_metadata WHERE key = 'active_generation'")[0]?.value ?? 1;
@@ -2764,7 +2800,7 @@ function advanceIndexRevision(db) {
 */
 function isUsableIndex(db) {
 	try {
-		return db.all("PRAGMA user_version")[0]?.user_version === 14;
+		return db.all("PRAGMA user_version")[0]?.user_version === 15;
 	} catch {
 		return false;
 	}
@@ -2941,13 +2977,17 @@ function insertProperties(db, pageId, doc) {
 * the document's identity. Without that row, filtering to a project page returns nothing for
 * the tasks written directly on it — the case the "Filter to <active tab>" shortcut exists for.
 *
-* Only the document's own concept goes in, never its aliases: the query resolves a filtered
-* name to its page and matches on every name that page answers to, so an alias row here would
-* be redundant now and stale after a rename.
+* The [[Scope]]s in the document's name sit on that root too (ADR 0051, amended 2026-09-29), so
+* the tasks on `[[Acme]] Website` answer to Acme. They come from the same scan that makes such a
+* page a Backlink of its scope (ADR 0083), so a page gives its tasks to exactly the concepts it
+* is a title reference of.
+*
+* Only the names the document is written with go in, never an alias of them: the query resolves
+* a filtered name to its page and matches on every name that page answers to, so an alias row
+* here would be redundant now and stale after a rename.
 */
 function insertTaskConcepts(db, pageId, doc, tasks, taskConcepts) {
 	if (tasks.length === 0) return;
-	const ownKey = conceptKey$1(doc.concept);
 	const written = /* @__PURE__ */ new Set();
 	const write = (blockLocalId, key) => {
 		const seen = `${blockLocalId} ${key}`;
@@ -2959,7 +2999,8 @@ function insertTaskConcepts(db, pageId, doc, tasks, taskConcepts) {
 			key
 		]);
 	};
-	for (const t of tasks) write(t.blockLocalId, ownKey);
+	const rootKeys = documentTaskConcepts(doc.concept).map(conceptKey$1);
+	for (const t of tasks) for (const key of rootKeys) write(t.blockLocalId, key);
 	for (const tc of taskConcepts) write(tc.blockLocalId, conceptKey$1(tc.concept));
 }
 /**
@@ -3844,6 +3885,15 @@ var ORDER_SQL = {
 	due: `(t.due IS NULL), t.due ASC, (t.priority IS NULL), t.priority ASC`
 };
 /**
+* What decides a tie the grouping leaves: the document's name, then the task's line, which a
+* person can see and which survive a rebuild. A folder graph re-derives the whole graph with
+* fresh page ids on any file change, so ordering by page id let equal tasks swap places in the
+* [[Tasks View]] and on a [[Kanban Board]] (ADR 0113) between one refresh and the next.
+* `page_id, block_local_id` come last only to keep the order total, so paging cannot repeat or
+* skip.
+*/
+var TIE_BREAK_SQL = "p.concept_key ASC, t.line ASC, t.page_id ASC, t.block_local_id ASC";
+/**
 * The WHERE clause and parameters shared by {@link tasksMatching} and its count, so the two
 * can never drift into answering different questions about the same filter.
 *
@@ -3912,7 +3962,7 @@ function tasksMatching(db, query, offset, limit) {
                 t.priority, t.waiting, t.doing, t.cancelled, t.due, t.completion, t.scheduled
          FROM tasks t JOIN pages p ON p.id = t.page_id
          WHERE ${predicate.where}
-         ORDER BY ${ORDER_SQL[query.groupBy]}, t.page_id ASC, t.block_local_id ASC
+         ORDER BY ${ORDER_SQL[query.groupBy]}, ${TIE_BREAK_SQL}
          LIMIT ? OFFSET ?`, [
 		...predicate.params,
 		limit + 1,
@@ -3924,30 +3974,35 @@ function tasksMatching(db, query, offset, limit) {
 		hits: [],
 		hasMore: false
 	};
-	const breadcrumbs = breadcrumbsFor(db, page);
+	const ancestry = ancestryFor(db, page);
 	return {
-		hits: page.map((row) => ({
-			...toHit(row),
-			breadcrumb: breadcrumbs.get(row.page_id)?.get(row.block_local_id) ?? []
-		})),
+		hits: page.map((row) => {
+			const found = ancestry.get(row.page_id)?.get(row.block_local_id);
+			return {
+				...toHit(row),
+				breadcrumb: found?.breadcrumb ?? [],
+				parentTask: found?.parentTask ?? null
+			};
+		}),
 		hasMore
 	};
 }
 /**
-* Ancestor labels for a whole page of tasks: one read for every document involved, then the
-* chains walked in JS. The same shape searchText uses, and for the same reason - a recursive
-* SQL walk per row would be one query per task.
+* Ancestor labels for a whole page of tasks, and each task's nearest task ancestor: one read for
+* every document involved, then the chains walked in JS. The same shape searchText uses, and for
+* the same reason - a recursive SQL walk per row would be one query per task.
 */
-function breadcrumbsFor(db, rows) {
+function ancestryFor(db, rows) {
 	const ids = [...new Set(rows.map((row) => row.page_id))];
 	const placeholders = ids.map(() => "?").join(",");
-	const blocks = db.all(`SELECT page_id, local_id, parent_local_id, label FROM blocks WHERE page_id IN (${placeholders})`, ids);
+	const blocks = db.all(`SELECT page_id, local_id, parent_local_id, kind, label FROM blocks WHERE page_id IN (${placeholders})`, ids);
 	const byPage = /* @__PURE__ */ new Map();
 	for (const block of blocks) {
 		let page = byPage.get(block.page_id);
 		if (!page) byPage.set(block.page_id, page = /* @__PURE__ */ new Map());
 		page.set(block.local_id, {
 			parent_local_id: block.parent_local_id,
+			kind: block.kind,
 			label: block.label
 		});
 	}
@@ -3957,10 +4012,24 @@ function breadcrumbsFor(db, rows) {
 		if (!page) continue;
 		let chains = out.get(row.page_id);
 		if (!chains) out.set(row.page_id, chains = /* @__PURE__ */ new Map());
-		chains.set(row.block_local_id, searchBreadcrumb(page, row.block_local_id));
+		chains.set(row.block_local_id, {
+			breadcrumb: searchBreadcrumb(page, row.block_local_id),
+			parentTask: nearestTask(page, row.block_local_id)
+		});
 	}
 	return out;
 }
+/** The label of the nearest ancestor of `localId` that is a task, or null. */
+function nearestTask(blocks, localId) {
+	let parent = blocks.get(localId)?.parent_local_id ?? null;
+	for (let guard = 0; parent !== null && guard <= blocks.size; guard++) {
+		const block = blocks.get(parent);
+		if (!block) break;
+		if (block.kind === "task") return block.label;
+		parent = block.parent_local_id;
+	}
+	return null;
+}
 /** How many tasks match. Uncapped: this counts an indexed join, not a text index. */
 function tasksMatchingCount(db, query) {
 	const predicate = taskPredicate(db, query);
@@ -4271,7 +4340,7 @@ function cacheRoot(env) {
 * recovered from a joined path (see there).
 */
 var CACHE_FILE_NAME = `local-cache.v${CACHE_DB_VERSION}.bin`;
-var INDEX_FILE_NAME = `index.v14.sqlite`;
+var INDEX_FILE_NAME = `index.v15.sqlite`;
 var VECTORS_FILE_NAME = `vectors.v1.sqlite`;
 function cacheFile(dir) {
 	return join(dir, CACHE_FILE_NAME);
@@ -10779,6 +10848,27 @@ function dayIsNotAPageName(day) {
 	return `“${day.trim()}” is a date, and a date is the name of that day's journal entry, so a page cannot be called that. Choose a different name.`;
 }
 //#endregion
+//#region ../client/src/lib/document/line-endings.ts
+/** `text` with every `\r\n` and every lone `\r` written as `\n`; `text` itself when it holds no `\r`. */
+function lineFeedsOnly(text) {
+	return text.includes("\r") ? text.replace(/\r\n?/g, "\n") : text;
+}
+/**
+* The changes that turn `text` into {@link lineFeedsOnly}`(text)`, in document order and each
+* against `text` as it is: one per `\r`, deleting it before a `\n` and replacing it with `\n`
+* anywhere else. For a writer that must change a shared text in place rather than replace it,
+* applying them from the last to the first.
+*/
+function lineFeedChanges(text) {
+	const changes = [];
+	for (let at = text.indexOf("\r"); at !== -1; at = text.indexOf("\r", at + 1)) changes.push({
+		from: at,
+		to: at + 1,
+		insert: text[at + 1] === "\n" ? "" : "\n"
+	});
+	return changes;
+}
+//#endregion
 //#region ../client/src/lib/document/wikilink/rename.ts
 /**
 * Rewriting [[Wikilink]] targets across a document's source, for the rewrite arm of a page
@@ -11421,8 +11511,9 @@ function createFilesystemDocumentStore(adapter, options = {}) {
 		}
 		return entries;
 	}
-	function notify(doc, text) {
-		for (const listener of doc.listeners) listener(text);
+	/** Tell an open document's subscribers its text, all but `except` (the editor that made the edit). */
+	function notify(doc, text, except) {
+		for (const listener of doc.listeners) if (listener !== except) listener(text);
 	}
 	/** The frontmatter block of `text`, given its parsed body (`''` when there is none). */
 	function headOf(text, body) {
@@ -11660,7 +11751,7 @@ function createFilesystemDocumentStore(adapter, options = {}) {
 				return doc.target;
 			},
 			getText: () => doc.buffer,
-			applyChange(change, origin = "editor") {
+			applyChange(change, origin = "editor", editor) {
 				doc.buffer = applyTextChange(doc.buffer, change);
 				doc.dirty = true;
 				if (doc.removed) {
@@ -11669,6 +11760,7 @@ function createFilesystemDocumentStore(adapter, options = {}) {
 				}
 				doc.save.call();
 				if (origin === "external") notify(doc, doc.buffer);
+				else if (editor) notify(doc, doc.buffer, editor);
 			},
 			subscribe(listener) {
 				doc.listeners.add(listener);
@@ -11676,12 +11768,12 @@ function createFilesystemDocumentStore(adapter, options = {}) {
 			}
 		};
 		doc.ready = adapter.read(doc.subdir, doc.fileName).then((content) => {
-			doc.buffer = content.text;
+			doc.buffer = lineFeedsOnly(content.text);
 			doc.baseText = content.text;
 			doc.lastModified = content.lastModified;
 			doc.size = content.size;
 			doc.loaded = true;
-			notify(doc, content.text);
+			notify(doc, doc.buffer);
 		}).catch(async (error) => {
 			if (await adapter.exists(doc.subdir, doc.fileName).catch(() => true)) doc.loadError = error;
 			else doc.loaded = true;
@@ -11699,7 +11791,14 @@ function createFilesystemDocumentStore(adapter, options = {}) {
 			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);
+		followDisk(doc, await adapter.read(doc.subdir, doc.fileName));
+	}
+	/**
+	* Bring an open document in line with its file as just read (`reconcileDecision`): nothing
+	* but the stamps when the file is what the buffer last synced with, a reload of a clean buffer,
+	* a conflict over a dirty one.
+	*/
+	function followDisk(doc, { text: diskText, lastModified, size }) {
 		const decision = reconcileDecision({
 			dirty: doc.dirty,
 			baseText: doc.baseText,
@@ -11713,14 +11812,14 @@ function createFilesystemDocumentStore(adapter, options = {}) {
 			return;
 		}
 		if (decision === "reload") {
-			doc.buffer = diskText;
+			doc.buffer = lineFeedsOnly(diskText);
 			doc.baseText = diskText;
 			doc.lastModified = lastModified;
 			doc.size = size;
 			doc.loaded = true;
 			doc.loadError = null;
 			doc.dirty = false;
-			notify(doc, diskText);
+			notify(doc, doc.buffer);
 			emitChange({ concept: conceptOf(doc) });
 			return;
 		}
@@ -11732,6 +11831,53 @@ function createFilesystemDocumentStore(adapter, options = {}) {
 		doc.save.cancel();
 		onConflict?.(doc.conflict);
 	}
+	/** A file's content, or null when it does not exist; any other failure rejects. */
+	async function readIfPresent(subdir, fileName) {
+		try {
+			return await adapter.read(subdir, fileName);
+		} catch (error) {
+			if (await adapter.exists(subdir, fileName).catch(() => true)) throw error;
+			return null;
+		}
+	}
+	/**
+	* A Formatting Scan's fix to an open document (ADR 0109): through the buffer, so the editor
+	* showing it is told, then saved now. The file is read first: an edit made outside the app
+	* since the buffer last synced is followed, a reload or a conflict over unsaved typing, and
+	* the fix is refused rather than saved over it.
+	*/
+	async function spliceOpenDocument(doc, expected, splices) {
+		await doc.ready;
+		await settled(doc);
+		if (doc.removed) return "gone";
+		if (doc.conflict) return "changed";
+		const disk = await readIfPresent(doc.subdir, doc.fileName);
+		if (disk === null || doc.removed) return "gone";
+		if (doc.saving || doc.conflict) return "changed";
+		followDisk(doc, disk);
+		if (doc.conflict || !doc.loaded) return "changed";
+		if (containsCipherFence(doc.buffer)) return "protected";
+		if (doc.buffer !== expected) return "changed";
+		for (let i = splices.length - 1; i >= 0; i--) doc.handle.applyChange(splices[i], "external");
+		await saveNow(doc);
+		return "written";
+	}
+	/** A Formatting Scan's fix to a document nobody has open: read, compare, write (ADR 0109). */
+	async function spliceClosedDocument(entry, expected, splices) {
+		const read = await readIfPresent(entry.subdir, entry.fileName);
+		if (read === null) return "gone";
+		const opened = open.get(entry.key);
+		if (opened) return spliceOpenDocument(opened, expected, splices);
+		if (containsCipherFence(read.text)) return "protected";
+		if (read.text !== expected) return "changed";
+		let text = read.text;
+		for (let i = splices.length - 1; i >= 0; i--) text = applyTextChange(text, splices[i]);
+		const written = await adapter.write(entry.subdir, entry.fileName, text);
+		entry.lastModified = written.lastModified;
+		entry.size = written.size;
+		emitChange({ concept: entry.concept });
+		return "written";
+	}
 	return {
 		open(target) {
 			return openDocNamed(target).handle;
@@ -11786,6 +11932,22 @@ function createFilesystemDocumentStore(adapter, options = {}) {
 				emitRegistryOnly();
 			}
 		},
+		async documentText(target) {
+			const entry = registry.get(conceptKey(target));
+			if (!entry) return null;
+			const doc = open.get(entry.key);
+			if (doc) {
+				await doc.ready;
+				if (doc.loaded) return doc.buffer;
+			}
+			return (await readIfPresent(entry.subdir, entry.fileName))?.text ?? null;
+		},
+		async spliceIfUnchanged(target, expected, splices) {
+			const entry = registry.get(conceptKey(target));
+			if (!entry) return "gone";
+			const doc = open.get(entry.key);
+			return doc ? spliceOpenDocument(doc, expected, splices) : spliceClosedDocument(entry, expected, splices);
+		},
 		onChange(listener) {
 			changed.add(listener);
 			return () => changed.delete(listener);
@@ -11841,13 +12003,13 @@ function createFilesystemDocumentStore(adapter, options = {}) {
 			doc.loadError = null;
 			if (choice === "take-disk") {
 				const { text, lastModified, size } = await adapter.read(doc.subdir, doc.fileName);
-				doc.buffer = text;
+				doc.buffer = lineFeedsOnly(text);
 				doc.baseText = text;
 				doc.lastModified = lastModified;
 				doc.size = size;
 				doc.dirty = false;
 				doc.conflict = null;
-				notify(doc, text);
+				notify(doc, doc.buffer);
 			} else {
 				const res = await adapter.write(doc.subdir, doc.fileName, doc.buffer);
 				doc.baseText = doc.buffer;
@@ -12479,7 +12641,17 @@ function createServerDocumentStore(graph, options) {
 		},
 		getYText(target) {
 			const docId = docIdFor(target);
-			return docId ? graph.docSync(docId).doc.getText("content") : void 0;
+			if (!docId) return void 0;
+			const ytext = graph.docSync(docId).doc.getText("content");
+			const changes = lineFeedChanges(ytext.toString());
+			if (changes.length > 0) ytext.doc.transact(() => {
+				for (let i = changes.length - 1; i >= 0; i--) {
+					const change = changes[i];
+					ytext.delete(change.from, change.to - change.from);
+					if (change.insert) ytext.insert(change.from, change.insert);
+				}
+			}, STORE);
+			return ytext;
 		},
 		async whenReady(target) {
 			const docId = docIdFor(target);
@@ -12781,6 +12953,28 @@ function createServerDocumentStore(graph, options) {
 			registry.set(docId, updated);
 			writeBackIdentity(docId);
 		},
+		async spliceIfUnchanged(docId, expected, splices, spliceOptions) {
+			if (!registry.has(docId)) return "gone";
+			const materialised = await materialise([docId], spliceOptions?.timeoutMs ?? COLD_CONTENT_TIMEOUT_MS);
+			try {
+				if (!registry.has(docId)) return "gone";
+				if (materialised.unconfirmed.length > 0) return "unconfirmed";
+				const ytext = graph.docSync(docId).doc.getText("content");
+				const text = ytext.toString();
+				if (containsCipherFence(text)) return "protected";
+				if (text !== expected) return "changed";
+				ytext.doc.transact(() => {
+					for (let i = splices.length - 1; i >= 0; i--) {
+						const splice = splices[i];
+						if (splice.to > splice.from) ytext.delete(splice.from, splice.to - splice.from);
+						if (splice.insert) ytext.insert(splice.from, splice.insert);
+					}
+				}, STORE);
+				return "written";
+			} finally {
+				materialised.release();
+			}
+		},
 		async reconcile() {},
 		async resolveConflict() {},
 		async createJournal(date, body = "") {
@@ -13507,6 +13701,7 @@ function assembleHeadlessGraph(parts) {
 	};
 	return {
 		graphId: parts.graphId,
+		clientUrl: parts.clientUrl ?? null,
 		name: parts.name,
 		store: parts.store,
 		index,
@@ -13634,6 +13829,7 @@ async function openHeadlessGraph(deps) {
 		}
 		return assembleHeadlessGraph({
 			graphId: deps.graphId,
+			clientUrl: deps.clientUrl ?? null,
 			name: sync.getMeta().name ?? deps.graphId,
 			accessLoss: () => sync.accessLoss(),
 			store: documents,
@@ -17167,6 +17363,243 @@ async function writeDownload(directory, name, bytes) {
 	}
 	throw new Error(`${directory} already holds a thousand files named like ${safe}.`);
 }
+//#endregion
+//#region ../client/src/lib/navigation/document-url.ts
+/** Encode a concept for the `[...concept]` rest param: per-segment, `/` kept. */
+function encodeConceptPath(concept) {
+	return concept.split("/").map(encodeURIComponent).join("/");
+}
+/** The Document URL for a concept within a graph. */
+function documentUrl(graphId, concept) {
+	return `${graphUrl(graphId)}/d/${encodeConceptPath(concept)}`;
+}
+/** The bare workspace URL for a graph. */
+function graphUrl(graphId) {
+	return `/g/${encodeURIComponent(graphId)}`;
+}
+/**
+* The words that identify a task while its tags change: the text after the checkbox and the tag
+* run, whitespace collapsed and Unicode NFC applied. A task written as tags alone is its tags.
+*/
+function taskWords(label) {
+	return (parseTaskTags(label).text || label).normalize("NFC").replace(/\s+/g, " ").trim();
+}
+/** The fingerprint of a task's words, from its label (tag run included or not). */
+async function taskFingerprint(label) {
+	const digest = await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(taskWords(label)));
+	return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("").slice(0, 12);
+}
+/** The reference's address: the Document URL with the task in its fragment, which a browser never sends. */
+function taskReferenceUrl(reference, origin = "") {
+	return `${origin}${documentUrl(reference.graphId, reference.document)}#task=${reference.line}-${reference.fingerprint}`;
+}
+var REFERENCE = /\/g\/([^/?#\s]+)\/d\/([^?#\s]+?)(?:\?[^#\s]*)?#task=(\d+)-([0-9a-f]{12})(?![0-9a-f])/;
+/**
+* The reference in `input`: the two lines as copied, the address alone, with any origin or none,
+* or null when `input` holds none.
+*/
+function parseTaskReference(input) {
+	const match = REFERENCE.exec(input);
+	if (!match) return null;
+	const [, graph, path, line, fingerprint] = match;
+	try {
+		return {
+			graphId: decodeURIComponent(graph),
+			document: path.split("/").map(decodeURIComponent).join("/"),
+			line: Number(line),
+			fingerprint
+		};
+	} catch {
+		return null;
+	}
+}
+/**
+* Find the task a reference names. First the named document's line, when the words there match;
+* then the one task in that document with those words; then the one task in the graph. None is
+* `task_not_found`, more than one `task_ambiguous`, since acting on a guess could change the
+* wrong task. A document that no longer answers to its name goes straight to the graph.
+*/
+async function resolveTaskReference(reference, sources) {
+	if (sources.graphId !== null && sources.graphId !== reference.graphId) return {
+		ok: false,
+		code: "other_graph",
+		servedGraphId: sources.graphId
+	};
+	const named = sources.resolveDocument(reference.document);
+	if (named !== null) {
+		const body = await sources.readBody(named);
+		if (body !== null) {
+			const matches = await taskLinesWith(body.split("\n"), reference.fingerprint);
+			if (matches.includes(reference.line)) return {
+				ok: true,
+				document: named,
+				line: reference.line,
+				body,
+				foundBy: "at_line"
+			};
+			if (matches.length === 1) return {
+				ok: true,
+				document: named,
+				line: matches[0],
+				body,
+				foundBy: "moved"
+			};
+			if (matches.length > 1) return {
+				ok: false,
+				code: "task_ambiguous",
+				candidates: matches.map((line) => ({
+					document: named,
+					line
+				}))
+			};
+		}
+	}
+	const found = [];
+	const looked = new Set(named === null ? [] : [named.toLowerCase()]);
+	for (const task of await sources.allTasks()) {
+		if (looked.has(task.document.toLowerCase())) continue;
+		if (await taskFingerprint(task.label) !== reference.fingerprint) continue;
+		looked.add(task.document.toLowerCase());
+		const body = await sources.readBody(task.document);
+		if (body === null) continue;
+		for (const line of await taskLinesWith(body.split("\n"), reference.fingerprint)) found.push({
+			document: task.document,
+			line,
+			body
+		});
+	}
+	if (found.length === 1) return {
+		ok: true,
+		...found[0],
+		foundBy: "other_document"
+	};
+	if (found.length > 1) return {
+		ok: false,
+		code: "task_ambiguous",
+		candidates: found.map(({ document, line }) => ({
+			document,
+			line
+		}))
+	};
+	return {
+		ok: false,
+		code: "task_not_found"
+	};
+}
+/** How many tasks `everyIndexedTask` asks the index for at a time. */
+var INDEX_PAGE = 500;
+/** Every task the index knows, in pages, as {@link TaskReferenceSources.allTasks} wants them. */
+async function everyIndexedTask(index, today) {
+	const query = {
+		concept: null,
+		statuses: TASK_STATUSES,
+		priorities: TASK_PRIORITY_FILTERS,
+		due: "any",
+		groupBy: "document",
+		today
+	};
+	const out = [];
+	for (let offset = 0;; offset += INDEX_PAGE) {
+		const page = await index.tasks(query, offset, INDEX_PAGE);
+		for (const hit of page.hits) out.push({
+			document: hit.concept,
+			line: hit.line,
+			label: hit.text
+		});
+		if (!page.hasMore) return out;
+	}
+}
+/** The lines of `lines` that hold a task with this fingerprint, never one inside a code fence. */
+async function taskLinesWith(lines, fingerprint) {
+	const inFence = /* @__PURE__ */ new Set();
+	for (const block of fencedBlocks(lines)) for (let i = block.start; i <= block.end; i++) inFence.add(i);
+	const out = [];
+	for (let i = 0; i < lines.length; i++) {
+		if (inFence.has(i) || parseTaskLine(lines[i]) === null) continue;
+		if (await taskFingerprint(bulletLabel(lines[i])) === fingerprint) out.push(i);
+	}
+	return out;
+}
+//#endregion
+//#region ../client/src/lib/document/view/minimal-replacement.ts
+/**
+* The smallest single replacement turning `text` into `next`: the shared prefix and suffix
+* trimmed away. Null when the two are equal.
+*
+* Used wherever a whole new text arrives for a document that is being edited - a heal, an
+* external write reaching an open editor - so that the change is the change and nothing more
+* (ADR 0066): on a synced graph a whole-document replace is one enormous CRDT operation that
+* clobbers everyone else's concurrent edits, and in any editor it throws the caret to the end.
+*/
+function minimalReplacement(text, next) {
+	if (next === text) return null;
+	let prefix = 0;
+	while (prefix < text.length && prefix < next.length && text[prefix] === next[prefix]) prefix++;
+	let suffix = 0;
+	while (suffix < text.length - prefix && suffix < next.length - prefix && text[text.length - 1 - suffix] === next[next.length - 1 - suffix]) suffix++;
+	return {
+		from: prefix,
+		to: text.length - suffix,
+		insert: next.slice(prefix, next.length - suffix)
+	};
+}
+//#endregion
+//#region ../client/src/lib/document/task-write.ts
+var MARKER = /^(\s*-\s+\[)[ xX](\])\s?/;
+/**
+* `line` with `changes` made, or null when `line` is not a task.
+*
+* A changed tag run is written in the fixed order the `#` helper writes (`serialiseTags`), for
+* the reason `applyTaskTag` gives: the run is a set, and a predictable order is worth more than
+* one that carries no meaning. A task already as asked comes back untouched, so a move that
+* changes nothing reorders nothing either.
+*/
+function taskLineWith(line, changes) {
+	const parsed = parseTaskLine(line);
+	const marker = MARKER.exec(line);
+	if (!parsed || !marker) return null;
+	const { done: wasDone, ...current } = parsed;
+	const tags = { ...current };
+	let done = wasDone;
+	switch (changes.status) {
+		case "open":
+			done = false;
+			tags.waiting = tags.doing = tags.cancelled = false;
+			break;
+		case "doing":
+			done = false;
+			tags.doing = true;
+			tags.waiting = tags.cancelled = false;
+			break;
+		case "waiting":
+			done = false;
+			tags.waiting = true;
+			tags.doing = tags.cancelled = false;
+			break;
+		case "done":
+			done = true;
+			tags.waiting = tags.doing = tags.cancelled = false;
+			break;
+		case "cancelled":
+			done = true;
+			tags.cancelled = true;
+			tags.waiting = tags.doing = false;
+			break;
+		case void 0: break;
+	}
+	if (changes.priority !== void 0) tags.priority = changes.priority;
+	if (changes.due !== void 0) tags.due = changes.due;
+	if (changes.scheduled !== void 0) tags.scheduled = changes.scheduled;
+	if (done === wasDone && sameTags(tags, current)) return line;
+	return [
+		`${marker[1]}${done ? "x" : " "}${marker[2]}`,
+		...serialiseTags(tags),
+		tags.text
+	].filter((part) => part !== "").join(" ");
+}
+function sameTags(a, b) {
+	return a.priority === b.priority && a.waiting === b.waiting && a.doing === b.doing && a.cancelled === b.cancelled && a.due === b.due && a.scheduled === b.scheduled && a.completion === b.completion;
+}
 /** UTF-16 units of document text returned before `truncated` is set. */
 var READ_TEXT_CAP = 2e5;
 /** A refusal the agent can act on: a stable code first, a sentence second. */
@@ -17445,7 +17878,7 @@ async function tasks(graph, args = {}) {
 		today: todayISO()
 	}, offset, limit);
 	return {
-		tasks: result.hits.map((hit) => ({
+		tasks: await Promise.all(result.hits.map(async (hit) => ({
 			concept: hit.concept,
 			kind: hit.kind,
 			line: hit.line,
@@ -17458,12 +17891,20 @@ async function tasks(graph, args = {}) {
 			due: hit.due,
 			scheduled: hit.scheduled,
 			completion: hit.completion,
-			breadcrumb: hit.breadcrumb
-		})),
+			breadcrumb: hit.breadcrumb,
+			reference: await referenceFor(graph, hit.concept, hit.line, hit.text)
+		}))),
 		total: result.total,
 		hasMore: result.hasMore
 	};
 }
+/**
+* Text an agent sent, in the form EtherPK writes: line feeds only (ADR 0112), then the
+* two-space Indent Unit (ADR 0067). Line endings go first so the normaliser reads whole lines.
+*/
+function asWritten(text) {
+	return normaliseIndentUnit(lineFeedsOnly(text));
+}
 async function editDocument(graph, args) {
 	if (args.old === "") throw new ToolError("invalid_argument", "old must not be empty.");
 	await graph.store.refresh();
@@ -17473,7 +17914,7 @@ async function editDocument(graph, args) {
 	const first = text.indexOf(args.old);
 	if (first === -1) throw new ToolError("no_match", `"${identity.concept}" does not contain the text to replace. Read the document again - it may have changed.`);
 	if (text.indexOf(args.old, first + 1) !== -1) throw new ToolError("ambiguous_match", `The text to replace occurs more than once in "${identity.concept}". Include more surrounding text so it matches exactly once.`);
-	const insert = normaliseIndentUnit(args.new);
+	const insert = asWritten(args.new);
 	graph.store.open(identity.concept).applyChange({
 		from: first,
 		to: first + args.old.length,
@@ -17487,7 +17928,7 @@ async function editDocument(graph, args) {
 	};
 }
 async function appendDocument(graph, args) {
-	const text = normaliseIndentUnit(args.text);
+	const text = asWritten(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();
@@ -17521,7 +17962,7 @@ async function createPage(graph, args) {
 	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 graph.store.createPage(title, asWritten(args.text ?? ""));
 	if (args.frontmatter && Object.keys(args.frontmatter).length > 0) {
 		await graph.store.whenReady(title);
 		const raw = graph.store.openRaw(title).getText();
@@ -17885,22 +18326,25 @@ async function readDocuments(graph, args) {
 	}
 	return { documents };
 }
-/** The task line rebuilt with these tags and checkbox: indent and marker kept, the tag run in the fixed order. */
-function taskLineWith(line, done, tags) {
-	const marker = /^(\s*-\s+\[)[ xX](\])\s?/.exec(line);
-	if (!marker) throw new Error("not a task line");
-	const run = serialiseTags(tags);
-	return `${marker[1]}${done ? "x" : " "}${marker[2]} ${[...run, tags.text].join(" ")}`.replace(/\s+$/, "");
-}
 /**
 * Change one task's status, priority or dates, by document and line (ADR 0032's grammar).
-* Status is exclusive and means what the index's own derivation means: `waiting` and `doing`
-* are unchecked states, `done` and `cancelled` checked ones, `open` none of them. The Client's
-* checkbox writes no completion date, so neither does this. `expect` is the stale-line guard:
-* the same one the Tasks View applies, made explicit for a caller working from a list.
+* The line is rewritten by the writer a Kanban Board move uses (`task-write.ts`), so a status
+* here means exactly what a lane means: exclusive, `waiting` and `doing` unchecked states, `done`
+* and `cancelled` checked ones, `open` none of them, and no completion date written. `expect` is
+* the stale-line guard, made explicit for a caller working from a list.
 */
 async function setTask(graph, args) {
-	if (!Number.isInteger(args.line) || args.line < 0) throw new ToolError("invalid_argument", "line must be a non-negative integer.");
+	if (args.reference !== void 0) {
+		const found = await requireReferencedTask(graph, args.reference);
+		return setTask(graph, {
+			concept: found.document,
+			line: found.line,
+			changes: args.changes
+		});
+	}
+	if (args.concept === void 0) throw new ToolError("invalid_argument", "Name the task by reference, or by concept and line.");
+	if (args.line === void 0 || !Number.isInteger(args.line) || args.line < 0) throw new ToolError("invalid_argument", "line must be a non-negative integer.");
+	const line = args.line;
 	const changes = args.changes ?? {};
 	if (changes.status !== void 0 && !TASK_STATUSES.includes(changes.status)) throw new ToolError("invalid_argument", `Unknown task status "${String(changes.status)}".`);
 	if (changes.priority !== void 0 && changes.priority !== null && ![
@@ -17914,49 +18358,19 @@ async function setTask(graph, args) {
 	const text = await liveText(graph, identity);
 	refuseIfProtected(identity.concept, text);
 	const lines = text.split("\n");
-	const current = lines[args.line];
+	const current = lines[line];
 	const parsed = current === void 0 ? null : parseTaskLine(current);
-	if (!parsed) throw new ToolError("task_moved", `Line ${args.line} of "${identity.concept}" is not a task now - read the document or list tasks again.`);
+	if (!parsed) throw new ToolError("task_moved", `Line ${line} of "${identity.concept}" is not a task now - read the document or list tasks again.`);
 	const afterCheckbox = current.replace(/^\s*-\s+\[[ xX]\]\s?/, "").trim();
-	if (args.expect !== void 0 && args.expect.trim() !== afterCheckbox && args.expect.trim() !== parsed.text.trim()) throw new ToolError("task_moved", `Line ${args.line} of "${identity.concept}" now reads "${parsed.text}", not "${args.expect}" - list tasks again before changing it.`);
-	const tags = { ...parsed };
-	let done = parsed.done;
-	switch (changes.status) {
-		case "open":
-			done = false;
-			tags.waiting = tags.doing = tags.cancelled = false;
-			break;
-		case "doing":
-			done = false;
-			tags.doing = true;
-			tags.waiting = tags.cancelled = false;
-			break;
-		case "waiting":
-			done = false;
-			tags.waiting = true;
-			tags.doing = tags.cancelled = false;
-			break;
-		case "done":
-			done = true;
-			tags.waiting = tags.doing = tags.cancelled = false;
-			break;
-		case "cancelled":
-			done = true;
-			tags.cancelled = true;
-			tags.waiting = tags.doing = false;
-			break;
-		case void 0: break;
-	}
-	if (changes.priority !== void 0) tags.priority = changes.priority;
-	if (changes.due !== void 0) tags.due = changes.due;
-	if (changes.scheduled !== void 0) tags.scheduled = changes.scheduled;
-	const next = taskLineWith(current, done, tags);
-	if (next !== current) {
-		const from = lines.slice(0, args.line).reduce((n, l) => n + l.length + 1, 0);
+	if (args.expect !== void 0 && args.expect.trim() !== afterCheckbox && args.expect.trim() !== parsed.text.trim()) throw new ToolError("task_moved", `Line ${line} of "${identity.concept}" now reads "${parsed.text}", not "${args.expect}" - list tasks again before changing it.`);
+	const next = taskLineWith(current, changes) ?? current;
+	const edit = minimalReplacement(current, next);
+	if (edit) {
+		const from = lines.slice(0, line).reduce((n, l) => n + l.length + 1, 0);
 		graph.store.open(identity.concept).applyChange({
-			from,
-			to: from + current.length,
-			insert: next
+			from: from + edit.from,
+			to: from + edit.to,
+			insert: edit.insert
 		}, "external");
 		await settle$2(graph);
 	}
@@ -17964,13 +18378,124 @@ async function setTask(graph, args) {
 	const status = after.done ? after.cancelled ? "cancelled" : "done" : after.waiting ? "waiting" : after.doing ? "doing" : "open";
 	return {
 		concept: identity.concept,
-		line: args.line,
+		line,
 		text: after.text,
 		status,
 		priority: after.priority,
 		due: after.due,
 		scheduled: after.scheduled,
-		changed: next !== current
+		changed: next !== current,
+		reference: await referenceFor(graph, identity.concept, line, bulletLabel(next))
+	};
+}
+/** A task's status from its parsed line, as the index derives it (`STATUS_SQL`). */
+function statusOf(task) {
+	return task.done ? task.cancelled ? "cancelled" : "done" : task.waiting ? "waiting" : task.doing ? "doing" : "open";
+}
+/** Where a Task Reference is resolved in this graph: its documents, read live, and its index. */
+function referenceSources(graph) {
+	return {
+		graphId: graph.backend.kind === "synced" ? graph.graphId : null,
+		resolveDocument: (name) => resolveIdentity(graph, name)?.concept ?? null,
+		async readBody(document) {
+			const identity = resolveIdentity(graph, document);
+			if (!identity) return null;
+			const text = await liveText(graph, identity);
+			return documentProtection(text).kind === "document" ? null : text;
+		},
+		allTasks: () => everyIndexedTask(graph.index, todayISO())
+	};
+}
+/** The Task Reference to the task at `line` of `concept`, whose label is `label`. */
+async function referenceFor(graph, concept, line, label) {
+	const fingerprint = await taskFingerprint(label);
+	return taskReferenceUrl({
+		graphId: graph.graphId,
+		document: concept,
+		line,
+		fingerprint
+	}, graph.clientUrl ?? "");
+}
+/** The task a Task Reference names in this graph, or the error that says why there is none. */
+async function requireReferencedTask(graph, reference) {
+	const parsed = parseTaskReference(reference);
+	if (!parsed) throw new ToolError("invalid_argument", "That is not a task reference: one ends in #task=<line>-<fingerprint>, as Copy task reference in EtherPK writes it.");
+	await graph.store.refresh();
+	const found = await resolveTaskReference(parsed, referenceSources(graph));
+	if (found.ok) return found;
+	if (found.code === "other_graph") throw new ToolError("other_graph", `That task reference is for another graph. This server serves "${graph.name}" (${found.servedGraphId}); ask the user to connect the graph the reference is from.`);
+	if (found.code === "task_ambiguous") throw new ToolError("task_ambiguous", `More than one task has those words (${found.candidates.map((candidate) => `"${candidate.document}" line ${candidate.line}`).join(", ")}), so none was chosen. Ask the user which one, or name it by concept and line.`);
+	throw new ToolError("task_not_found", "No task in the graph has those words now: it was edited or deleted. Ask the user for a fresh reference.");
+}
+/**
+* The block's own lines and everything nested under it: in the index's rows, which run in
+* document order, the rows after it until one that is not its descendant.
+*/
+function subtreeEnd(blocks, localId) {
+	let end = blocks[localId].endLine;
+	const inside = new Set([localId]);
+	for (let i = localId + 1; i < blocks.length; i++) {
+		const parent = blocks[i].parentId;
+		if (parent === null || !inside.has(parent)) break;
+		inside.add(i);
+		end = Math.max(end, blocks[i].endLine);
+	}
+	return end;
+}
+/**
+* The task a Task Reference names: its words and tags, where it is now, what is above it (the
+* headings and bullets its breadcrumb names) and its detail (its continuation lines and
+* everything nested under it), and how it was found. For the text around it, read the document.
+*/
+async function readTask(graph, args) {
+	const found = await requireReferencedTask(graph, args.reference);
+	const lines = found.body.split("\n");
+	const line = lines[found.line];
+	const task = parseTaskLine(line);
+	const { blocks } = deriveDoc(found.body);
+	const block = blocks.find((candidate) => candidate.startLine === found.line);
+	const end = block ? subtreeEnd(blocks, block.localId) : found.line;
+	return {
+		concept: found.document,
+		line: found.line,
+		text: task.text,
+		status: statusOf(task),
+		priority: task.priority,
+		due: task.due,
+		scheduled: task.scheduled,
+		breadcrumb: block ? ancestorChain(blocks, block.parentId) : [],
+		detail: lines.slice(found.line + 1, end + 1).join("\n"),
+		foundBy: found.foundBy,
+		reference: await referenceFor(graph, found.document, found.line, bulletLabel(line))
+	};
+}
+/**
+* Add a note under the task a Task Reference names: the text as a bullet one level under the
+* task, after its existing detail, so a Kanban Board's Task Detail shows it with the task. Text
+* that is already bullets is nested as it is.
+*/
+async function addTaskNote(graph, args) {
+	if (typeof args.text !== "string" || args.text.trim() === "") throw new ToolError("invalid_argument", "text must not be empty.");
+	const found = await requireReferencedTask(graph, args.reference);
+	const lines = found.body.split("\n");
+	const { blocks } = deriveDoc(found.body);
+	const block = blocks.find((candidate) => candidate.startLine === found.line);
+	const end = block ? subtreeEnd(blocks, block.localId) : found.line;
+	const childIndent = `${/^\s*/.exec(lines[found.line])[0]}  `;
+	const written = asWritten(args.text.trim());
+	const insert = (written.startsWith("- ") ? written : `- ${written.replace(/\n/g, "\n  ")}`).split("\n").map((noteLine) => noteLine === "" ? noteLine : childIndent + noteLine).join("\n");
+	const at = lines.slice(0, end + 1).reduce((n, l) => n + l.length + 1, 0) - 1;
+	graph.store.open(found.document).applyChange({
+		from: at,
+		to: at,
+		insert: `\n${insert}`
+	}, "external");
+	await settle$2(graph);
+	return {
+		concept: found.document,
+		line: found.line,
+		noteLine: end + 1,
+		reference: await referenceFor(graph, found.document, found.line, bulletLabel(lines[found.line]))
 	};
 }
 /** What an agent should know before it starts: where it is, what is here, what is set up. */
@@ -18936,6 +19461,7 @@ function createMcpServer(graph, info) {
 		"To rename a page or concept use plan_rename then rename, never a frontmatter edit: rename carries scoped concepts (\"[[Old]] Notes\") along and by default rewrites every [[Old]] link in the graph to the new name (strategy \"rewrite\") - strategy \"alias\" keeps the old name resolving instead. A rename onto a name that is taken merges two documents and needs confirm_merge: true. References inside protected documents cannot be seen or rewritten.",
 		"search has two kinds of matching: mode \"text\" (default) matches words and quoted phrases, and mode \"semantic\" finds passages about what a question or description means even when no words match. Use semantic for questions and descriptions, text for names, identifiers and exact phrases. \"hybrid\" returns both groups. When you answer from a search result, cite the document and where in it (its breadcrumb or lines). Semantic mode needs a one-time \"semantic setup\" on this computer - if it is not set up, search says so and names the command.",
 		"Start with graph_info to see what you are connected to. read_documents reads several documents in one call. tasks lists tasks and set_task changes one (status, priority, due and scheduled dates) by document and line.",
+		"A task reference is how a person hands you one task: its words, then an EtherPK address ending in #task=<line>-<fingerprint>. Pass the whole reference, or the address, to read_task for the task and its detail, to set_task (as reference) to change it, and to add_task_note to write what you did under it. It finds the task after lines are added above it or its tags change; if its words were edited it answers task_not_found, and you should ask the user for a fresh one.",
 		"Publishing: list_publications shows the publications this graph defines (a publication is a page whose frontmatter defines it - its outline is the site navigation) and the public documents none takes. A document is on a site when its frontmatter has public: true and names the publication in publications. create_publication and update_publication change the settings, and publish writes the site into the publish folder the user set for it on this machine with the etherpk-mcp publish command (the tool cannot choose a folder) and returns the report. Diagrams need a browser the user installs once with \"diagrams setup\".",
 		"Themes: a publication's look is a theme - Mustache templates, a stylesheet, a script and a manifest. list_themes shows the bundled ones (read-only) and the graph's own. read_theme writes a theme's files to a folder on this machine to read and edit. customise_publication_theme copies a publication's bundled theme into the graph and points the publication at the copy (create_theme copies any theme). write_theme_file, delete_theme_file and import_theme_folder change a graph theme. preview_theme renders a theme to a folder (with screenshots when a browser is set up) to check before publish. For a snippet such as an analytics script, an include slot (update_publication includes, e.g. head) filled by a page may be lighter than a theme copy.",
 		"Images and files are assets: upload_asset adds a file from this machine and returns the markdown to paste into a document. read_asset writes an asset to a local file you can open, and list_assets shows the assets documents reference. An asset is available only where a document you can read references it (or you uploaded it this session). read_asset, read_theme and preview_theme write under the graph's downloads directory and return the path - name a folder relative to it, never elsewhere.",
@@ -18983,7 +19509,7 @@ function createMcpServer(graph, info) {
 	}, async (args) => run(() => backlinks(graph, args.concept)));
 	server.registerTool("tasks", {
 		title: "Tasks",
-		description: `Tasks ("- [ ]" bullets) across the graph with their tags. Defaults to every unfinished task. A concept filter matches tasks written on that page, linking it, or nested under a block or heading that links it. At most 200 per call.`,
+		description: `Tasks ("- [ ]" bullets) across the graph with their tags. Defaults to every unfinished task. A concept filter matches tasks written on that page or on a page named for it ("[[Concept]] Notes"), linking it, or nested under a block or heading that links it. At most 200 per call.`,
 		inputSchema: {
 			concept: concept.optional(),
 			statuses: z.array(z.enum([
@@ -19009,12 +19535,26 @@ function createMcpServer(graph, info) {
 			limit: z.number().int().positive().max(200).optional()
 		}
 	}, async (args) => run(() => tasks(graph, args)));
+	server.registerTool("read_task", {
+		title: "Read a task",
+		description: "The task a task reference names: its text, status, priority, due and scheduled days, its document and current 0-based line, its breadcrumb (the headings and bullets above it), its detail (its continuation lines and everything nested under it), foundBy (at_line, moved or other_document) and its current reference. Errors: task_not_found (its words were edited or it was deleted), task_ambiguous (two tasks have its words; the message names them), other_graph (the reference is from another graph).",
+		inputSchema: { reference: z.string().min(1).describe("The task reference as the user gave it: the two lines, or the address alone.") }
+	}, async (args) => run(() => readTask(graph, args)));
+	server.registerTool("add_task_note", {
+		title: "Add a note under a task",
+		description: "Add text under the task a task reference names, one level in, after what is already nested there: a line of text becomes a bullet, and bullets are nested as written. Use it to record what you did about the task. Refuses as read_task does when the reference finds no single task.",
+		inputSchema: {
+			reference: z.string().min(1).describe("The task reference as the user gave it."),
+			text: z.string().min(1).describe("Markdown: a line, or \"- \" bullets.")
+		}
+	}, async (args) => run(() => addTaskNote(graph, args)));
 	server.registerTool("set_task", {
 		title: "Set a task",
-		description: "Change one task by document and 0-based line (as tasks and read_document count lines): its status (open, doing, waiting, done, cancelled - exclusive), priority (1, 2, 3 or null), due and scheduled days (YYYY-MM-DD or null). Pass expect with the task's text from tasks - if the line no longer holds that task the change is refused with error \"task_moved\" and nothing is edited.",
+		description: "Change one task, named by a task reference or by document and 0-based line (as tasks and read_document count lines): its status (open, doing, waiting, done, cancelled - exclusive), priority (1, 2, 3 or null), due and scheduled days (YYYY-MM-DD or null). By line, pass expect with the task's text from tasks - if the line no longer holds that task the change is refused with error \"task_moved\" and nothing is edited. A reference finds the task wherever it is now.",
 		inputSchema: {
-			concept,
-			line: z.number().int().nonnegative(),
+			reference: z.string().min(1).optional().describe("A task reference, in place of concept, line and expect."),
+			concept: concept.optional(),
+			line: z.number().int().nonnegative().optional(),
 			changes: z.object({
 				status: z.enum([
 					"open",
@@ -19888,6 +20428,7 @@ async function openSyncedForServe(wanted, args) {
 		keyring,
 		relayUrl: account.relayUrl,
 		token: account.tokenFor(graphId),
+		clientUrl: account.clientUrl,
 		presenceName: `Agent on ${hostname()}`,
 		readyTimeoutMs: 2e4,
 		persistDir,