prreviewbuddy 0.70.2 → 0.71.1

package/dist/server.js

@@ -1,4 +1,4 @@
-import { $ as MAX_WORKSPACE_PORT, $n as isClaimed, $r as resolveAgent, $t as markReadForReview, A as relativeTime$1, An as isWorktreeHeld, Ar as parseLifecycle, At as partFiles, B as readIndexToken, Bn as reviewedShaOf, Br as issuesOutstanding, Bt as isArchitectureId, C as track, Cn as originRemote, Cr as activityAttributes, Ct as mapRuntimes, D as endRun, Dn as MANAGED_ROOT, Dr as lifecycleItemLabel, Dt as ARCHITECTURE_DIR, E as completeRun, En as ReviewBeingDeletedError, Er as lifecycleChip, Et as describeRuntimes, F as runBatch, Fr as queueStamp, Ft as trackedFiles, Gn as loadJob, Gr as describeAuthorship, Gt as createArchitectureNotification, H as clearServerRecordOwnedBy, Hn as endedAt, Hr as reviewerDispositions, Ht as announceJob, I as activateQueued, In as findExistingReview, Ir as readQueue, It as ownersOf, J as stopChild, Jn as isLiveJob, Jr as resolveTarget, Jt as eventName, K as serverEntryExists, Kn as saveJob, Kr as WITHHELD_REASON, Kt as createPrState, L as compactQueue, Ln as checkCodeFreshness, Lr as doneVerb, Lt as QUOTE_LIMITS, M as extractPullRequestLinks, Mn as removeWorktree, Mr as queueAdd, Mt as repositoryKey, N as parsePullRequestLink, Nn as requestJobStop, Nr as queueAddMany, Nt as storeArchitecture, O as reportRun, On as createWorktree, Or as lifecyclePill, Ot as checkArchitecture, P as unsupportedReason, Pr as queueRemove, Pt as storedScopes, Q as DEFAULT_WORKSPACE_PORT, Qr as git, Qt as markRead, Rn as checkReview, Rr as isIssueOutstanding, Rt as REPOSITORY_SCOPE, S as isDriving, Sn as remoteHost, Sr as LIFECYCLES, St as waitingHistory, T as beginRun, Tr as isLifecycle, Tt as RUNTIME_WORDS, Un as fail, Ur as processDiscussion, Ut as branchOf, Vn as allJobs, Vr as questionsOutstanding, Vt as writeJsonAtomically, W as readServerRecord, Wn as isTerminal, Wr as recommendationsOf, Wt as subjectOf, Xn as progressSteps, Xr as isCommitReview, Xt as listNotifications, Yn as phasesFor, Yr as DetachedHeadError, Yt as headline, Z as writeServerRecord, Zn as purposeOf, Zr as resolveBase, Zt as markAllRead, _ as liveUpdateFor, _n as extractJsonText, _t as telemetryUploadConsent, a as wasBlocked, ai as STORE_ROOT, an as withUsageRecorded, ar as kissDecisionRefusal, at as failureOf$1, bn as forgeResolver, br as workspaceRevision, c as RefreshUnavailableError, ci as agentFor$1, cn as authorPreview, cr as lineagePosition, ct as reanalyseReview, d as mergeUpdateInto, di as AgentUnavailableError, dn as renderMarkdown, dr as mutateWorkspace, ei as resolveModel, en as pruneNotifications, er as decideKissRecommendation, et as MIN_WORKSPACE_PORT, f as updateReview, fn as CODE_BLOCK_CLASS, ft as readEvents, g as UpdateAlreadyRunningError, gn as asString, gr as reviewedCommit, gt as recordTelemetryUploadConsent, h as askCheckout, hn as renderInlineText, hr as recentWorkspaces, i as liveJobsFor, in as unreadCount$1, ir as indexReviewGroups, it as writePortPreference, j as batchIdentity, jn as readMarker, jr as sectionOf, jt as readArchitecture, k as stopRun, kn as holdWorktree, kr as offersLifecycle, kt as loadArchitecture, l as cancelUpdate, li as detectAgents, ln as hasAuthorContent, lr as loadWorkspace, lt as runJob, m as isUnchanged, mn as escapeHtml$1, mr as previousKissResult, n as deleteReview, ni as readAgentPreference, nn as removeNotification, nr as groupByLineage, nt as resolveWorkspacePort, o as discardJob, oi as AGENT_IDS, on as EXPLAIN_SIMPLY_PROMPT, or as kissDecisionsOf, ot as prepareReview, p as refreshPrContext, pn as CODE_COPY_CLASS, pr as presentedKissRunOf, pt as record, q as spawnServer, qr as kissOutcome, qt as createPrUpdate, r as lineageIds, ri as writeAgentPreference, rn as toneOf, rr as indexKeptIds, rt as statedWorkspacePort, s as FETCH_TIMEOUT_MS, si as agentById, sn as UNESTABLISHED_MOTIVATION, sr as latestKissRun, st as settleReview, t as deleteLineage, ti as clearAgentPreference, tn as readNotification, tr as followedRefName, tt as parseWorkspacePort, u as cancellableHere, ui as AgentCancelledError, un as GITHUB_MARKDOWN, vn as objectWithAnyOf, w as RUN_KINDS, wn as fillFileUrlTemplate, wr as activityLabel, wt as recordRuntimeBestEffort, x as startKissJob, xn as forgeFor, xr as workspaceStamps, xt as feedbackUrl, y as agentEnvOf, yn as claimRequestUrl, yr as touchWorkspace, yt as BUILD_VERSION, z as settleQueue, zn as followedBranch, zr as isQuestionOutstanding, zt as ancestorsOf } from "./delete_review-CRPRIRKg.js";
+import { $ as MAX_WORKSPACE_PORT, $n as isClaimed, $r as resolveBase, $t as markReadForReview, A as relativeTime$1, An as isWorktreeHeld, Ar as parseLifecycle, At as partFiles, B as readIndexToken, Bn as reviewedShaOf, Br as issuesOutstanding, Bt as isArchitectureId, C as track, Cn as originRemote, Cr as activityAttributes, Ct as mapRuntimes, D as endRun, Dn as MANAGED_ROOT, Dr as lifecycleItemLabel, Dt as ARCHITECTURE_DIR, E as completeRun, En as ReviewBeingDeletedError, Er as lifecycleChip, Et as describeRuntimes, F as runBatch, Fr as queueStamp, Ft as trackedFiles, Gn as loadJob, Gr as simpleExplanationOf, Gt as createArchitectureNotification, H as clearServerRecordOwnedBy, Hn as endedAt, Hr as reviewerDispositions, Ht as announceJob, I as activateQueued, In as findExistingReview, Ir as readQueue, It as ownersOf, J as stopChild, Jn as isLiveJob, Jr as WITHHELD_REASON, Jt as eventName, K as serverEntryExists, Kn as saveJob, Kr as withSimpleExplanation, Kt as createPrState, L as compactQueue, Ln as checkCodeFreshness, Lr as doneVerb, Lt as QUOTE_LIMITS, M as extractPullRequestLinks, Mn as removeWorktree, Mr as queueAdd, Mt as repositoryKey, N as parsePullRequestLink, Nn as requestJobStop, Nr as queueAddMany, Nt as storeArchitecture, O as reportRun, On as createWorktree, Or as lifecyclePill, Ot as checkArchitecture, P as unsupportedReason, Pr as queueRemove, Pt as storedScopes, Q as DEFAULT_WORKSPACE_PORT, Qr as isCommitReview, Qt as markRead, Rn as checkReview, Rr as isIssueOutstanding, Rt as REPOSITORY_SCOPE, S as isDriving, Sn as remoteHost, Sr as LIFECYCLES, St as waitingHistory, T as beginRun, Tr as isLifecycle, Tt as RUNTIME_WORDS, Un as fail, Ur as processDiscussion, Ut as branchOf, Vn as allJobs, Vr as questionsOutstanding, Vt as writeJsonAtomically, W as readServerRecord, Wn as isTerminal, Wr as recommendationsOf, Wt as subjectOf, Xn as progressSteps, Xr as resolveTarget, Xt as listNotifications, Yn as phasesFor, Yr as kissOutcome, Yt as headline, Z as writeServerRecord, Zn as purposeOf, Zr as DetachedHeadError, Zt as markAllRead, _ as liveUpdateFor, _n as extractJsonText, _t as telemetryUploadConsent, a as wasBlocked, ai as writeAgentPreference, an as withUsageRecorded, ar as kissDecisionRefusal, at as failureOf$1, bn as forgeResolver, br as workspaceRevision, c as RefreshUnavailableError, ci as AGENT_IDS, cn as authorPreview, cr as lineagePosition, ct as reanalyseReview, d as mergeUpdateInto, di as detectAgents, dn as renderMarkdown, dr as mutateWorkspace, ei as git, en as pruneNotifications, er as decideKissRecommendation, et as MIN_WORKSPACE_PORT, f as updateReview, fi as AgentCancelledError, fn as CODE_BLOCK_CLASS, ft as readEvents, g as UpdateAlreadyRunningError, gn as asString, gr as reviewedCommit, gt as recordTelemetryUploadConsent, h as askCheckout, hn as renderInlineText, hr as recentWorkspaces, i as liveJobsFor, ii as readAgentPreference, in as unreadCount$1, ir as indexReviewGroups, it as writePortPreference, j as batchIdentity, jn as readMarker, jr as sectionOf, jt as readArchitecture, k as stopRun, kn as holdWorktree, kr as offersLifecycle, kt as loadArchitecture, l as cancelUpdate, li as agentById, ln as hasAuthorContent, lr as loadWorkspace, lt as runJob, m as isUnchanged, mn as escapeHtml$1, mr as previousKissResult, n as deleteReview, ni as resolveModel, nn as removeNotification, nr as groupByLineage, nt as resolveWorkspacePort, o as discardJob, on as EXPLAIN_SIMPLY_PROMPT, or as kissDecisionsOf, ot as prepareReview, p as refreshPrContext, pi as AgentUnavailableError, pn as CODE_COPY_CLASS, pr as presentedKissRunOf, pt as record, q as spawnServer, qr as describeAuthorship, qt as createPrUpdate, r as lineageIds, ri as clearAgentPreference, rn as toneOf, rr as indexKeptIds, rt as statedWorkspacePort, s as FETCH_TIMEOUT_MS, si as STORE_ROOT, sn as UNESTABLISHED_MOTIVATION, sr as latestKissRun, st as settleReview, t as deleteLineage, ti as resolveAgent, tn as readNotification, tr as followedRefName, tt as parseWorkspacePort, u as cancellableHere, ui as agentFor$1, un as GITHUB_MARKDOWN, vn as objectWithAnyOf, w as RUN_KINDS, wn as fillFileUrlTemplate, wr as activityLabel, wt as recordRuntimeBestEffort, x as startKissJob, xn as forgeFor, xr as workspaceStamps, xt as feedbackUrl, y as agentEnvOf, yn as claimRequestUrl, yr as touchWorkspace, yt as BUILD_VERSION, z as settleQueue, zn as followedBranch, zr as isQuestionOutstanding, zt as ancestorsOf } from "./delete_review-BgIZpcsP.js";
 import { basename, isAbsolute, join, relative, resolve } from "node:path";
 import { execFile } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
@@ -453,6 +453,8 @@ var MESSAGE_COPY_CLASS = "pr-helper-msg-copy";
 var MESSAGE_ACTIONS_CLASS = "pr-helper-chat-actions";
 /** The Markdown itself, for surfaces that hold no message state to resolve an id against. */
 var MESSAGE_SOURCE_ATTR = "data-copy-source";
+/** A finding's text for a feedback draft, on its feedback checkbox. Copy's text less the reviewer's own working. */
+var FEEDBACK_SOURCE_ATTR = "data-feedback-source";
 var STATES$1 = {
 	idle: {
 		icon: "<path d=\"M0 6.75C0 5.784.784 5 1.75 5h1.5a.75.75 0 0 1 0 1.5h-1.5a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-1.5a.75.75 0 0 1 1.5 0v1.5A1.75 1.75 0 0 1 9.25 16h-7.5A1.75 1.75 0 0 1 0 14.25Z\"></path><path d=\"M5 1.75C5 .784 5.784 0 6.75 0h7.5C15.216 0 16 .784 16 1.75v7.5A1.75 1.75 0 0 1 14.25 11h-7.5A1.75 1.75 0 0 1 5 9.25Zm1.75-.25a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-7.5a.25.25 0 0 0-.25-.25Z\"></path>",
@@ -1095,23 +1097,253 @@ function renderAskBuddyMenu(kind) {
   </div>`;
 }
 //#endregion
+//#region ../../packages/review-harness/src/domain/ui/components/simple_explanation.ts
+/**
+* A finding's simple explanation: Buddy AI's plain-English account of it, kept on the card because
+* the reviewer asked for one.
+*
+* For reading the finding, not part of it. It carries no copy source, so Copy and Prepare feedback,
+* which take the card's first one, can only ever find the finding's own.
+*
+* A native disclosure, closed when the page loads and open when it has just been written. Whether a
+* reader left it open is not kept: the explanation is the durable part.
+*/
+var SIMPLE_EXPLANATION_LABEL = "Simple explanation";
+var ASK_MORE_LABEL = "Ask more →";
+function renderSimpleExplanation(text, options = {}) {
+	const body = renderMarkdown(text);
+	const askMore = options.askMore ? `<button type="button" class="pr-helper-simple-explanation-more" data-simple-explanation-more>${ASK_MORE_LABEL}</button>` : "";
+	const content = askMore && body.endsWith("</p>") ? `${body.slice(0, -4)} ${askMore}</p>` : body + askMore;
+	return `<details class="pr-helper-simple-explanation" data-simple-explanation${options.open ? " open" : ""}>
+        <summary class="pr-helper-simple-explanation-summary">${SIMPLE_EXPLANATION_LABEL}</summary>
+        <div class="pr-helper-simple-explanation-body pr-helper-markdown">${content}</div>
+      </details>`;
+}
+//#endregion
+//#region ../../packages/review-harness/src/domain/ui/components/pill_tooltips.ts
+/**
+* What every pill in the sidebar actually means, in one place.
+*
+* A pill is a single uppercase word standing in for a whole axis of judgement, and the axes are
+* not self-evident: MAJOR and "medium confidence" sit side by side on the same card and answer
+* completely different questions. Severity is how much the finding would matter *if it is real*;
+* confidence is how sure the analysis is that it *is* real. A reviewer who has collapsed those
+* into one mental "how bad is this" scale is reading the card wrong, and no amount of colour
+* fixes that — only words do.
+*
+* The wording is derived from the field guidance the model is actually given (see
+* STRUCTURED_OUTPUT_INSTRUCTIONS in ai_review/pipeline.ts). This file must not invent a richer
+* taxonomy than the prompt asks for: if the prompt does not define what separates "major" from
+* "minor", neither does the tooltip. It names the axis and where the value sits on it, and
+* leaves the grading to the model that did the grading.
+*
+* House style, because a tooltip is read once at a glance and never studied:
+*
+* 1. Open with the concept, not a sentence the reader has to parse into one. "PR risk — the
+*    overall risk level assigned to this pull request" lands before the clause finishes;
+*    "Overall risk this analysis assigned the pull request" makes them unpick the grammar first.
+* 2. Describe what the thing *is*, never how the extension builds it. A follow-up "builds on the
+*    original analysis" — that it is composed into the stored session is our problem, not theirs.
+* 3. Plain reviewer's English over product vocabulary. "During your review", not "before you
+*    sign off"; "the section of the Guide", not the section's own title read back at them.
+*/
+/** Ordered worst-first, matching how the prompt lists the enum. */
+var SEVERITY_SCALE = [
+	"critical",
+	"major",
+	"minor",
+	"nit"
+];
+var ATTENTION_SCALE = [
+	"high",
+	"medium",
+	"low"
+];
+/**
+* "2 of 4: critical → major → minor → nit" — the value's rank and the whole scale it sits on.
+*
+* Both halves earn their place: the rank alone leaves the reader guessing what the other steps
+* are, and the scale alone makes them count. An arrow rather than a bullet or comma, so the
+* ordering is visible rather than something the reader has to already know.
+*/
+function position(value, scale) {
+	const index = scale.indexOf(value);
+	if (index === -1) return scale.join(" → ");
+	return `${index + 1} of ${scale.length}: ${scale.join(" → ")}`;
+}
+function severityTip(severity) {
+	return `Severity — how much this would matter if it turns out to be real. ${position(severity, SEVERITY_SCALE)}.`;
+}
+/**
+* Only medium and low ever reach the screen (renderIssueConfidence suppresses "high"), but all
+* three are worded here so the copy does not depend on that rendering decision staying put.
+*
+* The second sentence is the one that matters. Confidence and severity sit side by side on the
+* same card, and a reader who has not been told otherwise will assume they are the same scale
+* read twice — so the tooltip says they are not, in as many words.
+*/
+function confidenceTip(confidence) {
+	return `Confidence — how sure the analysis is that this issue is real. This is separate from how serious it would be. ${{
+		high: "High means the analysis is confident it’s real.",
+		medium: "Medium means it’s worth confirming in the code before acting on it.",
+		low: "Low means it was likely reasoned from the diff alone, so check the surrounding code first."
+	}[confidence]}`;
+}
+function importanceTip(importance) {
+	return `Importance — how much attention this question deserves during your review. ${position(importance, ATTENTION_SCALE)}.`;
+}
+/**
+* The four statuses an "Analyse new changes" pass assigns to a finding.
+*
+* Each says what the *product* concluded and, where it matters, how much to trust it. "Still open"
+* carries the load: it is both a real judgement ("the changes do not address this") and the safe
+* default applied when the analysis said nothing about a finding at all, and the reviewer cannot
+* tell those apart from the badge — so the copy commits to the weaker of the two readings rather
+* than claiming a judgement that may not have been made.
+*/
+function findingStatusTip(status) {
+	return {
+		resolved: "Resolved — the new commits appear to address this finding. Worth a glance to confirm before you close it out.",
+		"still-open": "Still open — the new commits do not address this finding. Findings the analysis did not comment on are shown this way too, so this never disappears on its own.",
+		affected: "Affected — the code this finding concerns has changed, but not in a way that settles it. Re-read this one.",
+		new: "New — introduced by the changes pushed since your previous analysis."
+	}[status];
+}
+/** The reviewer-facing label for a status. Kept beside the tooltips so the two cannot drift. */
+function findingStatusLabel(status) {
+	return {
+		resolved: "Resolved",
+		"still-open": "Still open",
+		affected: "Affected",
+		new: "New"
+	}[status];
+}
+/**
+* What the commits pushed since did to an open question.
+*
+* "Still open" carries the same double load it does on a finding: a real judgement, and the default
+* for a question the reassessment never mentioned. The copy commits to the weaker reading, because
+* the reviewer must not read silence as an answer.
+*/
+function questionStatusTip(status) {
+	return {
+		answered: "Answered — the new commits settle this, and the answer is below. Worth a glance to confirm before you drop it.",
+		"still-open": "Still open — the new commits do not settle this. Questions the reassessment did not comment on are shown this way too, so this never disappears on its own.",
+		affected: "Affected — the code this question is about has changed without answering it. Read the question again before you ask it."
+	}[status];
+}
+/** The reviewer-facing label for a question status. Kept beside the tooltip so the two cannot drift. */
+function questionStatusLabel(status) {
+	return {
+		answered: "Answered",
+		"still-open": "Still open",
+		affected: "Affected"
+	}[status];
+}
+/**
+* The four impacts a repository investigation assigns to a finding.
+*
+* Every one of these says the evidence came from *outside* the diff, because that is the whole
+* reason to trust them more than the analysis they revise — and equally the reason to say where
+* they came from. "A coding agent read the repository" is the qualification, and a reviewer who
+* does not know that cannot weigh it.
+*
+* "Investigated" carries the same load "Still open" does on the other axis: it is both a real
+* judgement ("this evidence does not bear on that finding") and the default applied when the
+* reassessment said nothing about a finding at all. The copy commits to the weaker reading rather
+* than claiming a judgement that may not have been made.
+*/
+function investigationImpactTip(impact) {
+	return {
+		confirmed: "Confirmed — a repository investigation found evidence supporting this finding. It no longer rests on the diff alone.",
+		refuted: "Refuted — a repository investigation found evidence that this concern does not hold. Kept on the list, with the reasoning, rather than removed.",
+		revised: "Revised — a repository investigation changed what this finding says. Where its severity or confidence moved, the previous value is shown alongside.",
+		unchanged: "Investigated — this finding was reassessed against a repository investigation and stands as it was. Findings the reassessment did not comment on are shown this way too."
+	}[impact];
+}
+/**
+* The reviewer-facing label. Note `unchanged` → "Investigated": the reviewer's world contains a
+* finding that was looked into and survived, which is information. "Unchanged" describes our
+* bookkeeping — what the field did — and says nothing about the code.
+*/
+function investigationImpactLabel(impact) {
+	return {
+		confirmed: "Confirmed",
+		refuted: "Refuted",
+		revised: "Revised",
+		unchanged: "Investigated"
+	}[impact];
+}
+var DISMISSED_TIP = "Dismissed by you — you decided this finding needs no action. It stops counting towards what is left, and stays here so the decision is visible rather than lost.";
+var DISMISSAL_STALE_TIP = "Changed since you dismissed this — the code under this finding has moved, so the reading you dismissed it on no longer holds. Your decision is kept; the finding is back on the list until you confirm it.";
+var SECTION_TAG_TIP = "Guide section — the section of the Guide this finding belongs to. Click to open it in the Guide tab.";
+/**
+* Builds a pill's `class` and `data-tip` attributes together.
+*
+* They are emitted as one string rather than left to the call site because they are useless
+* apart: `data-tip` without `pr-helper-tip` never renders, and `pr-helper-tip` without a tip
+* renders an empty black rectangle on hover. Taking the pill's own classes as an argument means
+* there is no way to add the tooltip and clobber the styling, which is what a bare
+* `class="pr-helper-tip"` helper would have invited.
+*
+* Emits a leading space so it drops straight in after a tag name.
+*/
+function pillAttrs(classNames, tip) {
+	return ` class="${escapeHtml$1(classNames)} pr-helper-tip" data-tip="${escapeHtml$1(tip)}"`;
+}
+//#endregion
 //#region ../../packages/review-harness/src/domain/ui/components/finding_copy.ts
-/** An issue: its title in bold, the description, then the location when it has one. */
+/** An issue's Copy: its title in bold, the description, the update, the investigation, then the location. */
 function issueMarkdown(issue) {
+	return issueText(issue, true);
+}
+/** An issue as a feedback draft gives it: its Copy without the investigation. */
+function issueFeedbackMarkdown(issue) {
+	return issueText(issue, false);
+}
+/** A question's Copy: the question in bold, why it matters, the update, the investigation, then the files. */
+function questionMarkdown(question) {
+	return questionText(question, true);
+}
+/** A question as a feedback draft gives it: its Copy without the investigation. */
+function questionFeedbackMarkdown(question) {
+	return questionText(question, false);
+}
+function issueText(issue, investigation) {
 	return join$1([
 		bold(issue.title),
 		issue.description,
+		update(issue.reconciliationStatus && findingStatusLabel(issue.reconciliationStatus), issue.reconciliationNote),
+		...investigation ? [investigated(issue.investigationImpact, issue.investigationNote)] : [],
 		where(issue.file, issue.line, issue.relatedFiles)
 	]);
 }
-/** A question: the question in bold, why it matters when the review said, then the files. */
-function questionMarkdown(question) {
+function questionText(question, investigation) {
 	return join$1([
 		bold(question.question),
 		question.whyThisMatters,
+		labelled("Answered by the new changes", question.reconciliationAnswer),
+		update(question.reconciliationStatus && questionStatusLabel(question.reconciliationStatus), question.reconciliationNote),
+		...investigation ? [labelled("Answer from investigation", question.investigationAnswer), investigated(question.investigationImpact, question.investigationNote)] : [],
 		where(question.file, void 0, question.relatedFiles)
 	]);
 }
+/** What the last update said about the finding, under the status the card shows beside it. */
+function update(status, note) {
+	if (!note?.trim()) return void 0;
+	return `**After the new commits${status ? ` (${status.toLowerCase()})` : ""}:** ${note.trim()}`;
+}
+/**
+* What an investigation concluded, under the verdict the card's badge shows. "Investigated" is the
+* badge for a finding the evidence left as it was, which says nothing a heading does not.
+*/
+function investigated(impact, note) {
+	if (!note?.trim()) return void 0;
+	return `**Investigation${impact && impact !== "unchanged" ? ` (${investigationImpactLabel(impact).toLowerCase()})` : ""}:** ${note.trim()}`;
+}
+function labelled(label, text) {
+	return text?.trim() ? `**${label}:** ${text.trim()}` : void 0;
+}
 function bold(text) {
 	return `**${text.trim()}**`;
 }
@@ -1352,178 +1584,6 @@ function provenanceDetailLines(session) {
 	];
 }
 //#endregion
-//#region ../../packages/review-harness/src/domain/ui/components/pill_tooltips.ts
-/**
-* What every pill in the sidebar actually means, in one place.
-*
-* A pill is a single uppercase word standing in for a whole axis of judgement, and the axes are
-* not self-evident: MAJOR and "medium confidence" sit side by side on the same card and answer
-* completely different questions. Severity is how much the finding would matter *if it is real*;
-* confidence is how sure the analysis is that it *is* real. A reviewer who has collapsed those
-* into one mental "how bad is this" scale is reading the card wrong, and no amount of colour
-* fixes that — only words do.
-*
-* The wording is derived from the field guidance the model is actually given (see
-* STRUCTURED_OUTPUT_INSTRUCTIONS in ai_review/pipeline.ts). This file must not invent a richer
-* taxonomy than the prompt asks for: if the prompt does not define what separates "major" from
-* "minor", neither does the tooltip. It names the axis and where the value sits on it, and
-* leaves the grading to the model that did the grading.
-*
-* House style, because a tooltip is read once at a glance and never studied:
-*
-* 1. Open with the concept, not a sentence the reader has to parse into one. "PR risk — the
-*    overall risk level assigned to this pull request" lands before the clause finishes;
-*    "Overall risk this analysis assigned the pull request" makes them unpick the grammar first.
-* 2. Describe what the thing *is*, never how the extension builds it. A follow-up "builds on the
-*    original analysis" — that it is composed into the stored session is our problem, not theirs.
-* 3. Plain reviewer's English over product vocabulary. "During your review", not "before you
-*    sign off"; "the section of the Guide", not the section's own title read back at them.
-*/
-/** Ordered worst-first, matching how the prompt lists the enum. */
-var SEVERITY_SCALE = [
-	"critical",
-	"major",
-	"minor",
-	"nit"
-];
-var ATTENTION_SCALE = [
-	"high",
-	"medium",
-	"low"
-];
-/**
-* "2 of 4: critical → major → minor → nit" — the value's rank and the whole scale it sits on.
-*
-* Both halves earn their place: the rank alone leaves the reader guessing what the other steps
-* are, and the scale alone makes them count. An arrow rather than a bullet or comma, so the
-* ordering is visible rather than something the reader has to already know.
-*/
-function position(value, scale) {
-	const index = scale.indexOf(value);
-	if (index === -1) return scale.join(" → ");
-	return `${index + 1} of ${scale.length}: ${scale.join(" → ")}`;
-}
-function severityTip(severity) {
-	return `Severity — how much this would matter if it turns out to be real. ${position(severity, SEVERITY_SCALE)}.`;
-}
-/**
-* Only medium and low ever reach the screen (renderIssueConfidence suppresses "high"), but all
-* three are worded here so the copy does not depend on that rendering decision staying put.
-*
-* The second sentence is the one that matters. Confidence and severity sit side by side on the
-* same card, and a reader who has not been told otherwise will assume they are the same scale
-* read twice — so the tooltip says they are not, in as many words.
-*/
-function confidenceTip(confidence) {
-	return `Confidence — how sure the analysis is that this issue is real. This is separate from how serious it would be. ${{
-		high: "High means the analysis is confident it’s real.",
-		medium: "Medium means it’s worth confirming in the code before acting on it.",
-		low: "Low means it was likely reasoned from the diff alone, so check the surrounding code first."
-	}[confidence]}`;
-}
-function importanceTip(importance) {
-	return `Importance — how much attention this question deserves during your review. ${position(importance, ATTENTION_SCALE)}.`;
-}
-/**
-* The four statuses an "Analyse new changes" pass assigns to a finding.
-*
-* Each says what the *product* concluded and, where it matters, how much to trust it. "Still open"
-* carries the load: it is both a real judgement ("the changes do not address this") and the safe
-* default applied when the analysis said nothing about a finding at all, and the reviewer cannot
-* tell those apart from the badge — so the copy commits to the weaker of the two readings rather
-* than claiming a judgement that may not have been made.
-*/
-function findingStatusTip(status) {
-	return {
-		resolved: "Resolved — the new commits appear to address this finding. Worth a glance to confirm before you close it out.",
-		"still-open": "Still open — the new commits do not address this finding. Findings the analysis did not comment on are shown this way too, so this never disappears on its own.",
-		affected: "Affected — the code this finding concerns has changed, but not in a way that settles it. Re-read this one.",
-		new: "New — introduced by the changes pushed since your previous analysis."
-	}[status];
-}
-/** The reviewer-facing label for a status. Kept beside the tooltips so the two cannot drift. */
-function findingStatusLabel(status) {
-	return {
-		resolved: "Resolved",
-		"still-open": "Still open",
-		affected: "Affected",
-		new: "New"
-	}[status];
-}
-/**
-* What the commits pushed since did to an open question.
-*
-* "Still open" carries the same double load it does on a finding: a real judgement, and the default
-* for a question the reassessment never mentioned. The copy commits to the weaker reading, because
-* the reviewer must not read silence as an answer.
-*/
-function questionStatusTip(status) {
-	return {
-		answered: "Answered — the new commits settle this, and the answer is below. Worth a glance to confirm before you drop it.",
-		"still-open": "Still open — the new commits do not settle this. Questions the reassessment did not comment on are shown this way too, so this never disappears on its own.",
-		affected: "Affected — the code this question is about has changed without answering it. Read the question again before you ask it."
-	}[status];
-}
-/** The reviewer-facing label for a question status. Kept beside the tooltip so the two cannot drift. */
-function questionStatusLabel(status) {
-	return {
-		answered: "Answered",
-		"still-open": "Still open",
-		affected: "Affected"
-	}[status];
-}
-/**
-* The four impacts a repository investigation assigns to a finding.
-*
-* Every one of these says the evidence came from *outside* the diff, because that is the whole
-* reason to trust them more than the analysis they revise — and equally the reason to say where
-* they came from. "A coding agent read the repository" is the qualification, and a reviewer who
-* does not know that cannot weigh it.
-*
-* "Investigated" carries the same load "Still open" does on the other axis: it is both a real
-* judgement ("this evidence does not bear on that finding") and the default applied when the
-* reassessment said nothing about a finding at all. The copy commits to the weaker reading rather
-* than claiming a judgement that may not have been made.
-*/
-function investigationImpactTip(impact) {
-	return {
-		confirmed: "Confirmed — a repository investigation found evidence supporting this finding. It no longer rests on the diff alone.",
-		refuted: "Refuted — a repository investigation found evidence that this concern does not hold. Kept on the list, with the reasoning, rather than removed.",
-		revised: "Revised — a repository investigation changed what this finding says. Where its severity or confidence moved, the previous value is shown alongside.",
-		unchanged: "Investigated — this finding was reassessed against a repository investigation and stands as it was. Findings the reassessment did not comment on are shown this way too."
-	}[impact];
-}
-/**
-* The reviewer-facing label. Note `unchanged` → "Investigated": the reviewer's world contains a
-* finding that was looked into and survived, which is information. "Unchanged" describes our
-* bookkeeping — what the field did — and says nothing about the code.
-*/
-function investigationImpactLabel(impact) {
-	return {
-		confirmed: "Confirmed",
-		refuted: "Refuted",
-		revised: "Revised",
-		unchanged: "Investigated"
-	}[impact];
-}
-var DISMISSED_TIP = "Dismissed by you — you decided this finding needs no action. It stops counting towards what is left, and stays here so the decision is visible rather than lost.";
-var DISMISSAL_STALE_TIP = "Changed since you dismissed this — the code under this finding has moved, so the reading you dismissed it on no longer holds. Your decision is kept; the finding is back on the list until you confirm it.";
-var SECTION_TAG_TIP = "Guide section — the section of the Guide this finding belongs to. Click to open it in the Guide tab.";
-/**
-* Builds a pill's `class` and `data-tip` attributes together.
-*
-* They are emitted as one string rather than left to the call site because they are useless
-* apart: `data-tip` without `pr-helper-tip` never renders, and `pr-helper-tip` without a tip
-* renders an empty black rectangle on hover. Taking the pill's own classes as an argument means
-* there is no way to add the tooltip and clobber the styling, which is what a bare
-* `class="pr-helper-tip"` helper would have invited.
-*
-* Emits a leading space so it drops straight in after a tag name.
-*/
-function pillAttrs(classNames, tip) {
-	return ` class="${escapeHtml$1(classNames)} pr-helper-tip" data-tip="${escapeHtml$1(tip)}"`;
-}
-//#endregion
 //#region ../../packages/review-harness/src/domain/ai_review/investigation_record.ts
 /**
 * The records for one finding, oldest first. Records accumulate: every "Investigate Again" appends.
@@ -2532,7 +2592,7 @@ function renderIssuesTab(session, investigatingId, options) {
     <div class="pr-helper-issue-card pr-helper-severity-${issue.severity}${issue.reconciliationStatus ? ` pr-helper-issue-${issue.reconciliationStatus}` : ""}${issue.investigationImpact ? ` pr-helper-issue-investigation-${issue.investigationImpact}` : ""}${isDismissed && !stale ? " pr-helper-issue-card-dismissed" : ""}" data-finding-card="${escapeHtml$1(issue.id)}">
       <div class="pr-helper-issue-header">
         <div class="pr-helper-issue-title-row">
-          ${options?.feedbackSelect ? renderFeedbackPick("issue", issue.title) : ""}
+          ${options?.feedbackSelect ? renderFeedbackPick("issue", issue.title, issueFeedbackMarkdown(issue)) : ""}
           <p class="pr-helper-issue-title">${renderInlineText(issue.title)}</p>
           ${renderFindingCopySource(issueMarkdown(issue), "issue")}
           ${options?.askBuddy ? renderAskBuddyMenu("issue") : ""}
@@ -2548,7 +2608,7 @@ function renderIssuesTab(session, investigatingId, options) {
       </div>
       ${renderStaleDismissal(stale)}
       ${renderSeverityRevision(issue.priorSeverity, issue.severity)}
-      <p class="pr-helper-issue-desc">${renderInlineText(issue.description)}</p>
+      <p class="pr-helper-issue-desc">${renderInlineText(issue.description)}</p>${renderCardExplanation(simpleExplanationOf(session, "issue", issue.id)?.text, options)}
       ${renderReconciliationNote(issue.reconciliationNote)}
       ${renderInvestigationNote(issue.investigationNote)}
       ${renderExistingDiscussion(issue.existingDiscussion)}
@@ -2581,6 +2641,14 @@ function closedFindingsSummary(counts) {
 	if (byCommits === 0) return `Dismissed by you (${counts.done})`;
 	return `Dealt with (${counts.done})`;
 }
+/**
+* The finding's simple explanation, under what the finding says and above where it stands. Nothing
+* at all when the reviewer has not asked for one, so such a card is the card it always was.
+*/
+function renderCardExplanation(text, options) {
+	if (!text?.trim()) return "";
+	return renderSimpleExplanation(text, { askMore: options?.askBuddy });
+}
 /** The reviewer's own decision, said on the card so the closed pile is never one undifferentiated heap. */
 function renderDismissedBadge(isDismissed) {
 	if (!isDismissed) return "";
@@ -2624,7 +2692,7 @@ var INTENT_QUESTION_GROUP = "prb-intent";
 function questionHome(q) {
 	return q.category === "intent" ? INTENT_QUESTION_GROUP : q.sectionId;
 }
-function renderQuestionCard(q, sections, answered, records, now = Date.now(), investigatingId, options) {
+function renderQuestionCard(q, sections, answered, records, now = Date.now(), investigatingId, options, explanation) {
 	const importanceBadge = q.importance ? `<span${pillAttrs(`pr-helper-question-importance-badge pr-helper-question-importance-${q.importance}`, importanceTip(q.importance))}>${escapeHtml$1(q.importance)}</span>` : "";
 	const jumpLink = renderQuestionJump(q.file, options);
 	const settled = q.reconciliationStatus === "answered";
@@ -2635,7 +2703,7 @@ function renderQuestionCard(q, sections, answered, records, now = Date.now(), in
     <div class="pr-helper-question-card${answered ? " pr-helper-question-card-answered" : ""}${q.investigationImpact ? ` pr-helper-issue-investigation-${q.investigationImpact}` : ""}" data-finding-card="${escapeHtml$1(q.id)}"${questionHome(q) ? ` data-section-id="${escapeHtml$1(questionHome(q))}"` : ""}>
       <div class="pr-helper-issue-header">
         <div class="pr-helper-issue-title-row">
-          ${options?.feedbackSelect ? renderFeedbackPick("question", q.question) : ""}
+          ${options?.feedbackSelect ? renderFeedbackPick("question", q.question, questionFeedbackMarkdown(q)) : ""}
           <p class="pr-helper-issue-title">${renderInlineText(q.question)}</p>
           ${renderFindingCopySource(questionMarkdown(q), "question")}
           ${options?.askBuddy ? renderAskBuddyMenu("question") : ""}
@@ -2652,7 +2720,7 @@ function renderQuestionCard(q, sections, answered, records, now = Date.now(), in
           ${importanceBadge}
         </div>
       </div>
-      ${q.whyThisMatters ? `<h5>Why this matters</h5><p class="pr-helper-issue-desc">${renderInlineText(q.whyThisMatters)}</p>` : ""}
+      ${q.whyThisMatters ? `<h5>Why this matters</h5><p class="pr-helper-issue-desc">${renderInlineText(q.whyThisMatters)}</p>` : ""}${renderCardExplanation(explanation, options)}
       ${reconciliationAnswer}
       ${renderReconciliationNote(q.reconciliationNote)}
       ${investigationAnswer}
@@ -2694,9 +2762,12 @@ function renderQuestionsProgress(questions, answered) {
 * `autocomplete="off"` because the browser otherwise restores a box's tick when the page is loaded
 * again from history, and the selection it belonged to went with the page that made it: Back to a
 * review showed a ticked box that nothing had selected.
+*
+* It carries the text the card gives a feedback draft, which is narrower than its Copy: see
+* finding_copy.ts.
 */
-function renderFeedbackPick(kind, title) {
-	return `<input type="checkbox" class="pr-helper-feedback-pick" data-feedback-pick="${kind}" autocomplete="off" aria-label="${escapeHtml$1(`Include in feedback: ${title.trim()}`)}">`;
+function renderFeedbackPick(kind, title, feedback) {
+	return `<input type="checkbox" class="pr-helper-feedback-pick" data-feedback-pick="${kind}" ${FEEDBACK_SOURCE_ATTR}="${escapeHtml$1(feedback)}" autocomplete="off" aria-label="${escapeHtml$1(`Include in feedback: ${title.trim()}`)}">`;
 }
 function renderQuestionJump(file, options) {
 	if (!file || options?.suppressFileJump) return "";
@@ -2716,7 +2787,7 @@ function renderQuestionsTab(session, investigatingId, options) {
 	const progress = renderQuestionsProgress(result.questions, answered);
 	const records = session.investigations;
 	const now = Date.now();
-	const card = (q) => renderQuestionCard(q, sections, answered.has(q.id), records, now, investigatingId, options);
+	const card = (q) => renderQuestionCard(q, sections, answered.has(q.id), records, now, investigatingId, options, simpleExplanationOf(session, "question", q.id)?.text);
 	const open = result.questions.filter((q) => isQuestionOutstanding(q, answered));
 	const settled = result.questions.filter((q) => !isQuestionOutstanding(q, answered));
 	const closed = settled.length === 0 ? "" : renderClosedFindings(`Answered (${settled.length})`, settled.map(card).join(""), "questions", open.length === 0);
@@ -10067,11 +10138,45 @@ function defaultFetchDeps() {
 }
 //#endregion
 //#region ../../packages/review-harness/src/workspace/help_page.ts
-/** The diagrams are text on purpose: they are the same ones `prreviewbuddy --help` prints. */
-var TOPICS = [{
-	id: "what-gets-reviewed",
-	title: "What gets reviewed",
-	body: `<p>A review is the combined change between a base and the branch you review, shown as one
+/**
+* The agents by their own names, from the registry, so a new adapter is named here without this
+* file being touched. One that will not load is left out rather than taking the page with it.
+*/
+var AGENT_PRODUCTS = ((names) => names.length <= 1 ? names[0] ?? "" : `${names.slice(0, -1).join(", ")} or ${names[names.length - 1]}`)([...AGENT_IDS].sort().flatMap((id) => {
+	try {
+		const agent = agentById(id);
+		return agent ? [agent.displayName] : [];
+	} catch {
+		return [];
+	}
+}));
+/**
+* The concepts behind the CLI's commands live here rather than in `prreviewbuddy --help`, which
+* says what to type and points here for what it means. The diagrams are text on purpose.
+*/
+var TOPICS = [
+	{
+		id: "getting-started",
+		title: "Getting started",
+		body: `<p>PR Review Buddy has a coding agent you already use (${escapeHtml$1(AGENT_PRODUCTS)})
+    analyse a change in a checkout of its own, and lays out what it found here, in your workspace,
+    for you to review. The agent's analysis is a guide to the change, not a verdict on it.</p>
+    <p>Start a review from a terminal, in the repository:</p>
+    <ul>
+      <li><code>prreviewbuddy review</code> for the branch you have checked out</li>
+      <li><code>prreviewbuddy review --pr &lt;url&gt;</code> for a pull request</li>
+      <li><code>prreviewbuddy open</code> to list the reviews you have and open this workspace</li>
+    </ul>
+    <p>Or press <kbd class="prb-kbd">⌘P</kbd> (<kbd class="prb-kbd">Ctrl+P</kbd> elsewhere) to add a
+    review from here. <code>prreviewbuddy help</code> lists every command, and
+    <code>prreviewbuddy review --help</code> every option a review takes.</p>
+    <p>There is no account and no API key. PR Review Buddy uses the coding agent installed on your
+    machine and that agent's existing authentication, and never asks you for a credential.</p>`
+	},
+	{
+		id: "what-gets-reviewed",
+		title: "What gets reviewed",
+		body: `<p>A review is the combined change between a base and the branch you review, shown as one
     diff. It is not just the latest commit. The base determines the split point: the commit where
     your branch left it (git calls this the merge-base). PR Review Buddy reviews the changes on your
     branch since that point.</p>
@@ -10111,10 +10216,115 @@ feature:                   E</pre>
     </ul>
     <p>Every review shows its own range. The commit count beside the branch name at the top of a
     review opens its split point and the commits it covers.</p>`
-}, {
-	id: "keyboard",
-	title: "Keyboard",
-	body: `<p>Press <kbd class="prb-kbd">⌘K</kbd> on a Mac, or <kbd class="prb-kbd">Ctrl+K</kbd>
+	},
+	{
+		id: "isolated-checkouts",
+		title: "Isolated checkouts",
+		body: `<p>Every review is made in an isolated checkout: a separate git worktree of your
+    repository, created at the exact commit being reviewed. Your own checkout is never read or
+    written while a review runs, so you can keep working, switch branches or leave uncommitted
+    changes where they are.</p>
+    <p>A review is pinned to that commit. Commits you add afterwards do not change it; Update review
+    brings it up to date when you are ready.</p>
+    <p>The checkout is kept for six hours after the review finishes, because it is what Buddy AI
+    reads to answer your questions about the change, and what Update review starts from. After
+    that it is removed. The review itself stays, and a later question makes a new checkout for
+    itself.</p>`
+	},
+	{
+		id: "updating-and-reanalysing",
+		title: "Updating and reanalysing",
+		body: `<p>Four things can happen to a review once it exists. Each is a flag on
+    <code>prreviewbuddy review</code>, and the ones you need most are also in the workspace.</p>
+    <ul>
+      <li><b>Update</b> brings the review up to date with commits added since it was made. Its
+      findings are checked against the new commits rather than thrown away, and each says whether
+      the new commits affected it. In the workspace, Update review appears on a review whose
+      branch has moved on.</li>
+      <li><b>Reanalyse</b> analyses the same commit again, for a fresh judgement of the same change,
+      for example with a different model.</li>
+      <li><b>Fresh review</b> reviews the target again as a new review, and keeps the existing one
+      beside it.</li>
+      <li><b>Delete</b> removes a review and the checkouts it was made in. See
+      <a href="#reviews-and-ids">Reviews and review IDs</a>.</li>
+    </ul>`
+	},
+	{
+		id: "reviews-and-ids",
+		title: "Reviews and review IDs",
+		body: `<p>The same branch can have more than one review: a fresh review, for one, keeps the review
+    before it. A review ID tells them apart. It identifies one review, not a branch, and stays the same when the review is updated
+    or reanalysed.</p>
+    <p>Copy review ID is in each review's menu, and <code>prreviewbuddy open</code> prints the ID
+    beside every review. Use it with <code>--review</code> to act on that one review from a
+    terminal.</p>
+    <p>Deleting a review removes its record and the isolated checkouts it was made in. It never
+    touches your branch or its commits. Delete one from its menu, or tick reviews in the Reviews
+    list, one at a time or a whole branch at once, and delete them together.</p>`
+	},
+	{
+		id: "several-pull-requests",
+		title: "Several pull requests at once",
+		body: `<p><code>prreviewbuddy review --pr &lt;url&gt; &lt;url&gt; …</code> makes one ordinary
+    review per pull request, each with its own link, and prints them all when it ends. Two run at
+    a time unless <code>--concurrency</code> says otherwise.</p>
+    <p>One that fails does not stop the others. Ctrl-C stops them all, and running the same command
+    again carries each one on from where it got to. Add <code>--queue</code> to put each review on
+    your review queue as soon as it exists, rather than when it is ready.</p>`
+	},
+	{
+		id: "review-lenses",
+		title: "Review lenses",
+		body: `<p>A review lens asks a specialised question of the same change. It runs beside the
+    standard review, in the same workspace, rather than replacing it, and it does not need the
+    standard review to have been made first.</p>
+    <p>The KISS lens asks not whether the change is correct, but whether the complexity it
+    introduces is justified, or whether the same requirements could be met with less
+    machinery.</p>
+    <p>A lens writes for one of two audiences, and you always say which:</p>
+    <ul>
+      <li><b>Author</b>: for whoever wrote the change, as changes to make before submitting it.</li>
+      <li><b>Reviewer</b>: for somebody reviewing somebody else's work, with whether each point is
+      worth raising.</li>
+    </ul>
+    <p>It is never guessed from what you are reviewing, because a reviewer checks out somebody
+    else's branch and an author reviews their own pull request. Run one with
+    <code>prreviewbuddy review --lens kiss --audience author</code> or
+    <code>--audience reviewer</code>.</p>`
+	},
+	{
+		id: "workspace-server",
+		title: "The workspace server",
+		body: `<p>One workspace server on your machine serves every review. It keeps running after the
+    terminal that started it closes, so a review stays open, and its link keeps working, until you
+    stop the server.</p>
+    <p>Your workspace is at <code>http://localhost:${DEFAULT_WORKSPACE_PORT}</code> unless you have
+    moved it. Change the port in Settings, or with <code>prreviewbuddy config set port</code>; the new
+    port is used the next time the server starts. If another program is already on that port, PR
+    Review Buddy stops and says so rather than quietly moving somewhere you have not
+    bookmarked.</p>
+    <p>Restart the server with the button in the bar at the top. Stop it from Settings, which
+    stops every open review, not only the one in front of you. Nothing is deleted, and
+    <code>prreviewbuddy open</code> starts it again from any directory.</p>`
+	},
+	{
+		id: "retention",
+		title: "How long things are kept",
+		body: `<p>Everything lives in <code>~/.prreviewbuddy</code> on your machine, and is cleared up
+    automatically:</p>
+    <ul>
+      <li><b>Reviews</b> are kept for thirty days after you last opened or changed them.</li>
+      <li><b>Reviews you kept</b> (saved, marked Done, or on your review queue) are kept for ninety
+      days instead.</li>
+      <li><b>Isolated checkouts</b> are removed six hours after their work finishes. See
+      <a href="#isolated-checkouts">Isolated checkouts</a>.</li>
+    </ul>
+    <p><code>prreviewbuddy uninstall</code> removes all of it at once.</p>`
+	},
+	{
+		id: "keyboard",
+		title: "Keyboard",
+		body: `<p>Press <kbd class="prb-kbd">⌘K</kbd> on a Mac, or <kbd class="prb-kbd">Ctrl+K</kbd>
     elsewhere, to open the command palette. It lists what you can do on the page you are on, and
     after a key like <kbd class="prb-kbd">M</kbd> it shows the keys that can follow. It stays open
     until you choose something or press Escape. <kbd class="prb-kbd">⌘K</kbd> then
@@ -10122,7 +10332,14 @@ feature:                   E</pre>
     <p>Single keys, such as <kbd class="prb-kbd">J</kbd> and <kbd class="prb-kbd">K</kbd> on the
     Reviews list, never act while you are typing in a field.</p>
     <div data-shortcut-table></div>`
-}];
+	}
+];
+/** Every topic by name at the top, so one in the middle is found by reading a list, not a page. */
+function renderContents() {
+	return `<nav class="prb-help-contents" aria-label="Help topics">
+    <ul>${TOPICS.map((topic) => `<li><a href="#${topic.id}">${escapeHtml$1(topic.title)}</a></li>`).join("")}</ul>
+  </nav>`;
+}
 function renderHelpPage(view) {
 	return `<!doctype html>
 <html lang="en"${themeAttribute(view.theme)}>
@@ -10147,6 +10364,7 @@ ${renderWorkspaceRail({
 		unread: view.unreadNotifications ?? 0
 	})}
 <main class="prb-index prb-help">
+  ${renderContents()}
   ${TOPICS.map((topic) => `<section class="prb-help-topic" id="${topic.id}">
     <h2>${escapeHtml$1(topic.title)}</h2>
     ${topic.body}
@@ -11059,14 +11277,14 @@ var AskFailedError = class extends Error {};
 * the assistant keeps working after the session that produced the review has closed, which is the
 * whole reason the workspace is served rather than written to a file.
 */
-async function askAboutChange(workspace, question, sectionId, signal) {
+async function askAboutChange(workspace, question, sectionId, signal, context = {}) {
 	const cwd = await askCheckout(workspace);
 	const env = agentEnvOf(workspace);
 	const requestedModel = resolveModel({ review: { session: workspace.session } }) ?? void 0;
 	try {
 		return extractAnswer(await withUsageRecorded(workspace.id, "ask", env, (onUsage) => agentFor$1(env).run({
 			capability: "read-code",
-			prompt: buildPrompt$2(workspace, question, sectionId, cwd),
+			prompt: buildPrompt$2(workspace, question, sectionId, cwd, context),
 			cwd,
 			originRepoPath: workspace.repoPath,
 			env,
@@ -11125,7 +11343,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$2(workspace, question, sectionId, cwd) {
+function buildPrompt$2(workspace, question, sectionId, cwd, context = {}) {
 	const sections = workspace.session.result?.sections ?? [];
 	const reading = readingThemeLine(sections, sectionId);
 	const recent = workspace.transcript.slice(-4);
@@ -11148,10 +11366,47 @@ function buildPrompt$2(workspace, question, sectionId, cwd) {
 				return `Q${where ? ` ${where}` : ""}: ${entry.question}\nA: ${entry.answer}`;
 			}).join("\n\n")
 		] : [],
+		...continuingFrom(workspace, context.continuing),
+		...explainingFinding(workspace, context.explaining),
 		"---",
 		`QUESTION: ${question}`
 	].join("\n");
 }
+/**
+* The simple explanation a follow-up was asked from, however long ago it was written.
+*
+* Given in full rather than left to the recent turns above, which hold only the last four: a
+* reviewer who comes back a week later and presses Ask more is continuing from the explanation on
+* the card, not from whatever the conversation happens to still remember.
+*/
+function continuingFrom(workspace, continuing) {
+	if (!continuing) return [];
+	return [
+		"---",
+		`THE REVIEWER IS CONTINUING FROM THIS PLAIN-ENGLISH EXPLANATION YOU GAVE EARLIER OF ${findingName(workspace, continuing)}:`,
+		continuing.text
+	];
+}
+/**
+* Explain simply on a finding, whose answer is kept on the card and read again after the code has
+* moved on. So it explains the claim, what the finding says and why it was raised, rather than
+* asserting what the code does now: a later update or investigation says whether the claim still
+* holds, and an explanation written as a present-tense fact about the code would contradict it.
+*/
+function explainingFinding(workspace, explaining) {
+	if (!explaining) return [];
+	return [
+		"---",
+		`THE REVIEWER ASKED FOR A SIMPLE EXPLANATION OF ${findingName(workspace, explaining)}. It is kept beside that finding and read again later, possibly after the code has changed.`,
+		"Explain in plain English what the finding is saying and why it was raised: the concern as the review stated it, in terms of what was reviewed (for example \"this was raised because...\"), not as a statement about how the code behaves now. Do not judge whether it still holds; the review tracks that separately."
+	];
+}
+/** `THE ISSUE "<title>"` or `THE QUESTION "<question>"`, or just the kind when the finding is gone. */
+function findingName(workspace, finding) {
+	const result = workspace.session.result;
+	const title = finding.kind === "issue" ? result?.issues.find((issue) => issue.id === finding.id)?.title : result?.questions.find((question) => question.id === finding.id)?.question;
+	return `THE ${finding.kind.toUpperCase()}${title ? ` "${title.trim()}"` : ""}`;
+}
 //#endregion
 //#region ../../packages/review-harness/src/workspace/diagram.ts
 /** The same budget a question gets. Drawing is reading, and reading is what takes the time. */
@@ -13439,6 +13694,9 @@ async function handleAsk(req, res, workspace) {
 	const question = typeof body?.question === "string" ? body.question.trim() : "";
 	if (!question) return send(res, 400, { error: "No question given." });
 	const sectionId = typeof body?.sectionId === "string" ? body.sectionId : null;
+	const explains = findingNamed(workspace.session, body?.explains);
+	const continuesFrom = findingNamed(workspace.session, body?.continuesExplanation);
+	const continuing = continuesFrom ? simpleExplanationOf(workspace.session, continuesFrom.kind, continuesFrom.id) : void 0;
 	if (liveUpdateFor(workspace.id)) return send(res, 409, {
 		error: "This review is being updated. Ask again when the new review is ready.",
 		updating: true
@@ -13470,7 +13728,10 @@ async function handleAsk(req, res, workspace) {
 	try {
 		let answer;
 		try {
-			answer = await askAboutChange(workspace, question, sectionId, run.signal);
+			answer = await askAboutChange(workspace, question, sectionId, run.signal, {
+				...explains ? { explaining: explains } : {},
+				...continuing ? { continuing } : {}
+			});
 		} catch (error) {
 			failed();
 			if (run.state === "stopped") return sendIfOpen(res, 200, { stopped: true });
@@ -13486,6 +13747,7 @@ async function handleAsk(req, res, workspace) {
 			durationMs: Date.now() - startedAt,
 			ok: true
 		});
+		let explanation;
 		mutateWorkspace(workspace.id, (fresh) => {
 			fresh.transcript.push({
 				question,
@@ -13493,12 +13755,38 @@ async function handleAsk(req, res, workspace) {
 				sectionId,
 				askedAt: Date.now()
 			});
+			if (explains && findingNamed(fresh.session, explains) && answer.trim()) {
+				explanation = {
+					...explains,
+					text: answer.trim()
+				};
+				fresh.session.simpleExplanations = withSimpleExplanation(fresh.session.simpleExplanations, explanation);
+			}
 		});
-		sendIfOpen(res, 200, { answer });
+		sendIfOpen(res, 200, explanation ? {
+			answer,
+			explanation
+		} : { answer });
 	} finally {
 		endRun(run);
 	}
 }
+/** An issue or question of this review, named by kind and id; null for anything else. */
+function findingNamed(session, value) {
+	const named = value;
+	if (typeof named?.id !== "string") return null;
+	const id = named.id;
+	const result = session.result;
+	if (named.kind === "issue") return result?.issues.some((issue) => issue.id === id) ? {
+		kind: "issue",
+		id
+	} : null;
+	if (named.kind === "question") return result?.questions.some((question) => question.id === id) ? {
+		kind: "question",
+		id
+	} : null;
+	return null;
+}
 /** Only while somebody is listening. A page that left took its socket with it. */
 function sendIfOpen(res, status, body) {
 	if (res.writableEnded || res.destroyed) return;