prreviewbuddy 0.83.3 → 0.85.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 0.85.0
+
+**Replay the guided tour from any review.** A review's ⋯ menu now has Replay guided tour, which
+runs the tour on the review you are reading. Replay in Help opens the review you opened last, or,
+if that one is being analysed or updated, your newest review the tour can start on. It never picks
+a review that is busy while another would do. When the tour cannot start, you are told why rather
+than left on a page where nothing happens.
+
+## 0.84.2
+
+**Replay guided tour sits below its sentence** on Help's Welcome, rather than beside it.
+
+## 0.84.1
+
+**Replay guided tour is readable.** The button on Help's Welcome showed its label in the link
+colour on its own purple, so the words could not be seen. They are white now.
+
+## 0.84.0
+
+**A guided tour of your first review.** The first time you open a completed review, a short tour
+walks you through it: the story behind the change, where to focus, the suggested path, diagrams,
+issues, questions, the files, Buddy AI, and the review status that records your judgement. Each
+stop lights up the part of the page it describes. Skip it, or press Escape, and it does not come
+back by itself. Replay it from Help's Welcome at any time. The tour changes nothing about your
+review or your layout: whatever it opens to show you, it puts back.
+
+## 0.83.4
+
+**Help opens on Welcome, and its index stays beside you.** Help now starts with a short welcome:
+why PR Review Buddy exists, and the three principles behind it. The list of topics moves from the
+top of the page to a column beside them that stays in view as you scroll, and marks the topic you
+are reading. In a narrow window it goes back above the topics.
+
+**No underlined links.** Links across the workspace are told apart by colour, not underlines, at
+rest or on hover.
+
 ## 0.83.3
 
 **Peek at a collapsed sidebar.** Rest the pointer on the collapsed sidebar, or tab into it, and it

package/dist/server.js

@@ -1,4 +1,4 @@
-import { $ as MIN_WORKSPACE_PORT, $i as resolveModel, $n as RUN_RECORD_RETENTION_MS, $r as deleteCollection, $t as markRead, A as batchIdentity, Ai as isGradeFor, An as escapeHtml$1, At as loadArchitecture, Bi as WITHHELD_REASON, Bn as readMarker, Br as LIFECYCLES, Bt as ancestorsOf, C as RUN_KINDS, Ci as ANALYSIS_ONLY, Cn as UNESTABLISHED_MOTIVATION, Cr as kissDecisionsOf, Ct as mapRuntimes, D as reportRun, Di as findingAssessment, Dn as renderMarkdown, Dr as loadWorkspace, Dt as formatDuration, E as endRun, Ei as currentGradeIn, En as GITHUB_MARKDOWN, Er as lineagePosition, Et as describeRuntimes, F as activateQueued, Fi as followUpFindingId, Fn as withReviewLock, Ft as storedScopes, G as serverEntryExists, Gi as isCommitReview, Gn as findExistingReview, Gr as lifecycleItemLabel, Gt as subjectOf, Hi as resolveTarget, Hn as requestJobStop, Hr as activityLabel, Ht as writeJsonAtomically, I as compactQueue, Ii as asString, In as MANAGED_ROOT, Ir as summarise, It as trackedFiles, Ji as shortNameOf, Jn as followedBranch, Jr as parseLifecycle, Jt as createPrState, K as spawnServer, Ki as resolveBase, Kn as checkCodeFreshness, Kr as lifecyclePill, Kt as categoryOf, Li as extractJsonText, Ln as createWorktree, Lr as touchWorkspace, Lt as ownersOf, M as parsePullRequestLink, Mi as reassessIn, Mr as previousKissResult, Mt as readArchitecture, N as unsupportedReason, Ni as sourcePhrase, Nn as ReviewBeingDeletedError, Nr as recentWorkspaces, Nt as repositoryKey, O as stopRun, Oi as findingIn, On as CODE_BLOCK_CLASS, Ot as ARCHITECTURE_DIR, P as runBatch, Pi as wasReassessed, Pn as isBusy, Pr as reviewedCommit, Pt as storeArchitecture, Q as MAX_WORKSPACE_PORT, Qi as resolveAgent, Qn as fillFileUrlTemplate, Qr as createWithMembers, Qt as markAllRead, R as settleQueue, Ri as objectWithAnyOf, Rn as holdWorktree, Rr as workspaceRevision, Rt as QUOTE_LIMITS, S as track, Si as withExplanation, Sn as chatConversationSection, Sr as kissDecisionRefusal, St as waitingHistory, T as completeRun, Ti as assessmentLookup, Tn as hasAuthorContent, Tr as lineageKey, Tt as RUNTIME_WORDS, U as readServerRecord, Ui as originRemote, Ur as isLifecycle, Ut as announceJob, V as clearServerRecordOwnedBy, Vi as kissOutcome, Vn as removeWorktree, Vr as activityAttributes, Vt as isArchitectureId, Wi as DetachedHeadError, Wr as lifecycleChip, Wt as branchOf, X as writeServerRecord, Xi as git, Xn as fetchHead, Xr as collectionsStamp, Xt as eventName, Yi as shorthandOf, Yn as reviewedShaOf, Yr as sectionOf, Yt as createPrUpdate, Z as DEFAULT_WORKSPACE_PORT, Zi as refExists, Zn as forgeResolver, Zr as createCollection, Zt as listNotifications, _i as processDiscussion, _n as unforeseenFailure, _r as decideKissRecommendation, _t as telemetryUploadConsent, a as wasBlocked, aa as STORE_ROOT, ai as queueAdd, an as removeNotification, ar as loadJob, at as observeReview, b as startKissJob, bi as explanationOf, bn as agentEnvOf, br as indexKeptIds, c as RefreshUnavailableError, ca as agentFor$1, ci as queueStamp, cn as unreadAround, ct as reanalyseReview, d as mergeUpdateInto, da as isAgentId, di as isIssueOutstanding, dn as existingPaths, dr as phasesFor, ea as agentIdOf, ei as nameProblemText, en as markReadForReview, er as allJobs, et as parseWorkspacePort, fa as parkedReason, fi as isQuestionOutstanding, fn as ASK_REREAD_CEILING_MS, fr as progressSteps, ft as readEvents, g as liveUpdateFor, gi as reviewerDispositions, gn as storedConversation, gt as recordTelemetryUploadConsent, h as UpdateAlreadyRunningError, ha as AgentUnavailableError, hi as resolvedByConversation, hn as saveRefresh, hr as isClaimed, i as liveJobsFor, ii as updateCollections, in as readStateOf, ir as isTerminal, it as failureOf$1, j as extractPullRequestLinks, ji as promptGrade, jn as renderInlineText, jr as presentedKissRunOf, jt as partFiles, k as relativeTime$1, ki as gradeScale, kn as CODE_COPY_CLASS, kr as mutateWorkspace, kt as checkArchitecture, l as cancelUpdate, la as agentIdentityOf, li as readQueue, ln as unreadCount$1, lr as isLiveJob, lt as runJob, m as askCheckout, ma as AgentCancelledError, mi as questionsOutstanding, mn as prepareConversationWithin, n as deleteReview, na as readAgentPreference, ni as renameCollection, nn as pruneNotifications, nr as endedAt, nt as statedWorkspacePort, o as discardJob, oa as AGENT_IDS, oi as queueAddMany, on as retireNotification, or as pruneJobResidue, ot as prepareReview, p as updateReview, pa as runnableAgents, pi as issuesOutstanding, pn as adoptLegacyBaseline, pr as purposeOf, pt as record, q as stopChild, qi as AmbiguousRefError, qn as checkReview, qr as offersLifecycle, qt as createArchitectureNotification, r as lineageIds, ra as writeAgentPreference, ri as setMembership, rn as readNotification, rr as fail$1, rt as writePortPreference, s as FETCH_TIMEOUT_MS, sa as agentById, si as queueRemove, sn as toneOf, sr as saveJob, st as settleReview, t as deleteLineage, ta as clearAgentPreference, ti as readCollections, tn as moveIds, tr as attemptIdOf, tt as resolveWorkspacePort, u as cancellableHere, ua as detectAgents, ui as doneVerb, un as withUsageRecorded, ur as isTerminalJobPhase, v as kissAgentId, vi as recommendationsOf, vn as refreshPrContext, vr as followedRefName, w as beginRun, wi as analysisRefOf, wn as authorPreview, wr as latestKissRun, wt as recordRuntimeBestEffort, x as isDriving, xi as isExplanationAction, xn as EXPLAIN_SIMPLY_PROMPT, xr as indexReviewGroups, xt as feedbackUrl, yi as explanationActionOf, yn as isUnchanged, yr as groupByLineage, yt as BUILD_VERSION, z as readIndexToken, zi as describeAuthorship, zn as isWorktreeHeld, zr as workspaceStamps, zt as REPOSITORY_SCOPE } from "./delete_review-BED4mPxB.js";
+import { $ as MIN_WORKSPACE_PORT, $i as resolveModel, $n as RUN_RECORD_RETENTION_MS, $r as deleteCollection, $t as markRead, A as batchIdentity, Ai as isGradeFor, An as escapeHtml$1, At as loadArchitecture, Bi as WITHHELD_REASON, Bn as readMarker, Br as LIFECYCLES, Bt as ancestorsOf, C as RUN_KINDS, Ci as ANALYSIS_ONLY, Cn as UNESTABLISHED_MOTIVATION, Cr as kissDecisionsOf, Ct as mapRuntimes, D as reportRun, Di as findingAssessment, Dn as renderMarkdown, Dr as loadWorkspace, Dt as formatDuration, E as endRun, Ei as currentGradeIn, En as GITHUB_MARKDOWN, Er as lineagePosition, Et as describeRuntimes, F as activateQueued, Fi as followUpFindingId, Fn as withReviewLock, Ft as storedScopes, G as serverEntryExists, Gi as isCommitReview, Gn as findExistingReview, Gr as lifecycleItemLabel, Gt as subjectOf, Hi as resolveTarget, Hn as requestJobStop, Hr as activityLabel, Ht as writeJsonAtomically, I as compactQueue, Ii as asString, In as MANAGED_ROOT, Ir as summarise, It as trackedFiles, Ji as shortNameOf, Jn as followedBranch, Jr as parseLifecycle, Jt as createPrState, K as spawnServer, Ki as resolveBase, Kn as checkCodeFreshness, Kr as lifecyclePill, Kt as categoryOf, Li as extractJsonText, Ln as createWorktree, Lr as touchWorkspace, Lt as ownersOf, M as parsePullRequestLink, Mi as reassessIn, Mr as previousKissResult, Mt as readArchitecture, N as unsupportedReason, Ni as sourcePhrase, Nn as ReviewBeingDeletedError, Nr as recentWorkspaces, Nt as repositoryKey, O as stopRun, Oi as findingIn, On as CODE_BLOCK_CLASS, Ot as ARCHITECTURE_DIR, P as runBatch, Pi as wasReassessed, Pn as isBusy, Pr as reviewedCommit, Pt as storeArchitecture, Q as MAX_WORKSPACE_PORT, Qi as resolveAgent, Qn as fillFileUrlTemplate, Qr as createWithMembers, Qt as markAllRead, R as settleQueue, Ri as objectWithAnyOf, Rn as holdWorktree, Rr as workspaceRevision, Rt as QUOTE_LIMITS, S as track, Si as withExplanation, Sn as chatConversationSection, Sr as kissDecisionRefusal, St as waitingHistory, T as completeRun, Ti as assessmentLookup, Tn as hasAuthorContent, Tr as lineageKey, Tt as RUNTIME_WORDS, U as readServerRecord, Ui as originRemote, Ur as isLifecycle, Ut as announceJob, V as clearServerRecordOwnedBy, Vi as kissOutcome, Vn as removeWorktree, Vr as activityAttributes, Vt as isArchitectureId, Wi as DetachedHeadError, Wr as lifecycleChip, Wt as branchOf, X as writeServerRecord, Xi as git, Xn as fetchHead, Xr as collectionsStamp, Xt as eventName, Yi as shorthandOf, Yn as reviewedShaOf, Yr as sectionOf, Yt as createPrUpdate, Z as DEFAULT_WORKSPACE_PORT, Zi as refExists, Zn as forgeResolver, Zr as createCollection, Zt as listNotifications, _ as runningJobs, _i as processDiscussion, _n as unforeseenFailure, _r as decideKissRecommendation, _t as telemetryUploadConsent, a as wasBlocked, aa as STORE_ROOT, ai as queueAdd, an as removeNotification, ar as loadJob, at as observeReview, b as startKissJob, bi as explanationOf, bn as agentEnvOf, br as indexKeptIds, c as RefreshUnavailableError, ca as agentFor$1, ci as queueStamp, cn as unreadAround, ct as reanalyseReview, d as mergeUpdateInto, da as isAgentId, di as isIssueOutstanding, dn as existingPaths, dr as phasesFor, ea as agentIdOf, ei as nameProblemText, en as markReadForReview, er as allJobs, et as parseWorkspacePort, fa as parkedReason, fi as isQuestionOutstanding, fn as ASK_REREAD_CEILING_MS, fr as progressSteps, ft as readEvents, g as liveUpdateFor, gi as reviewerDispositions, gn as storedConversation, gt as recordTelemetryUploadConsent, h as UpdateAlreadyRunningError, ha as AgentUnavailableError, hi as resolvedByConversation, hn as saveRefresh, hr as isClaimed, i as liveJobsFor, ii as updateCollections, in as readStateOf, ir as isTerminal, it as failureOf$1, j as extractPullRequestLinks, ji as promptGrade, jn as renderInlineText, jr as presentedKissRunOf, jt as partFiles, k as relativeTime$1, ki as gradeScale, kn as CODE_COPY_CLASS, kr as mutateWorkspace, kt as checkArchitecture, l as cancelUpdate, la as agentIdentityOf, li as readQueue, ln as unreadCount$1, lr as isLiveJob, lt as runJob, m as askCheckout, ma as AgentCancelledError, mi as questionsOutstanding, mn as prepareConversationWithin, n as deleteReview, na as readAgentPreference, ni as renameCollection, nn as pruneNotifications, nr as endedAt, nt as statedWorkspacePort, o as discardJob, oa as AGENT_IDS, oi as queueAddMany, on as retireNotification, or as pruneJobResidue, ot as prepareReview, p as updateReview, pa as runnableAgents, pi as issuesOutstanding, pn as adoptLegacyBaseline, pr as purposeOf, pt as record, q as stopChild, qi as AmbiguousRefError, qn as checkReview, qr as offersLifecycle, qt as createArchitectureNotification, r as lineageIds, ra as writeAgentPreference, ri as setMembership, rn as readNotification, rr as fail$1, rt as writePortPreference, s as FETCH_TIMEOUT_MS, sa as agentById, si as queueRemove, sn as toneOf, sr as saveJob, st as settleReview, t as deleteLineage, ta as clearAgentPreference, ti as readCollections, tn as moveIds, tr as attemptIdOf, tt as resolveWorkspacePort, u as cancellableHere, ua as detectAgents, ui as doneVerb, un as withUsageRecorded, ur as isTerminalJobPhase, v as kissAgentId, vi as recommendationsOf, vn as refreshPrContext, vr as followedRefName, w as beginRun, wi as analysisRefOf, wn as authorPreview, wr as latestKissRun, wt as recordRuntimeBestEffort, x as isDriving, xi as isExplanationAction, xn as EXPLAIN_SIMPLY_PROMPT, xr as indexReviewGroups, xt as feedbackUrl, yi as explanationActionOf, yn as isUnchanged, yr as groupByLineage, yt as BUILD_VERSION, z as readIndexToken, zi as describeAuthorship, zn as isWorktreeHeld, zr as workspaceStamps, zt as REPOSITORY_SCOPE } from "./delete_review-BED4mPxB.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";
@@ -2562,11 +2562,11 @@ function renderOverviewTab(session, iconUrl = "", options) {
 	return `
     ${options?.authorContext ? renderAuthorContext(session, options.descriptionLink) : renderDescriptionLink(session, options?.descriptionLink)}
     ${renderWhyThisChange(result.motivation, session, result.questions, options)}
-    <section class="pr-helper-whats-changing" aria-labelledby="pr-helper-whats-changing-heading">
+    <section class="pr-helper-whats-changing" data-tour="whats-changing" aria-labelledby="pr-helper-whats-changing-heading">
       <h4 class="pr-helper-overview-heading" id="pr-helper-whats-changing-heading">What's changing</h4>
       <div class="pr-helper-review-summary pr-helper-markdown">${renderMarkdown(result.summary)}</div>
     </section>
-    <div class="pr-helper-risk-headline">
+    <div class="pr-helper-risk-headline" data-tour="risk">
       <div class="pr-helper-risk-headline-top">
         <span class="pr-helper-risk-dot pr-helper-risk-dot-${result.overallRisk}"></span>
         <span class="pr-helper-risk-headline-label">${escapeHtml$1(titleCase(result.overallRisk))} Risk</span>
@@ -2575,7 +2575,7 @@ function renderOverviewTab(session, iconUrl = "", options) {
       ${renderProvisionalReason(session)}
       ${result.recommendation ? `<div class="pr-helper-risk-headline-takeaway pr-helper-markdown">${renderMarkdown(result.recommendation)}</div>` : ""}
     </div>
-    <div class="pr-helper-overview-stats">
+    <div class="pr-helper-overview-stats" data-tour="stats">
       ${renderOverviewStat(metrics.sections, "Themes", "guide")}
       ${renderIssuesStat(issuesOutstanding(result.issues, reviewerDispositions(session)))}
       ${renderRemainingStat(questionsOutstanding(result.questions, new Set(session.answeredQuestionIds ?? [])), "Questions", "questions", "answered")}
@@ -2698,7 +2698,7 @@ function renderSuggestedPath(sections, heading) {
 	if (sections.length === 0) return "";
 	const items = sections.map((s) => `<li>${escapeHtml$1(s.title)}</li>`).join("");
 	return `
-    <div class="pr-helper-suggested-path">
+    <div class="pr-helper-suggested-path" data-tour="suggested-path">
       <h4 class="pr-helper-suggested-path-title">${escapeHtml$1(heading)}</h4>
       <ol class="pr-helper-suggested-path-list">${items}</ol>
       <p class="pr-helper-suggested-path-time">Estimated review time ≈${estimateTotalMinutes(sections)} minutes</p>
@@ -3555,6 +3555,42 @@ 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/workspace/guided_tour.ts
+function isGuidedTourState(value) {
+	return value === "completed" || value === "dismissed";
+}
+/**
+* Whether a review page opens the tour by itself: a live page (one with a server behind it) over a
+* standard result that no update is replacing, for a reviewer who has not already finished or
+* skipped it. Running reviews never qualify, so the tour cannot interrupt one.
+*/
+function offersGuidedTour(page) {
+	return page.live && page.hasResult && !page.updating && page.state === void 0;
+}
+/** The hash Replay opens a review at. Not a place the page knows, so the page drops it once read. */
+var TOUR_REPLAY_HASH = "#tour";
+/**
+* Whether the tour can be shown on a review: its analysis finished, and nothing is analysing or
+* updating it now. Whether the reviewer has marked it Reviewed has nothing to do with it.
+*/
+function tourEligible(review, busy) {
+	return review.hasStandardReview && !busy.has(review.id);
+}
+/**
+* The review Replay from Help opens: the one last opened, when the tour can be shown on it, and
+* otherwise the newest it can be shown on. Never a busy review, so none is chosen only when no
+* review qualifies. Replay from a review's own menu does not ask: it uses the review on screen.
+*/
+function chooseTourReview(reviews, busy) {
+	const last = reviews.filter((review) => review.lastViewedAt !== void 0).reduce((best, review) => !best || review.lastViewedAt > best.lastViewedAt ? review : best, null);
+	if (last && tourEligible(last, busy)) return last;
+	return reviews.filter((review) => tourEligible(review, busy)).reduce((best, review) => !best || review.createdAt > best.createdAt ? review : best, null);
+}
+function tourUnavailable(reviews, busy) {
+	if (chooseTourReview(reviews, busy)) return null;
+	return reviews.some((review) => review.hasStandardReview) ? "busy" : "none";
+}
+//#endregion
 //#region ../../packages/review-harness/src/domain/change_map/types.ts
 var MAP_ROLES = [
 	"intent",
@@ -6151,7 +6187,12 @@ function renderWorkspace(view) {
 <link rel="stylesheet" href="/assets/sidebar.css">
 <link rel="stylesheet" href="/assets/shell.css">
 </head>
-<body data-api-base="${escapeHtml$1(view.apiBase)}"${view.token ? ` data-token="${escapeHtml$1(view.token)}" data-notifications-since="${Date.now()}"` : ""}${view.editor ? ` data-editor-label="${escapeHtml$1(view.editor.label)}" data-editor-template="${escapeHtml$1(view.editor.template)}"` : ""}${view.repoPath ? ` data-repo-path="${escapeHtml$1(view.repoPath)}"` : ""}${view.revision === void 0 ? "" : ` data-workspace-revision="${escapeHtml$1(String(view.revision))}"`} data-session-id="${escapeHtml$1(view.session.id)}" data-explain-prompt="${escapeHtml$1(EXPLAIN_SIMPLY_PROMPT)}" data-way-back="${escapeHtml$1(wayBackSentence())}" data-default-view="${session.result ? "overview" : showsProgress(view) ? "progress" : "kiss"}">
+<body data-api-base="${escapeHtml$1(view.apiBase)}"${view.token ? ` data-token="${escapeHtml$1(view.token)}" data-notifications-since="${Date.now()}"` : ""}${view.editor ? ` data-editor-label="${escapeHtml$1(view.editor.label)}" data-editor-template="${escapeHtml$1(view.editor.template)}"` : ""}${view.repoPath ? ` data-repo-path="${escapeHtml$1(view.repoPath)}"` : ""}${view.revision === void 0 ? "" : ` data-workspace-revision="${escapeHtml$1(String(view.revision))}"`} data-session-id="${escapeHtml$1(view.session.id)}" data-explain-prompt="${escapeHtml$1(EXPLAIN_SIMPLY_PROMPT)}" data-way-back="${escapeHtml$1(wayBackSentence())}" data-default-view="${session.result ? "overview" : showsProgress(view) ? "progress" : "kiss"}"${offersGuidedTour({
+		live: view.token !== void 0,
+		hasResult: Boolean(session.result),
+		updating: updating(view),
+		state: view.guidedTour
+	}) ? " data-guided-tour=\"offer\"" : ""}${view.tourBusy ? " data-tour-busy" : ""}>
 ${renderGlobalBar({
 		unread: view.unreadNotifications ?? 0,
 		live: Boolean(view.token),
@@ -6689,6 +6730,7 @@ function renderIdMenu(view, freshness) {
 		branchItems ? `<button type="button" class="prb-menu-item" data-queue-action="${view.queued ? "remove" : "add"}">${queueItemLabel(view.queued === true)}</button>` : "",
 		canWrite ? `<button type="button" class="prb-menu-item" data-pin-toggle aria-pressed="${view.pinned === true}">${pinItemLabel(view.pinned === true)}</button>` : "",
 		`<button type="button" class="prb-menu-item" data-copy-id="${safe}">Copy review ID</button>`,
+		canWrite && view.session.result ? "<button type=\"button\" class=\"prb-menu-item\" data-tour-replay>Replay guided tour</button>" : "",
 		canWrite ? `<button type="button" class="prb-menu-item prb-menu-item-danger" data-delete="${safe}">Delete review</button>` : ""
 	].filter(Boolean);
 	return `<div class="prb-menu" data-menu data-review-menu${[
@@ -10673,7 +10715,7 @@ function readPreferences() {
 	try {
 		const parsed = JSON.parse(readFileSync(PREFERENCES_PATH, "utf8"));
 		if (!parsed || typeof parsed !== "object") return {};
-		const { askWidth, dismissedNotices, promptsCollapsed, changeMapRegister, theme, reviewSections, runsSections, reviewLayout, sidebar } = parsed;
+		const { askWidth, dismissedNotices, promptsCollapsed, changeMapRegister, theme, reviewSections, runsSections, reviewLayout, sidebar, guidedTour } = 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)) } : {},
@@ -10683,7 +10725,8 @@ function readPreferences() {
 			...readReviewSections(reviewSections),
 			...readRunsSections(runsSections),
 			...readLayout(reviewLayout),
-			...readSidebar(sidebar)
+			...readSidebar(sidebar),
+			...isGuidedTourState(guidedTour) ? { guidedTour } : {}
 		};
 	} catch {
 		return {};
@@ -10745,6 +10788,21 @@ function writeSidebar(patch) {
 		}, null, 2)}\n`);
 	} catch {}
 }
+/**
+* Remember how the guided tour was first answered. The first answer stands: a replay from Help, or
+* a second window finishing a tour another already skipped, is not a new answer to the offer.
+*/
+function writeGuidedTour(state) {
+	try {
+		const current = readPreferences();
+		if (current.guidedTour) return;
+		mkdirSync(STORE_ROOT, { recursive: true });
+		writeFileSync(PREFERENCES_PATH, `${JSON.stringify({
+			...current,
+			guidedTour: state
+		}, null, 2)}\n`);
+	} catch {}
+}
 /** Remember whether "Your prompts" is folded. Read-modify-write, like every other field here. */
 function writePromptsCollapsed(collapsed) {
 	try {
@@ -11474,6 +11532,30 @@ var AGENT_PRODUCTS = ((names) => names.length <= 1 ? names[0] ?? "" : `${names.s
 * says what to type and points here for what it means. The diagrams are text on purpose.
 */
 var TOPICS = [
+	{
+		id: "welcome",
+		title: "Welcome",
+		heading: `<p class="prb-help-eyebrow">Welcome to PR Review Buddy</p>
+    <h2 class="prb-help-headline">Understand before you approve.</h2>`,
+		body: `<p>Code review isn't just about finding bugs. It's about understanding what changed, why it
+    changed, and whether those changes make sense.</p>
+    <p>AI can generate code faster than ever. But someone still needs to understand it, challenge its
+    assumptions, and take responsibility for approving it.</p>
+    <p>That's why we built PR Review Buddy.</p>
+    <p>PR Review Buddy helps you make sense of changes before you approve them. It brings together
+    code, context, conversations and AI-assisted analysis so you can focus on what matters: making
+    informed engineering decisions.</p>
+    <p>The goal isn't to replace the reviewer. It's to make the reviewer better informed.</p>
+    <h3 class="prb-help-eyebrow">Our principles</h3>
+    <dl class="prb-help-principles">
+      <div><dt>Understanding over automation</dt>
+      <dd>AI should help you reason about changes, not make decisions on your behalf.</dd></div>
+      <div><dt>Evidence over assertions</dt>
+      <dd>Findings should be grounded in the code and context, so you can investigate and challenge them.</dd></div>
+      <div><dt>You remain in control</dt>
+      <dd>Choose your AI agent, explore the analysis, and make the final judgement yourself.</dd></div>
+    </dl>`
+	},
 	{
 		id: "getting-started",
 		title: "Getting started",
@@ -11675,7 +11757,27 @@ feature:                   E</pre>
     <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. */
+/**
+* Every topic by name beside the topics, so one in the middle is found by reading a list, not a
+* page. First in the document so a keyboard or a screen reader reaches it before the prose; the
+* stylesheet places it. `help_index.ts` marks the topic being read.
+*/
+/**
+* Where the tour lives once it has been seen. `/tour` picks the review when Replay is pressed (see
+* `chooseTourReview`); with none to pick, Help says why rather than offering a button that would
+* open a review the tour cannot start on.
+*/
+function renderTourAction(tour, failed) {
+	const lead = failed ? "<strong>The guided tour couldn't start.</strong> " : "";
+	const role = failed ? " role=\"status\"" : "";
+	if (tour === "available") return `<p class="prb-help-tour">The guided tour walks through a completed review, one part at a time,
+    starting with the one you opened last. A review's &#8943; menu replays it on that review.</p>
+    <p><a class="prb-help-tour-action" href="/tour">Replay guided tour</a></p>`;
+	if (tour === "busy") return `<p class="prb-help-tour"${role}>${lead}The guided tour walks through a completed review, and every
+    one you have is being analysed or updated right now. Replay it from here once that finishes.</p>`;
+	return `<p class="prb-help-tour"${role}>${lead}The guided tour walks through a completed review, and there
+    isn't one yet. Start a review from <a href="/">Reviews</a>, then replay the tour from here once it has finished.</p>`;
+}
 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>
@@ -11706,13 +11808,16 @@ ${renderWorkspaceRail({
 		sidebar: view.sidebar
 	})}
 <main class="prb-index prb-help">
-  <div class="prb-page-panel">
+  <div class="prb-help-layout">
   ${renderContents()}
+  <div class="prb-page-panel">
   ${TOPICS.map((topic) => `<section class="prb-help-topic" id="${topic.id}">
-    <h2>${escapeHtml$1(topic.title)}</h2>
+    ${topic.heading ?? `<h2>${escapeHtml$1(topic.title)}</h2>`}
     ${topic.body}
+    ${topic.id === "welcome" ? renderTourAction(view.tour, view.tourFailed === true) : ""}
   </section>`).join("")}
   </div>
+  </div>
   <p class="prb-help-version">PR Review Buddy v${escapeHtml$1(BUILD_VERSION)}</p>
 </main>
 </div>
@@ -15081,6 +15186,7 @@ async function handle(req, res, options) {
 	if (url.pathname === "/runs/remove") return void handleRunRemoval(req, res, options.indexToken);
 	if (url.pathname === "/runs/sections") return void handleRunsSections(req, res, options.indexToken);
 	if (url.pathname === "/help") return void handleHelp(req, res, url.searchParams, options.indexToken);
+	if (url.pathname === "/tour") return void handleTour(req, res, url.searchParams, options.indexToken);
 	if (url.pathname === "/notifications/open") return handleNotificationOpen(req, res, url.searchParams, options.indexToken);
 	if (url.pathname === "/notifications/recent") return handleRecentNotifications(req, res, url.searchParams, options.indexToken);
 	if (url.pathname === "/notifications/live") return handleLiveNotifications(req, res, url.searchParams, options.indexToken);
@@ -15341,10 +15447,30 @@ function handleHelp(req, res, params, indexToken) {
 		unreadNotifications: unreadCount$1(),
 		driving: isDriving(),
 		theme: readPreferences().theme,
-		sidebar: readPreferences().sidebar
+		sidebar: readPreferences().sidebar,
+		tour: tourUnavailable(recentWorkspaces(Number.MAX_SAFE_INTEGER), busyReviewIds()) ?? "available",
+		tourFailed: params.get("tour") === "unavailable"
 	}), indexCookieHeader(indexToken));
 }
 /**
+* Reviews something is analysing or updating right now. The guided tour is not shown on these: what
+* it would point at is about to be replaced. An assistant answering, or a diagram being drawn, is
+* not one of these: the review under it stays as it is.
+*/
+function busyReviewIds() {
+	return new Set(runningJobs().map((running) => running.job).filter((job) => purposeOf(job) !== "ask").map((job) => job.workspaceId));
+}
+/**
+* Replay guided tour, from Help. Chosen when it is pressed rather than when Help was drawn, so a
+* review that started updating in between is not opened to a tour that cannot start. With nothing to
+* open, back to Help's Welcome, which says why.
+*/
+function handleTour(req, res, params, indexToken) {
+	if (!indexAuthorised(req, params, indexToken)) return refuseIndex(req, res);
+	const review = chooseTourReview(recentWorkspaces(Number.MAX_SAFE_INTEGER), busyReviewIds());
+	redirect(res, review ? `/r/${encodeURIComponent(review.id)}?t=${encodeURIComponent(review.token)}${TOUR_REPLAY_HASH}` : "/help?tour=unavailable#welcome");
+}
+/**
 * Whether the caller is a browser navigating, rather than something reading the API.
 *
 * `Accept` is the only signal available and browsers are consistent about it: a navigation asks
@@ -16314,6 +16440,8 @@ async function sendWorkspacePage(res, workspace) {
 		dismissedNotices: readPreferences().dismissedNotices,
 		promptsCollapsed: readPreferences().promptsCollapsed === true,
 		reviewLayout: readPreferences().reviewLayout ?? {},
+		guidedTour: readPreferences().guidedTour,
+		tourBusy: busyReviewIds().has(workspace.id),
 		changeMapRegister: readPreferences().changeMapRegister ?? "simple",
 		architecture: await architecturePane(workspace),
 		transcript: workspace.transcript,
@@ -17119,6 +17247,7 @@ async function handlePrefs(req, res) {
 	const layout = readReviewLayoutPatch(body?.reviewLayout);
 	if (layout) writeReviewLayout(layout);
 	if (body?.changeMapRegister === "simple" || body?.changeMapRegister === "technical") writeChangeMapRegister(body.changeMapRegister);
+	if (isGuidedTourState(body?.guidedTour)) writeGuidedTour(body.guidedTour);
 	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 });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prreviewbuddy",
-  "version": "0.83.3",
+  "version": "0.85.0",
   "description": "Understand code changes before you approve them. Local branch and pull request reviews with Claude Code or Codex.",
   "license": "UNLICENSED",
   "homepage": "https://prreviewbuddy.com",

package/static/help.js

@@ -1 +1 @@
-import{at as e,d as t,f as n,ft as r,p as i,rt as a,t as o}from"./chunk-DwdwtB9r.js";a(),t(`global`,{}),document.querySelector(`[data-shortcut-table]`)?.replaceChildren(n(document,i(e(navigator)))),o(`/restart`),r(window,()=>window.location.reload());
+import{at as e,d as t,f as n,ft as r,p as i,rt as a,t as o}from"./chunk-DwdwtB9r.js";function s(e,t){if(e.length===0)return-1;if(t)return e.length-1;let n=0;return e.forEach((e,t)=>{e<=120&&(n=t)}),n}var c=new Set([`ArrowDown`,`ArrowUp`,`PageDown`,`PageUp`,`Home`,`End`,` `]);function l(e,t){let n=[...e.querySelectorAll(`.prb-help-contents a[href^="#"]`)],r=n.map(t=>e.getElementById(decodeURIComponent(t.hash.slice(1)))),i=e.defaultView;if(n.length===0||!i)return;let a=r.findIndex(e=>e!==null&&`#${e.id}`===i.location.hash),o=e=>{n.forEach((t,n)=>{n===e?t.setAttribute(`aria-current`,`location`):t.removeAttribute(`aria-current`)})},l=()=>{if(a>=0)return o(a);let n=t.scrollHeight>t.clientHeight?t:e.scrollingElement??e.documentElement,i=Math.max(0,n===t?t.getBoundingClientRect().top:0),c=r.map(e=>e?e.getBoundingClientRect().top-i:1/0),l=n.scrollTop>0&&n.scrollTop+n.clientHeight>=n.scrollHeight-2;o(s(c,l))},u=e=>{let t=r.findIndex(t=>t!==null&&`#${t.id}`===e);t<0||(a=t,o(t))},d=()=>{a<0||(a=-1,l())};e.addEventListener(`click`,e=>{let t=e.target?.closest?.(`a[href^="#"]`);t&&u(t.hash)}),i.addEventListener(`hashchange`,()=>u(i.location.hash)),t.addEventListener(`wheel`,d,{passive:!0}),t.addEventListener(`touchmove`,d,{passive:!0}),t.addEventListener(`pointerdown`,d),e.addEventListener(`keydown`,e=>{c.has(e.key)&&d()}),e.addEventListener(`scroll`,l,{capture:!0,passive:!0}),i.addEventListener(`resize`,l),l()}a(),t(`global`,{}),document.querySelector(`[data-shortcut-table]`)?.replaceChildren(n(document,i(e(navigator)))),o(`/restart`);var u=document.querySelector(`main.prb-help`);u&&l(document,u),r(window,()=>window.location.reload());