react-doctor 0.5.6 → 0.5.7-dev.350a6ed

package/dist/cli.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="79c9f922-1713-5894-a0aa-142d0cd9c7ba")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="87ed2e7a-69a3-5a4d-a104-8ba680ac1aa2")}catch(e){}}();
 import { createRequire } from "node:module";
 import * as NodeChildProcess from "node:child_process";
 import { execFile, execFileSync, spawn, spawnSync } from "node:child_process";
@@ -14,7 +14,7 @@ import * as OS from "node:os";
 import os, { tmpdir } from "node:os";
 import { parseJSON5 } from "confbox";
 import * as NodeUrl from "node:url";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { createJiti } from "jiti";
 import * as Crypto from "node:crypto";
 import crypto, { createHash, randomUUID } from "node:crypto";
@@ -22358,7 +22358,8 @@ var Diagnostic = class extends Class("Diagnostic")({
 	category: String$1,
 	fileContext: optional(Literals(["test", "story"])),
 	suppressionHint: optional(String$1),
-	relatedLocations: optional(ArraySchema(DiagnosticRelatedLocation))
+	relatedLocations: optional(ArraySchema(DiagnosticRelatedLocation)),
+	fixGroupId: optional(String$1)
 }) {};
 const JsonReportMode = Literals([
 	"full",
@@ -22400,6 +22401,7 @@ var JsonReportProjectEntry = class extends Class("JsonReportProjectEntry")({
 	score: Unknown,
 	skippedChecks: ArraySchema(String$1),
 	skippedCheckReasons: optional(Record$1(String$1, String$1)),
+	scannedFileCount: optional(Number$1),
 	elapsedMilliseconds: Number$1
 }) {};
 /**
@@ -35893,6 +35895,7 @@ const isLargeMinifiedFile = (absolutePath) => {
 	if (sizeBytes < 2e4) return false;
 	return isMinifiedSource(absolutePath);
 };
+const isErrnoException = (error) => error instanceof Error && "code" in error;
 const IGNORABLE_READDIR_ERROR_CODES = new Set([
 	"EACCES",
 	"EPERM",
@@ -35902,11 +35905,7 @@ const IGNORABLE_READDIR_ERROR_CODES = new Set([
 	"ELOOP",
 	"ENAMETOOLONG"
 ]);
-const isIgnorableReaddirError = (error) => {
-	if (typeof error !== "object" || error === null) return false;
-	const errorCode = error.code;
-	return typeof errorCode === "string" && IGNORABLE_READDIR_ERROR_CODES.has(errorCode);
-};
+const isIgnorableReaddirError = (error) => isErrnoException(error) && typeof error.code === "string" && IGNORABLE_READDIR_ERROR_CODES.has(error.code);
 const readDirectoryEntries = (directoryPath) => {
 	try {
 		return NFS.readdirSync(directoryPath, { withFileTypes: true });
@@ -35953,7 +35952,7 @@ const readPackageJsonUncached = (packageJsonPath) => {
 		return JSON.parse(NFS.readFileSync(packageJsonPath, "utf-8"));
 	} catch (error) {
 		if (error instanceof SyntaxError) return {};
-		if (error instanceof Error && "code" in error) {
+		if (isErrnoException(error)) {
 			const { code } = error;
 			if (code === "EISDIR" || code === "EACCES" || code === "EPERM" || code === "ENOENT") return {};
 		}
@@ -36678,17 +36677,13 @@ const isPackageJsonReactNativeAware = (packageJson) => {
 	return false;
 };
 const hasReactNativeWorkspaceAnywhere = (rootDirectory, rootPackageJson) => someWorkspacePackageJson(rootDirectory, rootPackageJson, isPackageJsonReactNativeAware);
-const getExpoDependencySpec = (packageJson) => {
-	const spec = packageJson.dependencies?.expo ?? packageJson.devDependencies?.expo ?? packageJson.peerDependencies?.expo ?? packageJson.optionalDependencies?.expo;
+const getDependencySpec = (packageJson, packageName) => {
+	const spec = packageJson.dependencies?.[packageName] ?? packageJson.devDependencies?.[packageName] ?? packageJson.peerDependencies?.[packageName] ?? packageJson.optionalDependencies?.[packageName];
 	return typeof spec === "string" ? spec : null;
 };
-const findExpoVersion = (rootDirectory, rootPackageJson) => findInWorkspacePackageJsons(rootDirectory, rootPackageJson, getExpoDependencySpec);
+const findExpoVersion = (rootDirectory, rootPackageJson) => findInWorkspacePackageJsons(rootDirectory, rootPackageJson, (packageJson) => getDependencySpec(packageJson, "expo"));
 const SHOPIFY_FLASH_LIST_PACKAGE_NAME = "@shopify/flash-list";
-const getShopifyFlashListDependencySpec = (packageJson) => {
-	const spec = packageJson.dependencies?.["@shopify/flash-list"] ?? packageJson.devDependencies?.["@shopify/flash-list"] ?? packageJson.peerDependencies?.["@shopify/flash-list"] ?? packageJson.optionalDependencies?.["@shopify/flash-list"];
-	return typeof spec === "string" ? spec : null;
-};
-const findShopifyFlashListVersion = (rootDirectory, rootPackageJson) => findInWorkspacePackageJsons(rootDirectory, rootPackageJson, getShopifyFlashListDependencySpec);
+const findShopifyFlashListVersion = (rootDirectory, rootPackageJson) => findInWorkspacePackageJsons(rootDirectory, rootPackageJson, (packageJson) => getDependencySpec(packageJson, SHOPIFY_FLASH_LIST_PACKAGE_NAME));
 const resolveCatalogBackedDependencyVersion = ({ rootDirectory, rootPackageJson, packageName, version }) => {
 	if (version === null || !isCatalogReference(version)) return version;
 	const catalogName = extractCatalogName(version);
@@ -36700,11 +36695,7 @@ const resolveCatalogBackedDependencyVersion = ({ rootDirectory, rootPackageJson,
 	if (!isFile(monorepoPackageJsonPath)) return version;
 	return resolveCatalogVersion(readPackageJson$1(monorepoPackageJsonPath), packageName, monorepoRoot, catalogName) ?? version;
 };
-const getNextjsDependencySpec = (packageJson) => {
-	const spec = packageJson.dependencies?.next ?? packageJson.devDependencies?.next ?? packageJson.peerDependencies?.next ?? packageJson.optionalDependencies?.next;
-	return typeof spec === "string" ? spec : null;
-};
-const findNextjsVersion = (rootDirectory, rootPackageJson) => findInWorkspacePackageJsons(rootDirectory, rootPackageJson, getNextjsDependencySpec);
+const findNextjsVersion = (rootDirectory, rootPackageJson) => findInWorkspacePackageJsons(rootDirectory, rootPackageJson, (packageJson) => getDependencySpec(packageJson, "next"));
 const getPreactVersion = (packageJson) => {
 	return {
 		...packageJson.peerDependencies,
@@ -36793,6 +36784,11 @@ const ES_TARGET_YEAR_BY_NAME = {
 	esnext: 9999
 };
 /**
+* tsconfig filenames probed when resolving a project's TypeScript
+* compiler options — the root config first, then a monorepo base config.
+*/
+const TSCONFIG_FILENAMES = ["tsconfig.json", "tsconfig.base.json"];
+/**
 * Project-config files that `StagedFiles.materialize` copies into
 * the temp directory alongside staged sources so oxlint resolves
 * `tsconfig` / `package.json` / lint configs the same way it would
@@ -36865,6 +36861,13 @@ const APP_ONLY_RULE_KEYS = new Set([
 ]);
 const COMPILER_CLEANUP_BUCKET = "compiler-cleanup";
 const COMPILER_CLEANUP_RULE_KEYS = new Set(["react-doctor/react-compiler-no-manual-memoization"]);
+const ROOT_CAUSE_GROUPABLE_RULE_KEYS = new Set([
+	"react-doctor/no-derived-state",
+	"react-doctor/no-derived-state-effect",
+	"react-doctor/no-derived-useState",
+	"react-doctor/no-adjust-state-on-prop-change",
+	"react-doctor/no-reset-all-state-on-prop-change"
+]);
 const MAX_GLOB_PATTERN_LENGTH_CHARS = 1024;
 const CONFIG_CACHE_TTL_MS = 300 * 1e3;
 const SOCKET_FREE_PURL_API_BASE = "https://firewall-api.socket.dev/purl";
@@ -37314,6 +37317,7 @@ const isTailwindAtLeast = (detected, required) => {
 	if (detected.major !== required.major) return detected.major > required.major;
 	return detected.minor >= required.minor;
 };
+const messageFromUnknown = (error) => error instanceof Error ? error.message : String(error);
 var InvalidGlobPatternError = class extends Error {
 	pattern;
 	reason;
@@ -37342,7 +37346,7 @@ const compileGlobPattern = (rawPattern) => {
 	try {
 		return import_picomatch.default.makeRe(normalizeGlobPattern(rawPattern), PICOMATCH_OPTIONS);
 	} catch (caughtError) {
-		throw new InvalidGlobPatternError(rawPattern, caughtError instanceof Error ? caughtError.message : String(caughtError));
+		throw new InvalidGlobPatternError(rawPattern, messageFromUnknown(caughtError));
 	}
 };
 const compileGlobPatternsLenient = (patterns, onInvalid) => {
@@ -37438,115 +37442,6 @@ const buildRuleSeverityControls = (config) => {
 		...config.buckets !== void 0 ? { buckets: config.buckets } : {}
 	};
 };
-const JSX_OPENER_TAG_PATTERN = /<[A-Za-z][\w.]*/g;
-const JSX_TAG_NAME_FOLLOW = /[A-Za-z]/;
-const isOpenerMatchInsideLineComment = (line, openerCharIndex) => {
-	let stringDelimiter = null;
-	for (let charIndex = 0; charIndex < openerCharIndex; charIndex++) {
-		const character = line[charIndex];
-		if (stringDelimiter !== null) {
-			if (character === "\\") {
-				charIndex++;
-				continue;
-			}
-			if (character === stringDelimiter) stringDelimiter = null;
-			continue;
-		}
-		if (character === "\"" || character === "'" || character === "`") {
-			stringDelimiter = character;
-			continue;
-		}
-		if (character === "/" && line[charIndex + 1] === "/") return true;
-	}
-	return false;
-};
-const findOpenerTagOnLine = (line) => {
-	for (const match of line.matchAll(JSX_OPENER_TAG_PATTERN)) {
-		if (match.index === void 0) continue;
-		if (!isOpenerMatchInsideLineComment(line, match.index)) return { startCharIndex: match.index + match[0].length };
-	}
-	return null;
-};
-const findJsxOpenerSpan = (lines, openerLineIndex) => {
-	const openerLine = lines[openerLineIndex];
-	if (openerLine === void 0) return null;
-	const opener = findOpenerTagOnLine(openerLine);
-	if (!opener) return null;
-	const lookaheadLimit = Math.min(lines.length, openerLineIndex + 32);
-	let braceDepth = 0;
-	let innerAngleDepth = 0;
-	let stringDelimiter = null;
-	for (let lineIndex = openerLineIndex; lineIndex < lookaheadLimit; lineIndex++) {
-		const currentLine = lines[lineIndex];
-		const startCharForLine = lineIndex === openerLineIndex ? opener.startCharIndex : 0;
-		for (let charIndex = startCharForLine; charIndex < currentLine.length; charIndex++) {
-			const character = currentLine[charIndex];
-			if (stringDelimiter !== null) {
-				if (character === "\\") {
-					charIndex++;
-					continue;
-				}
-				if (character === stringDelimiter) stringDelimiter = null;
-				continue;
-			}
-			if (character === "\"" || character === "'" || character === "`") {
-				stringDelimiter = character;
-				continue;
-			}
-			if (character === "{") {
-				braceDepth++;
-				continue;
-			}
-			if (character === "}") {
-				braceDepth--;
-				continue;
-			}
-			if (braceDepth !== 0) continue;
-			if (character === "<") {
-				const followCharacter = currentLine[charIndex + 1];
-				if (followCharacter !== void 0 && JSX_TAG_NAME_FOLLOW.test(followCharacter)) innerAngleDepth++;
-				continue;
-			}
-			if (character !== ">") continue;
-			const previousCharacter = currentLine[charIndex - 1];
-			const nextCharacter = currentLine[charIndex + 1];
-			if (previousCharacter === "=" || nextCharacter === "=") continue;
-			if (innerAngleDepth > 0) {
-				innerAngleDepth--;
-				continue;
-			}
-			return lineIndex;
-		}
-	}
-	return null;
-};
-const findEnclosingMultilineJsxOpenerStart = (lines, diagnosticLineIndex) => {
-	for (let candidateIndex = diagnosticLineIndex - 1; candidateIndex >= 0 && diagnosticLineIndex - candidateIndex <= 32; candidateIndex--) {
-		const openerCloseIndex = findJsxOpenerSpan(lines, candidateIndex);
-		if (openerCloseIndex !== null && openerCloseIndex >= diagnosticLineIndex) return candidateIndex;
-	}
-	return null;
-};
-const DISABLE_NEXT_LINE_PATTERN = /(?:\/\/|\/\*)\s*react-doctor-disable-next-line\b(?:\s+([^\r\n]*?))?\s*(?:\*\/)?\s*\}?\s*$/;
-const findStackedDisableCommentsAbove = (lines, anchorIndex) => {
-	const collected = [];
-	let isStillInChain = true;
-	for (let candidateIndex = anchorIndex - 1; candidateIndex >= 0 && anchorIndex - candidateIndex <= 10; candidateIndex--) {
-		const candidateLine = lines[candidateIndex];
-		if (candidateLine === void 0) break;
-		const match = candidateLine.match(DISABLE_NEXT_LINE_PATTERN);
-		if (match) {
-			collected.push({
-				commentLineIndex: candidateIndex,
-				ruleList: match[1],
-				isInChain: isStillInChain
-			});
-			continue;
-		}
-		isStillInChain = false;
-	}
-	return collected;
-};
 const LEGACY_RULE_KEY_TO_NATIVE_RULE_KEY = {
 	"effect/no-adjust-state-on-prop-change": "react-doctor/no-adjust-state-on-prop-change",
 	"effect/no-chain-state-updates": "react-doctor/no-chain-state-updates",
@@ -37671,7 +37566,13 @@ for (const [legacyRuleKey, nativeRuleKey] of Object.entries(LEGACY_RULE_KEY_TO_N
 }
 const getLegacyRuleKeysForNative = (ruleKey) => NATIVE_RULE_KEY_TO_LEGACY_RULE_KEYS.get(ruleKey) ?? [];
 const canonicalizeRuleKey = (ruleKey) => LEGACY_RULE_KEY_TO_NATIVE_RULE_KEY[ruleKey] ?? ruleKey;
-const isSameRuleKey = (candidateRuleKey, targetRuleKey) => canonicalizeRuleKey(candidateRuleKey) === canonicalizeRuleKey(targetRuleKey);
+const isReactDoctorShortIdOf = (bareRuleKey, qualifiedRuleKey) => !bareRuleKey.includes("/") && qualifiedRuleKey === `react-doctor/${bareRuleKey}`;
+const isSameRuleKey = (candidateRuleKey, targetRuleKey) => {
+	const canonicalCandidate = canonicalizeRuleKey(candidateRuleKey);
+	const canonicalTarget = canonicalizeRuleKey(targetRuleKey);
+	if (canonicalCandidate === canonicalTarget) return true;
+	return isReactDoctorShortIdOf(canonicalCandidate, canonicalTarget) || isReactDoctorShortIdOf(canonicalTarget, canonicalCandidate);
+};
 const getEquivalentRuleKeys = (ruleKey) => {
 	const nativeRuleKey = canonicalizeRuleKey(ruleKey);
 	return [nativeRuleKey, ...getLegacyRuleKeysForNative(nativeRuleKey)];
@@ -37681,12 +37582,182 @@ const stripDescriptionTail = (ruleList) => {
 	if (!descriptionMatch || descriptionMatch.index === void 0) return ruleList;
 	return ruleList.slice(0, descriptionMatch.index);
 };
-const isRuleListedInComment = (ruleList, ruleId) => {
+const tokenizeRuleList = (ruleList) => {
 	const trimmed = ruleList?.trim();
-	if (!trimmed) return true;
+	if (!trimmed) return [];
 	const ruleSection = stripDescriptionTail(trimmed).trim();
-	if (!ruleSection) return true;
-	return ruleSection.split(/[,\s]+/).some((token) => isSameRuleKey(token.trim(), ruleId));
+	if (!ruleSection) return [];
+	return ruleSection.split(/[,\s]+/).map((token) => token.trim()).filter(Boolean);
+};
+const FOREIGN_INLINE_DISABLE_PATTERN = /(?:\/\/|\/\*)[ \t]*(eslint|oxlint)-disable-(next-line|line)(?![\w-])([^\r\n]*)/;
+const FOREIGN_BLOCK_DISABLE_PATTERN = /\/\*[ \t]*(eslint|oxlint)-disable(?![\w-])([^*\r\n]*)/;
+const FOREIGN_BLOCK_ENABLE_PATTERN = /\/\*[ \t]*(?:eslint|oxlint)-enable(?![\w-])([^*\r\n]*)/;
+const buildHint = (tool, token, ruleId) => `oxlint matches plugin rules only by their full name, so \`${token}\` in your ${tool}-disable comment does not silence \`${ruleId}\` — change it to \`${ruleId}\`.`;
+const tokenMisnamesRule = (token, ruleId) => token !== ruleId && isSameRuleKey(token, ruleId);
+const detectInlineNearMiss = (lines, diagnosticLineIndex, ruleId) => {
+	const candidates = [{
+		line: lines[diagnosticLineIndex],
+		requiredScope: "line"
+	}, {
+		line: lines[diagnosticLineIndex - 1],
+		requiredScope: "next-line"
+	}];
+	for (const { line, requiredScope } of candidates) {
+		const match = line?.match(FOREIGN_INLINE_DISABLE_PATTERN);
+		if (!match) continue;
+		const [, tool, scope, ruleList] = match;
+		if (scope !== requiredScope) continue;
+		const tokens = tokenizeRuleList(ruleList);
+		if (tokens.includes(ruleId)) continue;
+		for (const token of tokens) if (tokenMisnamesRule(token, ruleId)) return buildHint(tool, token, ruleId);
+	}
+	return null;
+};
+const detectBlockNearMiss = (lines, diagnosticLineIndex, ruleId) => {
+	let openMisname = null;
+	const lastLineIndex = Math.min(diagnosticLineIndex, lines.length - 1);
+	for (let lineIndex = 0; lineIndex <= lastLineIndex; lineIndex++) {
+		const line = lines[lineIndex];
+		if (line === void 0 || !line.includes("-disable") && !line.includes("-enable")) continue;
+		const disableMatch = line.match(FOREIGN_BLOCK_DISABLE_PATTERN);
+		if (disableMatch) {
+			const [, tool, ruleList] = disableMatch;
+			const tokens = tokenizeRuleList(ruleList);
+			if (tokens.includes(ruleId)) openMisname = null;
+			else {
+				const misnamed = tokens.find((token) => tokenMisnamesRule(token, ruleId));
+				if (misnamed) openMisname = {
+					tool,
+					token: misnamed
+				};
+			}
+			continue;
+		}
+		const enableMatch = line.match(FOREIGN_BLOCK_ENABLE_PATTERN);
+		if (enableMatch) {
+			const enabledRules = tokenizeRuleList(enableMatch[1]);
+			if (enabledRules.length === 0 || enabledRules.some((rule) => isSameRuleKey(rule, ruleId))) openMisname = null;
+		}
+	}
+	return openMisname ? buildHint(openMisname.tool, openMisname.token, ruleId) : null;
+};
+const detectForeignDisableNearMiss = (lines, diagnosticLineIndex, ruleId) => {
+	if (!ruleId.startsWith("react-doctor/")) return null;
+	return detectInlineNearMiss(lines, diagnosticLineIndex, ruleId) ?? detectBlockNearMiss(lines, diagnosticLineIndex, ruleId);
+};
+const JSX_OPENER_TAG_PATTERN = /<[A-Za-z][\w.]*/g;
+const JSX_TAG_NAME_FOLLOW = /[A-Za-z]/;
+const isOpenerMatchInsideLineComment = (line, openerCharIndex) => {
+	let stringDelimiter = null;
+	for (let charIndex = 0; charIndex < openerCharIndex; charIndex++) {
+		const character = line[charIndex];
+		if (stringDelimiter !== null) {
+			if (character === "\\") {
+				charIndex++;
+				continue;
+			}
+			if (character === stringDelimiter) stringDelimiter = null;
+			continue;
+		}
+		if (character === "\"" || character === "'" || character === "`") {
+			stringDelimiter = character;
+			continue;
+		}
+		if (character === "/" && line[charIndex + 1] === "/") return true;
+	}
+	return false;
+};
+const findOpenerTagOnLine = (line) => {
+	for (const match of line.matchAll(JSX_OPENER_TAG_PATTERN)) {
+		if (match.index === void 0) continue;
+		if (!isOpenerMatchInsideLineComment(line, match.index)) return { startCharIndex: match.index + match[0].length };
+	}
+	return null;
+};
+const findJsxOpenerSpan = (lines, openerLineIndex) => {
+	const openerLine = lines[openerLineIndex];
+	if (openerLine === void 0) return null;
+	const opener = findOpenerTagOnLine(openerLine);
+	if (!opener) return null;
+	const lookaheadLimit = Math.min(lines.length, openerLineIndex + 32);
+	let braceDepth = 0;
+	let innerAngleDepth = 0;
+	let stringDelimiter = null;
+	for (let lineIndex = openerLineIndex; lineIndex < lookaheadLimit; lineIndex++) {
+		const currentLine = lines[lineIndex];
+		const startCharForLine = lineIndex === openerLineIndex ? opener.startCharIndex : 0;
+		for (let charIndex = startCharForLine; charIndex < currentLine.length; charIndex++) {
+			const character = currentLine[charIndex];
+			if (stringDelimiter !== null) {
+				if (character === "\\") {
+					charIndex++;
+					continue;
+				}
+				if (character === stringDelimiter) stringDelimiter = null;
+				continue;
+			}
+			if (character === "\"" || character === "'" || character === "`") {
+				stringDelimiter = character;
+				continue;
+			}
+			if (character === "{") {
+				braceDepth++;
+				continue;
+			}
+			if (character === "}") {
+				braceDepth--;
+				continue;
+			}
+			if (braceDepth !== 0) continue;
+			if (character === "<") {
+				const followCharacter = currentLine[charIndex + 1];
+				if (followCharacter !== void 0 && JSX_TAG_NAME_FOLLOW.test(followCharacter)) innerAngleDepth++;
+				continue;
+			}
+			if (character !== ">") continue;
+			const previousCharacter = currentLine[charIndex - 1];
+			const nextCharacter = currentLine[charIndex + 1];
+			if (previousCharacter === "=" || nextCharacter === "=") continue;
+			if (innerAngleDepth > 0) {
+				innerAngleDepth--;
+				continue;
+			}
+			return lineIndex;
+		}
+	}
+	return null;
+};
+const findEnclosingMultilineJsxOpenerStart = (lines, diagnosticLineIndex) => {
+	for (let candidateIndex = diagnosticLineIndex - 1; candidateIndex >= 0 && diagnosticLineIndex - candidateIndex <= 32; candidateIndex--) {
+		const openerCloseIndex = findJsxOpenerSpan(lines, candidateIndex);
+		if (openerCloseIndex !== null && openerCloseIndex >= diagnosticLineIndex) return candidateIndex;
+	}
+	return null;
+};
+const DISABLE_NEXT_LINE_PATTERN = /(?:\/\/|\/\*)\s*react-doctor-disable-next-line\b(?:\s+([^\r\n]*?))?\s*(?:\*\/)?\s*\}?\s*$/;
+const findStackedDisableCommentsAbove = (lines, anchorIndex) => {
+	const collected = [];
+	let isStillInChain = true;
+	for (let candidateIndex = anchorIndex - 1; candidateIndex >= 0 && anchorIndex - candidateIndex <= 10; candidateIndex--) {
+		const candidateLine = lines[candidateIndex];
+		if (candidateLine === void 0) break;
+		const match = candidateLine.match(DISABLE_NEXT_LINE_PATTERN);
+		if (match) {
+			collected.push({
+				commentLineIndex: candidateIndex,
+				ruleList: match[1],
+				isInChain: isStillInChain
+			});
+			continue;
+		}
+		isStillInChain = false;
+	}
+	return collected;
+};
+const isRuleListedInComment = (ruleList, ruleId) => {
+	const tokens = tokenizeRuleList(ruleList);
+	if (tokens.length === 0) return true;
+	return tokens.some((token) => isSameRuleKey(token, ruleId));
 };
 const DISABLE_LINE_PATTERN = /(?:\/\/|\/\*)\s*react-doctor-disable-line\b(?:\s+([^\r\n]*?))?\s*(?:\*\/)?\s*\}?\s*$/;
 const formatLineGap = (gapLineCount) => `${gapLineCount} line${gapLineCount === 1 ? "" : "s"}`;
@@ -37730,7 +37801,7 @@ const evaluateSuppression = (lines, diagnosticLineIndex, ruleId) => {
 	};
 	return {
 		isSuppressed: false,
-		nearMissHint: classifyFromComments([directComments, openerComments], diagnosticLineIndex, ruleId)
+		nearMissHint: classifyFromComments([directComments, openerComments], diagnosticLineIndex, ruleId) ?? detectForeignDisableNearMiss(lines, diagnosticLineIndex, ruleId)
 	};
 };
 /**
@@ -38520,7 +38591,6 @@ const PACKAGE_JSON_FILENAME = "package.json";
 const PACKAGE_JSON_CONFIG_KEY$1 = "reactDoctor";
 const LEGACY_CONFIG_FILENAME = "react-doctor.config.json";
 const jiti = createJiti(import.meta.url);
-const formatError = (error) => error instanceof Error ? error.message : String(error);
 const importDefaultExport = async (jitiInstance, filePath) => {
 	const imported = await jitiInstance.import(filePath);
 	return imported?.default ?? imported;
@@ -38552,7 +38622,7 @@ const loadModuleConfig = async (filePath) => {
 		try {
 			return await importDefaultExport(aliasJiti, filePath);
 		} catch (retryError) {
-			throw new Error(`${formatError(error)} (retry with ${SELF_PACKAGE_IMPORT_SPECIFIER} aliased to the running react-doctor package also failed: ${formatError(retryError)})`, { cause: retryError });
+			throw new Error(`${messageFromUnknown(error)} (retry with ${SELF_PACKAGE_IMPORT_SPECIFIER} aliased to the running react-doctor package also failed: ${messageFromUnknown(retryError)})`, { cause: retryError });
 		}
 	}
 };
@@ -38601,7 +38671,7 @@ const loadLegacyConfig = (directory) => {
 		}
 		warn(`${LEGACY_CONFIG_FILENAME} must contain an object, ignoring.`);
 	} catch (error) {
-		warn(`Failed to load ${LEGACY_CONFIG_FILENAME}: ${formatError(error)}`);
+		warn(`Failed to load ${LEGACY_CONFIG_FILENAME}: ${messageFromUnknown(error)}`);
 	}
 	return {
 		status: "invalid",
@@ -38628,7 +38698,7 @@ const loadConfigFromDirectory = async (directory) => {
 			warn(`${CONFIG_BASENAME}.${extension} must export an object, ignoring.`);
 			sawBrokenConfigFile = true;
 		} catch (error) {
-			warn(`Failed to load ${CONFIG_BASENAME}.${extension}: ${formatError(error)}`);
+			warn(`Failed to load ${CONFIG_BASENAME}.${extension}: ${messageFromUnknown(error)}`);
 			sawBrokenConfigFile = true;
 		}
 	}
@@ -38758,6 +38828,29 @@ const resolveScanTarget = async (requestedDirectory, options = {}) => {
 		didRedirectViaRootDir: redirectedDirectory !== null
 	};
 };
+const buildFixGroupId = (diagnostic) => createHash("sha1").update(JSON.stringify([
+	diagnostic.filePath,
+	`${diagnostic.plugin}/${diagnostic.rule}`,
+	diagnostic.message
+])).digest("hex").slice(0, 16);
+const isGroupableRule = (diagnostic) => ROOT_CAUSE_GROUPABLE_RULE_KEYS.has(`${diagnostic.plugin}/${diagnostic.rule}`);
+const assignFixGroups = (diagnostics) => {
+	const siteCountByGroupId = /* @__PURE__ */ new Map();
+	for (const diagnostic of diagnostics) {
+		if (!isGroupableRule(diagnostic)) continue;
+		const groupId = buildFixGroupId(diagnostic);
+		siteCountByGroupId.set(groupId, (siteCountByGroupId.get(groupId) ?? 0) + 1);
+	}
+	return diagnostics.map((diagnostic) => {
+		if (!isGroupableRule(diagnostic)) return diagnostic;
+		const groupId = buildFixGroupId(diagnostic);
+		if ((siteCountByGroupId.get(groupId) ?? 0) < 2) return diagnostic;
+		return {
+			...diagnostic,
+			fixGroupId: groupId
+		};
+	});
+};
 const getDirectDependencyNames = (packageJson) => new Set([...Object.keys(packageJson.dependencies ?? {}), ...Object.keys(packageJson.devDependencies ?? {})]);
 const buildExpoCheckContext = (rootDirectory, expoVersion) => {
 	const packageJson = readPackageJson$1(Path.join(rootDirectory, "package.json"));
@@ -39264,10 +39357,15 @@ const buildHardeningDiagnostic = (input) => ({
 	column: input.column ?? 0,
 	category: "Security"
 });
-const checkPnpmHardening = (rootDirectory) => {
-	if (!isPnpmManagedProject(rootDirectory)) return [];
-	const workspacePath = Path.join(rootDirectory, PNPM_WORKSPACE_FILE);
-	const settings = parseHardeningSettings(isFile(workspacePath) ? NFS.readFileSync(workspacePath, "utf-8") : "");
+const checkPnpmHardening = (scanDirectory) => {
+	if (!isPnpmManagedProject(scanDirectory)) return [];
+	const workspacePath = Path.join(scanDirectory, PNPM_WORKSPACE_FILE);
+	const hasWorkspaceFile = isFile(workspacePath);
+	if (!hasWorkspaceFile) {
+		const monorepoRoot = findMonorepoRoot(scanDirectory);
+		if (monorepoRoot !== null && isFile(Path.join(monorepoRoot, PNPM_WORKSPACE_FILE))) return [];
+	}
+	const settings = parseHardeningSettings(hasWorkspaceFile ? NFS.readFileSync(workspacePath, "utf-8") : "");
 	const diagnostics = [];
 	if (settings.minimumReleaseAge === null) diagnostics.push(buildHardeningDiagnostic({
 		message: "pnpm-workspace.yaml is missing `minimumReleaseAge` — newly published versions can ship malware that gets caught and unpublished within hours",
@@ -39903,7 +40001,7 @@ const readIgnoreFile = (filePath) => {
 	try {
 		content = NFS.readFileSync(filePath, "utf-8");
 	} catch (error) {
-		const errnoCode = error?.code;
+		const errnoCode = isErrnoException(error) ? error.code : void 0;
 		if (errnoCode && errnoCode !== "ENOENT") runSync(warn$1(`Could not read ignore file ${filePath}: ${errnoCode}`));
 		return [];
 	}
@@ -39941,8 +40039,8 @@ const collectIgnorePatterns = (rootDirectory) => {
 	cachedPatternsByRoot.set(rootDirectory, patterns);
 	return patterns;
 };
+const isRecord$2 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const KNIP_JSON_FILENAME = "knip.json";
-const isRecord$1$1 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const readJsonFileSafe = (filePath) => {
 	let rawContents;
 	try {
@@ -39958,10 +40056,10 @@ const readJsonFileSafe = (filePath) => {
 };
 const readKnipConfig = (rootDirectory) => {
 	const knipJson = readJsonFileSafe(path.join(rootDirectory, KNIP_JSON_FILENAME));
-	if (isRecord$1$1(knipJson)) return knipJson;
+	if (isRecord$2(knipJson)) return knipJson;
 	const packageJson = readJsonFileSafe(path.join(rootDirectory, "package.json"));
-	const packageKnipConfig = isRecord$1$1(packageJson) ? packageJson.knip : null;
-	return isRecord$1$1(packageKnipConfig) ? packageKnipConfig : null;
+	const packageKnipConfig = isRecord$2(packageJson) ? packageJson.knip : null;
+	return isRecord$2(packageKnipConfig) ? packageKnipConfig : null;
 };
 const normalizePatternList = (value) => {
 	if (typeof value === "string" && value.length > 0) return [value];
@@ -39973,10 +40071,10 @@ const prefixWorkspacePatterns = (workspacePattern, patterns) => {
 	return patterns.map((pattern) => pattern.startsWith("!") ? `!${normalizedWorkspacePattern}/${pattern.slice(1)}` : `${normalizedWorkspacePattern}/${pattern}`);
 };
 const collectKnipWorkspacePatterns = (workspaces, settingName) => {
-	if (!isRecord$1$1(workspaces)) return [];
+	if (!isRecord$2(workspaces)) return [];
 	const patterns = [];
 	for (const [workspacePattern, workspaceConfig] of Object.entries(workspaces)) {
-		if (!isRecord$1$1(workspaceConfig)) continue;
+		if (!isRecord$2(workspaceConfig)) continue;
 		patterns.push(...prefixWorkspacePatterns(workspacePattern, normalizePatternList(workspaceConfig[settingName])));
 	}
 	return patterns;
@@ -39986,12 +40084,11 @@ const collectKnipPatterns = (rootDirectory, settingName) => {
 	if (!config) return [];
 	return [...normalizePatternList(config[settingName]), ...collectKnipWorkspacePatterns(config.workspaces, settingName)];
 };
-const collectDeadCodeIgnorePatterns = (rootDirectory, userConfig) => {
+const collectDeadCodeIgnorePatterns = (rootDirectory) => {
 	const seen = /* @__PURE__ */ new Set();
 	const sources = [
 		readIgnoreFile(path.join(rootDirectory, ".gitignore")),
 		collectIgnorePatterns(rootDirectory),
-		userConfig?.ignore?.files ?? [],
 		collectKnipPatterns(rootDirectory, "ignore")
 	];
 	for (const source of sources) for (const pattern of source) seen.add(pattern);
@@ -40022,8 +40119,6 @@ const toCanonicalPath = (filePath) => {
 };
 const DEAD_CODE_PLUGIN = "deslop";
 const DEAD_CODE_CATEGORY = "Maintainability";
-const TSCONFIG_FILENAMES$1 = ["tsconfig.json", "tsconfig.base.json"];
-const isRecord$2 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const DEAD_CODE_WORKER_SCRIPT = `
 const inputChunks = [];
 process.stdin.on("data", (chunk) => inputChunks.push(chunk));
@@ -40081,7 +40176,7 @@ process.stdin.on("end", () => {
 });
 `;
 const resolveTsConfigPath = (rootDirectory) => {
-	for (const filename of TSCONFIG_FILENAMES$1) {
+	for (const filename of TSCONFIG_FILENAMES) {
 		const candidate = Path.join(rootDirectory, filename);
 		if (NFS.existsSync(candidate)) return candidate;
 	}
@@ -40269,11 +40364,10 @@ const runDeadCodeWorkerWithTimeout = (handle, timeoutMs) => new Promise((resolve
 	});
 });
 const checkDeadCode = async (options) => {
-	const { userConfig } = options;
 	const rootDirectory = toCanonicalPath(options.rootDirectory);
 	if (!NFS.existsSync(Path.join(rootDirectory, "package.json"))) return [];
 	const entryPatterns = collectDeadCodeEntryPatterns(rootDirectory);
-	const ignorePatterns = collectDeadCodeIgnorePatterns(rootDirectory, userConfig);
+	const ignorePatterns = collectDeadCodeIgnorePatterns(rootDirectory);
 	const result = parseDeadCodeWorkerResult(await runDeadCodeWorkerWithTimeout((options.createWorker ?? createDeadCodeWorker)({
 		rootDirectory,
 		entryPatterns,
@@ -40463,15 +40557,13 @@ var DeadCode = class DeadCode extends Service()("react-doctor/DeadCode") {
 	})()) }));
 	static layerOf = (diagnostics) => succeed$3(DeadCode, DeadCode.of({ run: () => fromIterable$1(diagnostics) }));
 };
-const createNodeReadFileLinesSync = (rootDirectory) => {
-	return (filePath) => {
-		const absolutePath = Path.isAbsolute(filePath) ? filePath : Path.join(rootDirectory, filePath);
-		try {
-			return NFS.readFileSync(absolutePath, "utf-8").split("\n");
-		} catch {
-			return null;
-		}
-	};
+const createNodeReadFileLinesSync = (rootDirectory) => (filePath) => {
+	const absolutePath = Path.isAbsolute(filePath) ? filePath : Path.join(rootDirectory, filePath);
+	try {
+		return NFS.readFileSync(absolutePath, "utf-8").split("\n");
+	} catch {
+		return null;
+	}
 };
 var Files = class Files extends Service()("react-doctor/Files") {
 	static layerNode = succeed$3(Files, Files.of({
@@ -40682,7 +40774,10 @@ var Git = class Git extends Service()("react-doctor/Git") {
 				directory: input.directory,
 				cause
 			}) });
-		}));
+		}), withSpan("git.exec", { attributes: {
+			"git.command": input.command,
+			"git.subcommand": input.args[0] ?? ""
+		} }));
 		const runGit = (directory, args) => runCommand({
 			command: "git",
 			args,
@@ -40710,7 +40805,7 @@ var Git = class Git extends Service()("react-doctor/Git") {
 			]);
 			if (candidates.status !== 0) return null;
 			return trimOrNull(candidates.stdout.split("\n")[0] ?? "");
-		});
+		}).pipe(withSpan("Git.defaultBranch"));
 		const branchExists = (directory, branch) => runGit(directory, [
 			"rev-parse",
 			"--verify",
@@ -40757,7 +40852,7 @@ var Git = class Git extends Service()("react-doctor/Git") {
 			const result = resultOption.value;
 			if (result.status !== 0) return null;
 			return parseGithubViewerPermission(result.stdout);
-		}).pipe(catch_$1(() => succeed$2(null)));
+		}).pipe(catch_$1(() => succeed$2(null)), withSpan("Git.githubViewerPermission"));
 		/**
 		* Resolves a `--diff A..B` / `A...B` commit range into a changed-file
 		* selection. Each endpoint is validated with `isSafeGitRevision`
@@ -40871,7 +40966,7 @@ var Git = class Git extends Service()("react-doctor/Git") {
 					changedFiles: splitNullSeparated(diff.stdout),
 					isCurrentChanges: false
 				};
-			}),
+			}).pipe(withSpan("Git.diffSelection")),
 			stagedFilePaths: (directory) => runGit(directory, [
 				"diff",
 				"--cached",
@@ -40913,7 +41008,7 @@ var Git = class Git extends Service()("react-doctor/Git") {
 					status: result.status,
 					stdout: result.stdout
 				};
-			}),
+			}).pipe(withSpan("Git.grep")),
 			changedLineRanges: ({ directory, baseRef, cached, files }) => gen(function* () {
 				if (files.length === 0) return [];
 				if (baseRef !== void 0 && !isSafeGitRevision(baseRef)) return null;
@@ -40929,7 +41024,7 @@ var Git = class Git extends Service()("react-doctor/Git") {
 				]);
 				if (result.status !== 0) return null;
 				return parseChangedLineRanges(result.stdout);
-			})
+			}).pipe(withSpan("Git.changedLineRanges"))
 		});
 	})).pipe(provide$2(layer$3.pipe(provide$2(mergeAll$1(layer$2, layer$1)))));
 	/**
@@ -41144,7 +41239,7 @@ const neutralizeDisableDirectives = async (rootDirectory, includePaths) => {
 		for (const [absolutePath, originalContent] of originalContents) try {
 			NFS.writeFileSync(absolutePath, originalContent);
 		} catch (error) {
-			process.stderr.write(`[react-doctor] Failed to restore inline disable directives in ${absolutePath}: ${error instanceof Error ? error.message : String(error)}\n[react-doctor] Run: git checkout -- ${absolutePath}\n`);
+			process.stderr.write(`[react-doctor] Failed to restore inline disable directives in ${absolutePath}: ${messageFromUnknown(error)}\n[react-doctor] Run: git checkout -- ${absolutePath}\n`);
 		}
 	};
 	const onExit = () => restore();
@@ -41250,7 +41345,7 @@ const resolveUserPlugin = (spec, configSourceDirectory) => {
 	try {
 		resolvedSpecifier = isRelative ? Path.resolve(configSourceDirectory, spec) : candidateRequire.resolve(spec);
 	} catch (error) {
-		warnConfigIssue(`config.plugins entry "${spec}" could not be resolved from ${configSourceDirectory}: ${error instanceof Error ? error.message : String(error)}`);
+		warnConfigIssue(`config.plugins entry "${spec}" could not be resolved from ${configSourceDirectory}: ${messageFromUnknown(error)}`);
 		return null;
 	}
 	const { name, ruleNames } = readPluginShape(resolvedSpecifier, (target) => candidateRequire(target));
@@ -41322,8 +41417,8 @@ const buildUserPluginRules = (userPlugin, severityControls) => {
 	}
 	return enabled;
 };
-const createOxlintConfig = ({ pluginPath, project, customRulesOnly = false, extendsPaths = [], ignoredTags = /* @__PURE__ */ new Set(), serverAuthFunctionNames, severityControls, userPlugins = [] }) => {
-	const reactHooksJsPlugin = resolveReactHooksJsPlugin(project.hasReactCompiler, customRulesOnly);
+const createOxlintConfig = ({ pluginPath, project, customRulesOnly = false, extendsPaths = [], ignoredTags = /* @__PURE__ */ new Set(), serverAuthFunctionNames, severityControls, userPlugins = [], disableReactHooksJsPlugin = false }) => {
+	const reactHooksJsPlugin = disableReactHooksJsPlugin ? null : resolveReactHooksJsPlugin(project.hasReactCompiler, customRulesOnly);
 	const reactCompilerRules = reactHooksJsPlugin ? applyRuleSeverityControls(filterRulesToAvailable(REACT_COMPILER_RULES, "react-hooks-js", reactHooksJsPlugin.availableRuleNames), severityControls) : {};
 	const jsPlugins = [];
 	if (reactHooksJsPlugin) jsPlugins.push(reactHooksJsPlugin.entry);
@@ -41383,7 +41478,6 @@ const resolveOxlintBinary = () => {
 	return Path.join(oxlintPackageDirectory, "bin", "oxlint");
 };
 const resolvePluginPath = () => esmRequire.resolve("oxlint-plugin-react-doctor");
-const TSCONFIG_FILENAMES = ["tsconfig.json", "tsconfig.base.json"];
 const resolveTsConfigRelativePath = (rootDirectory) => {
 	for (const filename of TSCONFIG_FILENAMES) if (NFS.existsSync(Path.join(rootDirectory, filename))) return `./${filename}`;
 	return null;
@@ -41755,7 +41849,7 @@ const scopeContainsNonImportBinding = (node, scopeNode, identifierName) => {
 const isIdentifierShadowedByLocalBinding = (identifier, sourceFile) => {
 	let currentNode = identifier.parent;
 	while (currentNode) {
-		if (isScopeNode(currentNode)) {
+		if (isScopeBoundary(currentNode)) {
 			if (scopeContainsNonImportBinding(currentNode, currentNode, identifier.text)) return true;
 		}
 		if (currentNode === sourceFile) return false;
@@ -41846,11 +41940,10 @@ const findResolutionInScope = (scopeNode, identifierName, reactImportBindings, s
 	});
 	return resolution;
 };
-const isScopeNode = isScopeBoundary;
 const resolveIdentifierBinding = (identifier, reactImportBindings, sourceFile, visitedDeclarations = /* @__PURE__ */ new Set()) => {
 	let currentNode = identifier.parent;
 	while (currentNode) {
-		if (isScopeNode(currentNode)) {
+		if (isScopeBoundary(currentNode)) {
 			const resolution = findResolutionInScope(currentNode, identifier.text, reactImportBindings, sourceFile, visitedDeclarations);
 			if (resolution) return resolution;
 		}
@@ -42020,9 +42113,9 @@ const parseOxlintOutput = (stdout, project, rootDirectory) => {
 	try {
 		parsed = JSON.parse(sanitizedStdout);
 	} catch {
-		throw new ReactDoctorError({ reason: new OxlintOutputUnparseable({ preview: stdout.slice(0, 200) }) });
+		throw new ReactDoctorError({ reason: new OxlintOutputUnparseable({ preview: stdout.slice(0, 600) }) });
 	}
-	if (!isOxlintOutput(parsed)) throw new ReactDoctorError({ reason: new OxlintOutputUnparseable({ preview: stdout.slice(0, 200) }) });
+	if (!isOxlintOutput(parsed)) throw new ReactDoctorError({ reason: new OxlintOutputUnparseable({ preview: stdout.slice(0, 600) }) });
 	const minifiedFileCache = /* @__PURE__ */ new Map();
 	const isMinifiedDiagnosticFile = (filename) => {
 		const absolutePath = Path.isAbsolute(filename) ? filename : Path.resolve(rootDirectory || ".", filename);
@@ -42098,7 +42191,7 @@ const spawnOxlint = (args, rootDirectory, nodeBinaryPath, spawnTimeoutMs = OXLIN
 		child.kill("SIGKILL");
 		reject(new ReactDoctorError({ reason: new OxlintBatchExceeded({
 			kind: "timeout",
-			detail: `${spawnTimeoutMs / 1e3}s budget exceeded`
+			detail: `${spawnTimeoutMs / MILLISECONDS_PER_SECOND}s budget exceeded`
 		}) }));
 	}, spawnTimeoutMs);
 	timeoutHandle.unref?.();
@@ -42313,6 +42406,28 @@ const writeOxlintConfig = (configPath, configToWrite) => {
 		NFS.closeSync(fileHandle);
 	}
 };
+const REACT_HOOKS_JS_DROP_PREFIX = "React Compiler rules (react-hooks-js/*) skipped — eslint-plugin-react-hooks failed to load in this environment";
+/**
+* Detects an oxlint config-load crash caused by the optional
+* `react-hooks-js` (eslint-plugin-react-hooks) React Compiler plugin and
+* builds the partial-failure note for it; returns `null` when the failure
+* was anything else.
+*
+* oxlint prints a framed error to stdout (not stderr) and exits non-zero
+* when a `jsPlugins` entry can't be imported; that non-JSON stdout
+* surfaces as `OxlintOutputUnparseable`. Because oxlint fails the WHOLE
+* config load on it, leaving the plugin in would drop every curated
+* react-doctor diagnostic too — so the caller retries with the plugin
+* stripped (issue #833). Both markers sit at the start of oxlint's
+* message, so they survive the `preview` slice even for deep pnpm paths.
+*/
+const reactHooksJsPluginDropNote = (error) => {
+	if (!(error instanceof ReactDoctorError) || error.reason._tag !== "OxlintOutputUnparseable") return null;
+	const { preview } = error.reason;
+	if (!preview.includes("Failed to load JS plugin") || !preview.includes("eslint-plugin-react-hooks")) return null;
+	const underlyingReason = preview.match(/Error:[^\n]*/)?.[0]?.trim();
+	return `${REACT_HOOKS_JS_DROP_PREFIX}${underlyingReason ? `: ${underlyingReason}` : ""}. Other rules ran normally.`;
+};
 /**
 * The oxlint runner. Composed of three pieces in `runners/oxlint/`:
 *
@@ -42340,15 +42455,16 @@ const runOxlint = async (options) => {
 	const pluginPath = resolvePluginPath();
 	const extendsPaths = (adoptExistingLintConfig && !customRulesOnly ? detectUserLintConfigPaths(rootDirectory) : []).filter(canOxlintExtendConfig);
 	const userPlugins = resolveUserPlugins(userConfig?.plugins, configSourceDirectory);
-	const buildConfig = (extendsForThisAttempt) => createOxlintConfig({
+	const buildConfig = (overrides) => createOxlintConfig({
 		pluginPath,
 		project,
 		customRulesOnly,
-		extendsPaths: extendsForThisAttempt,
+		extendsPaths: overrides.extendsPaths,
 		ignoredTags,
 		serverAuthFunctionNames,
 		severityControls,
-		userPlugins
+		userPlugins,
+		disableReactHooksJsPlugin: overrides.disableReactHooksJsPlugin
 	});
 	const restoreDisableDirectives = respectInlineDisables ? () => {} : await neutralizeDisableDirectives(rootDirectory, includePaths);
 	const configDirectory = NFS.mkdtempSync(Path.join(os.tmpdir(), "react-doctor-oxlintrc-"));
@@ -42384,12 +42500,22 @@ const runOxlint = async (options) => {
 			outputMaxBytes,
 			concurrency: options.concurrency
 		});
-		writeOxlintConfig(configPath, buildConfig(extendsPaths));
+		writeOxlintConfig(configPath, buildConfig({ extendsPaths }));
 		try {
 			return await runBatches();
 		} catch (error) {
+			const reactHooksJsDropNote = reactHooksJsPluginDropNote(error);
+			if (reactHooksJsDropNote !== null) {
+				writeOxlintConfig(configPath, buildConfig({
+					extendsPaths,
+					disableReactHooksJsPlugin: true
+				}));
+				const diagnostics = await runBatches();
+				onPartialFailure?.(reactHooksJsDropNote);
+				return diagnostics;
+			}
 			if (extendsPaths.length === 0) throw error;
-			writeOxlintConfig(configPath, buildConfig([]));
+			writeOxlintConfig(configPath, buildConfig({ extendsPaths: [] }));
 			return await runBatches();
 		}
 	} finally {
@@ -43187,17 +43313,17 @@ const runInspect = (input, hooks = {}) => gen(function* () {
 	}))))))));
 	const deadCodeFailureState = yield* get$2(deadCodeFailure);
 	const scanElapsedMilliseconds = Date.now() - scanStartTime;
-	const scanElapsedSeconds = (scanElapsedMilliseconds / 1e3).toFixed(1);
+	const scanElapsedSeconds = (scanElapsedMilliseconds / MILLISECONDS_PER_SECOND).toFixed(1);
 	if (!lintFailureState.didFail) if (deadCodeFailureState.didFail) yield* scanProgress.fail(DEAD_CODE_FAIL_TEXT);
 	else if (input.suppressScanSummary) yield* scanProgress.stop();
 	else yield* scanProgress.succeed(`Scanned ${scannedFilesLabel} in ${scanElapsedSeconds}s${workerCountSuffix}`);
 	yield* reporterService.finalize;
-	const finalDiagnostics = [
+	const finalDiagnostics = assignFixGroups([
 		...envCollected,
 		...supplyChainCollected,
 		...lintCollected,
 		...deadCodeCollected
-	];
+	]);
 	const githubViewerPermission = yield* join(githubViewerPermissionFiber);
 	const scoreMetadata = {
 		...repo !== null ? { repo } : {},
@@ -43424,7 +43550,7 @@ var StagedFiles = class StagedFiles extends Service()("react-doctor/StagedFiles"
 	static layerNode = effect(StagedFiles, gen(function* () {
 		const git = yield* Git;
 		return StagedFiles.of({
-			discoverSourceFiles: (directory) => git.stagedFilePaths(directory).pipe(map$3((entries) => entries.filter(isLintableSourceFile))),
+			discoverSourceFiles: (directory) => git.stagedFilePaths(directory).pipe(map$3((entries) => entries.filter(isLintableSourceFile)), withSpan("StagedFiles.discoverSourceFiles")),
 			materialize: ({ directory, stagedFiles, tempDirectory }) => materializeSourceTree({
 				directory,
 				files: stagedFiles,
@@ -43434,7 +43560,7 @@ var StagedFiles = class StagedFiles extends Service()("react-doctor/StagedFiles"
 				tempDirectory: tree.tempDirectory,
 				stagedFiles: tree.materializedFiles,
 				cleanup: tree.cleanup
-			})))
+			})), withSpan("StagedFiles.materialize"))
 		});
 	}));
 	/**
@@ -43567,6 +43693,7 @@ const buildJsonReport = (input) => {
 		score: result.score,
 		skippedChecks: result.skippedChecks,
 		...result.skippedCheckReasons ? { skippedCheckReasons: result.skippedCheckReasons } : {},
+		...typeof result.scannedFileCount === "number" ? { scannedFileCount: result.scannedFileCount } : {},
 		elapsedMilliseconds: result.elapsedMilliseconds
 	}));
 	const flattenedDiagnostics = projects.flatMap((entry) => entry.diagnostics);
@@ -43841,7 +43968,7 @@ const FALSY_CI_FLAG_VALUES = new Set([
 	"false"
 ]);
 const isCiFlagSet = (value) => value !== void 0 && !FALSY_CI_FLAG_VALUES.has(value.toLowerCase());
-const isCiEnvironment = () => CI_ENVIRONMENT_VARIABLES.some((environmentVariable) => Boolean(process.env[environmentVariable])) || isCiFlagSet(process.env.CI);
+const isCiEnvironment = (env = process.env) => CI_ENVIRONMENT_VARIABLES.some((environmentVariable) => Boolean(env[environmentVariable])) || isCiFlagSet(env.CI);
 const detectCiProvider = () => {
 	for (const [environmentVariable, provider] of CI_PROVIDER_BY_ENVIRONMENT_VARIABLE) if (process.env[environmentVariable]) return provider;
 	return isCiFlagSet(process.env.CI) ? "unknown" : null;
@@ -43866,6 +43993,53 @@ const detectCodingAgent = () => {
 const isCodingAgentEnvironment = () => detectCodingAgent() !== null;
 const isCiOrCodingAgentEnvironment = () => isCiEnvironment() || isCodingAgentEnvironment();
 //#endregion
+//#region src/cli/utils/detect-terminal-kind.ts
+const TERMINAL_BY_TERM_PROGRAM = [
+	["vscode", "vscode"],
+	["iTerm.app", "iterm"],
+	["Apple_Terminal", "apple-terminal"],
+	["WezTerm", "wezterm"],
+	["ghostty", "ghostty"],
+	["Hyper", "hyper"],
+	["Tabby", "tabby"],
+	["rio", "rio"]
+];
+/**
+* Best-effort label for the terminal emulator / editor hosting the CLI,
+* derived from terminal-identity env vars. Recorded as the `terminalKind` run
+* tag so we can see where React Doctor is actually run (nvim, VS Code, iTerm,
+* …) — the split Sentry can't otherwise see. Low-cardinality and free of any
+* username/path/secret, so it's safe as a tag. Editor terminals (nvim/vim)
+* win over the outer emulator because that's the surface a user is reading in;
+* "ci" marks a run with no interactive terminal; "unknown" when nothing matches.
+*/
+const detectTerminalKind = (env = process.env) => {
+	if (env.NVIM) return "neovim";
+	if (env.VIM_TERMINAL) return "vim";
+	const termProgram = env.TERM_PROGRAM;
+	if (termProgram) {
+		for (const [marker, label] of TERMINAL_BY_TERM_PROGRAM) if (termProgram === marker) return label;
+	}
+	if (env.KITTY_WINDOW_ID || env.TERM === "xterm-kitty") return "kitty";
+	if (env.WT_SESSION) return "windows-terminal";
+	if (env.ALACRITTY_WINDOW_ID || env.TERM === "alacritty") return "alacritty";
+	if (env.VTE_VERSION) return "vte";
+	if (env.TMUX) return "tmux";
+	if (isCiEnvironment(env)) return "ci";
+	return "unknown";
+};
+//#endregion
+//#region src/cli/utils/is-debug-flag.ts
+/**
+* Whether the user passed `--debug` (surface the run's Sentry trace id, and
+* force performance tracing on so there's a trace to surface). Read straight
+* from argv rather than Commander's parsed flags because `initializeSentry()`
+* runs before Commander parses — the same reason `shouldEnableSentry()` reads
+* `--no-score` from argv. Sharing this one reader keeps the init-time sampling
+* override and the end-of-run print in agreement.
+*/
+const isDebugFlagEnabled = (argv = process.argv) => argv.includes("--debug");
+//#endregion
 //#region src/cli/utils/is-git-hook-environment.ts
 const isGitHookEnvironment = () => Boolean(process.env.GIT_DIR);
 //#endregion
@@ -43888,6 +44062,7 @@ const NON_INTERACTIVE_ENVIRONMENT_VARIABLES = [
 const isNonInteractiveEnvironment = () => NON_INTERACTIVE_ENVIRONMENT_VARIABLES.some((envVariable) => Boolean(process.env[envVariable])) || isCodingAgentEnvironment();
 //#endregion
 //#region src/cli/utils/constants.ts
+const REACT_DOCTOR_CONFIG_PROJECT_NAME = "react-doctor";
 const STAGED_FILES_TEMP_DIR_PREFIX = "react-doctor-staged-";
 const BASELINE_FILES_TEMP_DIR_PREFIX = "react-doctor-baseline-";
 const GH_DEFAULT_BRANCH_PROBE_TIMEOUT_MS = 5e3;
@@ -43972,7 +44147,7 @@ const makeNoopConsole = () => ({
 });
 //#endregion
 //#region src/cli/utils/version.ts
-const VERSION = "0.5.6";
+const VERSION = "0.5.7-dev.350a6ed";
 //#endregion
 //#region src/cli/utils/json-mode.ts
 let context = null;
@@ -44122,7 +44297,9 @@ const buildRunContext = () => {
 		viaAction: isOfficialGithubAction(),
 		codingAgent: detectCodingAgent(),
 		interactive: !isNonInteractiveEnvironment(),
+		terminalKind: detectTerminalKind(),
 		jsonMode: isJsonModeActive(),
+		debug: isDebugFlagEnabled(),
 		invokedVia: detectInvokedVia()
 	};
 };
@@ -44192,7 +44369,9 @@ const buildSentryScope = (runContext = buildRunContext()) => {
 		viaAction: runContext.viaAction,
 		codingAgent: runContext.codingAgent,
 		interactive: runContext.interactive,
+		terminalKind: runContext.terminalKind,
 		jsonMode: runContext.jsonMode,
+		debug: runContext.debug,
 		invokedVia: runContext.invokedVia,
 		nodeMajor: runContext.nodeMajor
 	};
@@ -44330,13 +44509,13 @@ const isDevVersion = (version) => version === "0.0.0" || version.includes("-");
 * uploads source-map artifacts under, so stack frames symbolicate. Honors the
 * standard `SENTRY_RELEASE` override.
 */
-const resolveSentryRelease = () => process.env.SENTRY_RELEASE || `react-doctor@0.5.6`;
+const resolveSentryRelease = () => process.env.SENTRY_RELEASE || `react-doctor@0.5.7-dev.350a6ed`;
 /**
 * Deployment environment shown in Sentry's environment filter. Defaults to
 * `production` for tagged releases and `development` for dev/unbuilt versions,
 * overridable via the standard `SENTRY_ENVIRONMENT` env var.
 */
-const resolveSentryEnvironment = () => process.env.SENTRY_ENVIRONMENT || (isDevVersion("0.5.6") ? "development" : "production");
+const resolveSentryEnvironment = () => process.env.SENTRY_ENVIRONMENT || (isDevVersion("0.5.7-dev.350a6ed") ? "development" : "production");
 /**
 * Performance-tracing sample rate in `[0, 1]`. Reads `SENTRY_TRACES_SAMPLE_RATE`
 * (set to `0` to disable tracing) and falls back to
@@ -44400,7 +44579,7 @@ const flushSentry = async () => {
 const initializeSentry = () => {
 	if (isInitialized || !shouldEnableSentry()) return;
 	isInitialized = true;
-	resolvedTracesSampleRate = resolveTracesSampleRate();
+	resolvedTracesSampleRate = isDebugFlagEnabled() ? 1 : resolveTracesSampleRate();
 	const { tags, contexts } = buildSentryScope();
 	Sentry.init({
 		dsn: process.env.SENTRY_DSN || "https://f253d570240a59b8dbd77b7a548ef133@o4510226365743104.ingest.us.sentry.io/4511487817809920",
@@ -47616,6 +47795,11 @@ const setActiveRunTrace = (trace) => {
 	activeRunTrace = trace;
 };
 const getActiveRunTrace = () => activeRunTrace;
+let lastRunTraceId = null;
+const recordRunTraceId = (traceId) => {
+	lastRunTraceId = traceId;
+};
+const getLastRunTraceId = () => lastRunTraceId;
 //#endregion
 //#region src/cli/utils/to-span-attributes.ts
 /**
@@ -47678,14 +47862,13 @@ const withSentryRunSpan = (run, options = {}) => {
 		op: "cli.inspect",
 		attributes: toSpanAttributes(tags)
 	}, (rootSpan) => {
-		if (options.concurrentScan !== true) {
-			const spanContext = rootSpan.spanContext();
-			setActiveRunTrace({
-				traceId: spanContext.traceId,
-				spanId: spanContext.spanId,
-				sampled: (spanContext.traceFlags & 1) === 1
-			});
-		}
+		const spanContext = rootSpan.spanContext();
+		recordRunTraceId(spanContext.traceId);
+		if (options.concurrentScan !== true) setActiveRunTrace({
+			traceId: spanContext.traceId,
+			spanId: spanContext.spanId,
+			sampled: (spanContext.traceFlags & 1) === 1
+		});
 		return run(rootSpan);
 	});
 };
@@ -47825,6 +48008,42 @@ const recordScanMetrics = (input) => {
 	});
 };
 //#endregion
+//#region src/cli/utils/diagnostic-grouping.ts
+const buildRulePriorityMap = (scores) => {
+	const rulePriority = /* @__PURE__ */ new Map();
+	for (const score of scores) {
+		if (!score?.rules) continue;
+		for (const [ruleKey, info] of Object.entries(score.rules)) if (typeof info.priority === "number") rulePriority.set(ruleKey, info.priority);
+	}
+	return rulePriority;
+};
+const compareByRulePriority = (ruleKeyA, ruleKeyB, rulePriority) => {
+	const priorityA = rulePriority?.get(ruleKeyA);
+	const priorityB = rulePriority?.get(ruleKeyB);
+	if (priorityA === void 0 && priorityB === void 0) return 0;
+	if (priorityA === void 0) return 1;
+	if (priorityB === void 0) return -1;
+	return priorityB - priorityA;
+};
+const sortRuleGroupsByImportance = (diagnosticGroups, rulePriority) => diagnosticGroups.toSorted(([ruleKeyA], [ruleKeyB]) => compareByRulePriority(ruleKeyA, ruleKeyB, rulePriority));
+const buildSortedRuleGroups = (diagnostics, rulePriority) => sortRuleGroupsByImportance([...groupBy([...diagnostics], (diagnostic) => `${diagnostic.plugin}/${diagnostic.rule}`)], rulePriority);
+const getSharedFixSiteCount = (diagnostics) => {
+	if (diagnostics.length < 2) return 0;
+	const firstFixGroupId = diagnostics[0]?.fixGroupId;
+	if (!firstFixGroupId) return 0;
+	return diagnostics.every((diagnostic) => diagnostic.fixGroupId === firstFixGroupId) ? diagnostics.length : 0;
+};
+const FIX_RECIPE_DIRECTIVE_LABEL = "Curl with no cache & follow the canonical fix and false positive check recipe before fixing";
+const formatFixRecipeLine = (diagnostic) => hasPublishedFixRecipe(diagnostic) ? `${FIX_RECIPE_DIRECTIVE_LABEL}: ${buildRuleDocsUrl(diagnostic.plugin, diagnostic.rule)}` : null;
+const formatLearnMoreLine = (diagnostic) => hasPublishedFixRecipe(diagnostic) ? `Learn more: ${buildRuleDocsUrl(diagnostic.plugin, diagnostic.rule)}` : null;
+const buildRuleBlastRadii = (diagnostics) => buildSortedRuleGroups(diagnostics).map(([ruleKey, ruleDiagnostics]) => ({
+	ruleKey,
+	title: ruleDiagnostics[0].title ?? ruleKey,
+	siteCount: ruleDiagnostics.length,
+	fileCount: new Set(ruleDiagnostics.map((diagnostic) => diagnostic.filePath)).size
+})).toSorted((left, right) => right.fileCount - left.fileCount);
+const findMigrationScaleBuckets = (diagnostics) => buildRuleBlastRadii(diagnostics).filter((bucket) => bucket.fileCount >= 40);
+//#endregion
 //#region src/cli/utils/cli-logger.ts
 /**
 * Thin synchronous façade over Effect's `Console` module. Used by
@@ -47941,12 +48160,17 @@ const buildOutcomeAttributes = (input) => {
 		topRule = rule;
 		topRuleCount = count;
 	}
+	const largestRuleBucket = buildRuleBlastRadii(result.diagnostics)[0] ?? null;
 	let diagnosticsInTestFiles = 0;
 	let diagnosticsInStoryFiles = 0;
+	const findingsPerFixGroup = /* @__PURE__ */ new Map();
 	for (const diagnostic of result.diagnostics) {
 		if (diagnostic.fileContext === "test") diagnosticsInTestFiles += 1;
 		if (diagnostic.fileContext === "story") diagnosticsInStoryFiles += 1;
+		if (diagnostic.fixGroupId) findingsPerFixGroup.set(diagnostic.fixGroupId, (findingsPerFixGroup.get(diagnostic.fixGroupId) ?? 0) + 1);
 	}
+	let fixGroupedFindings = 0;
+	for (const count of findingsPerFixGroup.values()) fixGroupedFindings += count;
 	const attributes = {
 		outcome,
 		exitCode: wouldBlock ? 1 : 0,
@@ -47960,7 +48184,12 @@ const buildOutcomeAttributes = (input) => {
 		diagnosticsInTestFiles,
 		diagnosticsInStoryFiles,
 		distinctRulesFired: countByRule.size,
+		"diag.fixGroups": findingsPerFixGroup.size,
+		"diag.fixGroupedFindings": fixGroupedFindings,
 		topRule,
+		"migration.largestRuleBucketFiles": largestRuleBucket ? largestRuleBucket.fileCount : null,
+		"migration.largestRuleBucketSites": largestRuleBucket ? largestRuleBucket.siteCount : null,
+		"migration.largestRuleBucketRule": largestRuleBucket ? largestRuleBucket.ruleKey : null,
 		scannedFileCount: result.scannedFileCount ?? null,
 		elapsedMs: result.elapsedMilliseconds,
 		scanPhaseMs: result.scanElapsedMilliseconds ?? null,
@@ -48118,9 +48347,10 @@ const AGENT_GUIDANCE_LINES = [
 	"Investigate deeply where relevant: race conditions, security-sensitive flows, state propagation, multi-file refactors, and downstream dependency chains.",
 	"Ignore pure style preferences, theoretical issues without real impact, missing features, and unrelated pre-existing code.",
 	"Start with high-confidence fixes that preserve behavior. Leave low-confidence or product-dependent changes as notes.",
-	"Run `npx react-doctor@latest --verbose --diff` before and after changes, plus relevant tests after each focused batch.",
+	"Run `npx react-doctor@latest --verbose --scope changed` before and after changes, plus relevant tests after each focused batch.",
 	"When available, spawn subagents or isolated worktrees for independent rule families, then review and merge only the best safe fixes.",
 	"Split unrelated, broad, or behavior-changing work into separate PRs/branches instead of one large cleanup.",
+	"When one rule spans dozens of files (a migration-scale change), fix a representative sample first, confirm the recipe holds, and get the code owner's sign-off before changing the rest. Don't mass-fix a broad pattern in one unreviewed pass.",
 	"For confirmed issues that cannot be fixed now, create GitHub issues with the rule, file/line, confidence, impact, and proposed fix.",
 	"If a fix needs an API, UX, or architecture decision, stop and ask before editing."
 ];
@@ -48130,29 +48360,6 @@ const printAgentGuidance = () => gen(function* () {
 	yield* log("");
 });
 //#endregion
-//#region src/cli/utils/diagnostic-grouping.ts
-const buildRulePriorityMap = (scores) => {
-	const rulePriority = /* @__PURE__ */ new Map();
-	for (const score of scores) {
-		if (!score?.rules) continue;
-		for (const [ruleKey, info] of Object.entries(score.rules)) if (typeof info.priority === "number") rulePriority.set(ruleKey, info.priority);
-	}
-	return rulePriority;
-};
-const compareByRulePriority = (ruleKeyA, ruleKeyB, rulePriority) => {
-	const priorityA = rulePriority?.get(ruleKeyA);
-	const priorityB = rulePriority?.get(ruleKeyB);
-	if (priorityA === void 0 && priorityB === void 0) return 0;
-	if (priorityA === void 0) return 1;
-	if (priorityB === void 0) return -1;
-	return priorityB - priorityA;
-};
-const sortRuleGroupsByImportance = (diagnosticGroups, rulePriority) => diagnosticGroups.toSorted(([ruleKeyA], [ruleKeyB]) => compareByRulePriority(ruleKeyA, ruleKeyB, rulePriority));
-const buildSortedRuleGroups = (diagnostics, rulePriority) => sortRuleGroupsByImportance([...groupBy([...diagnostics], (diagnostic) => `${diagnostic.plugin}/${diagnostic.rule}`)], rulePriority);
-const FIX_RECIPE_DIRECTIVE_LABEL = "Curl with no cache & follow the canonical fix and false positive check recipe before fixing";
-const formatFixRecipeLine = (diagnostic) => hasPublishedFixRecipe(diagnostic) ? `${FIX_RECIPE_DIRECTIVE_LABEL}: ${buildRuleDocsUrl(diagnostic.plugin, diagnostic.rule)}` : null;
-const formatLearnMoreLine = (diagnostic) => hasPublishedFixRecipe(diagnostic) ? `Learn more: ${buildRuleDocsUrl(diagnostic.plugin, diagnostic.rule)}` : null;
-//#endregion
 //#region src/cli/utils/box-text.ts
 const ESCAPE = String.fromCharCode(27);
 const ANSI_ESCAPE_PATTERN = new RegExp(`${ESCAPE}\\[[0-9;]*m`, "g");
@@ -48193,6 +48400,15 @@ const boxText = (content, innerWidth) => {
 	].join("\n");
 };
 //#endregion
+//#region src/cli/utils/resolve-absolute-path.ts
+/**
+* Resolves a diagnostic's `filePath` (relative to its project root, or
+* already absolute) to an absolute path. Shared by the code-frame reader and
+* the terminal hyperlink builder so both turn a relative path into the same
+* on-disk location.
+*/
+const resolveAbsolutePath = (filePath, rootDirectory) => Path.isAbsolute(filePath) ? filePath : Path.resolve(rootDirectory || ".", filePath);
+//#endregion
 //#region src/cli/utils/build-code-frame.ts
 /**
 * Renders a syntax-highlighted source excerpt around a diagnostic site
@@ -48203,7 +48419,7 @@ const boxText = (content, innerWidth) => {
 */
 const buildCodeFrame = (input) => {
 	if (input.line <= 0) return null;
-	const absolutePath = Path.isAbsolute(input.filePath) ? input.filePath : Path.resolve(input.rootDirectory || ".", input.filePath);
+	const absolutePath = resolveAbsolutePath(input.filePath, input.rootDirectory);
 	let source;
 	try {
 		source = NFS.readFileSync(absolutePath, "utf8");
@@ -48243,6 +48459,16 @@ const resolveMeasureWidth = (reservedColumns = 0) => resolveClampedWidth({
 const DIVIDER_INDENT = "  ";
 const buildSectionDivider = () => highlighter.dim(`${DIVIDER_INDENT}${"─".repeat(resolveMeasureWidth(2))}`);
 //#endregion
+//#region src/cli/utils/format-hyperlink.ts
+const OSC = "\x1B]";
+const ST = "\x1B\\";
+/**
+* Wraps `text` in an OSC 8 hyperlink pointing at `uri`. The visible characters
+* are exactly `text`; the link is carried in escape sequences a capable
+* terminal turns into a click target.
+*/
+const formatHyperlink = (text, uri) => `${OSC}8;;${uri}${ST}${text}${OSC}8;;${ST}`;
+//#endregion
 //#region src/cli/utils/indent-multiline-text.ts
 const indentMultilineText = (text, linePrefix) => text.split("\n").map((lineText) => `${linePrefix}${lineText}`).join("\n");
 //#endregion
@@ -48396,17 +48622,23 @@ const clusterNearbyDiagnostics = (diagnostics) => {
 	}
 	return clusters;
 };
-const formatClusterLocation = (cluster) => {
+const formatClusterLocationText = (cluster) => {
+	const { filePath } = cluster.diagnostics[0];
+	if (cluster.startLine <= 0) return filePath;
+	if (cluster.endLine > cluster.startLine) return `${filePath}:${cluster.startLine}-${cluster.endLine}`;
+	return `${filePath}:${cluster.startLine}`;
+};
+const formatClusterLocation = (cluster, resolveSourceRoot, hyperlinks) => {
 	const lead = cluster.diagnostics[0];
 	const contextTag = formatFileContextTag(lead);
-	if (cluster.startLine <= 0) return `${lead.filePath}${contextTag}`;
-	if (cluster.endLine > cluster.startLine) return `${lead.filePath}:${cluster.startLine}-${cluster.endLine}${contextTag}`;
-	return `${lead.filePath}:${cluster.startLine}${contextTag}`;
+	const location = formatClusterLocationText(cluster);
+	if (!hyperlinks) return `${location}${contextTag}`;
+	return `${formatHyperlink(location, pathToFileURL(resolveAbsolutePath(lead.filePath, resolveSourceRoot(lead))).href)}${contextTag}`;
 };
-const buildDiagnosticClusterLines = (cluster, resolveSourceRoot, renderCodeFrame) => {
+const buildDiagnosticClusterLines = (cluster, resolveSourceRoot, renderCodeFrame, hyperlinks) => {
 	const lead = cluster.diagnostics[0];
 	const isMultiSite = cluster.diagnostics.length > 1;
-	const lines = ["", highlighter.gray(`${TOP_ERROR_DETAIL_INDENT}${formatClusterLocation(cluster)}`)];
+	const lines = ["", highlighter.gray(`${TOP_ERROR_DETAIL_INDENT}${formatClusterLocation(cluster, resolveSourceRoot, hyperlinks)}`)];
 	const codeFrame = renderCodeFrame ? buildCodeFrame({
 		filePath: lead.filePath,
 		line: cluster.startLine,
@@ -48425,7 +48657,7 @@ const buildDiagnosticClusterLines = (cluster, resolveSourceRoot, renderCodeFrame
 	}
 	return lines;
 };
-const buildRuleDetailBlock = (ruleKey, ruleDiagnostics, resolveSourceRoot, renderEverySite, isAgentEnvironment) => {
+const buildRuleDetailBlock = (ruleKey, ruleDiagnostics, resolveSourceRoot, renderEverySite, isAgentEnvironment, hyperlinks) => {
 	const representative = pickRepresentativeDiagnostic(ruleDiagnostics);
 	const { severity } = representative;
 	const trailingBadge = formatTrailingSiteBadge(ruleDiagnostics.length);
@@ -48439,13 +48671,15 @@ const buildRuleDetailBlock = (ruleKey, ruleDiagnostics, resolveSourceRoot, rende
 	const impactMessages = isCollapsedWarningGroup ? [...new Set(ruleDiagnostics.map((diagnostic) => diagnostic.message))] : [representative.message];
 	for (const impactMessage of impactMessages) for (const explanationLine of wrapTextToWidth(impactMessage, resolveMeasureWidth(4), { breakLongWords: false })) lines.push(`${TOP_ERROR_DETAIL_INDENT}${explanationLine}`);
 	if (representative.help) for (const fixLine of wrapTextToWidth(`→ ${representative.help}`, resolveMeasureWidth(4), { breakLongWords: false })) lines.push(highlighter.dim(`${TOP_ERROR_DETAIL_INDENT}${fixLine}`));
+	const sharedFixSiteCount = getSharedFixSiteCount(ruleDiagnostics);
+	if (sharedFixSiteCount > 0) lines.push(highlighter.dim(`${TOP_ERROR_DETAIL_INDENT}↳ One fix clears all ${sharedFixSiteCount} findings.`));
 	if (renderEverySite && isAgentEnvironment) {
 		const fixRecipeLine = formatFixRecipeLine(representative);
 		if (fixRecipeLine) lines.push(highlighter.gray(`${TOP_ERROR_DETAIL_INDENT}${fixRecipeLine}`));
 	}
 	const renderCodeFrame = severity === "error";
 	const sites = renderEverySite ? ruleDiagnostics : [representative];
-	if (!(isCollapsedWarningGroup && representative.help.includes(representative.filePath))) for (const cluster of clusterNearbyDiagnostics(sites)) lines.push(...buildDiagnosticClusterLines(cluster, resolveSourceRoot, renderCodeFrame));
+	if (!(isCollapsedWarningGroup && representative.help.includes(representative.filePath))) for (const cluster of clusterNearbyDiagnostics(sites)) lines.push(...buildDiagnosticClusterLines(cluster, resolveSourceRoot, renderCodeFrame, hyperlinks));
 	return lines;
 };
 const selectErrorRuleGroups = (diagnostics, rulePriority) => buildSortedRuleGroups(diagnostics.filter((diagnostic) => diagnostic.severity === "error"), rulePriority);
@@ -48457,8 +48691,21 @@ const buildOverflowSummaryLine = (diagnostics, rulePriority) => {
 	const command = highlighter.bold(highlighter.info("npx react-doctor@latest --verbose"));
 	return `  ${highlighter.dim("Run")} ${command} ${highlighter.dim("to list every error and warning")}`;
 };
+const formatMigrationBucketLine = (bucket) => `${TOP_ERROR_DETAIL_INDENT}${bucket.title} ${highlighter.gray(`×${bucket.siteCount} across ${bucket.fileCount} files`)}`;
+const buildMigrationScaleAdvisoryLines = (diagnostics) => {
+	const buckets = findMigrationScaleBuckets(diagnostics);
+	if (buckets.length === 0) return [];
+	const shownBuckets = buckets.slice(0, 3);
+	const lines = [`  ${highlighter.warn("⚠")} ${highlighter.bold("Migration-scale change")}${highlighter.dim(": sample before you sweep")}`, ...shownBuckets.map(formatMigrationBucketLine)];
+	const remainingBuckets = buckets.length - shownBuckets.length;
+	if (remainingBuckets > 0) lines.push(highlighter.gray(`${TOP_ERROR_DETAIL_INDENT}+${remainingBuckets} more ${remainingBuckets === 1 ? "rule" : "rules"} at this scale`));
+	for (const guidanceLine of wrapTextToWidth("Fixing all of them at once is hard to review and prone to subtle mistakes across the whole repo. Fix a representative few first and confirm the recipe holds. Then get the code owner's sign-off before changing the rest.", resolveMeasureWidth(4), { breakLongWords: false })) lines.push(highlighter.dim(`${TOP_ERROR_DETAIL_INDENT}${guidanceLine}`));
+	const command = highlighter.info("npx react-doctor@latest <path>");
+	lines.push(`${TOP_ERROR_DETAIL_INDENT}${highlighter.dim("Scope it down one area at a time:")} ${command}`);
+	return lines;
+};
 const getTopErrorRuleKeys = (diagnostics, limit, rulePriority) => new Set(selectTopErrorRuleGroups(diagnostics, limit, rulePriority).map(([ruleKey]) => ruleKey));
-const buildTopErrorsSection = (diagnostics, resolveSourceRoot, rulePriority) => {
+const buildTopErrorsSection = (diagnostics, resolveSourceRoot, hyperlinks, rulePriority) => {
 	const topRuleGroups = selectErrorRuleGroups(diagnostics, rulePriority).slice(0, 3);
 	if (topRuleGroups.length === 0) return {
 		lines: [],
@@ -48468,7 +48715,7 @@ const buildTopErrorsSection = (diagnostics, resolveSourceRoot, rulePriority) =>
 	const blockOffsets = [];
 	for (const [ruleKey, ruleDiagnostics] of topRuleGroups) {
 		blockOffsets.push(lines.length);
-		lines.push(...buildRuleDetailBlock(ruleKey, ruleDiagnostics, resolveSourceRoot, false, false));
+		lines.push(...buildRuleDetailBlock(ruleKey, ruleDiagnostics, resolveSourceRoot, false, false, hyperlinks));
 		lines.push("");
 	}
 	return {
@@ -48506,24 +48753,24 @@ const buildOverviewHeaderLines = (diagnostics) => {
 * single Effect.forEach over Console.log so failures or fiber
 * interruption produce predictable partial output.
 */
-const printDiagnostics = (diagnostics, isVerbose, sourceRoot, rulePriority, isAgentEnvironment = false, onboarding = {}) => gen(function* () {
+const printDiagnostics = (diagnostics, isVerbose, sourceRoot, rulePriority, isAgentEnvironment = false, onboarding = {}, hyperlinks = false) => gen(function* () {
 	const sectionPause = onboarding.sectionPause ?? void_;
 	const animateCountUp = onboarding.animateCountUp ?? false;
 	const resolveSourceRoot = typeof sourceRoot === "function" ? sourceRoot : () => sourceRoot;
 	let detailLines;
 	let topErrorBlockOffsets = [];
 	if (!isVerbose) {
-		const topErrors = buildTopErrorsSection(diagnostics, resolveSourceRoot, rulePriority);
+		const topErrors = buildTopErrorsSection(diagnostics, resolveSourceRoot, hyperlinks, rulePriority);
 		detailLines = topErrors.lines;
 		topErrorBlockOffsets = topErrors.blockOffsets;
 	} else detailLines = buildSortedRuleGroups(diagnostics, rulePriority).flatMap(([ruleKey, ruleDiagnostics]) => {
-		return [...buildRuleDetailBlock(ruleKey, ruleDiagnostics, resolveSourceRoot, true, isAgentEnvironment), ""];
+		return [...buildRuleDetailBlock(ruleKey, ruleDiagnostics, resolveSourceRoot, true, isAgentEnvironment, hyperlinks), ""];
 	});
 	const overflowLine = isVerbose ? void 0 : buildOverflowSummaryLine(diagnostics, rulePriority);
 	const categoryTallies = buildCategoryDiagnosticGroups(diagnostics, rulePriority).map(buildCategoryTally);
 	const categoryLines = buildCategoryTallyLines(categoryTallies);
 	const overviewDividerLines = detailLines.length > 0 && categoryLines.length > 0 ? [buildSectionDivider()] : [];
-	const { lines, sectionStarts } = joinSections(detailLines, overviewDividerLines, buildOverviewHeaderLines(diagnostics), categoryLines, overflowLine ? [overflowLine] : []);
+	const { lines, sectionStarts } = joinSections(detailLines, overviewDividerLines, buildOverviewHeaderLines(diagnostics), categoryLines, overflowLine ? [overflowLine] : [], buildMigrationScaleAdvisoryLines(diagnostics));
 	const [detailStart, , , categoryStart] = sectionStarts;
 	const pauseBeforeLineIndices = detailStart == null ? /* @__PURE__ */ new Set() : new Set(topErrorBlockOffsets.map((offset) => detailStart + offset));
 	let lineIndex = 0;
@@ -48578,6 +48825,48 @@ const computeProjectedScore = async (topErrorSource, rescoreSource, currentScore
 //#endregion
 //#region src/cli/utils/filter-diagnostics-by-categories.ts
 const filterDiagnosticsByCategories = (diagnostics, categories) => categories.size === 0 ? [...diagnostics] : diagnostics.filter((diagnostic) => categories.has(diagnostic.category));
+//#endregion
+//#region src/cli/utils/supports-hyperlinks.ts
+const HYPERLINK_CAPABLE_TERM_PROGRAMS = new Set([
+	"iTerm.app",
+	"WezTerm",
+	"vscode",
+	"Hyper",
+	"ghostty",
+	"Tabby",
+	"rio"
+]);
+const parseVteVersion = (raw) => {
+	const parsed = Number.parseInt(raw ?? "", 10);
+	return Number.isNaN(parsed) ? 0 : parsed;
+};
+/**
+* Whether `stream` is a terminal that renders OSC 8 hyperlinks. Auto-detected
+* from terminal-identity env vars; the de-facto `FORCE_HYPERLINK` env var
+* overrides detection (`FORCE_HYPERLINK=0`/`false` forces off, any other value
+* forces on), mirroring how the ecosystem's terminal libraries gate the same
+* feature. Off for non-TTYs, `TERM=dumb`, and CI (whose log viewers render the
+* raw escape rather than a link). Unknown terminals default to off.
+*/
+const supportsHyperlinks = (stream = process.stdout, env = process.env) => {
+	const forced = env.FORCE_HYPERLINK;
+	if (forced !== void 0 && forced !== "") return forced !== "0" && forced.toLowerCase() !== "false";
+	if (stream.isTTY !== true) return false;
+	if (env.TERM === "dumb") return false;
+	if (isCiEnvironment(env)) return false;
+	if (env.WT_SESSION) return true;
+	if (env.KITTY_WINDOW_ID || env.TERM === "xterm-kitty") return true;
+	if (parseVteVersion(env.VTE_VERSION) >= 5e3) return true;
+	return Boolean(env.TERM_PROGRAM && HYPERLINK_CAPABLE_TERM_PROGRAMS.has(env.TERM_PROGRAM));
+};
+//#endregion
+//#region src/cli/utils/should-render-hyperlinks.ts
+/**
+* Whether to emit OSC 8 clickable `file:line` locations for this run: a
+* hyperlink-capable terminal AND not a coding agent (whose output parsers
+* would choke on the escape sequences).
+*/
+const shouldRenderHyperlinks = (stream = process.stdout) => supportsHyperlinks(stream) && !isCodingAgentEnvironment();
 const FORCE_ONBOARDING_ENV_VAR = "REACT_DOCTOR_FORCE_ONBOARDING";
 const FALSY_FLAG_VALUES = new Set([
 	"",
@@ -48597,10 +48886,9 @@ const canAnimateOnboarding = (stream = process.stdout) => {
 };
 //#endregion
 //#region src/cli/utils/onboarding-state.ts
-const GLOBAL_CONFIG_PROJECT_NAME$2 = "react-doctor";
 const ONBOARDED_AT_KEY = "onboardedAt";
 const getOnboardingStore = (options = {}) => new Conf({
-	projectName: GLOBAL_CONFIG_PROJECT_NAME$2,
+	projectName: REACT_DOCTOR_CONFIG_PROJECT_NAME,
 	cwd: options.cwd
 });
 const hasCompletedOnboarding = (options = {}) => {
@@ -49056,6 +49344,78 @@ const resolveCliCategories = (categoryFlag) => {
 	return resolvedCategories.length > 0 ? resolvedCategories : void 0;
 };
 //#endregion
+//#region src/cli/utils/git-hook-shared.ts
+const HOOK_FILE_NAME = "pre-commit";
+const HOOK_RELATIVE_PATH = "hooks/pre-commit";
+const LEGACY_HOOK_RUNNER_RELATIVE_PATH = ".react-doctor/hooks/pre-commit";
+const HUSKY_HOOKS_PATH = ".husky";
+const VITE_PLUS_HOOKS_PATH = ".vite-hooks";
+const LEFTHOOK_CONFIG_FILES = ["lefthook.yml", "lefthook.yaml"];
+const PRE_COMMIT_CONFIG_FILE = ".pre-commit-config.yaml";
+const OVERCOMMIT_CONFIG_FILE = ".overcommit.yml";
+const REACT_DOCTOR_COMMAND = "react-doctor --staged --blocking warning";
+const NON_BLOCKING_REACT_DOCTOR_COMMAND = [
+	"react_doctor_output=$(mktemp \"${TMPDIR:-/tmp}/react-doctor-hook.XXXXXX\");",
+	`if ${REACT_DOCTOR_COMMAND} > "$react_doctor_output" 2>&1; then`,
+	"rm -f \"$react_doctor_output\";",
+	"else",
+	"rm -f \"$react_doctor_output\";",
+	`printf "%s\\n" "React Doctor found staged regressions." "Run ${REACT_DOCTOR_COMMAND} to inspect." "Want them fixed? Ask your agent to run that command and resolve the findings." >&2;`,
+	"fi"
+].join(" ");
+const PACKAGE_JSON_FILE_NAME = "package.json";
+const runGit = (projectRoot, args) => {
+	try {
+		return execFileSync("git", [...args], {
+			cwd: projectRoot,
+			encoding: "utf8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).trim();
+	} catch {
+		return null;
+	}
+};
+const resolveGitPath = (baseDirectory, value) => Path.isAbsolute(value) ? value : Path.resolve(baseDirectory, value);
+const isRecord$1 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const getPackageJsonPath = (projectRoot) => Path.join(projectRoot, PACKAGE_JSON_FILE_NAME);
+const readPackageJson = (projectRoot) => {
+	try {
+		return JSON.parse(NFS.readFileSync(getPackageJsonPath(projectRoot), "utf8"));
+	} catch {
+		return null;
+	}
+};
+const writeJsonFile$1 = (filePath, value) => {
+	NFS.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
+};
+const packageHasDependency = (projectRoot, dependencyName) => {
+	const packageJson = readPackageJson(projectRoot);
+	if (!isRecord$1(packageJson)) return false;
+	return [
+		"dependencies",
+		"devDependencies",
+		"optionalDependencies"
+	].some((fieldName) => {
+		const dependencies = packageJson[fieldName];
+		return isRecord$1(dependencies) && typeof dependencies[dependencyName] === "string";
+	});
+};
+const packageHasRecordKey = (projectRoot, key) => {
+	const packageJson = readPackageJson(projectRoot);
+	return isRecord$1(packageJson) && isRecord$1(packageJson[key]);
+};
+const packageHasNestedRecordKey = (projectRoot, key, nestedKey) => {
+	const packageJson = readPackageJson(projectRoot);
+	if (!isRecord$1(packageJson)) return false;
+	const value = packageJson[key];
+	return isRecord$1(value) && isRecord$1(value[nestedKey]);
+};
+const ensureTrailingNewline = (content) => content.endsWith("\n") ? content : `${content}\n`;
+//#endregion
 //#region src/cli/utils/scan-result-cache.ts
 const CACHE_DISABLED_VALUES = new Set(["1", "true"]);
 const TOOLCHAIN_PACKAGE_SPECIFIERS = [
@@ -49066,7 +49426,7 @@ const TOOLCHAIN_PACKAGE_SPECIFIERS = [
 	"eslint-plugin-react-hooks/package.json"
 ];
 const bundledRequire = createRequire(import.meta.url);
-const isRecord$1 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const normalizeForStableJson = (value) => {
 	if (value === null) return null;
 	if (value === void 0) return void 0;
@@ -49095,24 +49455,9 @@ const stringifyStableJson = (value) => {
 	}
 };
 const hashString = (value) => crypto.createHash("sha1").update(value).digest("hex");
-const runGit$1 = (directory, args) => {
-	try {
-		return execFileSync("git", [...args], {
-			cwd: directory,
-			encoding: "utf8",
-			stdio: [
-				"ignore",
-				"pipe",
-				"ignore"
-			]
-		}).trim();
-	} catch {
-		return null;
-	}
-};
-const readHeadSha = (projectDirectory) => runGit$1(projectDirectory, ["rev-parse", "HEAD"]);
+const readHeadSha = (projectDirectory) => runGit(projectDirectory, ["rev-parse", "HEAD"]);
 const isWorktreeClean = (projectDirectory) => {
-	const status = runGit$1(projectDirectory, [
+	const status = runGit(projectDirectory, [
 		"status",
 		"--porcelain=v1",
 		"--untracked-files=normal"
@@ -49120,7 +49465,7 @@ const isWorktreeClean = (projectDirectory) => {
 	return status !== null && status.length === 0;
 };
 const hasHiddenTrackedFileState = (projectDirectory) => {
-	const output = runGit$1(projectDirectory, ["ls-files", "-v"]);
+	const output = runGit(projectDirectory, ["ls-files", "-v"]);
 	if (output === null) return true;
 	return output.split("\n").some((line) => line.length > 0 && line[0] !== "H");
 };
@@ -49133,7 +49478,7 @@ const resolveCacheFilePath = (projectDirectory) => {
 const readPersistedCache = (cacheFilePath) => {
 	try {
 		const parsed = JSON.parse(fs.readFileSync(cacheFilePath, "utf8"));
-		if (!isRecord$1(parsed) || parsed.version !== 1) return {
+		if (!isRecord(parsed) || parsed.version !== 1) return {
 			version: 1,
 			entries: []
 		};
@@ -49143,8 +49488,8 @@ const readPersistedCache = (cacheFilePath) => {
 		};
 		const entries = [];
 		for (const entry of parsed.entries) {
-			if (!isRecord$1(entry) || typeof entry.key !== "string" || typeof entry.createdAtMs !== "number") continue;
-			if (!isRecord$1(entry.payload) || !Array.isArray(entry.payload.diagnostics)) continue;
+			if (!isRecord(entry) || typeof entry.key !== "string" || typeof entry.createdAtMs !== "number") continue;
+			if (!isRecord(entry.payload) || !Array.isArray(entry.payload.diagnostics)) continue;
 			entries.push(entry);
 		}
 		return {
@@ -49676,6 +50021,7 @@ const finalizeAndRender = (input) => gen(function* () {
 	}
 	const animateRender = !options.silent && !options.verbose && canAnimateOnboarding(process.stdout);
 	const pause = onboardingSectionPause(animateRender);
+	const useHyperlinks = shouldRenderHyperlinks(process.stdout);
 	const demotedDiagnosticCount = diagnostics.length - surfaceDiagnostics.length;
 	const lintSourceFileCount = options.includePaths.length > 0 ? options.includePaths.length : project.sourceFileCount;
 	if (printedDiagnostics.length === 0) {
@@ -49701,7 +50047,7 @@ const finalizeAndRender = (input) => gen(function* () {
 	yield* printDiagnostics([...printedDiagnostics], options.verbose, directory, buildRulePriorityMap([score]), isCodingAgentEnvironment(), {
 		sectionPause: pause,
 		animateCountUp: animateRender
-	});
+	}, useHyperlinks);
 	if (options.isNonInteractiveEnvironment && options.outputSurface !== "prComment") yield* printAgentGuidance();
 	if (options.categoryFilters.size === 0 && demotedDiagnosticCount > 0) {
 		yield* log(highlighter.gray(`  ${demotedDiagnosticCount} demoted from the ${options.outputSurface} surface (e.g. design cleanup) — run \`npx react-doctor@latest .\` locally for the full list.`));
@@ -49890,24 +50236,18 @@ const isExpectedUserError = (error) => error instanceof CliInputError || isProje
 //#region src/cli/utils/build-handoff-payload.ts
 const buildHandoffPayload = (input) => {
 	const topGroups = buildSortedRuleGroups(input.diagnostics).slice(0, 3);
+	const migrationScaleBuckets = new Map(findMigrationScaleBuckets(input.diagnostics).map((bucket) => [bucket.ruleKey, bucket]));
 	let outputDirectory = null;
 	try {
 		outputDirectory = writeDiagnosticsDirectory([...input.diagnostics], input.outputDirectory);
 	} catch {}
-	const lines = [
-		"Before fixing anything, first ask me whether I'd like to add React Doctor to CI so every pull request is scanned automatically. Explain that:",
-		`- It's used by teams at ${CI_TRUST_COMPANIES}.`,
-		"- I don't have to fix everything at once; CI keeps new PRs clean while I incrementally pay down the existing issues.",
-		`- Setup guide: ${CI_URL}`,
-		"If I say yes, run `npx react-doctor install` (or add the GitHub Actions workflow). Either way, then continue with the fixes below.",
-		"",
-		`Fix the top ${topGroups.length} React Doctor ${topGroups.length === 1 ? "issue" : "issues"} in ${input.projectName} on this pass — leave the rest for a follow-up.`,
-		""
-	];
+	const lines = [`Fix the top ${topGroups.length} React Doctor ${topGroups.length === 1 ? "issue" : "issues"} in ${input.projectName} on this pass — leave the rest for a follow-up.`, ""];
 	topGroups.forEach(([ruleKey, ruleDiagnostics], index) => {
 		const representative = ruleDiagnostics[0];
 		const severityLabel = representative.severity === "error" ? "ERROR" : "WARN";
-		lines.push(`${index + 1}. ${severityLabel} ${representative.category}: ${representative.title ?? ruleKey} (×${ruleDiagnostics.length})`, `   ${representative.message}`);
+		const sharedFixSiteCount = getSharedFixSiteCount(ruleDiagnostics);
+		const countBadge = sharedFixSiteCount > 0 ? `one fix · ${sharedFixSiteCount} sites` : `×${ruleDiagnostics.length}`;
+		lines.push(`${index + 1}. ${severityLabel} ${representative.category}: ${representative.title ?? ruleKey} (${countBadge})`, `   ${representative.message}`);
 		const fixRecipeLine = formatFixRecipeLine(representative);
 		if (fixRecipeLine) lines.push(`   ${fixRecipeLine}`);
 		const uniqueFiles = [...new Set(ruleDiagnostics.map((diagnostic) => diagnostic.filePath))];
@@ -49917,10 +50257,19 @@ const buildHandoffPayload = (input) => {
 		}
 		const remainingFiles = uniqueFiles.length - 3;
 		if (remainingFiles > 0) lines.push(`   - +${remainingFiles} more files`);
+		const migrationBucket = migrationScaleBuckets.get(ruleKey);
+		if (migrationBucket) lines.push(`   Migration-scale (${migrationBucket.fileCount} files): fix a representative sample, confirm the recipe holds, and get the code owner's sign-off before changing the rest in one pass.`);
 	});
 	lines.push("");
 	if (outputDirectory) lines.push(`Full results for all ${input.diagnostics.length} issues (diagnostics.json + a .txt per rule): ${outputDirectory}`, "");
-	lines.push("Read each file and fix the root cause — don't suppress or silence the rule.", "", "Verify against the real thing, don't assume: confirm each change matches the canonical fix recipe you fetched for that rule, then re-run `npx react-doctor@latest --verbose` and check the issue is actually gone against the real tool before moving on.", "", "Teach me as you go: for every issue you touch, explain it in plain language (no jargon) — what the problem is, why it's a problem, and how serious it is in human terms. Describe the real-world impact and severity concretely (e.g. \"this crashes the page for users on Safari\" vs. \"this is a minor cleanup with no user impact\") so I understand why it matters, not just what changed.", "", "Then work through the rest from the full results above.");
+	lines.push("Read each file and fix the root cause — don't suppress or silence the rule.", "", "Findings that share a `fixGroupId` (in diagnostics.json) are one root cause — a single fix clears all of them, so treat each `fixGroupId` as ONE task, not one per site.", "", "Verify against the real thing, don't assume: confirm each change matches the canonical fix recipe you fetched for that rule, then re-run `npx react-doctor@latest --verbose` and check the issue is actually gone against the real tool before moving on.", "", "Teach me as you go: for every issue you touch, explain it in plain language (no jargon) — what the problem is, why it's a problem, and how serious it is in human terms. Describe the real-world impact and severity concretely (e.g. \"this crashes the page for users on Safari\" vs. \"this is a minor cleanup with no user impact\") so I understand why it matters, not just what changed.", "");
+	const shownRuleKeys = new Set(topGroups.map(([ruleKey]) => ruleKey));
+	const deferredMigrationBuckets = [...migrationScaleBuckets.values()].filter((bucket) => !shownRuleKeys.has(bucket.ruleKey));
+	if (deferredMigrationBuckets.length > 0) {
+		const ruleSummaries = deferredMigrationBuckets.map((bucket) => `${bucket.title} (${bucket.fileCount} files)`).join(", ");
+		lines.push(`Some of the rest are migration-scale (span dozens of files): ${ruleSummaries}. For each, fix a representative sample, confirm the recipe holds, and get the code owner's sign-off before changing the rest in one pass.`, "");
+	}
+	lines.push("Then work through the rest from the full results above.");
 	return lines.join("\n");
 };
 //#endregion
@@ -49964,78 +50313,6 @@ const detectAvailableAgents = async () => {
 	return getSkillAgentTypes().filter((agent) => agent !== "universal" && detected.has(agent));
 };
 //#endregion
-//#region src/cli/utils/git-hook-shared.ts
-const HOOK_FILE_NAME = "pre-commit";
-const HOOK_RELATIVE_PATH = "hooks/pre-commit";
-const LEGACY_HOOK_RUNNER_RELATIVE_PATH = ".react-doctor/hooks/pre-commit";
-const HUSKY_HOOKS_PATH = ".husky";
-const VITE_PLUS_HOOKS_PATH = ".vite-hooks";
-const LEFTHOOK_CONFIG_FILES = ["lefthook.yml", "lefthook.yaml"];
-const PRE_COMMIT_CONFIG_FILE = ".pre-commit-config.yaml";
-const OVERCOMMIT_CONFIG_FILE = ".overcommit.yml";
-const REACT_DOCTOR_COMMAND = "react-doctor --staged --blocking warning";
-const NON_BLOCKING_REACT_DOCTOR_COMMAND = [
-	"react_doctor_output=$(mktemp \"${TMPDIR:-/tmp}/react-doctor-hook.XXXXXX\");",
-	`if ${REACT_DOCTOR_COMMAND} > "$react_doctor_output" 2>&1; then`,
-	"rm -f \"$react_doctor_output\";",
-	"else",
-	"rm -f \"$react_doctor_output\";",
-	`printf "%s\\n" "React Doctor found staged regressions." "Run ${REACT_DOCTOR_COMMAND} to inspect." "Want them fixed? Ask your agent to run that command and resolve the findings." >&2;`,
-	"fi"
-].join(" ");
-const PACKAGE_JSON_FILE_NAME = "package.json";
-const runGit = (projectRoot, args) => {
-	try {
-		return execFileSync("git", [...args], {
-			cwd: projectRoot,
-			encoding: "utf8",
-			stdio: [
-				"ignore",
-				"pipe",
-				"ignore"
-			]
-		}).trim();
-	} catch {
-		return null;
-	}
-};
-const resolveGitPath = (baseDirectory, value) => Path.isAbsolute(value) ? value : Path.resolve(baseDirectory, value);
-const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-const getPackageJsonPath = (projectRoot) => Path.join(projectRoot, PACKAGE_JSON_FILE_NAME);
-const readPackageJson = (projectRoot) => {
-	try {
-		return JSON.parse(NFS.readFileSync(getPackageJsonPath(projectRoot), "utf8"));
-	} catch {
-		return null;
-	}
-};
-const writeJsonFile$1 = (filePath, value) => {
-	NFS.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
-};
-const packageHasDependency = (projectRoot, dependencyName) => {
-	const packageJson = readPackageJson(projectRoot);
-	if (!isRecord(packageJson)) return false;
-	return [
-		"dependencies",
-		"devDependencies",
-		"optionalDependencies"
-	].some((fieldName) => {
-		const dependencies = packageJson[fieldName];
-		return isRecord(dependencies) && typeof dependencies[dependencyName] === "string";
-	});
-};
-const packageHasRecordKey = (projectRoot, key) => {
-	const packageJson = readPackageJson(projectRoot);
-	return isRecord(packageJson) && isRecord(packageJson[key]);
-};
-const packageHasNestedRecordKey = (projectRoot, key, nestedKey) => {
-	const packageJson = readPackageJson(projectRoot);
-	if (!isRecord(packageJson)) return false;
-	const value = packageJson[key];
-	return isRecord(value) && isRecord(value[nestedKey]);
-};
-const ensureTrailingNewline = (content) => content.endsWith("\n") ? content : `${content}\n`;
-//#endregion
 //#region src/cli/utils/install-doctor-script.ts
 const DOCTOR_SCRIPT_NAME = "doctor";
 const FALLBACK_DOCTOR_SCRIPT_NAME = "react-doctor";
@@ -50061,31 +50338,31 @@ const findNearestPackageDirectory = (startDirectory, stopDirectory) => {
 };
 const hasDoctorScript = (projectRoot) => {
 	const packageJson = readPackageJson(findNearestPackageDirectory(projectRoot) ?? projectRoot);
-	if (!isRecord(packageJson)) return false;
+	if (!isRecord$1(packageJson)) return false;
 	const scripts = packageJson.scripts;
-	if (!isRecord(scripts)) return false;
+	if (!isRecord$1(scripts)) return false;
 	return isReactDoctorScriptCommand(scripts[DOCTOR_SCRIPT_NAME]) || isReactDoctorScriptCommand(scripts[FALLBACK_DOCTOR_SCRIPT_NAME]);
 };
 const hasDoctorDependency = (packageJson) => DEPENDENCY_FIELD_NAMES.some((fieldName) => {
 	const dependencies = packageJson[fieldName];
-	return isRecord(dependencies) && Object.hasOwn(dependencies, "react-doctor");
+	return isRecord$1(dependencies) && Object.hasOwn(dependencies, "react-doctor");
 });
 const installDoctorScript = (options) => {
 	const packageDirectory = findNearestPackageDirectory(options.projectRoot) ?? options.projectRoot;
 	const packageJsonPath = getPackageJsonPath(packageDirectory);
 	const packageJson = readPackageJson(packageDirectory);
-	if (!isRecord(packageJson)) return {
+	if (!isRecord$1(packageJson)) return {
 		packageJsonPath,
 		scriptStatus: "skipped",
 		scriptReason: "missing-or-invalid-package-json"
 	};
 	const scripts = packageJson.scripts;
 	const scriptTarget = (() => {
-		if (scripts !== void 0 && !isRecord(scripts)) return {
+		if (scripts !== void 0 && !isRecord$1(scripts)) return {
 			status: "skipped",
 			reason: "invalid-scripts"
 		};
-		const scriptRecord = isRecord(scripts) ? scripts : {};
+		const scriptRecord = isRecord$1(scripts) ? scripts : {};
 		if (isReactDoctorScriptCommand(scriptRecord[DOCTOR_SCRIPT_NAME])) return {
 			scriptName: DOCTOR_SCRIPT_NAME,
 			status: "existing"
@@ -50119,7 +50396,7 @@ const installDoctorScript = (options) => {
 	if (scriptStatus === "created") writeJsonFile$1(packageJsonPath, {
 		...packageJson,
 		scripts: {
-			...isRecord(scripts) ? scripts : {},
+			...isRecord$1(scripts) ? scripts : {},
 			[scriptTarget.scriptName ?? DOCTOR_SCRIPT_NAME]: DOCTOR_SCRIPT_COMMAND
 		}
 	});
@@ -50273,38 +50550,52 @@ const upgradeReactDoctorWorkflowInPlace = (projectRoot) => {
 //#region src/cli/utils/hash-project-root.ts
 const hashProjectRoot = (projectRoot) => createHash("sha256").update(Path.resolve(projectRoot)).digest("hex");
 //#endregion
-//#region src/cli/utils/action-upgrade-prompt.ts
-const GLOBAL_CONFIG_PROJECT_NAME$1 = "react-doctor";
-const getActionUpgradeStore = (options = {}) => new Conf({
-	projectName: GLOBAL_CONFIG_PROJECT_NAME$1,
-	cwd: options.cwd
-});
-const hasHandledActionUpgrade = (projectRoot, storeOptions = {}) => {
-	try {
-		const upgrades = getActionUpgradeStore(storeOptions).get("actionUpgrades", {});
-		return Boolean(upgrades[hashProjectRoot(projectRoot)]);
-	} catch {
-		return true;
-	}
-};
-const recordActionUpgradeDecision = (projectRoot, outcome, storeOptions = {}) => {
-	try {
-		const store = getActionUpgradeStore(storeOptions);
-		const upgrades = store.get("actionUpgrades", {});
-		store.set("actionUpgrades", {
-			...upgrades,
-			[hashProjectRoot(projectRoot)]: {
-				rootDirectory: Path.resolve(projectRoot),
-				outcome,
-				at: (/* @__PURE__ */ new Date()).toISOString()
+//#region src/cli/utils/project-decision-store.ts
+const createProjectDecisionStore = (storeKey) => {
+	const getStore = (options = {}) => new Conf({
+		projectName: REACT_DOCTOR_CONFIG_PROJECT_NAME,
+		cwd: options.cwd
+	});
+	return {
+		getConfigPath: (options = {}) => getStore(options).path,
+		hasHandled: (projectRoot, options = {}) => {
+			try {
+				return Boolean(getStore(options).get(storeKey, {})[hashProjectRoot(projectRoot)]);
+			} catch {
+				return true;
 			}
-		});
-		return true;
-	} catch {
-		return false;
-	}
+		},
+		record: (projectRoot, outcome, options = {}) => {
+			try {
+				const store = getStore(options);
+				store.set(storeKey, {
+					...store.get(storeKey, {}),
+					[hashProjectRoot(projectRoot)]: {
+						rootDirectory: Path.resolve(projectRoot),
+						outcome,
+						at: (/* @__PURE__ */ new Date()).toISOString()
+					}
+				});
+				return true;
+			} catch {
+				return false;
+			}
+		}
+	};
 };
 //#endregion
+//#region src/cli/utils/action-upgrade-prompt.ts
+const store$1 = createProjectDecisionStore("actionUpgrades");
+store$1.getConfigPath;
+const hasHandledActionUpgrade = store$1.hasHandled;
+const recordActionUpgradeDecision = store$1.record;
+//#endregion
+//#region src/cli/utils/ci-prompt-decision.ts
+const store = createProjectDecisionStore("ciPrompts");
+store.getConfigPath;
+const hasHandledCiPrompt = store.hasHandled;
+const recordCiPromptDecision = store.record;
+//#endregion
 //#region src/cli/utils/open-url.ts
 const resolveOpenCommand = (url) => {
 	if (process$1.platform === "darwin") return {
@@ -50760,22 +51051,22 @@ const buildAgentHookScript = () => [
 	"",
 	"run_react_doctor() {",
 	"  if [ -x ./node_modules/.bin/react-doctor ]; then",
-	"    ./node_modules/.bin/react-doctor --verbose --diff --blocking warning --no-score",
+	"    ./node_modules/.bin/react-doctor --verbose --scope changed --blocking warning --no-score",
 	"    return",
 	"  fi",
 	"",
 	"  if command -v react-doctor >/dev/null 2>&1; then",
-	"    react-doctor --verbose --diff --blocking warning --no-score",
+	"    react-doctor --verbose --scope changed --blocking warning --no-score",
 	"    return",
 	"  fi",
 	"",
 	"  if command -v pnpm >/dev/null 2>&1; then",
-	"    pnpm dlx react-doctor@latest --verbose --diff --blocking warning --no-score",
+	"    pnpm dlx react-doctor@latest --verbose --scope changed --blocking warning --no-score",
 	"    return",
 	"  fi",
 	"",
 	"  if command -v npx >/dev/null 2>&1; then",
-	"    npx --yes react-doctor@latest --verbose --diff --blocking warning --no-score",
+	"    npx --yes react-doctor@latest --verbose --scope changed --blocking warning --no-score",
 	"    return",
 	"  fi",
 	"",
@@ -50933,13 +51224,13 @@ const installPackageJsonHook = (options, strategy) => {
 	const packageJsonPath = getPackageJsonPath(options.projectRoot);
 	const didHookExist = NFS.existsSync(packageJsonPath);
 	const packageJson = readPackageJson(options.projectRoot);
-	const nextPackageJson = isRecord(packageJson) ? { ...packageJson } : {};
+	const nextPackageJson = isRecord$1(packageJson) ? { ...packageJson } : {};
 	const parentKeys = strategy.path.slice(0, -1);
 	const leafKey = strategy.path[strategy.path.length - 1];
 	let parent = nextPackageJson;
 	for (const key of parentKeys) {
 		const existing = parent[key];
-		const cloned = isRecord(existing) ? { ...existing } : {};
+		const cloned = isRecord$1(existing) ? { ...existing } : {};
 		parent[key] = cloned;
 		parent = cloned;
 	}
@@ -51110,7 +51401,7 @@ const isHuskyProject = (projectRoot) => NFS.existsSync(Path.join(projectRoot, ".
 const isVitePlusProject = (projectRoot) => packageHasDependency(projectRoot, "vite-plus");
 const isSimpleGitHooksProject = (projectRoot) => {
 	const packageJson = readPackageJson(projectRoot);
-	return isRecord(packageJson) && isRecord(packageJson["simple-git-hooks"]) || packageHasDependency(projectRoot, "simple-git-hooks") || NFS.existsSync(Path.join(projectRoot, ".simple-git-hooks.cjs"));
+	return isRecord$1(packageJson) && isRecord$1(packageJson["simple-git-hooks"]) || packageHasDependency(projectRoot, "simple-git-hooks") || NFS.existsSync(Path.join(projectRoot, ".simple-git-hooks.cjs"));
 };
 const getLefthookConfigPath = (projectRoot) => {
 	for (const fileName of LEFTHOOK_CONFIG_FILES) {
@@ -51276,7 +51567,7 @@ const detectPackageManager = (projectRoot) => {
 	let currentDirectory = Path.resolve(projectRoot);
 	while (true) {
 		const packageJson = readPackageJson(currentDirectory);
-		if (isRecord(packageJson) && typeof packageJson.packageManager === "string") {
+		if (isRecord$1(packageJson) && typeof packageJson.packageManager === "string") {
 			const packageManagerName = packageJson.packageManager.split("@")[0];
 			if (packageManagerName === "pnpm" || packageManagerName === "yarn" || packageManagerName === "bun" || packageManagerName === "npm") return packageManagerName;
 		}
@@ -51352,12 +51643,12 @@ const isSupplyChainTrustError = (error) => {
 const formatInstallCommand = (input) => [input.command, ...input.args].join(" ");
 const installReactDoctorDependency = async (options) => {
 	const packageJson = readPackageJson(options.projectRoot);
-	if (!isRecord(packageJson)) return {
+	if (!isRecord$1(packageJson)) return {
 		dependencyStatus: "skipped",
 		dependencyReason: "missing-or-invalid-package-json"
 	};
 	if (hasDoctorDependency(packageJson)) return { dependencyStatus: "existing" };
-	if (packageJson.devDependencies !== void 0 && !isRecord(packageJson.devDependencies)) return {
+	if (packageJson.devDependencies !== void 0 && !isRecord$1(packageJson.devDependencies)) return {
 		dependencyStatus: "skipped",
 		dependencyReason: "invalid-dev-dependencies"
 	};
@@ -51521,10 +51812,12 @@ const runInstallReactDoctor = async (options = {}) => {
 	const existingWorkflow = readReactDoctorWorkflow(projectRoot);
 	const canInstallWorkflow = !NFS.existsSync(workflowTargetPath);
 	const canUpgradeWorkflow = existingWorkflow !== null && workflowUsesV1Action(existingWorkflow.content) && !hasHandledActionUpgrade(projectRoot);
-	const shouldInstallWorkflow = canInstallWorkflow && (Boolean(options.yes) || !skipPrompts && await askAddToGitHubActions(prompt) === "yes");
+	const ciPromptOutcome = canInstallWorkflow && !options.yes && !skipPrompts && !hasHandledCiPrompt(projectRoot) ? await askAddToGitHubActions(prompt) : null;
+	const shouldInstallWorkflow = canInstallWorkflow && (Boolean(options.yes) || ciPromptOutcome === "yes");
 	const upgradePromptOutcome = canUpgradeWorkflow && !options.yes && !skipPrompts ? await askUpgradeActionVersion(prompt) : null;
 	const shouldUpgradeWorkflow = canUpgradeWorkflow && (Boolean(options.yes) || upgradePromptOutcome === "yes");
 	if (upgradePromptOutcome === "no" && !options.dryRun) recordActionUpgradeDecision(projectRoot, "declined");
+	if ((ciPromptOutcome === "yes" || ciPromptOutcome === "no") && !options.dryRun) recordCiPromptDecision(projectRoot, ciPromptOutcome === "yes" ? "accepted" : "declined");
 	const selectedAgents = skipPrompts ? detectedAgents : (await prompt({
 		type: "multiselect",
 		name: "agents",
@@ -51771,18 +52064,24 @@ const handoffToAgent = async (input) => {
 	if (!input.interactive || input.diagnostics.length === 0) return;
 	cliLogger.break();
 	const projectRootForCi = findNearestPackageDirectory(input.rootDirectory) ?? input.rootDirectory;
-	if (!isReactDoctorWorkflowInstalled(projectRootForCi)) {
+	const isGitHubActionsConfigured = isReactDoctorWorkflowInstalled(projectRootForCi);
+	if (!isGitHubActionsConfigured && !hasHandledCiPrompt(projectRootForCi)) {
 		const ciOutcome = await askAddToGitHubActions();
 		recordCount(METRIC.agentHandoff, 1, {
 			outcome: `ci-${ciOutcome}`,
 			diagnosticsCount: input.diagnostics.length
 		});
 		if (ciOutcome === "cancel") return;
+		recordCiPromptDecision(projectRootForCi, ciOutcome === "yes" ? "accepted" : "declined");
 		if (ciOutcome === "yes") {
 			await setUpGitHubActions({ rootDirectory: input.rootDirectory });
 			cliLogger.break();
 		}
-	} else await maybeOfferActionUpgrade(projectRootForCi);
+	} else if (isGitHubActionsConfigured) await maybeOfferActionUpgrade(projectRootForCi);
+	else recordCount(METRIC.agentHandoff, 1, {
+		outcome: "ci-suppressed",
+		diagnosticsCount: input.diagnostics.length
+	});
 	const { handoffTarget } = await prompts({
 		type: "select",
 		name: "handoffTarget",
@@ -52005,6 +52304,7 @@ const reportErrorToSentry = async (error) => {
 				sampled: runTrace.sampled,
 				sampleRand: Math.random()
 			});
+			recordRunTraceId(scope.getPropagationContext().traceId);
 			return Sentry.captureException(error);
 		});
 		await Sentry.flush(SENTRY_FLUSH_TIMEOUT_MS);
@@ -52088,7 +52388,7 @@ const printMultiProjectSummary = (input) => gen(function* () {
 	yield* log(`${highlighter.success("✔")} Scanned ${totalScannedFileCount} ${totalScannedFileCount === 1 ? "file" : "files"} in ${formatElapsedTime(totalElapsedMilliseconds)}`);
 	if (displayDiagnostics.length > 0) {
 		yield* log("");
-		yield* printDiagnostics(displayDiagnostics, verbose, resolveDiagnosticSourceRoot, buildRulePriorityMap(completedScans.map((scan) => scan.result.score)), isCodingAgentEnvironment(), { animateCountUp: animateRender });
+		yield* printDiagnostics(displayDiagnostics, verbose, resolveDiagnosticSourceRoot, buildRulePriorityMap(completedScans.map((scan) => scan.result.score)), isCodingAgentEnvironment(), { animateCountUp: animateRender }, shouldRenderHyperlinks(process.stdout));
 	}
 	const lowestScoredScan = findLowestScoredScan(completedScans);
 	const aggregateScore = lowestScoredScan?.result.score ?? null;
@@ -52126,9 +52426,8 @@ const printMultiProjectSummary = (input) => gen(function* () {
 });
 //#endregion
 //#region src/cli/utils/prompt-install-setup.ts
-const GLOBAL_CONFIG_PROJECT_NAME = "react-doctor";
 const getSetupPromptStore = (options = {}) => new Conf({
-	projectName: GLOBAL_CONFIG_PROJECT_NAME,
+	projectName: REACT_DOCTOR_CONFIG_PROJECT_NAME,
 	cwd: options.cwd
 });
 const getSetupPromptProjectKey = (projectRoot) => hashProjectRoot(projectRoot);
@@ -52139,6 +52438,24 @@ const hasDisabledSetupPrompt = (projectRoot, storeOptions = {}) => {
 		return false;
 	}
 };
+const disableSetupPrompt = (projectRoot, storeOptions = {}) => {
+	try {
+		const store = getSetupPromptStore(storeOptions);
+		const projects = store.get("projects", {});
+		const projectKey = getSetupPromptProjectKey(projectRoot);
+		store.set("projects", {
+			...projects,
+			[projectKey]: {
+				...projects[projectKey] ?? {},
+				rootDirectory: Path.resolve(projectRoot),
+				setupPrompt: false
+			}
+		});
+		return true;
+	} catch {
+		return false;
+	}
+};
 const resolveInstallSetupProjectRoot = (options) => {
 	if (options.scanDirectories.length === 0) return findNearestPackageDirectory(options.scanRoot) ?? options.scanRoot;
 	const packageDirectories = /* @__PURE__ */ new Set();
@@ -52545,6 +52862,14 @@ const runExplain = async (fileLineArgument, context) => {
 		const colorizedRule = colorizeRuleByDiagnostic(ruleIdentifier, diagnostic.severity);
 		const severityLabel = colorizeRuleByDiagnostic(diagnostic.severity, diagnostic.severity);
 		cliLogger.log(`${severitySymbol} ${colorizedRule} ${highlighter.dim(`(${severityLabel})`)} — ${diagnostic.message}`);
+		const codeFrame = buildCodeFrame({
+			filePath: diagnostic.filePath,
+			line: diagnostic.line,
+			column: diagnostic.column,
+			endLine: diagnostic.endLine,
+			rootDirectory: targetDirectory
+		});
+		if (codeFrame) cliLogger.log(indentMultilineText(codeFrame, "  "));
 		if (diagnostic.category) cliLogger.dim(`  Category: ${diagnostic.category}`);
 		if (diagnostic.help) cliLogger.dim(`  ${diagnostic.help}`);
 		cliLogger.dim(`  If this needs follow-up or looks like a false positive, open: ${buildDiagnosticIssueUrl({
@@ -52594,6 +52919,10 @@ const validateModeFlags = (flags) => {
 	if (flags.staged && (flags.scope === "full" || flags.scope === "changed")) throw new CliInputError(`Cannot combine --staged with --scope ${flags.scope}; use --scope files or --scope lines, or drop --scope.`);
 	if (flags.score && flags.json) throw new CliInputError("Cannot combine --score and --json; pick one output mode.");
 	if (flags.score && flags.telemetry === false) throw new CliInputError("Cannot combine --score with --no-telemetry; --score prints the score that --no-telemetry disables.");
+	if (flags.debug && (flags.score === false || flags.telemetry === false)) {
+		const disablingFlag = flags.score === false ? "--no-score" : "--no-telemetry";
+		throw new CliInputError(`Cannot combine --debug with ${disablingFlag}; ${disablingFlag} disables the Sentry reporting --debug needs to capture a trace.`);
+	}
 };
 //#endregion
 //#region src/cli/commands/inspect.ts
@@ -52941,11 +53270,13 @@ const inspectAction = async (directory, flags) => {
 			})) {
 				printAgentInstallHint();
 				recordCount(METRIC.agentInstallHintShown, 1);
+				disableSetupPrompt(setupProjectRoot);
 			}
 		}
 	} catch (error) {
 		const isUserError = isExpectedUserError(error);
 		const sentryEventId = isUserError ? void 0 : await reportErrorToSentry(error);
+		if (isDebugFlagEnabled()) await flushSentry();
 		if (isJsonMode) {
 			writeJsonErrorReport(error, sentryEventId);
 			process.exitCode = 1;
@@ -53668,6 +53999,33 @@ const normalizeHelpInvocation = (argv, knownCommands) => {
 	return [...nodeArguments, "--help"];
 };
 //#endregion
+//#region src/cli/utils/print-debug-trace.ts
+/**
+* The `--debug` end-of-run line, pure so it's testable without the Sentry SDK.
+* Mirrors the crash-reference phrasing in `handle-error.ts` ("mention this when
+* reporting") so users learn one habit for both paths. A `null` trace says why,
+* so `--debug` never silently does nothing.
+*/
+const buildDebugTraceMessage = (traceId) => traceId === null ? "Sentry trace unavailable for this run (no trace was recorded)." : `Sentry trace (mention this when reporting): ${traceId}`;
+/**
+* Prints the run's Sentry trace id to stderr at the end of a `--debug` run, so
+* maintainers can pull the full trace from a pasted id. Runs from the process
+* `exit` handler, so it's the last line on both the success path and the error
+* funnels (which `process.exit()` before the promise chain could resume).
+*
+* Writes straight to `process.stderr` (not `Console`) for three reasons: the
+* exit handler is synchronous, JSON mode patches the global console to no-ops —
+* a diagnostic the user explicitly asked for must survive that — and stderr
+* keeps `--json` / `--score` stdout machine-clean. The write is wrapped because
+* a diagnostic must never throw out of an exit handler.
+*/
+const printDebugTrace = () => {
+	if (!Sentry.isInitialized()) return;
+	try {
+		process.stderr.write(`${highlighter.dim(buildDebugTraceMessage(getLastRunTraceId()))}\n`);
+	} catch {}
+};
+//#endregion
 //#region src/cli/utils/removed-cli-flags.ts
 const REMOVED_FLAGS = new Map([
 	["--full", "use `--diff false` to force a full scan"],
@@ -53694,6 +54052,7 @@ const ROOT_FLAG_SPEC = {
 	longOptionsWithoutValues: new Set([
 		"--color",
 		"--dead-code",
+		"--debug",
 		"--help",
 		"--json",
 		"--json-compact",
@@ -53861,6 +54220,9 @@ const stripUnknownCliFlags = (argv) => {
 initializeSentry();
 process.on("SIGINT", exitGracefully);
 process.on("SIGTERM", exitGracefully);
+process.on("exit", () => {
+	if (isDebugFlagEnabled()) printDebugTrace();
+});
 unrefStdin();
 guardStdin();
 const formatExampleLines = (examples) => {
@@ -53872,7 +54234,7 @@ ${highlighter.dim("Examples:")}
 ${formatExampleLines([
 	["react-doctor", "scan the current project"],
 	["react-doctor ./apps/web", "scan a specific directory"],
-	["react-doctor --diff main", "scan only files changed vs. main"],
+	["react-doctor --scope changed --base main", "scan only new issues vs. main"],
 	["react-doctor --project modules/a,modules/b", "score each module separately (names or paths)"],
 	["react-doctor --staged", "scan staged files (pre-commit hook)"],
 	["react-doctor --category Security", "show only one diagnostic category"],
@@ -53905,7 +54267,7 @@ ${highlighter.dim("Learn more:")}
   ${highlighter.info(CANONICAL_GITHUB_URL)}
 `;
 const collectCategoryOption = (value, previousValues) => [...previousValues ?? [], value];
-const program = new Command().name("react-doctor").description("Diagnose React codebase health").version(VERSION, "-v, --version", "display the version number").argument("[directory]", "project directory to scan", ".").option("--lint", "enable linting").option("--no-lint", "skip linting").option("--dead-code", "enable dead-code analysis (default)").option("--no-dead-code", "skip dead-code analysis (unused files / exports / dependencies, circular imports)").option("--verbose", "show every rule and per-file details (default shows top 3 rules)").option("--output-dir <dir>", "directory for the full diagnostics dump (default: a temp folder)").option("--score", "output only the score").option("--json", "output a single structured JSON report (suppresses other output)").option("--json-compact", "with --json, emit compact JSON (no indentation)").option("-y, --yes", "skip prompts, scan all workspace projects").option("--no-parallel", "lint serially with one worker (default: parallel across CPU cores; set the worker count with REACT_DOCTOR_PARALLEL)").option("--project <name>", "select projects: workspace names or directory paths (comma-separated for multiple); overrides the `projects` config field").option("--scope <value>", "how much to scan/report: full (default), files, changed (only new issues vs base), or lines (only changed lines)").option("--base <ref>", "base git ref for files/changed/lines scope (auto-detected when omitted)").addOption(new Option("--diff [base]", "[deprecated] alias for --scope changed (pass `false` to force a full scan)").hideHelp()).addOption(new Option("--changed-files-from <file>", "scan source files listed in a newline-delimited changed-files file").hideHelp()).option("--no-score", "skip the score API, the share URL, and crash reporting").addOption(new Option("--category <category>", "only show diagnostics in a category (repeatable; e.g. Security)").argParser(collectCategoryOption)).option("--no-telemetry", "alias for --no-score (skip the score API, share URL, and crash reporting)").option("--staged", "scan only staged (git index) files for pre-commit hooks").option("--blocking <level>", "severity that fails CI: error (default), warning, or none (advisory)").addOption(new Option("--fail-on <level>", "[deprecated] alias for --blocking <level>").hideHelp()).option("--no-respect-inline-disables", "audit mode: neutralize inline lint suppressions before scanning").option("--warnings", "show warning-severity diagnostics (default)").option("--no-warnings", "hide warning-severity diagnostics (errors only)").option("--color", "force colored output").option("--no-color", "disable colored output (also honors NO_COLOR)").addHelpText("after", renderRootHelpEpilog);
+const program = new Command().name("react-doctor").description("Diagnose React codebase health").version(VERSION, "-v, --version", "display the version number").argument("[directory]", "project directory to scan", ".").option("--lint", "enable linting").option("--no-lint", "skip linting").option("--dead-code", "enable dead-code analysis (default)").option("--no-dead-code", "skip dead-code analysis (unused files / exports / dependencies, circular imports)").option("--verbose", "show every rule and per-file details (default shows top 3 rules)").option("--debug", "force a Sentry trace and print its id at the end (paste it into a bug report)").option("--output-dir <dir>", "directory for the full diagnostics dump (default: a temp folder)").option("--score", "output only the score").option("--json", "output a single structured JSON report (suppresses other output)").option("--json-compact", "with --json, emit compact JSON (no indentation)").option("-y, --yes", "skip prompts, scan all workspace projects").option("--no-parallel", "lint serially with one worker (default: parallel across CPU cores; set the worker count with REACT_DOCTOR_PARALLEL)").option("--project <name>", "select projects: workspace names or directory paths (comma-separated for multiple); overrides the `projects` config field").option("--scope <value>", "how much to scan/report: full (default), files, changed (only new issues vs base), or lines (only changed lines)").option("--base <ref>", "base git ref for files/changed/lines scope (auto-detected when omitted)").addOption(new Option("--diff [base]", "[deprecated] alias for --scope changed (pass `false` to force a full scan)").hideHelp()).addOption(new Option("--changed-files-from <file>", "scan source files listed in a newline-delimited changed-files file").hideHelp()).option("--no-score", "skip the score API, the share URL, and crash reporting").addOption(new Option("--category <category>", "only show diagnostics in a category (repeatable; e.g. Security)").argParser(collectCategoryOption)).option("--no-telemetry", "alias for --no-score (skip the score API, share URL, and crash reporting)").option("--staged", "scan only staged (git index) files for pre-commit hooks").option("--blocking <level>", "severity that fails CI: error (default), warning, or none (advisory)").addOption(new Option("--fail-on <level>", "[deprecated] alias for --blocking <level>").hideHelp()).option("--no-respect-inline-disables", "audit mode: neutralize inline lint suppressions before scanning").option("--warnings", "show warning-severity diagnostics (default)").option("--no-warnings", "hide warning-severity diagnostics (errors only)").option("--color", "force colored output").option("--no-color", "disable colored output (also honors NO_COLOR)").addHelpText("after", renderRootHelpEpilog);
 program.action(inspectAction);
 program.command("why <location>").description("Explain why a rule fired (or why a suppression didn't apply) at a file:line").option("--project <name>", "select projects: workspace names or directory paths (comma-separated for multiple)").option("-c, --cwd <cwd>", "working directory", process.cwd()).option("--color", "force colored output").option("--no-color", "disable colored output (also honors NO_COLOR)").action((location, options) => whyAction(location, options));
 program.command("install").alias("setup").description("Install the react-doctor skill into your coding agents and optional git hook").option("-y, --yes", "skip prompts, install for all detected agents").option("--dry-run", "show what would be installed without writing files").option("--agent-hooks", "install native non-blocking agent hooks for Claude Code and Cursor").option("-c, --cwd <cwd>", "working directory", process.cwd()).option("--color", "force colored output").option("--no-color", "disable colored output (also honors NO_COLOR)").addHelpText("after", renderInstallHelpEpilog).action(installAction);
@@ -53948,4 +54310,4 @@ Promise.resolve().then(() => assertNoRemovedFlags(process.argv)).then(() => prog
 export {};
 
 //# sourceMappingURL=cli.js.map
-//# debugId=79c9f922-1713-5894-a0aa-142d0cd9c7ba
+//# debugId=87ed2e7a-69a3-5a4d-a104-8ba680ac1aa2