prreviewbuddy 0.45.0 → 0.46.0

package/dist/server.js

@@ -1,4 +1,4 @@
-import { $t as recentWorkspaces, A as createPrState, An as STORE_ROOT, At as fail, B as toneOf, C as readEvents, Cn as git, Ct as fillFileUrlTemplate, D as announceJob, Dn as readAgentPreference, Dt as reviewedShaOf, E as telemetryUploadConsent, En as clearAgentPreference, Et as followedBranch, F as markAllRead, Ft as isLiveJob, G as MANAGED_ROOT, Gt as latestKissRun, H as withUsageRecorded, Ht as followedRefName, I as markRead, In as AgentCancelledError, It as phasesFor, Jt as loadWorkspace, K as readMarker, L as pruneNotifications, Ln as AgentUnavailableError, Lt as progressSteps, M as eventName, Mt as loadJob, N as headline, Nt as saveJob, O as branchOf, On as writeAgentPreference, Ot as allJobs, P as listNotifications, Pn as agentFor, Q as readIndexToken, Qt as previousKissResult, R as readNotification, Rt as purposeOf, Sn as isCommitReview, St as remoteHost, T as recordTelemetryUploadConsent, Tn as resolveModel, Tt as checkReview, U as EXPLAIN_SIMPLY_PROMPT, V as unreadCount$1, Vt as isClaimed, W as ReviewBeingDeletedError, Wt as indexReviewGroups, X as compactQueue, Xt as mutateWorkspace, Y as relativeTime$1, _ as agentEnvOf, _n as reviewerDispositions, _t as statedWorkspacePort, a as wasBlocked, an as workspaceStamps, at as spawnServer, c as RefreshUnavailableError, cn as queueAddMany, ct as writeServerRecord, d as refreshPrContext, dn as readQueue, dt as feedbackUrl, en as reviewedCommit, et as clearServerRecord, f as isUnchanged, fn as doneVerb, ft as DEFAULT_WORKSPACE_PORT, gn as questionsOutstanding, gt as resolveWorkspacePort, h as liveUpdateFor, hn as issuesOutstanding, ht as parseWorkspacePort, i as liveJobsFor, in as workspaceRevision, it as serverEntryExists, j as createPrUpdate, jn as AGENT_IDS, jt as isTerminal, k as subjectOf, kt as endedAt, l as mergeUpdateInto, ln as queueRemove, lt as BUILD_VERSION, m as UpdateAlreadyRunningError, mn as isQuestionOutstanding, mt as MIN_WORKSPACE_PORT, n as deleteReview, nt as readServerRecord, o as discardJob, on as dequeueOnComplete, p as askCheckout, pn as isIssueOutstanding, pt as MAX_WORKSPACE_PORT, q as removeWorktree, qt as lineagePosition, r as lineageIds, rn as touchWorkspace, s as FETCH_TIMEOUT_MS, sn as queueAdd, t as deleteLineage, u as updateReview, un as queueStamp, vn as processDiscussion, vt as writePortPreference, w as record, wt as checkCodeFreshness, x as runJob, xt as forgeFor, y as startKissJob, yn as describeAuthorship, yt as claimRequestUrl, z as removeNotification } from "./delete_review-BWMmO81Q.js";
+import { A as createPrState, An as writeAgentPreference, At as allJobs, B as toneOf, Bt as purposeOf, C as readEvents, Ct as forgeFor, D as announceJob, Dn as resolveModel, Dt as checkReview, E as telemetryUploadConsent, Et as checkCodeFreshness, F as markAllRead, Ft as saveJob, G as extractJsonText, H as withUsageRecorded, I as markRead, In as agentFor, J as readMarker, K as ReviewBeingDeletedError, Kt as indexReviewGroups, L as pruneNotifications, Lt as isLiveJob, M as eventName, Mn as STORE_ROOT, Mt as fail, N as headline, Nn as AGENT_IDS, Nt as isTerminal, O as branchOf, On as clearAgentPreference, Ot as followedBranch, P as listNotifications, Pt as loadJob, Q as compactQueue, Qt as mutateWorkspace, R as readNotification, Rn as AgentCancelledError, Rt as phasesFor, T as recordTelemetryUploadConsent, Tn as git, Tt as fillFileUrlTemplate, U as EXPLAIN_SIMPLY_PROMPT, Ut as isClaimed, V as unreadCount$1, W as asString, Wt as followedRefName, Xt as loadWorkspace, Y as removeWorktree, Yt as lineagePosition, Z as relativeTime$1, _ as agentEnvOf, _n as issuesOutstanding, _t as parseWorkspacePort, a as wasBlocked, an as touchWorkspace, bn as processDiscussion, bt as writePortPreference, c as RefreshUnavailableError, cn as dequeueOnComplete, d as refreshPrContext, dn as queueRemove, dt as BUILD_VERSION, en as previousKissResult, et as readIndexToken, f as isUnchanged, fn as queueStamp, gn as isQuestionOutstanding, gt as MIN_WORKSPACE_PORT, h as liveUpdateFor, hn as isIssueOutstanding, ht as MAX_WORKSPACE_PORT, i as liveJobsFor, it as readServerRecord, j as createPrUpdate, jt as endedAt, k as subjectOf, kn as readAgentPreference, kt as reviewedShaOf, l as mergeUpdateInto, ln as queueAdd, m as UpdateAlreadyRunningError, mn as doneVerb, mt as DEFAULT_WORKSPACE_PORT, n as deleteReview, nn as reviewedCommit, nt as clearServerRecord, o as discardJob, on as workspaceRevision, ot as serverEntryExists, p as askCheckout, pn as readQueue, pt as feedbackUrl, q as MANAGED_ROOT, qt as latestKissRun, r as lineageIds, s as FETCH_TIMEOUT_MS, sn as workspaceStamps, st as spawnServer, t as deleteLineage, tn as recentWorkspaces, u as updateReview, un as queueAddMany, ut as writeServerRecord, vn as questionsOutstanding, vt as resolveWorkspacePort, w as record, wn as isCommitReview, wt as remoteHost, x as runJob, xn as describeAuthorship, xt as claimRequestUrl, y as startKissJob, yn as reviewerDispositions, yt as statedWorkspacePort, z as removeNotification, zn as AgentUnavailableError, zt as progressSteps } from "./delete_review-lmVdoybL.js";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { createHash, timingSafeEqual } from "node:crypto";
@@ -1657,7 +1657,7 @@ function renderProvisionalReason(session) {
 function renderOverviewActions(session, options) {
 	const explain = hasExplainedSimply(session) ? `<p class="pr-helper-explain-simply-done">Explained in simple terms. See the Assistant tab.</p>` : `<button type="button" class="pr-helper-explain-simply-button">Explain in simple terms</button>`;
 	if (!options?.diagrams) return explain;
-	return `<div class="pr-helper-overview-actions">${explain}<button type="button" class="pr-helper-diagram-button" data-diagram-request="">Show implementation diagram</button></div>`;
+	return `<div class="pr-helper-overview-actions">${explain}<button type="button" class="pr-helper-map-button" data-view-nav="map">Diagrams</button></div>`;
 }
 function renderOverviewTab(session, iconUrl = "", options) {
 	if (!session) return renderNoReviewState(iconUrl);
@@ -1901,7 +1901,7 @@ function renderGuideSectionCard(section, counts, activeGuidedSectionId, status,
           <button type="button" class="pr-helper-guide-start-cta" data-guide-start="${escapeHtml$1(section.id)}">
             ${isActive ? "Resume guided review →" : isCompleted ? "Review again →" : "Start guided review →"}
           </button>
-          ${options?.diagrams ? `<button type="button" class="pr-helper-diagram-button" data-diagram-request="${escapeHtml$1(section.id)}">Diagram this theme</button>` : ""}
+          ${options?.diagrams ? `<button type="button" class="pr-helper-diagram-button" data-diagram-request="${escapeHtml$1(section.id)}">Generate theme diagram</button>` : ""}
           ${undo}
         </div>
       </div>
@@ -2609,6 +2609,458 @@ function renderDrawnFrom(diagram, reviewedSha) {
 	return `<p class="prb-diagram-stale">Drawn from <code>${escapeHtml$1(diagram.commitSha.slice(0, 7))}</code>, before this review was brought up to date. Regenerate to draw it from the commit the review now describes.</p>`;
 }
 //#endregion
+//#region ../../packages/review-harness/src/domain/change_map/types.ts
+var MAP_ROLES = [
+	"intent",
+	"actor",
+	"concept",
+	"state",
+	"constraint",
+	"risk",
+	"outcome"
+];
+var MAP_STAGES = [
+	"Intent",
+	"Behaviour",
+	"Shared state",
+	"Risks & constraints",
+	"Outcome"
+];
+//#endregion
+//#region ../../packages/review-harness/src/domain/change_map/parse.ts
+/**
+* A model's answer, turned into a change map.
+*
+* Tolerant in the same way `kiss/parse.ts` is. Fields go missing, arrive as the wrong type or
+* run long, and all of that degrades to something honest. What it will not do is invent a map: a
+* JSON object with no nodes in it throws, because an empty picture presented as "this change has no
+* ideas in it" is a confident wrong claim.
+*
+* Only shape is settled here. Whether the edges point at real nodes, whether a theme id is one this
+* review has, and whether what is left is still worth drawing are `validate.ts`'s questions, because
+* they need the review to answer.
+*/
+/**
+* Lengths past which text stops fitting the medium.
+*
+* A node is read at a glance, beside eleven others. The prompt asks for this brevity; these are
+* what happens when it is ignored, and they cut at a word rather than mid-word.
+*/
+var LIMITS = {
+	mapTitle: 100,
+	intent: 320,
+	title: 80,
+	body: 220,
+	why: 160,
+	anchor: 80,
+	label: 48,
+	note: 200
+};
+/** Where a role sits when the model forgot to say. The usual place, not the only one. */
+var STAGE_OF_ROLE = {
+	intent: 0,
+	concept: 1,
+	actor: 2,
+	state: 2,
+	constraint: 3,
+	risk: 3,
+	outcome: 4
+};
+function parseChangeMap(raw) {
+	let parsed;
+	try {
+		parsed = JSON.parse(extractJsonText(raw));
+	} catch {
+		throw new Error("Could not parse the change map as JSON.");
+	}
+	return normalizeChangeMap(parsed);
+}
+/**
+* Any value, made into a change map or refused.
+*
+* Exported because a stored map is read back through it too. A review file is JSON on disk that a
+* previous version wrote, or someone edited, and the page drawing it deserves the same guarantees
+* as the page drawing a map that has just arrived. Running it twice changes nothing.
+*/
+function normalizeChangeMap(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("The change map was not a JSON object.");
+	const obj = value;
+	if (!Array.isArray(obj.nodes) || obj.nodes.length === 0) throw new Error("The change map had no nodes. This usually means the model ignored the requested shape.");
+	const { nodes, ids } = normalizeNodes(obj.nodes);
+	return {
+		schemaVersion: 1,
+		title: clip(asString(obj.title).trim(), LIMITS.mapTitle) || "Change map",
+		intent: register(obj.intent, LIMITS.intent) ?? {
+			simple: "",
+			technical: ""
+		},
+		nodes,
+		edges: normalizeEdges(obj.edges, ids)
+	};
+}
+/**
+* Nodes, with ids made safe and unique.
+*
+* The model's own ids are what its edges refer to, so they are remembered alongside the safe ones;
+* `ids` maps one to the other. A second node claiming an id already taken is dropped rather than
+* renamed: the edges naming that id cannot say which of the two they meant.
+*/
+function normalizeNodes(value) {
+	const ids = /* @__PURE__ */ new Map();
+	const taken = /* @__PURE__ */ new Set();
+	const nodes = [];
+	for (const item of value) {
+		if (typeof item !== "object" || item === null) continue;
+		const entry = item;
+		const title = register(entry.title, LIMITS.title);
+		if (!title) continue;
+		const given = asString(entry.id).trim() || title.technical;
+		if (ids.has(given)) continue;
+		const id = uniqueId(slug(given) || `n${nodes.length + 1}`, taken);
+		ids.set(given, id);
+		taken.add(id);
+		const role = MAP_ROLES.includes(entry.role) ? entry.role : "concept";
+		const why = register(entry.why, LIMITS.why);
+		const anchor = clip(asString(entry.anchor).trim(), LIMITS.anchor);
+		const sectionId = asString(entry.sectionId).trim();
+		nodes.push({
+			id,
+			role,
+			stage: stageOf(entry.stage, role),
+			weight: entry.weight === "primary" ? "primary" : "supporting",
+			title,
+			body: register(entry.body, LIMITS.body) ?? {
+				simple: "",
+				technical: ""
+			},
+			...why ? { why } : {},
+			...anchor ? { anchor } : {},
+			...sectionId ? { sectionId } : {}
+		});
+	}
+	return {
+		nodes,
+		ids
+	};
+}
+function normalizeEdges(value, ids) {
+	if (!Array.isArray(value)) return [];
+	const edges = [];
+	for (const item of value) {
+		if (typeof item !== "object" || item === null) continue;
+		const entry = item;
+		const label = register(entry.label, LIMITS.label);
+		const from = ids.get(asString(entry.from).trim()) ?? asString(entry.from).trim();
+		const to = ids.get(asString(entry.to).trim()) ?? asString(entry.to).trim();
+		if (!label || !from || !to) continue;
+		const note = register(entry.note, LIMITS.note);
+		edges.push({
+			from,
+			to,
+			label,
+			...note ? { note } : {}
+		});
+	}
+	return edges;
+}
+/**
+* Both registers, or null when there is nothing in either.
+*
+* A missing register borrows the other rather than rendering blank: the reviewer who chose Simple
+* and gets the technical sentence has lost some ease, where one who gets nothing has lost the node.
+* A bare string is taken as both, which is what a model means when it forgets the shape.
+*/
+function register(value, limit) {
+	if (typeof value === "string") {
+		const text = clip(value.trim(), limit);
+		return text ? {
+			simple: text,
+			technical: text
+		} : null;
+	}
+	if (typeof value !== "object" || value === null) return null;
+	const entry = value;
+	const simple = clip(asString(entry.simple).trim(), limit);
+	const technical = clip(asString(entry.technical).trim(), limit);
+	if (!simple && !technical) return null;
+	return {
+		simple: simple || technical,
+		technical: technical || simple
+	};
+}
+function stageOf(value, role) {
+	return typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 4 ? value : STAGE_OF_ROLE[role];
+}
+/** Short, lowercase, and safe in an attribute, a selector and a URL. */
+function slug(value) {
+	return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40);
+}
+function uniqueId(base, taken) {
+	if (!taken.has(base)) return base;
+	let n = 2;
+	while (taken.has(`${base}-${n}`)) n += 1;
+	return `${base}-${n}`;
+}
+/** Cut at the last word boundary under the limit, and say that something was cut. */
+function clip(text, limit) {
+	if (text.length <= limit) return text;
+	const cut = text.slice(0, limit - 1);
+	const space = cut.lastIndexOf(" ");
+	return `${(space > limit / 2 ? cut.slice(0, space) : cut).trimEnd()}…`;
+}
+//#endregion
+//#region ../../packages/review-harness/src/domain/change_map/validate.ts
+/**
+* Checking a change map against the review it claims to describe, and against what can be drawn.
+*
+* The enforcement boundary, in the spirit of `kiss/validate.ts`: what the model got slightly wrong
+* is repaired and counted, and what cannot be repaired is refused. An edge to a node that does not
+* exist is dropped rather than drawn into nowhere. A theme id this review never had is withdrawn,
+* because "Open in Review Path" on it would open nothing. A map with more than a reader can hold is
+* cut back in reading order, keeping the ideas the model said matter most.
+*
+* What it refuses is a map with nothing left to connect. Two ideas and one relationship is the
+* least that is a map rather than a list, and a list is what the written guide already is.
+*/
+/** A map that could not be used. Carries the reply, as `KissRejected` does, for the same reason. */
+var ChangeMapRejected = class extends Error {
+	answer;
+	constructor(message, answer) {
+		super(message);
+		this.answer = answer;
+	}
+};
+function validateChangeMap(raw, sectionIds) {
+	try {
+		return checkChangeMap(parseChangeMap(raw), sectionIds);
+	} catch (error) {
+		throw new ChangeMapRejected(error instanceof Error ? error.message : String(error), raw);
+	}
+}
+/**
+* A stored map, or null if it is no longer one this page can draw.
+*
+* The same rules a fresh map passes, applied to what is on disk. A review file written by an older
+* version, edited by hand or cut short is a page that shows the ordinary empty state and a way to
+* generate a new map, never a page that throws.
+*/
+function readStoredChangeMap(value, sectionIds) {
+	try {
+		return checkChangeMap(normalizeChangeMap(value), sectionIds).map;
+	} catch {
+		return null;
+	}
+}
+function checkChangeMap(map, sectionIds) {
+	const audit = {
+		droppedNodes: 0,
+		droppedEdges: 0,
+		withdrawnSections: 0,
+		demotedPrimaries: 0
+	};
+	const nodes = demoteExtraPrimaries(capNodes(map.nodes, audit).map((node) => withKnownSection(node, sectionIds, audit)), audit);
+	const known = new Set(nodes.map((node) => node.id));
+	const seen = /* @__PURE__ */ new Set();
+	const edges = [];
+	for (const edge of map.edges) {
+		const key = `${edge.from}\u0000${edge.to}`;
+		if (!known.has(edge.from) || !known.has(edge.to) || edge.from === edge.to || seen.has(key) || edges.length >= 16) {
+			audit.droppedEdges += 1;
+			continue;
+		}
+		seen.add(key);
+		edges.push(edge);
+	}
+	if (nodes.length < 2 || edges.length === 0) throw new Error("The change map had too little in it to draw: it needs at least two ideas and one relationship.");
+	return {
+		map: {
+			...map,
+			nodes: inReadingOrder(nodes),
+			edges
+		},
+		audit
+	};
+}
+/**
+* Down to `MAX_NODES`, keeping the primaries and then the earliest of the rest.
+*
+* The model lists nodes in reading order, so "earliest" is "the part of the story it reached
+* first". Cutting the tail loses detail at the end; cutting a primary would lose the point.
+*/
+function capNodes(nodes, audit) {
+	if (nodes.length <= 12) return nodes;
+	const primaries = nodes.filter((node) => node.weight === "primary").slice(0, 3);
+	const rest = nodes.filter((node) => !primaries.includes(node)).slice(0, 12 - primaries.length);
+	const kept = /* @__PURE__ */ new Set([...primaries, ...rest]);
+	audit.droppedNodes += nodes.length - kept.size;
+	return nodes.filter((node) => kept.has(node));
+}
+function withKnownSection(node, sectionIds, audit) {
+	if (node.sectionId === void 0 || sectionIds.includes(node.sectionId)) return node;
+	audit.withdrawnSections += 1;
+	const { sectionId: _withdrawn, ...rest } = node;
+	return rest;
+}
+/** Everything is not the point. Past three, "primary" has stopped meaning anything. */
+function demoteExtraPrimaries(nodes, audit) {
+	let primaries = 0;
+	return nodes.map((node) => {
+		if (node.weight !== "primary") return node;
+		primaries += 1;
+		if (primaries <= 3) return node;
+		audit.demotedPrimaries += 1;
+		return {
+			...node,
+			weight: "supporting"
+		};
+	});
+}
+/** By stage, keeping the model's own order within one. A stable sort does exactly that. */
+function inReadingOrder(nodes) {
+	return [...nodes].sort((a, b) => a.stage - b.stage);
+}
+//#endregion
+//#region ../../packages/review-harness/src/workspace/change_map_view.ts
+/** The body of the map pane: the map, or the way to get one. The pane's frame is `page.ts`'s. */
+function renderChangeMapBody(input) {
+	const { stored, sections, reviewedSha, register } = input;
+	const map = stored ? readStoredChangeMap(stored, sections.map((section) => section.id)) : null;
+	const stale = Boolean(map && stored?.commitSha && reviewedSha && stored.commitSha !== reviewedSha);
+	if (!map || !stored || stale) return renderEmpty(stale);
+	const titles = new Map(sections.map((section) => [section.id, section.title]));
+	return `<div class="prb-map" data-change-map data-register="${register}">
+    <header class="prb-map-head">
+      <div class="prb-map-heading">
+        <h4 class="prb-map-title">${escapeHtml$1(map.title)}</h4>
+        ${map.intent.simple || map.intent.technical ? `<p class="prb-map-intent">${both(map.intent)}</p>` : ""}
+      </div>
+      <div class="prb-map-tools">
+        ${renderRegisterSwitch(register)}
+        <button type="button" class="prb-diagram-redraw" data-diagram-request="" data-diagram-kind="map">Regenerate</button>
+      </div>
+    </header>
+    <p class="prb-map-hint">Read from the goal to the outcome. Select an idea to see what it connects to.</p>
+    ${renderBoard(map, titles)}
+    ${renderList(map)}
+  </div>`;
+}
+function renderEmpty(stale) {
+	return `<div class="prb-map-empty" data-change-map-empty>
+    ${stale ? "<p class=\"prb-map-stale\">The review has moved on since the last map was drawn.</p>" : ""}
+    <h4 class="prb-map-empty-title">See the change as a map</h4>
+    <p>See how the main ideas in this change connect, what depends on what, and where the important risks are. Each idea links back to its theme in the Review Path.</p>
+    <p class="prb-map-empty-note">Buddy AI builds it from this review, in plain words and technical ones. It takes a minute or two.</p>
+    <button type="button" class="prb-map-generate" data-diagram-request="" data-diagram-kind="map">Generate change map</button>
+  </div>`;
+}
+/** Two pressed-state buttons rather than a checkbox: both choices are named, and neither is "off". */
+function renderRegisterSwitch(register) {
+	const option = (value, label) => `<button type="button" class="prb-map-register" data-map-register-option="${value}" aria-pressed="${register === value}">${label}</button>`;
+	return `<div class="prb-map-registers" role="group" aria-label="Wording">${option("simple", "Simple")}${option("technical", "Technical")}</div>`;
+}
+/**
+* The board: one column per stage the map uses, in reading order, and the lines between them.
+*
+* Only the stages that have something in them get a column. A map of a small change with no shared
+* state should not carry an empty "Shared state" column that asks the reviewer to wonder what is
+* missing from it.
+*/
+function renderBoard(map, titles) {
+	const stages = [...new Set(map.nodes.map((node) => node.stage))].sort((a, b) => a - b);
+	const columns = stages.map((stage) => `<div class="prb-map-stage" data-map-stage="${stage}">
+        <h5 class="prb-map-stage-title">${escapeHtml$1(MAP_STAGES[stage] ?? "")}</h5>
+        ${map.nodes.filter((node) => node.stage === stage).sort((a, b) => Number(b.weight === "primary") - Number(a.weight === "primary")).map((node) => renderNode(node, titles, map)).join("")}
+      </div>`).join("");
+	const labels = map.edges.map((edge, index) => renderEdgeLabel(edge, index)).join("");
+	return `<div class="prb-map-board" data-map-board style="--prb-map-stages: ${stages.length}">
+    <svg class="prb-map-edges" data-map-edges aria-hidden="true" focusable="false"></svg>
+    ${columns}
+    <div class="prb-map-labels" aria-hidden="true">${labels}</div>
+  </div>`;
+}
+/** The part a node plays, as a word. Never colour alone. */
+var ROLE_LABEL = {
+	intent: "Goal",
+	actor: "Actor",
+	concept: "Idea",
+	state: "Shared state",
+	constraint: "Rule",
+	risk: "Risk",
+	outcome: "Outcome"
+};
+function renderNode(node, titles, map) {
+	const id = escapeHtml$1(node.id);
+	const theme = node.sectionId ? titles.get(node.sectionId) : void 0;
+	const names = new Map(map.nodes.map((other) => [other.id, other.title]));
+	const inline = map.edges.map((edge, index) => ({
+		edge,
+		index
+	})).filter(({ edge }) => edge.from === node.id && names.has(edge.to)).map(({ edge, index }) => `<li data-inline-edge="${index}" hidden><em>${both(edge.label)}</em> <span aria-hidden="true">→</span> ${both(names.get(edge.to))}</li>`).join("");
+	return `<article class="prb-map-node" data-map-node="${id}" data-role="${node.role}" data-weight="${node.weight}" tabindex="0" aria-labelledby="prb-map-node-${id}">
+    <p class="prb-map-role">${ROLE_LABEL[node.role]}${node.weight === "primary" ? "<span class=\"prb-map-core\"> · Core idea</span>" : ""}</p>
+    <h5 class="prb-map-node-title" id="prb-map-node-${id}">${both(node.title)}</h5>
+    ${node.body.simple || node.body.technical ? `<p class="prb-map-node-body">${both(node.body)}</p>` : ""}
+    ${node.why ? `<p class="prb-map-why"><span class="prb-map-why-lead">Why it matters:</span> ${both(node.why)}</p>` : ""}
+    ${node.anchor ? `<code class="prb-map-anchor">${escapeHtml$1(node.anchor)}</code>` : ""}
+    ${inline ? `<ul class="prb-map-inline" aria-hidden="true">${inline}</ul>` : ""}
+    ${node.sectionId && theme ? `<button type="button" class="prb-map-goto" data-goto-section="${escapeHtml$1(node.sectionId)}" aria-label="Open ${escapeHtml$1(theme)} in the Review Path">Review Path: ${escapeHtml$1(theme)} <span aria-hidden="true">→</span></button>` : ""}
+  </article>`;
+}
+/** Placed by the client, at the middle of its line. Written here so its words are escaped here. */
+function renderEdgeLabel(edge, index) {
+	return `<span class="prb-map-label" data-map-edge="${index}" data-from="${escapeHtml$1(edge.from)}" data-to="${escapeHtml$1(edge.to)}">${both(edge.label)}</span>`;
+}
+/**
+* The same relationships as sentences.
+*
+* For a screen reader, which cannot follow a line; for a narrow pane, where the lines are hardest to
+* follow; and for the case where laying the lines out failed, when this is the map.
+*/
+function renderList(map) {
+	const names = new Map(map.nodes.map((node) => [node.id, node.title]));
+	return `<details class="prb-map-list">
+    <summary>Read as a list</summary>
+    <ol>${map.edges.map((edge) => {
+		const from = names.get(edge.from);
+		const to = names.get(edge.to);
+		if (!from || !to) return "";
+		return `<li><strong>${both(from)}</strong> <em>${both(edge.label)}</em> <strong>${both(to)}</strong>${edge.note ? `<span class="prb-map-note"> — ${both(edge.note)}</span>` : ""}</li>`;
+	}).join("")}</ol>
+  </details>`;
+}
+/**
+* Both registers, side by side in the markup; the board's `data-register` shows one.
+*
+* Backtick spans become code, after escaping, as in every other place model prose is shown: the
+* technical register names identifiers, and a literal pair of ticks around one reads as noise.
+*/
+function both(text) {
+	if (text.simple === text.technical) return renderInlineText(text.simple);
+	return `<span data-reg="simple">${renderInlineText(text.simple)}</span><span data-reg="technical">${renderInlineText(text.technical)}</span>`;
+}
+//#endregion
+//#region ../../packages/review-harness/src/workspace/diagram_modes.ts
+var MODES = [{
+	mode: "map",
+	title: "Change map",
+	subtitle: "Understand this change"
+}, {
+	mode: "diagram",
+	title: "Implementation",
+	subtitle: "How the code does it"
+}];
+/**
+* `ready` says which pictures exist, shown as a small check on the tab, so from either tab the
+* reviewer can tell whether the other one is already there or would cost a run. Always in the
+* markup and hidden when not ready, so the client can flip it when a drawing lands.
+*/
+function renderDiagramModes(selected, ready) {
+	return `<div class="prb-diagram-modes" role="tablist" aria-label="Kind of diagram">${MODES.map(({ mode, title, subtitle }) => `<button type="button" role="tab" class="prb-diagram-mode" data-view-nav="${mode}" data-diagram-mode="${mode}" aria-selected="${mode === selected}" tabindex="${mode === selected ? 0 : -1}"${ready[mode] ? " data-ready" : ""}>
+        <span class="prb-diagram-mode-title">${title}<span class="prb-diagram-mode-ready" data-mode-ready${ready[mode] ? "" : " hidden"}><span aria-hidden="true">✓</span><span class="prb-visually-hidden">, generated</span></span></span>
+        <span class="prb-diagram-mode-subtitle">${subtitle}</span>
+      </button>`).join("")}</div>`;
+}
+//#endregion
 //#region ../../packages/review-harness/src/workspace/file_links.ts
 /**
 * Where a file lives on the pull request, when there is one.
@@ -2857,7 +3309,7 @@ function renderPrContextView(view, attribution, refresh, conversation) {
 	const { pullRequest, discussion } = view.prContext;
 	const { processed } = view;
 	const buckets = BUCKETS.map((bucket) => renderBucket(bucket.title, bucket.note, processed[bucket.key])).join("");
-	return `<h3 class="prb-doc-title">PR context</h3>
+	return `${renderDocHead("PR context", renderFocusToggle("prcontext", "PR context"))}
 ${renderProvenance$1(pullRequest, discussion.fetchedAt, processed)}
 ${renderRefresh(refresh)}
 ${renderAttribution(attribution, processed)}
@@ -2925,7 +3377,7 @@ function renderAttribution(attribution, processed) {
 */
 function renderNothingConnected(conversation) {
 	const reason = conversation?.kind === "no-request" ? "This branch had no pull request open when the review was made, so there was no discussion to bring in." : conversation && conversation.kind !== "attached" ? conversationNote$1(conversation) : "";
-	return `<h3 class="prb-doc-title">PR context</h3>
+	return `${renderDocHead("PR context", renderFocusToggle("prcontext", "PR context"))}
 <p class="prb-pr-empty">
   No pull request discussion was brought into this review, so none of the findings have been
   checked against what other reviewers have already said.
@@ -3058,6 +3510,9 @@ function verdictLabel(verdict) {
 * difference between "the analysis had nothing to say" and "the analysis did not run" should be
 * available to a test as a fact rather than as a substring of prose.
 */
+/** Both KISS panes can take the whole review page, in every state they are drawn in. */
+var KISS_TOGGLE = renderFocusToggle("kiss", "KISS review");
+var RECS_HEAD = renderDocHead("Recommendations", renderFocusToggle("kissrecs", "Recommendations"));
 /**
 * What each payoff level is called where a reader can see it.
 *
@@ -3128,7 +3583,7 @@ function renderKissSummary(view) {
 	if (!run) return renderKissEmpty(view.canRun);
 	if (run.status === "generating") return renderRunning(run, view.job ?? null);
 	if (run.status === "failed" || !run.result) return renderFailed(run, view);
-	return `${renderDocHead("KISS review", renderAnalysisDetails(provenanceFacts(run)))}
+	return `${renderDocHead("KISS review", `${renderAnalysisDetails(provenanceFacts(run))}${KISS_TOGGLE}`)}
 <div class="prb-kiss-fresh-region" data-kiss-fresh-region data-reviewed-sha="${escapeHtml$1(run.reviewedSha)}"${view.freshness ? ` data-freshness="${escapeHtml$1(JSON.stringify(view.freshness))}"` : ""}${view.dismissedFreshnessSha ? ` data-dismissed-sha="${escapeHtml$1(view.dismissedFreshnessSha)}"` : ""}>${renderKissFreshness(run.reviewedSha, view.freshness ?? null, {
 		dismissedSha: view.dismissedFreshnessSha,
 		actions: view.canRun
@@ -3177,14 +3632,14 @@ function renderKissFreshness(reviewedSha, freshness, options = {}) {
 function renderKissRecommendations(view) {
 	const presented = presentedKissRun(view);
 	const result = presented?.result;
-	if (!result) return `<h3 class="prb-doc-title">Recommendations</h3>${renderNoRunYet(view)}`;
+	if (!result) return `${RECS_HEAD}${renderNoRunYet(view)}`;
 	const earlier = earlierNote(view, presented);
-	if (result.recommendations.length === 0) return `<h3 class="prb-doc-title">Recommendations</h3>${earlier}
+	if (result.recommendations.length === 0) return `${RECS_HEAD}${earlier}
     <div class="prb-kiss-outcome" data-review-outcome="empty">
       <h4 class="prb-kiss-outcome-title">Nothing to simplify</h4>
       <p class="prb-kiss-outcome-body">The analysis completed and did not identify a materially simpler way to meet these requirements.</p>
     </div>`;
-	return `<h3 class="prb-doc-title">Recommendations</h3>${earlier}
+	return `${RECS_HEAD}${earlier}
 ${result.recommendations.map((recommendation) => renderRecommendation(recommendation)).join("")}`;
 }
 /**
@@ -3212,7 +3667,7 @@ function earlierNote(view, presented) {
 * else's code for the person who wrote it.
 */
 function renderKissEmpty(canRun) {
-	return `${renderDocHead("KISS review")}
+	return `${renderDocHead("KISS review", KISS_TOGGLE)}
 <p class="prb-kiss-lede">${escapeHtml$1(KISS_DESCRIPTION)}</p>
 <p class="prb-kiss-note">KISS looks at whether the complexity here is justified. It does not replace the review beside it, which is where correctness and risk are answered.</p>
 ${renderRunControl(canRun, "Run KISS review")}`;
@@ -3264,7 +3719,7 @@ function renderRunning(run, job) {
 	const phase = job?.phase ?? "analysing";
 	const copy = phaseSentence(job) || "Running KISS review. This takes about as long as a review.";
 	const progress = job?.progress ? ` <span class="prb-job-progress">${escapeHtml$1(job.progress)}</span>` : "";
-	return `${renderDocHead("KISS review")}
+	return `${renderDocHead("KISS review", KISS_TOGGLE)}
 <div class="prb-kiss-status" data-kiss-phase="${escapeHtml$1(phase)}" role="status" aria-live="polite">
   <p><span class="prb-spinner" aria-hidden="true"></span> ${escapeHtml$1(copy)}${progress}</p>
   <p class="prb-kiss-status-note">Started ${escapeHtml$1(relativeTime$1(run.startedAt))}. The review beside this one is unaffected and can be read while it runs.</p>
@@ -3278,7 +3733,7 @@ function renderRunning(run, job) {
 */
 function renderFailed(run, view) {
 	const standing = view.previous ?? null;
-	return `${renderDocHead("KISS review")}
+	return `${renderDocHead("KISS review", KISS_TOGGLE)}
 <div class="prb-kiss-outcome" data-review-outcome="failed">
   <h4 class="prb-kiss-outcome-title">KISS review could not be completed</h4>
   <p class="prb-kiss-outcome-body">${escapeHtml$1(run.error ?? "The analysis did not finish.")}</p>
@@ -4048,11 +4503,12 @@ function renderAvailable(job, fileCount) {
 * with the broken phase marked, so the answer is which step failed rather than merely that
 * something did.
 */
+var PROGRESS_TOGGLE = renderFocusToggle("progress", "Review progress");
 function renderProgressView(job, fileCount) {
-	if (job.phase === "failed") return `<h3 class="prb-doc-title">Review stopped</h3>
+	if (job.phase === "failed") return `${renderDocHead("Review stopped", PROGRESS_TOGGLE)}
     ${renderSteps(job)}
     <div class="prb-progress-failure">${renderFailureBody(job, { lead: false })}</div>`;
-	return `<h3 class="prb-doc-title">Review in progress</h3>
+	return `${renderDocHead("Review in progress", PROGRESS_TOGGLE)}
     <p class="prb-progress-lead">Building the context needed to review this change.</p>
     ${renderSteps(job)}
     ${renderAvailable(job, fileCount)}
@@ -4285,17 +4741,42 @@ function renderFilesView(view, sections) {
         ${renderFiles(view, sections)}
       </section>`;
 }
+/**
+* What the implementation tab says before anything has been drawn on it.
+*
+* Hidden by the stylesheet the moment a card is in the pane, so the client can add the first
+* drawing without having to remember to take this away.
+*/
+function renderImplementationEmpty() {
+	return `<div class="prb-map-empty prb-diagram-empty" data-diagram-empty>
+    <h4 class="prb-map-empty-title">Trace how the code does it</h4>
+    <p>Which parts of the change call which, and in what order. Draw the whole change here, or one theme from its Review Path card.</p>
+    <button type="button" class="prb-map-generate" data-diagram-request="">Generate implementation diagram</button>
+  </div>`;
+}
 /** The standard review's panes, drawn only where there is a standard result to draw them from. */
 function renderStandardViews(view, sections) {
 	const { session } = view;
 	const result = session.result;
-	return `<section class="prb-view" data-view="overview">${renderDocHead("Review overview", renderAnalysisDetails(analysisDetailItems(session)))}${renderOverviewTab(session, "", {
+	return `<section class="prb-view" data-view="overview">${renderDocHead("Review overview", `${renderAnalysisDetails(analysisDetailItems(session))}${renderFocusToggle("overview", "Overview")}`)}${renderOverviewTab(session, "", {
 		diagrams: true,
 		detailsInHeader: true
 	})}</section>
       <section class="prb-view" data-view="guide" hidden>${renderWorkspaceGuide(session)}</section>
-      <section class="prb-view" data-view="diagram" hidden data-diagram-pane${view.pendingDiagram ? ` data-diagram-running="${escapeHtml$1(view.pendingDiagram.sectionId ?? "")}"` : ""}>
-        <h3 class="prb-doc-title">Diagrams</h3>
+      <section class="prb-view" data-view="map" hidden data-map-pane data-map-register="${view.changeMapRegister ?? "simple"}"${view.pendingDiagram?.drawing === "map" ? " data-map-running" : ""}>
+        ${renderDocHead("Diagrams", renderFocusToggle("map", "Change map"))}
+        ${renderDiagramModes("map", diagramsReady(view))}
+        <div class="prb-map-body" data-map-body>${renderChangeMapBody({
+		stored: view.changeMap,
+		sections,
+		reviewedSha: view.reviewedSha ?? null,
+		register: view.changeMapRegister ?? "simple"
+	})}</div>
+      </section>
+      <section class="prb-view" data-view="diagram" hidden data-diagram-pane${view.pendingDiagram && view.pendingDiagram.drawing !== "map" ? ` data-diagram-running="${escapeHtml$1(view.pendingDiagram.sectionId ?? "")}"` : ""}>
+        ${renderDocHead("Diagrams", renderFocusToggle("diagram", "Implementation diagrams"))}
+        ${renderDiagramModes("diagram", diagramsReady(view))}
+        ${renderImplementationEmpty()}
         ${renderDiagrams(view.diagrams ?? [], sections, view.reviewedSha ?? null)}
       </section>
       <section class="prb-view" data-view="issues" hidden>
@@ -4613,7 +5094,7 @@ function renderRail(view, sections, stale = false) {
     <div class="prb-rail-path" id="prb-rail-path">
       ${themes || "<p class=\"prb-rail-heading\">No themes</p>"}
     </div>
-    ${(view.diagrams?.length ?? 0) > 0 ? railLink("diagram", "diagrams", "Diagrams", diagramsBadge(view.diagrams?.length ?? 0)) : ""}
+    ${railLink("map", "diagrams", "Diagrams", diagramsBadge(diagramCount(view)), void 0, "diagram")}
     ${railLink("issues", "issues", "Issues", findingsBadge(issuesOutstanding(issues, dispositions)))}
     ${railLink("questions", "questions", "Questions", remainingBadge(questionsOutstanding(questions, answered), "question", "answered"))}
     ${railLink("files", "files", "Files", totalBadge(view.changeSet.data.files.length, "files"))}
@@ -4721,7 +5202,24 @@ function recommendationsBadge(count) {
 	};
 }
 /** Drawings are facts too, and the label is a sentence, so it has to be a sentence about one. */
+/** The map and the implementation diagrams together: everything behind the one rail item. */
+function diagramCount(view) {
+	return (mapShown(view) ? 1 : 0) + (view.diagrams?.length ?? 0);
+}
+/** Which of the two tabs has something on it, for the check each tab carries. */
+function diagramsReady(view) {
+	return {
+		map: mapShown(view),
+		diagram: (view.diagrams?.length ?? 0) > 0
+	};
+}
+/** A map from a commit the review no longer describes is not shown, so it is neither counted nor ready. */
+function mapShown(view) {
+	const drawnFrom = view.changeMap?.commitSha;
+	return Boolean(view.changeMap) && !(drawnFrom && view.reviewedSha && drawnFrom !== view.reviewedSha);
+}
 function diagramsBadge(count) {
+	if (count === 0) return null;
 	return {
 		text: String(count),
 		label: count === 1 ? "1 diagram" : `${count} diagrams`
@@ -4797,8 +5295,8 @@ function renderBadge(badge) {
 	return `<span class="prb-rail-count${badge.done ? " prb-rail-count-done" : ""}" aria-label="${escapeHtml$1(badge.label)}">${escapeHtml$1(badge.text)}</span>`;
 }
 /** A null badge renders nothing, for the case where zero would be a claim rather than a total. */
-function railLink(view, icon, label, badge, note) {
-	return `<button type="button" class="prb-rail-item prb-rail-link" data-view-nav="${view}"${note ? ` title="${escapeHtml$1(note)}"` : ""}>
+function railLink(view, icon, label, badge, note, alsoCurrentOn) {
+	return `<button type="button" class="prb-rail-item prb-rail-link" data-view-nav="${view}"${alsoCurrentOn ? ` data-view-also="${alsoCurrentOn}"` : ""}${note ? ` title="${escapeHtml$1(note)}"` : ""}>
     ${railIcon(icon)}
     <span class="prb-rail-label"><span class="prb-rail-title">${escapeHtml$1(label)}</span></span>
     ${renderBadge(badge)}
@@ -7338,7 +7836,7 @@ async function askAboutChange(workspace, question, sectionId, signal) {
 	try {
 		return extractAnswer(await withUsageRecorded(workspace.id, "ask", env, (onUsage) => agentFor(env).run({
 			capability: "read-code",
-			prompt: buildPrompt$1(workspace, question, sectionId, cwd),
+			prompt: buildPrompt$2(workspace, question, sectionId, cwd),
 			cwd,
 			originRepoPath: workspace.repoPath,
 			env,
@@ -7397,7 +7895,7 @@ function extractAnswer(raw) {
 * where X is in another theme, and a prompt that had quietly dropped X would answer confidently
 * and wrongly.
 */
-function buildPrompt$1(workspace, question, sectionId, cwd) {
+function buildPrompt$2(workspace, question, sectionId, cwd) {
 	const section = workspace.session.result?.sections.find((s) => s.id === sectionId);
 	const recent = workspace.transcript.slice(-4);
 	return [
@@ -7449,6 +7947,7 @@ function beginRun(workspaceId, kind, detail, now = Date.now()) {
 		kind,
 		question: detail.question ?? null,
 		sectionId: detail.sectionId,
+		...detail.drawing ? { drawing: detail.drawing } : {},
 		startedAt: now,
 		signal: controller.signal,
 		state: "running",
@@ -7464,6 +7963,7 @@ function reportRun(workspaceId, kind) {
 	return {
 		question: run.question,
 		sectionId: run.sectionId,
+		...run.drawing ? { drawing: run.drawing } : {},
 		startedAt: run.startedAt
 	};
 }
@@ -7562,7 +8062,7 @@ async function drawDiagram(workspace, sectionId, signal) {
 	try {
 		raw = await withUsageRecorded(workspace.id, "diagram", env, (onUsage) => agentFor(env).run({
 			capability: "read-code",
-			prompt: buildPrompt(workspace, sectionId, cwd),
+			prompt: buildPrompt$1(workspace, sectionId, cwd),
 			cwd,
 			originRepoPath: workspace.repoPath,
 			env,
@@ -7618,7 +8118,7 @@ function extractDiagram(raw) {
 * show what it calls into, and a prompt that had quietly dropped the rest would draw a component
 * with no edges leaving it and present that as the shape of the code.
 */
-function buildPrompt(workspace, sectionId, cwd) {
+function buildPrompt$1(workspace, sectionId, cwd) {
 	const section = workspace.session.result?.sections.find((s) => s.id === sectionId);
 	return [
 		SYSTEM_PROMPT,
@@ -7634,6 +8134,183 @@ function buildPrompt(workspace, sectionId, cwd) {
 		section ? `DRAW: the "${section.title}" theme of this change. Centre the diagram on it, and show what it calls into and what calls it where that is needed to make sense of it.` : "DRAW: this change as a whole, at the level a reviewer needs to understand what it does."
 	].join("\n");
 }
+//#endregion
+//#region ../../packages/review-harness/src/domain/change_map/prompt.ts
+/**
+* What a change map is asked to be.
+*
+* Not the implementation diagram made smaller. That one asks "how does the code do this?" and is
+* right to name functions; this one asks "what is this change about, and why does each part matter
+* to the next?", and a function is a node here only when it is the handle a reader needs to find
+* the idea. The two prompts are separate because a single one asked to be both at once produces a
+* call graph with friendlier labels, which is the failure this feature exists to fix.
+*
+* The map is built from the review rather than beside it. The Review Path already decided what the
+* themes of this change are; a map that rediscovered them would sooner or later disagree with the
+* guide it sits next to, and the reviewer would be left to work out which one was wrong.
+*/
+var CHANGE_MAP_PROMPT = `You are Buddy AI, PR Review Buddy's review assistant. A developer is trying to understand a code change before and while reviewing it, and learns best visually. Build a CHANGE MAP: a small diagram of the ideas in this change and how they bear on one another.
+
+This is not a call graph. It answers "what is this change about, what are the important ideas, how do they depend on or affect each other, and where is the risk?" — not "which function calls which". A reviewer who has never seen this code should be able to read the map left to right and come away with a correct mental model of the change.
+
+Build it from the REVIEW GUIDE below. Its themes are already the important ideas of this change; reuse them, keep their meaning, and link a node to its theme with "sectionId" wherever the node is one of those themes. You have the working tree too: open files to check a relationship is real before you draw it, and never draw what a change of this kind usually looks like.
+
+What goes on the map:
+- One "intent" node: what the change is trying to accomplish for the person using it.
+- The main ideas ("concept"): the behaviour introduced or changed.
+- Actors and boundaries ("actor") only where they matter to the story: the CLI, a server, the browser, the filesystem, a worker, an external service.
+- Shared state or data ("state") that more than one part reads or writes.
+- Rules the change must keep ("constraint"), and what goes wrong if it does not ("risk").
+- One "outcome" node: what the person using it gets, or would lose.
+Leave out anything a reader can assume. Do not make a node for every file or function. 12 nodes is a hard maximum, and most changes need 5 to 9.
+
+Reading order. Every node has a "stage" from 0 to 4, and the map is read by stage, left to right:
+0 intent · 1 behaviour · 2 shared state and actors · 3 risks and constraints · 4 outcome.
+List nodes in the order the story reaches them.
+
+Importance. Mark the ideas a reviewer most needs to understand, at most 3 of them, as "weight": "primary", and every other node "supporting". Say why an idea matters in its "why" — never give a score, a rating or a number.
+
+Edges carry the meaning. Every edge has a short verb phrase "label" read from → to, such as: creates, reads from, writes to, depends on, requires, protects, can race with, happens before, removes from, invalidates, preserves, changes the behaviour of. An edge that only says "uses" or "calls" or has no label is not allowed. Add a one-sentence "note" when the verb alone would not explain the relationship. At most 16 edges. Draw the relationships that explain causality, not every connection that exists.
+
+Two registers. Every title, body, why, label and note is an object with "simple" and "technical" versions of the SAME claim. The graph is identical in both; only the words differ.
+- simple: everyday words for someone who does not know this codebase. Where it genuinely helps, one real-world analogy may carry through the whole map (a shared whiteboard, a queue at a counter), but do not force an analogy onto every node.
+- technical: the precise terms a developer would use, including the mechanism.
+Titles are plain-English names for ideas ("Only one process updates the queue at a time"), never identifiers. Put the identifier or file a reader could search for in "anchor" instead ("withWriteLock()").
+
+Keep text short, because a node is read at a glance beside the others: a title of at most 6 words, a body of ONE sentence of at most 20 words, a why of at most 15 words, a label of two to four words. Leave detail to the Review Path; the map is for the shape. Most maps need 6 to 12 edges: draw the spine of the story, and give no node more than 3 or 4 edges.
+
+Reply with one JSON object and nothing else, in exactly this shape:
+
+{
+  "title": "<short noun phrase naming the change>",
+  "intent": { "simple": "<one sentence>", "technical": "<one sentence>" },
+  "nodes": [
+    {
+      "id": "<short-kebab-id>",
+      "role": "intent | actor | concept | state | constraint | risk | outcome",
+      "stage": 0,
+      "weight": "primary | supporting",
+      "title": { "simple": "...", "technical": "..." },
+      "body": { "simple": "...", "technical": "..." },
+      "why": { "simple": "...", "technical": "..." },
+      "anchor": "<optional identifier or path>",
+      "sectionId": "<optional theme id from the review guide>"
+    }
+  ],
+  "edges": [
+    {
+      "from": "<node id>",
+      "to": "<node id>",
+      "label": { "simple": "...", "technical": "..." },
+      "note": { "simple": "...", "technical": "..." }
+    }
+  ]
+}
+
+"why", "anchor", "sectionId" and "note" are optional. Every other field is required.
+
+For example, for a change that caches user profiles, two of the nodes and the edge between them might be:
+
+{ "id": "profile-cache", "role": "state", "stage": 2, "weight": "primary",
+  "title": { "simple": "A saved copy of each profile", "technical": "In-memory profile cache" },
+  "body": { "simple": "Pages read the saved copy instead of asking the database every time.", "technical": "getProfile() reads through an LRU keyed by user id; misses fall back to the database." },
+  "why": { "simple": "If the copy is out of date, people see old details.", "technical": "Every read path now depends on invalidation being correct." },
+  "anchor": "ProfileCache" }
+{ "id": "profile-edit", "role": "concept", "stage": 1, "weight": "supporting",
+  "title": { "simple": "Editing your profile", "technical": "Profile update endpoint" },
+  "body": { "simple": "Saving changes writes the new details.", "technical": "PUT /profile writes the row and must evict the cache entry." } }
+{ "from": "profile-edit", "to": "profile-cache",
+  "label": { "simple": "must refresh", "technical": "invalidates" },
+  "note": { "simple": "Otherwise the saved copy keeps showing the old details.", "technical": "A missed eviction serves stale data until the entry expires." } }`;
+//#endregion
+//#region ../../packages/review-harness/src/workspace/change_map.ts
+/** A diagram's budget. The map reads the same change and writes less code-shaped output. */
+var CHANGE_MAP_TIMEOUT_MS = 18e4;
+/** A change map needs something to map. Refused before any agent is asked. */
+var ChangeMapUnavailableError = class extends Error {};
+/**
+* Map the change, from the review the reviewer is already reading.
+*
+* The same isolation a diagram gets: a checkout pinned to the reviewed commit, the review's own
+* model, and its usage recorded against the review. Callable on its own, with nothing about the
+* request in it, so the day maps are drawn without being asked for is a new caller, not a new
+* function.
+*
+* Failures come back as the diagram's own errors, because to the reviewer this is the same act —
+* asking for a picture — and the pane already knows how to say either one.
+*/
+async function drawChangeMap(workspace, signal) {
+	const result = workspace.session.result;
+	if (!result) throw new ChangeMapUnavailableError("This review has no analysis yet, so there is nothing to map.");
+	const cwd = await askCheckout(workspace);
+	const env = agentEnvOf(workspace);
+	const requestedModel = resolveModel({ review: { session: workspace.session } }) ?? void 0;
+	let raw;
+	try {
+		raw = await withUsageRecorded(workspace.id, "change-map", env, (onUsage) => agentFor(env).run({
+			capability: "read-code",
+			prompt: buildPrompt(workspace, cwd),
+			cwd,
+			originRepoPath: workspace.repoPath,
+			env,
+			...requestedModel ? { requestedModel } : {},
+			timeoutMs: CHANGE_MAP_TIMEOUT_MS,
+			signal,
+			onUsage
+		}), void 0, requestedModel);
+	} catch (error) {
+		if (error instanceof AgentUnavailableError) throw new DiagramUnavailableError(`${error.message} It is what this review was made with, so nothing can be drawn.`);
+		throw error;
+	}
+	let map;
+	try {
+		({map} = validateChangeMap(raw, result.sections.map((section) => section.id)));
+	} catch (error) {
+		if (error instanceof ChangeMapRejected) throw new DiagramMalformedError(`Buddy AI did not return a change map that could be drawn. ${error.message}`);
+		throw error;
+	}
+	return {
+		...map,
+		commitSha: reviewedCommit(workspace),
+		createdAt: Date.now(),
+		promptVersion: "2"
+	};
+}
+/**
+* The review, the change, and the simple explanation the reviewer has already read, if any.
+*
+* That last one is what keeps Simple mode and "Explain in simple terms" one explanation rather than
+* two. A reviewer who has just read that the queue is like a shared whiteboard should find the same
+* whiteboard on the map, not a second analogy that makes them wonder which one is right.
+*/
+function buildPrompt(workspace, cwd) {
+	const simple = simpleExplanation(workspace);
+	return [
+		CHANGE_MAP_PROMPT,
+		"---",
+		`CHANGE: ${workspace.changeSet.headRef} compared against ${workspace.changeSet.baseRef}, in the checkout at ${cwd}`,
+		"---",
+		"REVIEW GUIDE (JSON). Its \"sections\" are the Review Path themes; their \"id\" values are the only valid \"sectionId\" values:",
+		JSON.stringify(workspace.session.result),
+		...simple ? [
+			"---",
+			"SIMPLE EXPLANATION THE REVIEWER HAS ALREADY READ. Keep to its analogy and its framing in the \"simple\" register, so the two explanations agree:",
+			simple
+		] : [],
+		"---",
+		"DIFF:",
+		workspace.diff
+	].join("\n");
+}
+/** The latest whole-change "Explain in simple terms" answer, which is the one the map sits beside. */
+function simpleExplanation(workspace) {
+	const turns = workspace.transcript ?? [];
+	for (let i = turns.length - 1; i >= 0; i -= 1) {
+		const turn = turns[i];
+		if (turn.question === "Explain this review in plain English for someone unfamiliar with this codebase. Avoid jargon, use a simple everyday analogy if it helps, and keep it skippable — a couple of short paragraphs is enough." && !turn.sectionId && turn.answer.trim()) return turn.answer.trim();
+	}
+	return null;
+}
 var FileOutsideRepositoryError = class extends Error {};
 /**
 * Resolve a path against the reviewed repository, refusing anything outside it.
@@ -7990,11 +8667,12 @@ function readPreferences() {
 	try {
 		const parsed = JSON.parse(readFileSync(PREFERENCES_PATH, "utf8"));
 		if (!parsed || typeof parsed !== "object") return {};
-		const { askWidth, dismissedNotices, promptsCollapsed } = parsed;
+		const { askWidth, dismissedNotices, promptsCollapsed, changeMapRegister } = parsed;
 		return {
 			...typeof askWidth === "number" && Number.isFinite(askWidth) ? { askWidth: clampAskWidth(askWidth) } : {},
 			...Array.isArray(dismissedNotices) ? { dismissedNotices: dismissedNotices.filter((key) => typeof key === "string" && NOTICE_KEY.test(key)) } : {},
-			...typeof promptsCollapsed === "boolean" ? { promptsCollapsed } : {}
+			...typeof promptsCollapsed === "boolean" ? { promptsCollapsed } : {},
+			...changeMapRegister === "simple" || changeMapRegister === "technical" ? { changeMapRegister } : {}
 		};
 	} catch {
 		return {};
@@ -8021,6 +8699,16 @@ function writePromptsCollapsed(collapsed) {
 		}, null, 2)}\n`);
 	} catch {}
 }
+/** Remember which words the change map is read in. Read-modify-write, like every other field here. */
+function writeChangeMapRegister(register) {
+	try {
+		mkdirSync(STORE_ROOT, { recursive: true });
+		writeFileSync(PREFERENCES_PATH, `${JSON.stringify({
+			...readPreferences(),
+			changeMapRegister: register
+		}, null, 2)}\n`);
+	} catch {}
+}
 /** Remember that the reviewer has read a notice. Refuses anything not shaped like a key. */
 function dismissNotice(key) {
 	if (!NOTICE_KEY.test(key)) return false;
@@ -9023,6 +9711,7 @@ async function sendWorkspacePage(res, workspace) {
 		askWidth: readPreferences().askWidth,
 		dismissedNotices: readPreferences().dismissedNotices,
 		promptsCollapsed: readPreferences().promptsCollapsed === true,
+		changeMapRegister: readPreferences().changeMapRegister ?? "simple",
 		transcript: workspace.transcript,
 		pendingAsk: reportRun(workspace.id, "ask"),
 		pendingDiagram: reportRun(workspace.id, "diagram"),
@@ -9043,6 +9732,7 @@ async function sendWorkspacePage(res, workspace) {
 		lastPrRefresh: workspace.lastPrRefresh,
 		lastUpdate: notice,
 		diagrams: workspace.diagrams,
+		changeMap: workspace.changeMap,
 		reviewedSha: reviewedCommit(workspace),
 		revision: workspaceRevision(workspace),
 		lineage: lineagePosition(workspace),
@@ -9466,10 +10156,15 @@ async function handleStop(req, res, workspace) {
 */
 async function handleDiagram(req, res, workspace) {
 	const body = await readJson(req);
-	const sectionId = typeof body?.sectionId === "string" ? body.sectionId : null;
+	const drawing = body?.kind === "map" ? "map" : "implementation";
+	const sectionId = drawing === "implementation" && typeof body?.sectionId === "string" ? body.sectionId : null;
 	const scope = sectionId ?? "change";
-	const redraw = (workspace.diagrams ?? []).some((diagram) => diagram.scope === scope);
-	const started = beginRun(workspace.id, "diagram", { sectionId });
+	const redraw = drawing === "map" ? workspace.changeMap !== void 0 : (workspace.diagrams ?? []).some((diagram) => diagram.scope === scope);
+	if (drawing === "map" && !workspace.session.result) return send(res, 409, { error: "This review has no analysis yet, so there is nothing to map." });
+	const started = beginRun(workspace.id, "diagram", {
+		sectionId,
+		drawing
+	});
 	if ("alreadyRunning" in started) return send(res, 409, {
 		error: "A diagram of this review is already being drawn.",
 		running: true
@@ -9478,6 +10173,7 @@ async function handleDiagram(req, res, workspace) {
 	record({
 		event: "diagram_requested",
 		reviewId: workspace.id,
+		drawing,
 		scoped: sectionId !== null,
 		redraw
 	});
@@ -9485,18 +10181,21 @@ async function handleDiagram(req, res, workspace) {
 	const failed = () => record({
 		event: "diagram_drawn",
 		reviewId: workspace.id,
+		drawing,
 		durationMs: Date.now() - startedAt,
 		ok: false,
 		...run.state === "stopped" ? { cancelled: true } : {}
 	});
 	try {
 		let diagram;
+		let changeMap;
 		try {
-			diagram = await drawDiagram(workspace, sectionId, run.signal);
+			if (drawing === "map") changeMap = await drawChangeMap(workspace, run.signal);
+			else diagram = await drawDiagram(workspace, sectionId, run.signal);
 		} catch (error) {
 			failed();
 			if (run.state === "stopped") return sendIfOpen(res, 200, { stopped: true });
-			if (error instanceof DiagramUnavailableError || error instanceof DiagramMalformedError) return sendIfOpen(res, 502, { error: error.message });
+			if (error instanceof DiagramUnavailableError || error instanceof DiagramMalformedError || error instanceof ChangeMapUnavailableError) return sendIfOpen(res, 502, { error: error.message });
 			throw error;
 		}
 		if (!completeRun(run)) {
@@ -9506,9 +10205,21 @@ async function handleDiagram(req, res, workspace) {
 		record({
 			event: "diagram_drawn",
 			reviewId: workspace.id,
+			drawing,
 			durationMs: Date.now() - startedAt,
 			ok: true
 		});
+		if (changeMap) {
+			let kept = false;
+			mutateWorkspace(workspace.id, (fresh) => {
+				if (changeMap.commitSha && reviewedCommit(fresh) && changeMap.commitSha !== reviewedCommit(fresh) || fresh.jobId !== workspace.jobId || !fresh.session.result) return;
+				fresh.changeMap = changeMap;
+				kept = true;
+			});
+			if (!kept) return sendIfOpen(res, 409, { error: "The review moved to a newer commit while this map was being drawn. Generate it again to map the review as it is now." });
+			return sendIfOpen(res, 200, { changeMap });
+		}
+		if (!diagram) return sendIfOpen(res, 502, { error: "Buddy AI did not return a diagram." });
 		mutateWorkspace(workspace.id, (fresh) => {
 			const diagrams = [...fresh.diagrams ?? []];
 			const existing = diagrams.findIndex((one) => one.scope === scope);
@@ -9608,6 +10319,7 @@ async function handlePrefs(req, res) {
 	if (typeof askWidth === "number") writeAskWidth(askWidth);
 	else if (askWidth === null) clearAskWidth();
 	if (typeof body?.promptsCollapsed === "boolean") writePromptsCollapsed(body.promptsCollapsed);
+	if (body?.changeMapRegister === "simple" || body?.changeMapRegister === "technical") writeChangeMapRegister(body.changeMapRegister);
 	if (typeof body?.dismissNotice === "string" && !dismissNotice(body.dismissNotice)) return send(res, 400, { error: "Not a notice this page can dismiss." });
 	send(res, 200, { ok: true });
 }
@@ -9705,6 +10417,7 @@ var VIEWS = [
 	"files",
 	"prcontext",
 	"diagram",
+	"map",
 	"kiss",
 	"kissrecs"
 ];