@appsoftwareltd/etherpk-mcp 0.8.52 → 0.8.54

package/dist/main.js

@@ -32,9 +32,11 @@ import Mustache from "mustache";
 import { lookup } from "node:dns";
 import { request } from "node:https";
 import { BlockList, isIP } from "node:net";
+import { UndirectedGraph } from "graphology";
+import louvain from "graphology-communities-louvain";
 var package_default = {
 	name: "@appsoftwareltd/etherpk-mcp",
-	version: "0.8.52",
+	version: "0.8.54",
 	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",
@@ -60,6 +62,9 @@ var package_default = {
 		"@noble/hashes": "2.2.0",
 		"@sqlite.org/sqlite-wasm": "3.53.0-build1",
 		"fake-indexeddb": "^6.2.5",
+		"graphology": "^0.26.0",
+		"graphology-communities-louvain": "^2.0.2",
+		"graphology-types": "^0.24.8",
 		"katex": "^0.17.0",
 		"lib0": "0.2.117",
 		"markdown-it": "15.0.2",
@@ -8830,6 +8835,94 @@ function lastNonBlank(lines) {
 	return -1;
 }
 //#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
+* concepts a [[Wikilink]] joins, in one answer.
+*
+* Everything comes from rows the index already holds: the `pages` and `aliases` tables, and the
+* `links` table grouped by source document. No document is opened or parsed, which is what lets
+* a whole graph be drawn from one round trip.
+*
+* A [[Protected Document]] contributes no body links (the parser suppresses links inside the
+* cipher fence, and the index never sees plaintext), so it appears here as a name with lines in
+* from plaintext documents and none out. Its title scopes still draw a line, because a page's
+* name is visible wherever the page is.
+*/
+function linkGraph(db) {
+	const generation = activeIndexGeneration(db);
+	const pages = db.all("SELECT concept, concept_key AS key, kind, protected FROM pages WHERE generation = ? ORDER BY id", [generation]);
+	const aliases = db.all("SELECT a.alias_key AS key, p.concept_key AS page FROM aliases a JOIN pages p ON p.id = a.page_id WHERE p.generation = ? ORDER BY a.page_id", [generation]);
+	const rows = db.all(`SELECT p.concept_key AS source, json_group_array(json_array(l.concept_key, l.concept, l.in_title)) AS links
+         FROM links l JOIN pages p ON p.id = l.page_id
+         WHERE p.generation = ?
+         GROUP BY p.id`, [generation]);
+	const concepts = /* @__PURE__ */ new Map();
+	for (const page of pages) {
+		if (concepts.has(page.key)) continue;
+		const concept = {
+			key: page.key,
+			name: page.concept,
+			kind: page.kind
+		};
+		concepts.set(page.key, page.protected ? {
+			...concept,
+			protected: true
+		} : concept);
+	}
+	const pageOfAlias = /* @__PURE__ */ new Map();
+	for (const alias of aliases) if (!concepts.has(alias.key) && !pageOfAlias.has(alias.key)) pageOfAlias.set(alias.key, alias.page);
+	const resolve = (key) => concepts.has(key) ? key : pageOfAlias.get(key) ?? key;
+	const parsed = rows.map((row) => ({
+		source: row.source,
+		links: JSON.parse(row.links)
+	}));
+	const spellings = /* @__PURE__ */ new Map();
+	for (const row of parsed) for (const [key, written] of row.links) {
+		if (concepts.has(resolve(key))) continue;
+		const counts = spellings.get(key) ?? /* @__PURE__ */ new Map();
+		counts.set(written, (counts.get(written) ?? 0) + 1);
+		spellings.set(key, counts);
+	}
+	for (const [key, counts] of spellings) {
+		let name = "";
+		let best = 0;
+		for (const [written, count] of counts) if (count > best || count === best && written < name) {
+			name = written;
+			best = count;
+		}
+		concepts.set(key, {
+			key,
+			name,
+			kind: "pageless"
+		});
+	}
+	const ordered = [...concepts.values()].sort((a, b) => a.key < b.key ? -1 : a.key > b.key ? 1 : 0);
+	const position = new Map(ordered.map((concept, index) => [concept.key, index]));
+	const lines = /* @__PURE__ */ new Map();
+	for (const row of parsed) {
+		const source = position.get(row.source);
+		if (source === void 0) continue;
+		for (const [key, , inTitle] of row.links) {
+			const target = position.get(resolve(key));
+			if (target === void 0 || source === target) continue;
+			const id = `${source}:${target}`;
+			const line = lines.get(id) ?? {
+				source,
+				target,
+				mentions: 0
+			};
+			line.mentions += 1;
+			if (inTitle) line.inTitle = true;
+			lines.set(id, line);
+		}
+	}
+	return {
+		concepts: ordered,
+		links: [...lines.values()].sort((a, b) => a.source - b.source || a.target - b.target)
+	};
+}
+//#endregion
 //#region ../client/src/lib/document/index-worker/core.ts
 /**
 * The index server, free of any transport (ADR 0041 §2). It owns the SQLite database and
@@ -9144,6 +9237,17 @@ function createIndexCore(host) {
 					usage
 				}];
 			}
+			case "link-graph": {
+				const graph = db ? linkGraph(db) : {
+					concepts: [],
+					links: []
+				};
+				return [{
+					type: "link-graph",
+					id: request.id,
+					graph
+				}];
+			}
 			case "semantic-status": {
 				const status = db ? semanticStatus(db, request.model) : {
 					available: false,
@@ -9837,6 +9941,12 @@ function createRemoteGraphIndex(source, transport, options) {
 				needles: [...needles]
 			}))).usage;
 		},
+		async linkGraph() {
+			return (await request((id) => ({
+				type: "link-graph",
+				id
+			}))).graph;
+		},
 		async searchText(query, offset, limit, filters) {
 			const response = await request((id) => ({
 				type: "search-text",
@@ -15160,6 +15270,82 @@ function parseImageDisplaySizeHint(alt) {
 	return parsed;
 }
 //#endregion
+//#region ../client/src/lib/document/outliner.ts
+function lineIndent(line) {
+	return line.length - line.trimStart().length;
+}
+function isBulletLine(line) {
+	return /^-\s/.test(line.trimStart());
+}
+//#endregion
+//#region ../client/src/lib/document/publish/markdown/list-item-end-rule.ts
+/** The lines this parse ended a list item at. */
+function endedAt(state) {
+	const env = state.env;
+	env.etherpkListItemEnds ??= /* @__PURE__ */ new Set();
+	return env.etherpkListItemEnds;
+}
+/** A line whose indentation, if any, is spaces only. */
+var SPACE_INDENTED = /^ *\S/;
+/** An empty bullet as the editor reads one: a dash and whitespace, indented with spaces. */
+var EMPTY_BULLET = /^ *-[ \t]+$/;
+/** The block rules whose reading of a line this rule ended an item at is never the editor's. */
+var READ_AS_A_PARAGRAPH = [
+	"lheading",
+	"reference",
+	"html_block",
+	"code"
+];
+/** Line `line` as typed, from its true start: inside a quote `bMarks` starts after the `>`. */
+function rawLine(state, line) {
+	const end = state.eMarks[line];
+	return state.src.slice(state.src.lastIndexOf("\n", end - 1) + 1, end);
+}
+/**
+* The first line of the innermost list item the parse is inside, or null when it is in no item or
+* inside a quote. Walking back over the tokens pushed so far, the openers not yet closed are the
+* containers the parse is inside, innermost first. A block being read has not pushed its own tokens.
+*/
+function openItemLine(state) {
+	let closed = 0;
+	let item = null;
+	for (let i = state.tokens.length - 1; i >= 0; i--) {
+		const token = state.tokens[i];
+		if (token.nesting === -1) closed++;
+		else if (token.nesting === 1) {
+			if (closed > 0) closed--;
+			else if (token.type === "blockquote_open") return null;
+			else if (token.type === "list_item_open" && item === null) item = token.map?.[0] ?? null;
+		}
+	}
+	return item;
+}
+function listItemEndRule(md) {
+	md.block.ruler.before("paragraph", "etherpk_list_item_end", (state, line, _endLine, silent) => {
+		if (!silent) return false;
+		if (endedAt(state).has(state.line) && EMPTY_BULLET.test(rawLine(state, line))) return true;
+		if (state.listIndent < 0 || state.sCount[line] >= state.blkIndent) return false;
+		const start = openItemLine(state);
+		if (start === null) return false;
+		const bullet = rawLine(state, start);
+		const text = rawLine(state, line);
+		if (!isBulletLine(bullet) || !SPACE_INDENTED.test(bullet) || !SPACE_INDENTED.test(text)) return false;
+		if (lineIndent(text) >= lineIndent(bullet) + 2) return false;
+		endedAt(state).add(line);
+		return true;
+	}, { alt: [
+		"paragraph",
+		"blockquote",
+		"reference"
+	] });
+	for (const name of READ_AS_A_PARAGRAPH) {
+		const rule = md.block.ruler.__rules__.find((candidate) => candidate.name === name);
+		if (!rule) continue;
+		const read = rule.fn;
+		md.block.ruler.at(name, (state, startLine, endLine, silent) => !endedAt(state).has(startLine) && read(state, startLine, endLine, silent), { alt: rule.alt });
+	}
+}
+//#endregion
 //#region ../client/src/lib/document/publish/markdown/mark-rule.ts
 var EQUALS = 61;
 function tokenize(state, silent) {
@@ -15430,6 +15616,7 @@ function createDocumentRenderer(options) {
 	});
 	const validateLink = md.validateLink;
 	md.validateLink = (url) => validateLink(url) || /^file:\/\//i.test(url);
+	listItemEndRule(md);
 	wikilinkRule(md, options.resolve);
 	markRule(md);
 	mathRule(md);
@@ -17363,6 +17550,29 @@ async function writeDownload(directory, name, bytes) {
 	}
 	throw new Error(`${directory} already holds a thousand files named like ${safe}.`);
 }
+/**
+* Namespace a View kind to the extension that contributes it, so two extensions
+* can each contribute a kind without colliding. First-party (core) kinds are
+* unprefixed (`document`, `backlinks`, …); extension kinds are
+* `"<extensionId>.<kind>"`, mirroring the `publisher.command` convention.
+*/
+function namespacedViewKind(extensionId, kind) {
+	return `${extensionId}.${kind}`;
+}
+//#endregion
+//#region ../client/src/lib/graph-view/identity.ts
+/**
+* The [[Graph View]]'s names: its extension id, its two View kinds and their identities, and its
+* Command ids. Kept apart from the registration so the workspace can ensure the Sidebar
+* resident, and the address code can name the whole graph, without importing the View itself.
+*
+* Two kinds rather than one kind with two targets, because the Layout finds a resident by kind
+* (`findView`, residents.ts) and places a View by its kind's natural region: the resident must
+* never be confused with the whole graph, and each has its own home.
+*/
+var GRAPH_VIEW_EXTENSION_ID = "graph-view";
+namespacedViewKind(GRAPH_VIEW_EXTENSION_ID, "local");
+namespacedViewKind(GRAPH_VIEW_EXTENSION_ID, "whole");
 //#endregion
 //#region ../client/src/lib/navigation/document-url.ts
 /** Encode a concept for the `[...concept]` rest param: per-segment, `/` kept. */
@@ -17521,6 +17731,295 @@ async function taskLinesWith(lines, fingerprint) {
 	return out;
 }
 //#endregion
+//#region ../client/src/lib/graph-view/model/graph-model.ts
+/**
+* The [[Graph View]]'s model: the index's {@link LinkGraph} turned into a graphology graph the
+* drawing and the insight lists both read, and the questions asked of it (what is near a
+* concept, what route joins two).
+*
+* Framework-free and DOM-free, so it is Node-tested and the Headless Client answers the same
+* questions with the same code (its `graph_insights` and `graph_path` tools).
+*
+* One line per pair. The index keeps each direction as its own link, because the Hub measure
+* counts the documents linking TO a concept. A picture of who links to whom reads the same
+* either way, so the two directions are joined here and their mentions added up.
+*/
+function createGraphModel(data) {
+	const graph = new UndirectedGraph();
+	const linkedFrom = /* @__PURE__ */ new Map();
+	for (const concept of data.concepts) {
+		const attributes = {
+			name: concept.name,
+			kind: concept.kind,
+			linkedFrom: 0
+		};
+		graph.addNode(concept.key, concept.protected ? {
+			...attributes,
+			protected: true
+		} : attributes);
+	}
+	for (const link of data.links) {
+		const source = data.concepts[link.source]?.key;
+		const target = data.concepts[link.target]?.key;
+		if (source === void 0 || target === void 0 || source === target) continue;
+		linkedFrom.set(target, (linkedFrom.get(target) ?? 0) + 1);
+		if (graph.hasEdge(source, target)) graph.updateEdgeAttributes(source, target, (line) => ({
+			mentions: line.mentions + link.mentions,
+			...line.inTitle || link.inTitle ? { inTitle: true } : {}
+		}));
+		else graph.addEdge(source, target, link.inTitle ? {
+			mentions: link.mentions,
+			inTitle: true
+		} : { mentions: link.mentions });
+	}
+	const concepts = /* @__PURE__ */ new Map();
+	for (const concept of data.concepts) {
+		const count = linkedFrom.get(concept.key) ?? 0;
+		graph.setNodeAttribute(concept.key, "linkedFrom", count);
+		concepts.set(concept.key, {
+			...concept,
+			linkedFrom: count,
+			joined: graph.degree(concept.key)
+		});
+	}
+	return {
+		concepts,
+		graph
+	};
+}
+/** Whether a concept passes the viewer's filter. Pages always do. */
+function passesFilter(attributes, filter) {
+	if (attributes.kind === "journal") return filter.journals;
+	if (attributes.kind === "pageless") {
+		if (filter.pageless === "all") return true;
+		return filter.pageless === "mentioned-twice" && attributes.linkedFrom >= 2;
+	}
+	return true;
+}
+/**
+* The graph a viewer sees: the concepts the filter keeps, and the lines between them. A
+* Pageless Concept exists only through the wikilinks naming it, so one left with no line shown
+* (named only by the journal entries a viewer has hidden, say) is dropped rather than drawn as a
+* ring joined to nothing. A page with no lines stays: it is an Isolated Document, worth seeing.
+*/
+function visibleGraph(model, filter) {
+	const graph = subgraph(model.graph, (_key, attributes) => passesFilter(attributes, filter));
+	graph.forEachNode((key, attributes) => {
+		if (attributes.kind === "pageless" && graph.degree(key) === 0) graph.dropNode(key);
+	});
+	return graph;
+}
+/** The part of `graph` whose concepts `keep` accepts, with every line between two of them. */
+function subgraph(graph, keep) {
+	const out = new UndirectedGraph();
+	graph.forEachNode((key, attributes) => {
+		if (keep(key, attributes)) out.addNode(key, { ...attributes });
+	});
+	graph.forEachEdge((_edge, attributes, source, target) => {
+		if (out.hasNode(source) && out.hasNode(target)) out.addEdge(source, target, { ...attributes });
+	});
+	return out;
+}
+/**
+* The fewest lines from one concept to another in `graph`, as the concepts passed through, or
+* null when none joins them. A breadth-first search: every line counts the same, so the first
+* time the search reaches `to` is by a shortest route. Written here rather than taken from
+* graphology-shortest-path, whose extensionless CommonJS subpath the Headless Client's Node
+* ESM loader cannot import.
+*/
+function shortestPath(graph, from, to) {
+	if (!graph.hasNode(from) || !graph.hasNode(to)) return null;
+	if (from === to) return [from];
+	const cameFrom = new Map([[from, from]]);
+	let frontier = [from];
+	while (frontier.length > 0) {
+		const next = [];
+		for (const key of frontier) for (const neighbour of graph.neighbors(key)) {
+			if (cameFrom.has(neighbour)) continue;
+			cameFrom.set(neighbour, key);
+			if (neighbour === to) {
+				const path = [to];
+				for (let step = key; step !== from; step = cameFrom.get(step) ?? from) path.push(step);
+				path.push(from);
+				return path.reverse();
+			}
+			next.push(neighbour);
+		}
+		frontier = next;
+	}
+	return null;
+}
+//#endregion
+//#region ../client/src/lib/graph-view/model/insights.ts
+/**
+* The lists the whole-graph [[Graph View]] shows beside the picture, and the Headless Client's
+* `graph_insights` tool returns: [[Hub]]s, [[Pageless Concept]]s by how many documents mention
+* them, [[Isolated Document]]s, [[Cluster]]s and [[Bridge]]s.
+*
+* Each list is something a person can act on: a Hub is worth a good page, a much-mentioned
+* Pageless Concept is a page nobody has written yet, an Isolated Document is a page to connect,
+* and a Bridge is where two areas of a graph meet.
+*/
+var byCountThenName = (a, b) => b.count - a.count || a.name.localeCompare(b.name);
+/** Concepts by the documents that link to them, most first, leaving out those nothing links to. */
+function hubs(model, limit) {
+	return ranked(model, limit, () => true);
+}
+/** Pageless Concepts by the documents that mention them: the pages most asked for and never written. */
+function pagelessByDocuments(model, limit) {
+	return ranked(model, limit, (concept) => concept.kind === "pageless");
+}
+function ranked(model, limit, include) {
+	const rows = [];
+	for (const concept of model.concepts.values()) if (concept.linkedFrom > 0 && include(concept)) rows.push({
+		key: concept.key,
+		name: concept.name,
+		kind: concept.kind,
+		count: concept.linkedFrom
+	});
+	return rows.sort(byCountThenName).slice(0, limit);
+}
+/**
+* Pages with no line in either direction, sorted by name. A scope in a page's own name is a
+* line, so a scoped page and its scope are never isolated. Journal entries are left out: a day
+* with no links is ordinary, not a page waiting to be connected.
+*/
+function isolatedDocuments(model) {
+	const rows = [];
+	for (const concept of model.concepts.values()) if (concept.kind === "page" && concept.joined === 0) rows.push({
+		key: concept.key,
+		name: concept.name,
+		kind: concept.kind,
+		count: 0
+	});
+	return rows.sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+* Group `graph`'s concepts with Louvain community detection over the lines alone, unweighted, so
+* one long page naming a concept fifty times does not pull it into that page's group. The
+* random choices Louvain makes come from a fixed seed, so the same graph always gives the same
+* Clusters and the same colours.
+*/
+function findClusters(graph, minSize = 3) {
+	const clusterOf = /* @__PURE__ */ new Map();
+	if (graph.size === 0) return {
+		clusters: [],
+		clusterOf
+	};
+	const community = louvain(graph, {
+		getEdgeWeight: null,
+		rng: seededRandom(2654435769)
+	});
+	const members = /* @__PURE__ */ new Map();
+	for (const [key, id] of Object.entries(community)) {
+		const list = members.get(id);
+		if (list) list.push(key);
+		else members.set(id, [key]);
+	}
+	return {
+		clusters: [...members.values()].filter((keys) => keys.length >= minSize).map((keys) => {
+			const hub = keys.reduce((best, key) => isBiggerHub(graph, key, best) ? key : best);
+			return {
+				keys,
+				hub,
+				name: graph.getNodeAttribute(hub, "name")
+			};
+		}).sort((a, b) => b.keys.length - a.keys.length || a.name.localeCompare(b.name)).map((group, id) => {
+			for (const key of group.keys) clusterOf.set(key, id);
+			return {
+				id,
+				name: group.name,
+				hub: group.hub,
+				size: group.keys.length
+			};
+		}),
+		clusterOf
+	};
+}
+function isBiggerHub(graph, key, than) {
+	const a = graph.getNodeAttributes(key);
+	const b = graph.getNodeAttributes(than);
+	return a.linkedFrom > b.linkedFrom || a.linkedFrom === b.linkedFrom && a.name.localeCompare(b.name) < 0;
+}
+/** mulberry32: a small seeded generator, so Louvain's tie-breaking is repeatable. */
+function seededRandom(seed) {
+	let state = seed >>> 0;
+	return () => {
+		state = state + 1831565813 >>> 0;
+		let t = state;
+		t = Math.imul(t ^ t >>> 15, t | 1);
+		t ^= t + Math.imul(t ^ t >>> 7, t | 61);
+		return ((t ^ t >>> 14) >>> 0) / 4294967296;
+	};
+}
+/**
+* Concepts that carry the links between Clusters, most first.
+*
+* Each line joining two different Clusters gives each of its two ends a share of the link
+* between those Clusters: the whole of it when it is the only such line, a hundredth when there
+* are a hundred. A concept's share is then weighted by how much of its own linking crosses
+* Clusters at all, so the concept sitting between two groups outranks the member at the far
+* end of its one outside line. Linear in the number of lines; exact betweenness centrality,
+* the textbook measure, took 9 to 38 seconds on a real 2,838 document graph and ranked the
+* Hubs again.
+*
+* Journal entries are never ranked: a day touches whatever was on your mind, and that says
+* nothing about how two topics connect.
+*/
+function bridges(graph, { clusters, clusterOf }, limit) {
+	const pairId = (a, b) => a < b ? `${a}:${b}` : `${b}:${a}`;
+	const crossing = /* @__PURE__ */ new Map();
+	graph.forEachEdge((_edge, _line, source, target) => {
+		const a = clusterOf.get(source);
+		const b = clusterOf.get(target);
+		if (a === void 0 || b === void 0 || a === b) return;
+		crossing.set(pairId(a, b), (crossing.get(pairId(a, b)) ?? 0) + 1);
+	});
+	if (crossing.size === 0) return [];
+	const shares = /* @__PURE__ */ new Map();
+	const crossingLines = /* @__PURE__ */ new Map();
+	graph.forEachEdge((_edge, _line, source, target) => {
+		const a = clusterOf.get(source);
+		const b = clusterOf.get(target);
+		if (a === void 0 || b === void 0 || a === b) return;
+		const pair = pairId(a, b);
+		const credit = 1 / (crossing.get(pair) ?? 1);
+		for (const end of [source, target]) {
+			const own = shares.get(end) ?? /* @__PURE__ */ new Map();
+			own.set(pair, (own.get(pair) ?? 0) + credit);
+			shares.set(end, own);
+			crossingLines.set(end, (crossingLines.get(end) ?? 0) + 1);
+		}
+	});
+	const nameOf = (id) => clusters[id]?.name ?? "";
+	const found = [];
+	for (const [key, pairs] of shares) {
+		const attributes = graph.getNodeAttributes(key);
+		if (attributes.kind === "journal") continue;
+		const outside = (crossingLines.get(key) ?? 0) / Math.max(1, graph.degree(key));
+		let total = 0;
+		let bestPair = "";
+		let bestShare = -1;
+		for (const [pair, share] of pairs) {
+			total += share;
+			if (share > bestShare) {
+				bestShare = share;
+				bestPair = pair;
+			}
+		}
+		const own = clusterOf.get(key) ?? -1;
+		const [first, second] = bestPair.split(":").map(Number);
+		const other = first === own ? second : first;
+		found.push({
+			key,
+			name: attributes.name,
+			score: total * outside,
+			between: [nameOf(own), nameOf(other)]
+		});
+	}
+	return found.sort((a, b) => b.score - a.score || a.name.localeCompare(b.name)).slice(0, limit);
+}
+//#endregion
 //#region ../client/src/lib/document/view/minimal-replacement.ts
 /**
 * The smallest single replacement turning `text` into `next`: the shared prefix and suffix
@@ -17862,6 +18361,86 @@ async function backlinks(graph, concept) {
 		}))
 	};
 }
+/**
+* What the whole-graph [[Graph View]] lists beside its picture, for an agent: the same model
+* and the same rules (graph-view/model), over the same index query, so an agent and a person
+* looking at the Graph View see the same Hubs, Clusters and Bridges.
+*/
+async function graphInsights(graph, args = {}) {
+	const limit = Math.max(1, bounded(args.limit, 15, 50));
+	await graph.store.refresh();
+	const model = createGraphModel(await graph.index.linkGraph());
+	const shown = visibleGraph(model, {
+		journals: args.journals ?? true,
+		pageless: args.pageless ?? "mentioned-twice"
+	});
+	const clustered = findClusters(shown);
+	const isolated = isolatedDocuments(model);
+	const byDocuments = (rows) => rows.map((row) => ({
+		concept: row.name,
+		documents: row.count
+	}));
+	const membersOf = /* @__PURE__ */ new Map();
+	for (const [key, id] of clustered.clusterOf) {
+		const facts = model.concepts.get(key);
+		if (facts) membersOf.set(id, [...membersOf.get(id) ?? [], facts]);
+	}
+	return {
+		shown: {
+			concepts: shown.order,
+			lines: shown.size
+		},
+		hubs: byDocuments(hubs(model, limit)),
+		pageless: byDocuments(pagelessByDocuments(model, limit)),
+		isolated: {
+			total: isolated.length,
+			concepts: isolated.slice(0, limit).map((row) => row.name),
+			truncated: isolated.length > limit
+		},
+		clusters: clustered.clusters.slice(0, limit).map((cluster) => ({
+			name: cluster.name,
+			size: cluster.size,
+			members: (membersOf.get(cluster.id) ?? []).sort((a, b) => b.linkedFrom - a.linkedFrom || a.name.localeCompare(b.name)).slice(0, 5).map((member) => member.name)
+		})),
+		bridges: bridges(shown, clustered, limit).map((bridge) => ({
+			concept: bridge.name,
+			joins: bridge.between
+		}))
+	};
+}
+/** The fewest wikilink steps from one concept to another, through every concept, or null when nothing joins them. */
+async function graphPath(graph, args) {
+	await graph.store.refresh();
+	const model = createGraphModel(await graph.index.linkGraph());
+	const resolve = (asked) => {
+		const name = asked.trim() === "today" ? todayISO() : asked.trim();
+		if (name === "") throw new ToolError("invalid_argument", "from and to must not be empty.");
+		const key = conceptKey(name);
+		if (model.concepts.has(key)) return key;
+		const alias = graph.index.allConcepts().find((candidate) => candidate.key === key && candidate.kind === "alias");
+		const page = alias?.canonical === void 0 ? void 0 : conceptKey(alias.canonical);
+		if (page !== void 0 && model.concepts.has(page)) return page;
+		throw new ToolError("not_found", `No concept is named "${asked}". Names are case-insensitive; list_documents and search find one.`);
+	};
+	const from = resolve(args.from);
+	const to = resolve(args.to);
+	const journals = args.journals ?? true;
+	if (!journals) for (const end of [from, to]) {
+		const concept = model.concepts.get(end);
+		if (concept?.kind === "journal") throw new ToolError("invalid_argument", `${concept.name} is a journal entry, and journals: false leaves journal entries out. Ask again with journals left on.`);
+	}
+	const path = shortestPath(visibleGraph(model, {
+		journals,
+		pageless: "all"
+	}), from, to);
+	const nameOf = (key) => model.concepts.get(key)?.name ?? key;
+	return {
+		from: nameOf(from),
+		to: nameOf(to),
+		path: path?.map(nameOf) ?? null,
+		steps: path ? path.length - 1 : null
+	};
+}
 async function tasks(graph, args = {}) {
 	const offset = bounded(args.offset, 0, Number.MAX_SAFE_INTEGER);
 	const limit = bounded(args.limit, 100, 200);
@@ -19460,6 +20039,7 @@ function createMcpServer(graph, info) {
 		"Edit with edit_document (an exact, unique old→new replacement) or append_document - read first, then edit, and never paste a whole page back.",
 		"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.",
+		"graph_insights says what the links show across the whole graph (the most-linked concepts, pages many documents ask for that do not exist yet, pages linked to nothing, groups of related concepts and the concepts bridging them), and graph_path finds how two concepts are connected. Use them to answer questions about the shape of the graph, or to suggest pages to write or link.",
 		"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\".",
@@ -19507,6 +20087,29 @@ function createMcpServer(graph, info) {
 		description: "Every document that links to a concept with [[Concept]], with the linking block or paragraph, and every document scoped by it (a title such as \"[[Concept]] Notes\" is a reference of kind \"title\"). Aliases are pooled: linking an alias counts.",
 		inputSchema: { concept }
 	}, async (args) => run(() => backlinks(graph, args.concept)));
+	const journals = z.boolean().optional().describe("Count journal entries as part of the graph (default true).");
+	server.registerTool("graph_insights", {
+		title: "Graph insights",
+		description: `What the whole graph's links show, as the Graph View lists it. hubs: the concepts linked from the most documents. pageless: concepts many documents mention that have no page yet (pages worth writing). isolated: pages with no wikilinks in or out (pages to connect). clusters: groups of concepts that link to one another more than to the rest, named after their biggest hub, with their best-known members. bridges: concepts carrying the links between two clusters, with the two they join. shown counts the concepts and lines the clusters and bridges were found in. Hubs, pageless and isolated always count every document. At most 50 rows per list (default 15).`,
+		inputSchema: {
+			limit: z.number().int().positive().max(50).optional(),
+			journals,
+			pageless: z.enum([
+				"all",
+				"mentioned-twice",
+				"none"
+			]).optional().describe("Which pageless concepts the clusters and bridges consider: those two or more documents mention (default), all, or none.")
+		}
+	}, async (args) => run(() => graphInsights(graph, args)));
+	server.registerTool("graph_path", {
+		title: "Graph path",
+		description: "The fewest wikilink steps between two concepts, in either direction, as the list of concepts passed through; path is null when nothing joins them. Answers \"how is this connected to that?\".",
+		inputSchema: {
+			from: concept,
+			to: concept,
+			journals
+		}
+	}, async (args) => run(() => graphPath(graph, args)));
 	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 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.`,