@appsoftwareltd/etherpk-mcp 0.12.0 → 0.13.0

package/dist/main.js

@@ -717,7 +717,7 @@ function looksLikeAgentSetupCode(value) {
 }
 var package_default = {
 	name: "@appsoftwareltd/etherpk-mcp",
-	version: "0.12.0",
+	version: "0.13.0",
 	license: "Elastic-2.0",
 	description: "EtherPK Headless Client: an MCP server over a synced knowledge graph, run beside the agent on the user's own machine.",
 	type: "module",
@@ -1541,6 +1541,7 @@ async function openVault(envelope, key) {
 	};
 	throw new EnvelopeError(`unexpected vault envelope kind ${envelope[1] ?? "none"}`);
 }
+contextAad("settings-vault", "v1");
 var PAD_TO = 64;
 var LENGTH_PREFIX = 2;
 function graphNameAad(graphId) {
@@ -1743,6 +1744,19 @@ function createSyncApi(deps) {
 			method: "PUT",
 			body: JSON.stringify(write)
 		}).then((r) => r.version),
+		/**
+		* The person's Settings Vault (ADR 0148), or null while the account has none. An agent
+		* token is refused it: only the account's own devices read it.
+		*/
+		getSettingsVault: () => call("/api/v1/sync/settings-vault").catch((e) => {
+			if (e instanceof SyncApiError && e.status === 404) return null;
+			throw e;
+		}),
+		/** Write the Settings Vault, signed. Resolves to the new version. A stale `expectedVersion` rejects with status 409. */
+		putSettingsVault: (write) => call("/api/v1/sync/settings-vault", {
+			method: "PUT",
+			body: JSON.stringify(write)
+		}).then((r) => r.version),
 		/** Key Replacement (ADR 0128): new keys, and everything an old copy of them reached cut off. */
 		replaceKeys: (replacement) => call("/api/v1/sync/keys/replace", {
 			method: "POST",
@@ -2560,7 +2574,7 @@ var TLS_CODES = /* @__PURE__ */ new Set([
 function describeConnectionFailure(error, syncServer) {
 	if (error instanceof SyncApiError) {
 		if (error.status === 404 && error.message === "HTTP 404") return `${syncServer} is not a Sync Server (it may be the EtherPK app). Use the Sync Server address shown in EtherPK under a synced graph's Settings > Agents.`;
-		if (error.status === 401) return `${syncServer} did not accept the token: it may have been revoked, mistyped, or left unused for 30 days. Make a setup code in EtherPK (a synced graph's Settings > Agents) and run login again.`;
+		if (error.status === 401) return `${syncServer} did not accept the token: it may have been revoked, mistyped, or left unused for 30 days. Create an Agent Setup Code in EtherPK (the Graphs page's Agents tab, or a synced graph's Settings > Agents) and run login again.`;
 		return null;
 	}
 	if (error instanceof TypeError && error.message === "fetch failed") {
@@ -2638,9 +2652,9 @@ function resolveGraphById(graphs, vault, graphId) {
 /**
 * How the Headless Client gets and gives up its agent token (ADR 0132), against the Sync Server's
 * own routes. Separate from the shared REST bridge (`sync-api.ts`), which always sends a token:
-* redeeming a setup code is the one call made before this computer holds any.
+* redeeming an Agent Setup Code is the one call made before this computer holds any.
 *
-* - `redeemSetupCode`: `login --code` trades the one-time code for the agent token.
+* - `redeemSetupCode`: `login --code` trades the one-time Agent Setup Code for the agent token.
 * - `exchangeForAgentToken`: a standard token, pasted into `login` or left in the login file by
 *   an older version, is traded for an agent token; the Sync Server revokes the standard one.
 * - `revokeHeldToken`: `logout` revokes the token it is about to forget, so no token is left on
@@ -2656,7 +2670,6 @@ var AgentTokenError = class extends Error {
 		this.name = "AgentTokenError";
 	}
 };
-var OLDER_SERVER = "This Sync Server runs an older version of EtherPK that cannot give agent tokens. Ask whoever runs it to update it, or log in with an access token from its Access tokens page.";
 function base(syncServer) {
 	return syncServer.replace(/\/+$/, "");
 }
@@ -2666,38 +2679,31 @@ async function tokenFrom(response) {
 	if (response.ok && typeof body?.token === "string") return body.token;
 	throw new AgentTokenError(body?.error?.message ?? `HTTP ${response.status}`, response.status, body?.error?.code);
 }
-/** Trade a one-time setup code for an agent token named `name` ("Agent on <hostname>"). */
+/** Trade a one-time Agent Setup Code for an agent token named `name` ("Agent on <hostname>"). */
 async function redeemSetupCode(call) {
-	const response = await (call.fetch ?? fetch)(`${base(call.syncServer)}/api/v1/sync/agent-tokens`, {
+	return tokenFrom(await (call.fetch ?? fetch)(`${base(call.syncServer)}/api/v1/sync/agent-tokens`, {
 		method: "POST",
 		headers: { "content-type": "application/json" },
 		body: JSON.stringify({
 			setupCode: call.code,
 			name: call.name
 		})
-	});
-	if (response.status === 404 && !response.headers.get("content-type")?.includes("json")) throw new AgentTokenError(OLDER_SERVER, 404);
-	return tokenFrom(response);
+	}));
 }
-/**
-* Trade the standard token `token` for an agent token named `name`; the server revokes `token`.
-* Null on a server from before agent tokens, where the standard token simply goes on working.
-*/
+/** Trade the standard token `token` for an agent token named `name`; the server revokes `token`. */
 async function exchangeForAgentToken(call) {
-	const response = await (call.fetch ?? fetch)(`${base(call.syncServer)}/api/v1/sync/agent-tokens`, {
+	return tokenFrom(await (call.fetch ?? fetch)(`${base(call.syncServer)}/api/v1/sync/agent-tokens`, {
 		method: "POST",
 		headers: {
 			"content-type": "application/json",
 			authorization: `Bearer ${call.token}`
 		},
 		body: JSON.stringify({ name: call.name })
-	});
-	if (response.status === 404 && !response.headers.get("content-type")?.includes("json")) return null;
-	return tokenFrom(response);
+	}));
 }
 /**
 * Revoke the token this computer holds. True once the server has revoked it; false when it could
-* not be reached or refused (already revoked, expired, or a server from before this route), which
+* not be reached or refused (already revoked or expired), which
 * a logout reports but does not stop for: the local copy is forgotten either way.
 */
 async function revokeHeldToken(call) {
@@ -3017,8 +3023,8 @@ async function forgetLoginSecrets(syncServer, stored, keychain) {
 /**
 * A login an older Headless Client made holds a standard token, which reaches everything a
 * signed-in session does. Trade it for an agent token, which the Sync Server revokes the standard
-* one for, and save that in its place. Anything that stops the trade (a server from before agent
-* tokens, no network) leaves the login as it was, to be tried again on the next run.
+* one for, and save that in its place. A trade that fails (no network, a server not answering)
+* leaves the login as it was, to be tried again on the next run.
 */
 async function upgradeToAgentToken(opts) {
 	const { path, credentials, keychain, name, say } = opts;
@@ -3036,7 +3042,6 @@ async function upgradeToAgentToken(opts) {
 				token: current.pat,
 				name
 			});
-			if (!agentToken) return current;
 			const where = await saveLogin({
 				config,
 				path,
@@ -3055,7 +3060,7 @@ async function upgradeToAgentToken(opts) {
 		});
 	} catch (error) {
 		const reason = error instanceof Error ? error.message : String(error);
-		if (opts.stillWorks && !await opts.stillWorks(credentials.pat).catch(() => true)) say(`etherpk-mcp: could not replace the access token for ${credentials.syncServer} with an agent token (${reason}), and the old token no longer works. Make a setup code in EtherPK (a synced graph's Settings > Agents) and run login again.`);
+		if (opts.stillWorks && !await opts.stillWorks(credentials.pat).catch(() => true)) say(`etherpk-mcp: could not replace the access token for ${credentials.syncServer} with an agent token (${reason}), and the old token no longer works. Create an Agent Setup Code in EtherPK (the Graphs page's Agents tab, or a synced graph's Settings > Agents) and run login again.`);
 		else say(`etherpk-mcp: could not replace the access token for ${credentials.syncServer} with an agent token this time (${reason}). It goes on working, and the next run tries again.`);
 		return credentials;
 	}
@@ -6226,7 +6231,7 @@ var SNIPPET_TOKENS = 24;
 * scores merely reintroduces the long-document bias bm25 exists to remove. Counting is cruder,
 * robust, and explainable in one sentence - and it orders by a number the row displays.
 */
-function searchText$1(db, query, offset, limit, filters = []) {
+function searchText$2(db, query, offset, limit, filters = []) {
 	const match = buildFtsMatch(query);
 	if (match === null) return {
 		groups: [],
@@ -15088,71 +15093,6 @@ function withPublishFolder(folders, graphKey, publicationId, folder) {
 	} };
 }
 //#endregion
-//#region ../client/src/lib/document/calendar/month-grid-core.ts
-/** `YYYY-MM-DD` for a local date — the journal file-name format (fs/identity.ts). */
-function formatISODate(date) {
-	return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}-${String(date.getDate()).padStart(2, "0")}`;
-}
-/** Today, as the ISO day the user is living in. The app's single definition of "today". */
-function todayISO(now = /* @__PURE__ */ new Date()) {
-	return formatISODate(now);
-}
-var ISO_SHAPE = /^(\d{4})-(\d{2})-(\d{2})$/;
-/**
-* The local `Date` a `YYYY-MM-DD` string names, or `null` when it names no day that exists.
-*
-* The shape test alone is not enough: `2026-02-30` and `2026-13-01` match it and are not days.
-* Round-tripping through `Date` catches both, because JS silently rolls an out-of-range field
-* forward (31 February becomes 3 March) and the re-format then disagrees with the input.
-*/
-function parseISODate(value) {
-	const match = ISO_SHAPE.exec(value.trim());
-	if (!match) return null;
-	const [, y, m, d] = match;
-	const date = new Date(Number(y), Number(m) - 1, Number(d));
-	return formatISODate(date) === value.trim() ? date : null;
-}
-/** True when `value` names a calendar day that actually exists. */
-function isCalendarDay(value) {
-	return parseISODate(value) !== null;
-}
-/** A new Date `days` after `date` (normalises across month/year boundaries). */
-function shiftDate(date, days) {
-	return new Date(date.getFullYear(), date.getMonth(), date.getDate() + days);
-}
-//#endregion
-//#region ../client/src/lib/document/journal-concept.ts
-/**
-* What makes a [[Concept]] a [[Journal Concept]] — the one predicate that decides where a
-* promoting [[Draft]] writes, and which concepts refuse to be renamed (ADR 0056).
-*
-* It is deliberately **not** the `\d{4}-\d{2}-\d{2}` shape it grew out of. While the shape only
-* guarded rename, letting `2026-13-45` through cost nothing; now that the same answer decides
-* whether a file lands in `journals/` or `pages/`, a loose test would mint a journal entry for a
-* day no calendar can display or reach again.
-*
-* Pure; no DOM, no I/O.
-*/
-/**
-* True when `concept` names a calendar day that exists — a [[Journal Entry]]'s identity.
-*
-* Journal identity is the day itself, so this is case- and alias-free: there is nothing to
-* normalise beyond surrounding whitespace.
-*/
-function isJournalConcept(concept) {
-	return isCalendarDay(concept);
-}
-/**
-* Why a [[Page]] cannot be called `day`: a day is the name of that day's [[Journal Entry]].
-*
-* A page given one sits in `pages/` answering to the day, which is what an older version left
-* behind when a Draft for a date promoted to a page. Creating a page and renaming one both
-* refuse with this, on both backends, so the copy is the same wherever the user meets it.
-*/
-function dayIsNotAPageName(day) {
-	return `“${day.trim()}” is a date, and a date is the name of that day's journal entry, so a page cannot be called that. Choose a different name.`;
-}
-//#endregion
 //#region ../client/src/lib/document/protection/cipher-fence.ts
 /**
 * The `etherpk-cipher` fence as it appears in document *text* — finding one, reading what it holds
@@ -15235,6 +15175,157 @@ function lastNonBlank(lines) {
 	return -1;
 }
 //#endregion
+//#region ../client/src/lib/agent-read/read-rules.ts
+/**
+* What an agent may read of a graph, and how much, for both readers that give a language model the
+* graph's text: the [[Headless Client]]'s MCP tools (`apps/mcp/src/tools.ts`) and an [[Agent Chat]]
+* in the browser (`documents-reader.ts`, ADR 0147). Kept in one place so the size caps, the test for
+* protected text and the shape of a search or backlinks answer cannot drift between the two.
+*
+* The two differ in one rule, which each reader states for itself: the Headless Client lists a
+* [[Protected Document]] by name, while an Agent Chat leaves it out entirely, because what it reads
+* may be sent to a model provider.
+*/
+/** UTF-16 units of one document's text given before the rest is cut and the answer says so. */
+var READ_TEXT_CAP = 2e5;
+/** UTF-16 units across one bulk read before the rest is cut. */
+var READ_MANY_TEXT_CAP = 4e5;
+/** `text` cut at `cap`, and whether it was. */
+function capText(text, cap = READ_TEXT_CAP) {
+	return text.length > cap ? {
+		text: text.slice(0, cap),
+		truncated: true
+	} : {
+		text,
+		truncated: false
+	};
+}
+/** Whether `text` is a Protected Document's: its whole body one encrypted fence. */
+function isProtectedDocumentText(text) {
+	return documentProtection(text).kind === "document";
+}
+/**
+* A page of the documents whose text matches `query`, as [[Search]] reads it: a `key:value` term
+* whose key some unprotected document carries is a [[Property Filter]] (ADR 0107), and anything
+* else is words. The index holds no protected text, so no answer here can quote one.
+*/
+async function searchText$1(index, query, offset, limit) {
+	const keys = await index.propertyKeys();
+	const { words, filters } = parseSearchQuery(query, new Set(keys.map((info) => info.key.toLowerCase())));
+	if (filters.length > 0 && words.trim() === "") {
+		const documents = await index.propertyMatch(filters);
+		return {
+			results: documents.slice(offset, offset + limit).map((doc) => ({
+				concept: doc.concept,
+				kind: doc.kind,
+				matches: 0,
+				hits: [],
+				properties: doc.properties
+			})),
+			total: documents.length,
+			totalCapped: false,
+			hasMore: offset + limit < documents.length
+		};
+	}
+	const [result, count] = await Promise.all([index.searchText(words, offset, limit, filters), index.searchTextCount(words, filters)]);
+	return {
+		results: result.groups.map((group) => ({
+			concept: group.concept,
+			kind: group.kind,
+			matches: group.matches,
+			hits: group.hits.map((hit) => ({
+				line: hit.line,
+				breadcrumb: hit.breadcrumb,
+				snippet: hit.snippet.map((segment) => segment.text).join("")
+			}))
+		})),
+		total: count.total,
+		totalCapped: count.capped,
+		hasMore: result.hasMore
+	};
+}
+/**
+* The documents that link to a concept, each with the places it does. A [[Template]]'s body is a
+* pattern rather than a reference (ADR 0144), so only its name is reported.
+*/
+function backlinkSources(groups) {
+	return withoutTemplateContent(groups).map((group) => ({
+		concept: group.sourceConcept,
+		kind: group.sourceKind,
+		references: group.refs.map((ref) => ({
+			kind: ref.kind,
+			line: ref.line,
+			breadcrumb: ref.breadcrumb,
+			text: ref.kind === "block" ? ref.subtree.map((node) => node.text).join("\n") : ref.context?.text ?? ""
+		}))
+	}));
+}
+//#endregion
+//#region ../client/src/lib/document/calendar/month-grid-core.ts
+/** `YYYY-MM-DD` for a local date — the journal file-name format (fs/identity.ts). */
+function formatISODate(date) {
+	return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}-${String(date.getDate()).padStart(2, "0")}`;
+}
+/** Today, as the ISO day the user is living in. The app's single definition of "today". */
+function todayISO(now = /* @__PURE__ */ new Date()) {
+	return formatISODate(now);
+}
+var ISO_SHAPE = /^(\d{4})-(\d{2})-(\d{2})$/;
+/**
+* The local `Date` a `YYYY-MM-DD` string names, or `null` when it names no day that exists.
+*
+* The shape test alone is not enough: `2026-02-30` and `2026-13-01` match it and are not days.
+* Round-tripping through `Date` catches both, because JS silently rolls an out-of-range field
+* forward (31 February becomes 3 March) and the re-format then disagrees with the input.
+*/
+function parseISODate(value) {
+	const match = ISO_SHAPE.exec(value.trim());
+	if (!match) return null;
+	const [, y, m, d] = match;
+	const date = new Date(Number(y), Number(m) - 1, Number(d));
+	return formatISODate(date) === value.trim() ? date : null;
+}
+/** True when `value` names a calendar day that actually exists. */
+function isCalendarDay(value) {
+	return parseISODate(value) !== null;
+}
+/** A new Date `days` after `date` (normalises across month/year boundaries). */
+function shiftDate(date, days) {
+	return new Date(date.getFullYear(), date.getMonth(), date.getDate() + days);
+}
+//#endregion
+//#region ../client/src/lib/document/journal-concept.ts
+/**
+* What makes a [[Concept]] a [[Journal Concept]] — the one predicate that decides where a
+* promoting [[Draft]] writes, and which concepts refuse to be renamed (ADR 0056).
+*
+* It is deliberately **not** the `\d{4}-\d{2}-\d{2}` shape it grew out of. While the shape only
+* guarded rename, letting `2026-13-45` through cost nothing; now that the same answer decides
+* whether a file lands in `journals/` or `pages/`, a loose test would mint a journal entry for a
+* day no calendar can display or reach again.
+*
+* Pure; no DOM, no I/O.
+*/
+/**
+* True when `concept` names a calendar day that exists — a [[Journal Entry]]'s identity.
+*
+* Journal identity is the day itself, so this is case- and alias-free: there is nothing to
+* normalise beyond surrounding whitespace.
+*/
+function isJournalConcept(concept) {
+	return isCalendarDay(concept);
+}
+/**
+* Why a [[Page]] cannot be called `day`: a day is the name of that day's [[Journal Entry]].
+*
+* A page given one sits in `pages/` answering to the day, which is what an older version left
+* behind when a Draft for a date promoted to a page. Creating a page and renaming one both
+* refuse with this, on both backends, so the copy is the same wherever the user meets it.
+*/
+function dayIsNotAPageName(day) {
+	return `“${day.trim()}” is a date, and a date is the name of that day's journal entry, so a page cannot be called that. Choose a different name.`;
+}
+//#endregion
 //#region ../client/src/lib/document/types.ts
 var DocumentNotFoundError = class extends Error {
 	target;
@@ -16975,8 +17066,34 @@ function taskLineWith(line, changes) {
 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;
+//#endregion
+//#region src/tools.ts
+/**
+* The eight tools an agent gets, as plain functions over an open {@link HeadlessGraph}. The MCP
+* layer (`mcp-server.ts`) only serialises these; everything an agent can and cannot do is
+* decided here, and tested here over both backends - the loopback relay standing in for the
+* Sync Server, and an in-memory folder - without a server or a transport. The tools see only
+* `HeadlessDocuments`: every one starts with `refresh()` so a folder is re-read before it is
+* answered from, and a write ends with `settle()` so success means durable.
+*
+* The rules (ADR 0072, [[2026-09-15 Headless Client And MCP]]):
+*
+* - A [[Protected Document]] is listed by name and nothing else. Reading refuses; every write
+*   refuses, frontmatter included. The Headless Client never holds a Protection Key, so this is
+*   a courtesy to the agent rather than the guarantee - the guarantee is that there is nothing
+*   here to serve.
+* - Edits are anchored: `edit_document` replaces one exact, unique occurrence and lands as one
+*   `applyChange` range, which the sync engine carries as one `Y.Text` change that merges with
+*   whoever is typing elsewhere in the page. There is no whole-page replace.
+* - Every write passes through the paste / import indent normaliser, so an agent that writes
+*   four-space bullets lands on the grid like everyone else.
+* - Every result is bounded: pages are paged, a document read is capped and says so.
+* - `search` has a `mode`: `text` (the index's FTS, the default), `semantic` (nearest
+*   [[Passage]]s by [[Embedding]], ADR 0076) and `hybrid` (both, as two labelled groups rather
+*   than one fused ranking - the same choice the Search modal makes, so the agent can see WHY
+*   something matched). Semantic mode needs the model set up on this machine; without it the
+*   refusal says what to run.
+*/
 /** A refusal the agent can act on: a stable code first, a sentence second. */
 var ToolError = class extends Error {
 	code;
@@ -16986,8 +17103,6 @@ var ToolError = class extends Error {
 		this.name = "ToolError";
 	}
 };
-/** UTF-16 units across one `read_documents` call before the rest is cut. */
-var READ_MANY_TEXT_CAP = 4e5;
 /** Keys the frontmatter tools never read or write; each has a tool of its own. */
 var OWNED_KEYS = /* @__PURE__ */ new Set([
 	"title",
@@ -17077,7 +17192,7 @@ async function liveText(graph, identity) {
 	return graph.store.open(identity.concept).getText();
 }
 function refuseIfProtected(concept, text) {
-	if (documentProtection(text).kind === "document") throw new ToolError("protected_document", `"${concept}" is a protected document. Its content is encrypted under a key this client never holds, so it cannot be read or changed here - the user can unlock it in EtherPK.`);
+	if (isProtectedDocumentText(text)) throw new ToolError("protected_document", `"${concept}" is a protected document. Its content is encrypted under a key this client never holds, so it cannot be read or changed here - the user can unlock it in EtherPK.`);
 }
 function page$1(items, offset, limit) {
 	return {
@@ -17123,13 +17238,14 @@ async function readDocument(graph, concept) {
 	const identity = requireIdentity(graph, concept);
 	const text = await liveText(graph, identity);
 	refuseIfProtected(identity.concept, text);
+	const capped = capText(text, READ_TEXT_CAP);
 	return {
 		concept: identity.concept,
 		kind: identity.kind,
 		aliases: identity.aliases,
-		text: text.length > 2e5 ? text.slice(0, READ_TEXT_CAP) : text,
+		text: capped.text,
 		frontmatter: agentFrontmatter(graph.store.openRaw(identity.concept).getText()),
-		truncated: text.length > READ_TEXT_CAP
+		truncated: capped.truncated
 	};
 }
 async function search(graph, args) {
@@ -17185,40 +17301,9 @@ async function searchSemantic(graph, query, offset, limit) {
 function round(similarity) {
 	return Math.round(similarity * 1e3) / 1e3;
 }
-async function searchText(graph, query, offset, limit) {
-	const keys = await graph.index.propertyKeys();
-	const { words, filters } = parseSearchQuery(query, new Set(keys.map((info) => info.key.toLowerCase())));
-	if (filters.length > 0 && words.trim() === "") {
-		const documents = await graph.index.propertyMatch(filters);
-		return {
-			results: documents.slice(offset, offset + limit).map((doc) => ({
-				concept: doc.concept,
-				kind: doc.kind,
-				matches: 0,
-				hits: [],
-				properties: doc.properties
-			})),
-			total: documents.length,
-			totalCapped: false,
-			hasMore: offset + limit < documents.length
-		};
-	}
-	const [result, count] = await Promise.all([graph.index.searchText(words, offset, limit, filters), graph.index.searchTextCount(words, filters)]);
-	return {
-		results: result.groups.map((group) => ({
-			concept: group.concept,
-			kind: group.kind,
-			matches: group.matches,
-			hits: group.hits.map((hit) => ({
-				line: hit.line,
-				breadcrumb: hit.breadcrumb,
-				snippet: hit.snippet.map((segment) => segment.text).join("")
-			}))
-		})),
-		total: count.total,
-		totalCapped: count.capped,
-		hasMore: result.hasMore
-	};
+/** The index's text group, read as Search reads it (shared with the browser's Agent Chat). */
+function searchText(graph, query, offset, limit) {
+	return searchText$1(graph.index, query, offset, limit);
 }
 async function backlinks(graph, concept) {
 	const target = concept.trim() === "today" ? todayISO() : concept.trim();
@@ -17226,16 +17311,7 @@ async function backlinks(graph, concept) {
 	await graph.store.refresh();
 	return {
 		concept: target,
-		sources: withoutTemplateContent(await graph.index.backlinks(target)).map((group) => ({
-			concept: group.sourceConcept,
-			kind: group.sourceKind,
-			references: group.refs.map((ref) => ({
-				kind: ref.kind,
-				line: ref.line,
-				breadcrumb: ref.breadcrumb,
-				text: ref.kind === "block" ? ref.subtree.map((node) => node.text).join("\n") : ref.context?.text ?? ""
-			}))
-		}))
+		sources: backlinkSources(await graph.index.backlinks(target))
 	};
 }
 /**
@@ -17375,7 +17451,7 @@ async function templateBodyFor(graph, name) {
 		raw = graph.store.openRaw(identity.concept).getText();
 	}
 	const { data, body } = parseFrontmatter(raw);
-	if (!identity || !isTemplate(data, identity.kind) || documentProtection(body).kind === "document") throw new ToolError("invalid_argument", `"${name}" is not a Template. A page is a Template when its frontmatter says template: true; search for template:true to list them.`);
+	if (!identity || !isTemplate(data, identity.kind) || isProtectedDocumentText(body)) throw new ToolError("invalid_argument", `"${name}" is not a Template. A page is a Template when its frontmatter says template: true; search for template:true to list them.`);
 	return templateBody(raw);
 }
 /**
@@ -17801,7 +17877,7 @@ async function readDocuments(graph, args) {
 			continue;
 		}
 		const text = await liveText(graph, identity);
-		if (documentProtection(text).kind === "document") {
+		if (isProtectedDocumentText(text)) {
 			documents.push({
 				concept: identity.concept,
 				error: "protected_document",
@@ -17898,7 +17974,7 @@ function referenceSources(graph) {
 			const identity = resolveIdentity(graph, document);
 			if (!identity) return null;
 			const text = await liveText(graph, identity);
-			return documentProtection(text).kind === "document" ? null : text;
+			return isProtectedDocumentText(text) ? null : text;
 		},
 		allTasks: () => everyIndexedTask(graph.index, todayISO())
 	};
@@ -20278,7 +20354,7 @@ function createIndexCore(host) {
 				}];
 			}
 			case "search-text": {
-				const page = db ? searchText$1(db, request.query, request.offset, request.limit, request.filters ?? []) : {
+				const page = db ? searchText$2(db, request.query, request.offset, request.limit, request.filters ?? []) : {
 					groups: [],
 					hasMore: false
 				};
@@ -25409,11 +25485,12 @@ async function pollDeviceApproval(api, request) {
 * (ADR 0072). Two routes, both already served by the Sync Server for every new device:
 *
 * - **Device Approval** (ADR 0125), the default: this process posts a commitment to a one-time
-*   key; once an unlocked EtherPK tab answers, it prints the code both screens show. The user
-*   approves in the tab AND presses y here: a server can play the approving device itself, and
+*   key; once EtherPK answers on a device where the account's Encryption Keys are unlocked, it
+*   prints the code both screens show. The user approves on that device AND presses y here: a
+*   server can play the approving device itself, and
 *   only the user, comparing the two screens, can tell. The key that arrives is checked against
 *   the vault before it is used. No secret passes through the terminal.
-* - **Recovery Code**, behind a flag, for a box with no tab to hand: the code derives the wrap
+* - **Recovery Code**, behind a flag, for a box with no unlocked device to hand: the code derives the wrap
 *   key, which opens the vault; what is cached is the vault key, never the code.
 *
 * Pure over an injected clock and output so the flow is testable without a terminal.
@@ -25440,8 +25517,8 @@ var SIGNAL_EXIT_CODES = {
 * The keys the approval wait answers to. `y` confirms the codes match; `n` says they do not, which
 * cancels the request; `r` switches to the Recovery Code; Ctrl-C (a key while the terminal is in
 * raw mode) and SIGINT, SIGTERM or SIGHUP quit. Every way out aborts the wait, so it cancels its
-* approval server-side before anything exits: a login left pending showed its stale code in every
-* unlocked tab for ten minutes. `exitCode` is set once the user has quit.
+* approval server-side before anything exits: a login left pending showed its stale code on every
+* unlocked device for ten minutes. `exitCode` is set once the user has quit.
 */
 function approvalWaitControls() {
 	const abort = new AbortController();
@@ -25509,8 +25586,8 @@ async function unlockByDeviceApproval(api, io) {
 	const request = await beginDeviceApproval(api);
 	const where = io.clientUrl ? `open EtherPK at ${io.clientUrl}` : "open EtherPK in a browser";
 	io.say("");
-	io.say(`To approve this device, ${where} (any page - it need not be a note), connected to this account`);
-	io.say("with its Encryption Keys unlocked. A prompt will appear there, and this terminal then shows a code to compare.");
+	io.say(`To approve this device, ${where} (any page - it need not be a note) on any device where this account's`);
+	io.say("Encryption Keys are unlocked. A prompt will appear there, and this terminal then shows a code to compare.");
 	io.say("");
 	io.say("Waiting (up to ten minutes)…");
 	const abandon = async () => {
@@ -25764,13 +25841,12 @@ var VERSION = package_default.version;
 var CMD = /[\\/]_npx[\\/]/.test(process.argv[1] ?? "") ? "npx @appsoftwareltd/etherpk-mcp" : "etherpk-mcp";
 var USAGE = `etherpk-mcp - EtherPK Headless Client (an MCP server over one synced graph)
 
-  ${CMD} login --sync-server <url> [--code <setup code>] [--recovery-code]
-      Sign this machine in as a device of your account. Make a setup code in EtherPK
-      (a synced graph's Settings > Agents, or <url>/account/tokens) and pass it with --code:
-      it works once, within 10 minutes, and gets this machine an agent token of its own,
-      which can do only what an agent needs. Then unlock your Encryption Keys by Device
-      Approval: open EtherPK in a browser connected to the account with its Encryption Keys
-      unlocked, approve there if it shows the same code, then press y. Press r while waiting,
+  ${CMD} login --sync-server <url> [--code <Agent Setup Code>] [--recovery-code]
+      Sign in this computer as a device of your account. Create an Agent Setup Code in EtherPK
+      (the Graphs page's Agents tab, or a synced graph's Settings > Agents, or <url>/account/tokens) and pass it with --code: it works once, within 10
+      minutes, and gets this computer an Agent Token limited to the routes an agent needs. Then
+      unlock your Encryption Keys by Device Approval: confirm the matching code in EtherPK on
+      any device where your Encryption Keys are unlocked, then press y. Press r while waiting,
       or pass --recovery-code, to type your Recovery Code instead (or ETHERPK_RECOVERY_CODE,
       for a scripted setup).
       For a script, --pat <token> or ETHERPK_PAT takes an account-wide access token instead,
@@ -25972,11 +26048,11 @@ async function login(args) {
 	const syncServer = normaliseSyncServer(args["sync-server"] ?? (known.length === 1 ? known[0] : await ask("Sync Server URL: ", { hint: "pass --sync-server <url>" })));
 	if (!/^https?:\/\//.test(syncServer)) fail("The Sync Server must be an http(s) URL.");
 	const previous = config.servers[syncServer];
-	const given = (args.code ?? args.pat ?? process.env.ETHERPK_PAT ?? await ask("Setup code (make one in EtherPK: a synced graph's Settings > Agents): ", {
+	const given = (args.code ?? args.pat ?? process.env.ETHERPK_PAT ?? await ask(`Agent Setup Code (create one in EtherPK: the Graphs page's Agents tab, or a synced graph's Settings > Agents): `, {
 		secret: true,
-		hint: "pass --code <setup code>"
+		hint: "pass --code <Agent Setup Code>"
 	})).trim();
-	if (!given) fail("A setup code is required. Make one in EtherPK: a synced graph's Settings > Agents.");
+	if (!given) fail(`An Agent Setup Code is required. Create one in EtherPK: the Graphs page's Agents tab, or a synced graph's Settings > Agents.`);
 	const name = agentTokenName();
 	let token;
 	let redeemed = false;
@@ -25988,7 +26064,7 @@ async function login(args) {
 		}).catch((error) => fail(describeLoginFailure(error, syncServer)));
 		redeemed = true;
 	} else if (accessTokenKind(given) !== null) token = given;
-	else fail("That is neither a setup code (epk_setup_...) nor an access token (epk_pat_...). Make a setup code in EtherPK: a synced graph's Settings > Agents.");
+	else fail(`That is neither an Agent Setup Code (epk_setup_...) nor an access token (epk_pat_...). Create an Agent Setup Code in EtherPK: the Graphs page's Agents tab, or a synced graph's Settings > Agents.`);
 	const abandon = async (error) => {
 		if (redeemed) await revokeHeldToken({
 			syncServer,
@@ -26008,18 +26084,16 @@ async function login(args) {
 	const vaultKey = await (args["recovery-code"] ? byRecoveryCode() : approveOrFallBack(account, byRecoveryCode)).catch(abandon);
 	if (accessTokenKind(token) === "standard") {
 		const given = token;
-		const agentToken = await exchangeForAgentToken({
+		token = await exchangeForAgentToken({
 			syncServer,
 			token,
 			name
 		}).catch(async (error) => {
-			if (!await tokenStillWorks(syncServer, given)) fail(`Could not swap the access token for an agent token (${describeLoginFailure(error, syncServer)}), and the access token you gave no longer works. Run login again with a setup code.`);
-			console.log(`Could not swap the access token for an agent token (${describeLoginFailure(error, syncServer)}), so this computer keeps the access token you gave. Run login again to try again.`);
+			const reason = describeLoginFailure(error, syncServer);
+			if (!await tokenStillWorks(syncServer, given)) return fail(`Could not swap the access token for an Agent Token (${reason}), and the access token you gave no longer works. Run login again with an Agent Setup Code.`);
+			return fail(`Could not swap the access token for an Agent Token (${reason}). Nothing was kept on this computer: run login again.`);
 		});
-		if (agentToken) {
-			token = agentToken;
-			console.log(`The access token you gave has been revoked. This computer now holds an agent token of its own, which can do only what an agent needs. If you used that access token anywhere else, make a new one at ${syncServer}/account/tokens.`);
-		} else if (agentToken === null) console.log("This Sync Server runs an older version of EtherPK that cannot give agent tokens, so this computer keeps the access token you gave.");
+		console.log(`The access token you gave has been revoked. This computer now holds an Agent Token, limited to the routes an agent needs. If you used that access token anywhere else, create a new one at ${syncServer}/account/tokens.`);
 	}
 	if (previous) {
 		const before = await loginCredentials(syncServer, previous, keychain()).catch(() => null);