react-doctor 0.2.14-dev.bb15252 → 0.2.14-dev.bdb9e36

package/dist/cli.js

@@ -1,3 +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]="d012dbb2-27e9-5092-9eab-c7fa4573f0b2")}catch(e){}}();
 import { createRequire } from "node:module";
 import { execFileSync, spawn, spawnSync } from "node:child_process";
 import * as Path from "node:path";
@@ -17,6 +19,8 @@ import * as Otlp from "effect/unstable/observability/Otlp";
 import * as Context from "effect/Context";
 import os, { tmpdir } from "node:os";
 import * as Console from "effect/Console";
+import { parseJSON5 } from "confbox";
+import { createJiti } from "jiti";
 import * as Fiber from "effect/Fiber";
 import * as Filter from "effect/Filter";
 import * as Option from "effect/Option";
@@ -30,7 +34,10 @@ import * as ChildProcess from "effect/unstable/process/ChildProcess";
 import { ChildProcessSpawner } from "effect/unstable/process/ChildProcessSpawner";
 import * as ts from "typescript";
 import { gzipSync } from "node:zlib";
+import * as Sentry from "@sentry/node";
 import { performance } from "node:perf_hooks";
+import * as Tracer from "effect/Tracer";
+import * as Exit from "effect/Exit";
 import { stripVTControlCharacters } from "node:util";
 import tty from "node:tty";
 import { codeFrameColumns } from "@babel/code-frame";
@@ -39,6 +46,8 @@ import basePrompts from "prompts";
 import { SKILL_MANIFEST_FILE, detectInstalledSkillAgents, getSkillAgentConfig, getSkillAgentTypes, installSkillsFromSource } from "agent-install";
 import { fileURLToPath } from "node:url";
 import Conf from "conf";
+import { generateCode, loadFile, writeFile } from "magicast";
+import { getConfigFromVariableDeclaration, getDefaultExportOptions } from "magicast/helpers";
 //#region \0rolldown/runtime.js
 var __create$1 = Object.create;
 var __defProp$1 = Object.defineProperty;
@@ -6290,7 +6299,8 @@ const MILLISECONDS_PER_SECOND = 1e3;
 const SCORE_API_URL = "https://www.react.doctor/api/score";
 const ENTERPRISE_CONTACT_URL = "https://react.doctor/enterprise";
 const SHARE_BASE_URL = "https://react.doctor/share";
-const PROMPTS_RULES_BASE_URL = "https://www.react.doctor/prompts/rules";
+const DOCS_URL = "https://www.react.doctor/docs";
+const DOCS_RULES_BASE_URL = `${DOCS_URL}/rules`;
 const FETCH_TIMEOUT_MS = 1e4;
 const GITHUB_VIEWER_PERMISSION_TIMEOUT_MS = 2e3;
 const DEFAULT_BRANCH_CANDIDATES = ["main", "master"];
@@ -6308,11 +6318,19 @@ const STAGED_FILES_PROJECT_CONFIG_FILENAMES = [
 	"tsconfig.json",
 	"tsconfig.base.json",
 	"package.json",
-	"react-doctor.config.json",
+	"doctor.config.ts",
+	"doctor.config.mts",
+	"doctor.config.cts",
+	"doctor.config.js",
+	"doctor.config.mjs",
+	"doctor.config.cjs",
+	"doctor.config.json",
+	"doctor.config.jsonc",
 	"oxlint.json",
 	".oxlintrc.json"
 ];
 const CANONICAL_GITHUB_URL = "https://github.com/millionco/react-doctor";
+const CANONICAL_DISCORD_URL = "https://react.doctor/discord";
 const SKILL_NAME = "react-doctor";
 const OXLINT_OUTPUT_MAX_BYTES = 50 * 1024 * 1024;
 const OXLINT_SPAWN_TIMEOUT_MS = 6e4;
@@ -7498,66 +7516,135 @@ const validateConfigTypes = (config) => {
 const warn = (message) => {
 	Effect.runSync(Console.warn(message));
 };
-const CONFIG_FILENAME = "react-doctor.config.json";
-const PACKAGE_JSON_CONFIG_KEY = "reactDoctor";
-const loadConfigFromDirectory = (directory) => {
-	const configFilePath = path.join(directory, CONFIG_FILENAME);
-	if (isFile(configFilePath)) try {
-		const fileContent = fs.readFileSync(configFilePath, "utf-8");
-		const parsed = JSON.parse(fileContent);
-		if (isPlainObject(parsed)) return {
-			config: validateConfigTypes(parsed),
-			sourceDirectory: directory
-		};
-		warn(`${CONFIG_FILENAME} must be a JSON object, ignoring.`);
-	} catch (error) {
-		warn(`Failed to parse ${CONFIG_FILENAME}: ${error instanceof Error ? error.message : String(error)}`);
-	}
-	const packageJsonPath = path.join(directory, "package.json");
-	if (isFile(packageJsonPath)) try {
-		const fileContent = fs.readFileSync(packageJsonPath, "utf-8");
-		const packageJson = JSON.parse(fileContent);
+const CONFIG_BASENAME = "doctor.config";
+const CONFIG_EXTENSIONS = [
+	"ts",
+	"mts",
+	"cts",
+	"js",
+	"mjs",
+	"cjs",
+	"json",
+	"jsonc"
+];
+const DATA_CONFIG_EXTENSIONS = new Set(["json", "jsonc"]);
+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 loadModuleConfig = async (filePath) => {
+	const imported = await jiti.import(filePath);
+	return imported?.default ?? imported;
+};
+const readDataConfig = (filePath) => parseJSON5(fs.readFileSync(filePath, "utf-8"));
+const readEmbeddedPackageJsonConfig = (directory) => {
+	const packageJsonPath = path.join(directory, PACKAGE_JSON_FILENAME);
+	if (!isFile(packageJsonPath)) return null;
+	try {
+		const packageJson = parseJSON5(fs.readFileSync(packageJsonPath, "utf-8"));
 		if (isPlainObject(packageJson)) {
-			const embeddedConfig = packageJson[PACKAGE_JSON_CONFIG_KEY];
-			if (isPlainObject(embeddedConfig)) return {
-				config: validateConfigTypes(embeddedConfig),
-				sourceDirectory: directory
+			const embeddedConfig = packageJson[PACKAGE_JSON_CONFIG_KEY$1];
+			if (isPlainObject(embeddedConfig)) return embeddedConfig;
+		}
+	} catch {}
+	return null;
+};
+const loadPackageJsonConfig = (directory) => {
+	const embeddedConfig = readEmbeddedPackageJsonConfig(directory);
+	if (!embeddedConfig) return null;
+	return {
+		config: validateConfigTypes(embeddedConfig),
+		sourceDirectory: directory,
+		configFilePath: path.join(directory, PACKAGE_JSON_FILENAME),
+		format: "package-json"
+	};
+};
+const loadConfigFromDirectory = async (directory) => {
+	let sawBrokenConfigFile = false;
+	for (const extension of CONFIG_EXTENSIONS) {
+		const filePath = path.join(directory, `${CONFIG_BASENAME}.${extension}`);
+		if (!isFile(filePath)) continue;
+		const isDataFile = DATA_CONFIG_EXTENSIONS.has(extension);
+		try {
+			const parsed = isDataFile ? readDataConfig(filePath) : await loadModuleConfig(filePath);
+			if (isPlainObject(parsed)) return {
+				status: "found",
+				loaded: {
+					config: validateConfigTypes(parsed),
+					sourceDirectory: directory,
+					configFilePath: filePath,
+					format: isDataFile ? "json" : "module"
+				}
 			};
+			warn(`${CONFIG_BASENAME}.${extension} must export an object, ignoring.`);
+			sawBrokenConfigFile = true;
+		} catch (error) {
+			warn(`Failed to load ${CONFIG_BASENAME}.${extension}: ${formatError(error)}`);
+			sawBrokenConfigFile = true;
 		}
-	} catch {
-		return null;
 	}
-	return null;
+	const packageJsonConfig = loadPackageJsonConfig(directory);
+	if (packageJsonConfig) return {
+		status: "found",
+		loaded: packageJsonConfig
+	};
+	if (isFile(path.join(directory, LEGACY_CONFIG_FILENAME))) warn(`${LEGACY_CONFIG_FILENAME} is no longer read — rename it to ${CONFIG_BASENAME}.json (or author a ${CONFIG_BASENAME}.ts).`);
+	return {
+		status: sawBrokenConfigFile ? "invalid" : "absent",
+		loaded: null
+	};
 };
 const cachedConfigs = /* @__PURE__ */ new Map();
-const loadConfigWithSource = (rootDirectory) => {
-	const cached = cachedConfigs.get(rootDirectory);
-	if (cached !== void 0) return cached;
-	const localConfig = loadConfigFromDirectory(rootDirectory);
-	if (localConfig) {
-		cachedConfigs.set(rootDirectory, localConfig);
-		return localConfig;
-	}
-	if (isProjectBoundary(rootDirectory)) {
-		cachedConfigs.set(rootDirectory, null);
-		return null;
-	}
+const clearConfigCache = () => {
+	cachedConfigs.clear();
+};
+const loadConfigWalkingUp = async (rootDirectory) => {
+	const localResult = await loadConfigFromDirectory(rootDirectory);
+	if (localResult.status === "found") return localResult.loaded;
+	if (localResult.status === "invalid" || isProjectBoundary(rootDirectory)) return null;
 	let ancestorDirectory = path.dirname(rootDirectory);
 	while (ancestorDirectory !== path.dirname(ancestorDirectory)) {
-		const ancestorConfig = loadConfigFromDirectory(ancestorDirectory);
-		if (ancestorConfig) {
-			cachedConfigs.set(rootDirectory, ancestorConfig);
-			return ancestorConfig;
-		}
-		if (isProjectBoundary(ancestorDirectory)) {
-			cachedConfigs.set(rootDirectory, null);
-			return null;
-		}
+		const ancestorResult = await loadConfigFromDirectory(ancestorDirectory);
+		if (ancestorResult.status === "found") return ancestorResult.loaded;
+		if (isProjectBoundary(ancestorDirectory)) return null;
 		ancestorDirectory = path.dirname(ancestorDirectory);
 	}
-	cachedConfigs.set(rootDirectory, null);
 	return null;
 };
+const loadConfigWithSource = (rootDirectory) => {
+	const cached = cachedConfigs.get(rootDirectory);
+	if (cached !== void 0) return cached;
+	const loadPromise = loadConfigWalkingUp(rootDirectory);
+	cachedConfigs.set(rootDirectory, loadPromise);
+	return loadPromise;
+};
+const directoryHasCurrentConfig = (directory) => {
+	for (const extension of CONFIG_EXTENSIONS) if (isFile(path.join(directory, `${CONFIG_BASENAME}.${extension}`))) return true;
+	return readEmbeddedPackageJsonConfig(directory) !== null;
+};
+/**
+* Walks up from `rootDirectory` (same boundary semantics as
+* `loadConfigWithSource`) looking for a pre-migration
+* `react-doctor.config.json` that is no longer read. Returns the first one
+* found, or `null` when a current-format config supersedes it or none exists
+* before a project boundary. Detection only — the CLI performs the rename.
+*/
+const findLegacyConfig = (rootDirectory) => {
+	let directory = rootDirectory;
+	while (true) {
+		if (directoryHasCurrentConfig(directory)) return null;
+		const legacyFilePath = path.join(directory, LEGACY_CONFIG_FILENAME);
+		if (isFile(legacyFilePath)) return {
+			legacyFilePath,
+			directory
+		};
+		if (isProjectBoundary(directory)) return null;
+		const parentDirectory = path.dirname(directory);
+		if (parentDirectory === directory) return null;
+		directory = parentDirectory;
+	}
+};
 const resolveConfigRootDir = (config, configSourceDirectory) => {
 	if (!config || !configSourceDirectory) return null;
 	const rawRootDir = config.rootDir;
@@ -7585,8 +7672,7 @@ const resolveDiagnoseTarget = (directory, options = {}) => {
 * (`inspect()`, `diagnose()`, and the CLI's `inspectAction`):
 *
 *   1. Resolve the requested directory to absolute.
-*   2. Load `react-doctor.config.(json|js)` / `package.json#reactDoctor`
-*      if present.
+*   2. Load `doctor.config.*` / `package.json#reactDoctor` if present.
 *   3. Honor `config.rootDir` to redirect the scan to a nested
 *      project root, if configured.
 *   4. Walk into a nested React subproject when the requested
@@ -7604,9 +7690,9 @@ const resolveDiagnoseTarget = (directory, options = {}) => {
 * via its own cache). Routing through `resolveScanTarget` keeps every
 * shell in agreement on what "the scan directory" means.
 */
-const resolveScanTarget = (requestedDirectory, options = {}) => {
+const resolveScanTarget = async (requestedDirectory, options = {}) => {
 	const absoluteRequested = path.resolve(requestedDirectory);
-	const loadedConfig = loadConfigWithSource(absoluteRequested);
+	const loadedConfig = await loadConfigWithSource(absoluteRequested);
 	const userConfig = loadedConfig?.config ?? null;
 	const configSourceDirectory = loadedConfig?.sourceDirectory ?? null;
 	const redirectedDirectory = resolveConfigRootDir(userConfig, configSourceDirectory);
@@ -7930,6 +8016,61 @@ const checkExpoPackageJsonConflicts = (context) => {
 	}));
 	return diagnostics;
 };
+const APP_CONFIG_JSON_FILES = ["app.config.json", "app.json"];
+const APP_CONFIG_DYNAMIC_FILES = [
+	"app.config.ts",
+	"app.config.js",
+	"app.config.cjs",
+	"app.config.mjs"
+];
+const ExpoConfigSchema = Schema.Struct({
+	newArchEnabled: Schema.optional(Schema.Boolean),
+	updates: Schema.optional(Schema.Struct({ disableAntiBrickingMeasures: Schema.optional(Schema.Boolean) }))
+});
+const AppManifestSchema = Schema.Struct({ expo: Schema.optional(ExpoConfigSchema) });
+const NO_CONFIG = {
+	config: null,
+	configFile: null
+};
+const decodeExpoConfig = (filePath) => {
+	let raw;
+	try {
+		raw = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+	} catch {
+		return null;
+	}
+	return Option.getOrNull(Schema.decodeUnknownOption(AppManifestSchema)(raw))?.expo ?? null;
+};
+const readExpoAppConfig = (rootDirectory) => {
+	if (APP_CONFIG_DYNAMIC_FILES.some((fileName) => isFile(path.join(rootDirectory, fileName)))) return NO_CONFIG;
+	for (const fileName of APP_CONFIG_JSON_FILES) {
+		const filePath = path.join(rootDirectory, fileName);
+		if (!isFile(filePath)) continue;
+		const config = decodeExpoConfig(filePath);
+		if (config) return {
+			config,
+			configFile: fileName
+		};
+	}
+	return NO_CONFIG;
+};
+const REANIMATED_PACKAGE = "react-native-reanimated";
+const WORKLETS_PACKAGE = "react-native-worklets";
+const FIRST_NEW_ARCH_ONLY_REANIMATED_MAJOR = 4;
+const checkExpoReanimatedNewArch = (context) => {
+	const reanimatedSpec = context.packageJson.dependencies?.[REANIMATED_PACKAGE] ?? context.packageJson.devDependencies?.[REANIMATED_PACKAGE];
+	const reanimatedMajor = reanimatedSpec === void 0 ? null : getLowestDependencyMajor(reanimatedSpec);
+	if (!(reanimatedMajor !== null && reanimatedMajor >= FIRST_NEW_ARCH_ONLY_REANIMATED_MAJOR || context.directDependencyNames.has(WORKLETS_PACKAGE))) return [];
+	const appConfig = readExpoAppConfig(context.rootDirectory);
+	if (appConfig.config?.newArchEnabled !== false) return [];
+	return [buildExpoDiagnostic({
+		rule: "expo-reanimated-v4-requires-new-arch",
+		severity: "error",
+		filePath: appConfig.configFile ?? "app.json",
+		message: "react-native-reanimated v4 supports only the New Architecture, but `newArchEnabled: false` is set in your app config, so the app will crash on first launch.",
+		help: "Remove `newArchEnabled: false` from your app config (the New Architecture is the default on SDK 52+), or pin react-native-reanimated to v3 if you must stay on the legacy architecture."
+	})];
+};
 const EXPO_ROUTER_REACT_NAVIGATION_MIN_SDK_MAJOR = 56;
 const EXPO_ROUTER_REACT_NAVIGATION_MAX_SDK_MAJOR_EXCLUSIVE = 57;
 const checkExpoRouterReactNavigation = (context) => {
@@ -7945,6 +8086,17 @@ const checkExpoRouterReactNavigation = (context) => {
 		help: "Remove these `@react-navigation/*` packages and replace direct imports with their expo-router equivalents. See https://docs.expo.dev/router/migrate/sdk-55-to-56/"
 	})];
 };
+const checkExpoUpdatesConfig = (context) => {
+	const appConfig = readExpoAppConfig(context.rootDirectory);
+	if (appConfig.config?.updates?.disableAntiBrickingMeasures !== true) return [];
+	return [buildExpoDiagnostic({
+		rule: "expo-updates-no-unsafe-production-config",
+		severity: "error",
+		filePath: appConfig.configFile ?? "app.json",
+		message: "`updates.disableAntiBrickingMeasures: true` disables expo-updates' recovery safeguards and is liable to leave installed apps in a permanently bricked state, so it must not be used in production.",
+		help: "Remove `disableAntiBrickingMeasures` from your app config's `updates` block. See https://docs.expo.dev/versions/latest/config/app/#updates"
+	})];
+};
 const VECTOR_ICONS_MIN_SDK_MAJOR = 56;
 const SCOPED_VECTOR_ICONS_NAMESPACE = "@react-native-vector-icons/";
 const CONFLICTING_VECTOR_ICONS_PACKAGES = ["@expo/vector-icons", "react-native-vector-icons"];
@@ -7971,7 +8123,9 @@ const checkExpoProject = (rootDirectory, project) => {
 		...checkExpoLockfile(context),
 		...checkExpoGitignore(context),
 		...checkExpoEnvLocalFiles(context),
-		...checkExpoMetroConfig(context)
+		...checkExpoMetroConfig(context),
+		...checkExpoReanimatedNewArch(context),
+		...checkExpoUpdatesConfig(context)
 	];
 };
 const PNPM_WORKSPACE_FILE = "pnpm-workspace.yaml";
@@ -8088,6 +8242,69 @@ const checkPnpmHardening = (rootDirectory) => {
 	}));
 	return diagnostics;
 };
+const BUILDER_BOB_PACKAGE = "react-native-builder-bob";
+const isBuilderBobLibrary = (packageJson) => {
+	const bobConfig = packageJson[BUILDER_BOB_PACKAGE];
+	return typeof bobConfig === "object" && bobConfig !== null;
+};
+const checkReactNativeLibraryDependencies = (rootDirectory) => {
+	const packageJson = readPackageJson$1(path.join(rootDirectory, "package.json"));
+	if (!isBuilderBobLibrary(packageJson)) return [];
+	const misplaced = ["react", "react-native"].filter((name) => packageJson.dependencies?.[name] !== void 0);
+	if (misplaced.length === 0) return [];
+	const quoted = misplaced.map((name) => `"${name}"`).join(" and ");
+	return [{
+		filePath: "package.json",
+		plugin: "react-doctor",
+		rule: "rn-library-react-in-dependencies",
+		severity: "warning",
+		message: `This react-native-builder-bob library lists ${quoted} in \`dependencies\` — that ships a second copy into consumer apps, causing "Invalid hook call" (duplicate React) and duplicate-native-module crashes.`,
+		help: `Move ${quoted} to \`peerDependencies\` (keep ${misplaced.length === 1 ? "it" : "them"} in \`devDependencies\` for local development).`,
+		line: 0,
+		column: 0,
+		category: "Correctness"
+	}];
+};
+const BABEL_CONFIG_FILE_NAMES = [
+	"babel.config.js",
+	"babel.config.cjs",
+	"babel.config.mjs",
+	"babel.config.json",
+	".babelrc",
+	".babelrc.js",
+	".babelrc.json"
+];
+const LEGACY_PRESET_SPEC = "module:metro-react-native-babel-preset";
+const checkReactNativeMetroBabelPreset = (rootDirectory) => {
+	for (const fileName of BABEL_CONFIG_FILE_NAMES) {
+		const filePath = path.join(rootDirectory, fileName);
+		if (!isFile(filePath)) continue;
+		let contents;
+		try {
+			contents = fs.readFileSync(filePath, "utf-8");
+		} catch {
+			continue;
+		}
+		if (!contents.includes(LEGACY_PRESET_SPEC)) continue;
+		return [{
+			filePath: fileName,
+			plugin: "react-doctor",
+			rule: "rn-no-metro-babel-preset",
+			severity: "error",
+			message: "`module:metro-react-native-babel-preset` was renamed to `@react-native/babel-preset` and is no longer installed by React Native 0.73+ — this preset reference fails to resolve and breaks the Metro/Babel transform.",
+			help: "Replace the preset with `module:@react-native/babel-preset` (or `babel-preset-expo` on Expo) and remove the old `metro-react-native-babel-preset` dependency.",
+			line: 0,
+			column: 0,
+			category: "Correctness"
+		}];
+	}
+	return [];
+};
+const isReactNativeProject = (project) => project.framework === "react-native" || project.framework === "expo" || project.hasReactNativeWorkspace || project.expoVersion !== null;
+const checkReactNativeProject = (rootDirectory, project) => {
+	if (!isReactNativeProject(project)) return [];
+	return [...checkReactNativeMetroBabelPreset(rootDirectory), ...checkReactNativeLibraryDependencies(rootDirectory)];
+};
 const REDUCED_MOTION_GREP_PATTERN = "prefers-reduced-motion|useReducedMotion|MotionConfig|reducedMotion";
 const REDUCED_MOTION_FILE_GLOBS = [
 	"*.ts",
@@ -8653,8 +8870,8 @@ var Config = class Config extends Context.Service()("react-doctor/Config") {
 		const cache = yield* Cache.make({
 			capacity: 16,
 			timeToLive: CONFIG_CACHE_TTL_MS,
-			lookup: (directory) => Effect.sync(() => {
-				const loaded = loadConfigWithSource(directory);
+			lookup: (directory) => Effect.promise(async () => {
+				const loaded = await loadConfigWithSource(directory);
 				const redirected = resolveConfigRootDir(loaded?.config ?? null, loaded?.sourceDirectory ?? null);
 				return {
 					config: loaded?.config ?? null,
@@ -10833,7 +11050,7 @@ const runInspect = (input, hooks = {}) => Effect.gen(function* () {
 	const afterLint = hooks.afterLint ?? NO_HOOKS.afterLint;
 	yield* beforeLint(project, lintIncludePaths ?? void 0);
 	const isDiffMode = input.includePaths.length > 0;
-	const showWarnings = input.warnings ?? resolvedConfig.config?.warnings ?? false;
+	const showWarnings = input.warnings ?? resolvedConfig.config?.warnings ?? true;
 	const transform = buildDiagnosticPipeline({
 		rootDirectory: scanDirectory,
 		userConfig: resolvedConfig.config,
@@ -10845,7 +11062,8 @@ const runInspect = (input, hooks = {}) => Effect.gen(function* () {
 	const environmentDiagnostics = isDiffMode ? [] : [
 		...checkReducedMotion(scanDirectory),
 		...checkPnpmHardening(scanDirectory),
-		...checkExpoProject(scanDirectory, project)
+		...checkExpoProject(scanDirectory, project),
+		...checkReactNativeProject(scanDirectory, project)
 	];
 	const envCollected = yield* Stream.runCollect(applyPerElementPipeline(Stream.fromIterable(environmentDiagnostics)));
 	const lintFailure = yield* Ref.make({
@@ -10960,7 +11178,6 @@ const runInspect = (input, hooks = {}) => Effect.gen(function* () {
 	"inspect.isCi": input.isCi,
 	"inspect.scoreSurface": input.scoreSurface ?? "score"
 } }));
-Layer.mergeAll(Project.layerNode, Config.layerNode, DeadCode.layerNode, Files.layerNode, Git.layerNode, Linter.layerOxlint, LintPartialFailures.layerLive, Progress.layerNoop, Reporter.layerNoop, Score.layerHttp);
 const parseNodeVersion = (versionString) => {
 	const [major = 0, minor = 0, patch = 0] = versionString.replace(/^v/, "").trim().split(".").map(Number);
 	return {
@@ -11283,6 +11500,26 @@ const buildJsonReport = (input) => {
 	};
 };
 /**
+* Single source of truth for the skipped-check accounting shared by the
+* CLI renderer (`react-doctor/src/inspect.ts → finalizeAndRender`) and the
+* programmatic shell (`@react-doctor/api → diagnose()`). Both surface a
+* failed lint / dead-code pass instead of a false "all clear", so the
+* branch logic lives here once.
+*/
+const buildSkippedChecks = (input) => {
+	const skippedChecks = [];
+	if (input.didLintFail) skippedChecks.push("lint");
+	if (input.didDeadCodeFail) skippedChecks.push("dead-code");
+	const skippedCheckReasons = {};
+	if (input.didLintFail && input.lintFailureReason !== null) skippedCheckReasons.lint = input.lintFailureReason;
+	else if (input.lintPartialFailures.length > 0) skippedCheckReasons["lint:partial"] = input.lintPartialFailures.join("; ");
+	if (input.didDeadCodeFail && input.deadCodeFailureReason !== null) skippedCheckReasons["dead-code"] = input.deadCodeFailureReason;
+	return {
+		skippedChecks,
+		skippedCheckReasons
+	};
+};
+/**
 * Programmatic façade over `Git.diffSelection`. Async because the
 * Git service runs through Effect's `ChildProcess` (true subprocess
 * spawn, not `spawnSync`).
@@ -11387,12 +11624,32 @@ const highlighter = {
 	bold: import_picocolors.default.bold
 };
 /**
-* Canonical URL for a rule's reviewer-tested fix recipe, served at
-* `https://www.react.doctor/prompts/rules/<plugin>/<rule>.md`. The
-* `/doctor` playbook fetches it on demand so each fix follows the
-* canonical recipe instead of being improvised per diagnostic.
+* Override picocolors' automatic color detection. picocolors decides
+* once, at import time, from `NO_COLOR` / `FORCE_COLOR` / `TERM` / TTY.
+* This lets the CLI honor an explicit `--color` / `--no-color` flag
+* (clig.dev, Output: "Disable color … if the user requested it") by
+* swapping in a fresh set of formatters. Call it before any colored
+* output is produced. Every call site reads `highlighter.<method>` at
+* call time, so reassigning the properties propagates everywhere.
+*/
+const setColorEnabled = (enabled) => {
+	const colors = import_picocolors.default.createColors(enabled);
+	highlighter.error = colors.red;
+	highlighter.warn = colors.yellow;
+	highlighter.info = colors.cyan;
+	highlighter.success = colors.green;
+	highlighter.dim = colors.dim;
+	highlighter.gray = colors.gray;
+	highlighter.bold = colors.bold;
+};
+/**
+* Canonical URL for a rule's documentation page — its reviewer-tested fix
+* recipe rendered for humans — served at
+* `https://www.react.doctor/docs/rules/<plugin>/<rule>`. The CLI links here
+* from its fix-recipe directive so each fix follows the canonical recipe
+* instead of being improvised per diagnostic.
 */
-const buildRulePromptUrl = (plugin, rule) => `${PROMPTS_RULES_BASE_URL}/${plugin}/${rule}.md`;
+const buildRuleDocsUrl = (plugin, rule) => `${DOCS_RULES_BASE_URL}/${plugin}/${rule}`;
 const groupBy = (items, keyFn) => {
 	const groups = /* @__PURE__ */ new Map();
 	for (const item of items) {
@@ -11405,8 +11662,8 @@ const groupBy = (items, keyFn) => {
 };
 /**
 * Whether a diagnostic's rule has a published per-rule fix recipe at
-* `${PROMPTS_RULES_BASE_URL}/react-doctor/<rule>.md`
-* (see `buildRulePromptUrl`).
+* `${DOCS_RULES_BASE_URL}/react-doctor/<rule>`
+* (see `buildRuleDocsUrl`).
 *
 * Recipes are generated from react-doctor's own engine rules, so only
 * those resolve. Dead-code (`deslop`), the synthetic environment and
@@ -11418,151 +11675,796 @@ const groupBy = (items, keyFn) => {
 */
 const hasPublishedFixRecipe = (diagnostic) => diagnostic.plugin === "react-doctor" && Object.hasOwn(reactDoctorPlugin.rules, diagnostic.rule);
 //#endregion
-//#region ../../node_modules/.pnpm/chalk@5.6.2/node_modules/chalk/source/vendor/ansi-styles/index.js
-const ANSI_BACKGROUND_OFFSET = 10;
-const wrapAnsi16 = (offset = 0) => (code) => `\u001B[${code + offset}m`;
-const wrapAnsi256 = (offset = 0) => (code) => `\u001B[${38 + offset};5;${code}m`;
-const wrapAnsi16m = (offset = 0) => (red, green, blue) => `\u001B[${38 + offset};2;${red};${green};${blue}m`;
-const styles$1 = {
-	modifier: {
-		reset: [0, 0],
-		bold: [1, 22],
-		dim: [2, 22],
-		italic: [3, 23],
-		underline: [4, 24],
-		overline: [53, 55],
-		inverse: [7, 27],
-		hidden: [8, 28],
-		strikethrough: [9, 29]
-	},
-	color: {
-		black: [30, 39],
-		red: [31, 39],
-		green: [32, 39],
-		yellow: [33, 39],
-		blue: [34, 39],
-		magenta: [35, 39],
-		cyan: [36, 39],
-		white: [37, 39],
-		blackBright: [90, 39],
-		gray: [90, 39],
-		grey: [90, 39],
-		redBright: [91, 39],
-		greenBright: [92, 39],
-		yellowBright: [93, 39],
-		blueBright: [94, 39],
-		magentaBright: [95, 39],
-		cyanBright: [96, 39],
-		whiteBright: [97, 39]
-	},
-	bgColor: {
-		bgBlack: [40, 49],
-		bgRed: [41, 49],
-		bgGreen: [42, 49],
-		bgYellow: [43, 49],
-		bgBlue: [44, 49],
-		bgMagenta: [45, 49],
-		bgCyan: [46, 49],
-		bgWhite: [47, 49],
-		bgBlackBright: [100, 49],
-		bgGray: [100, 49],
-		bgGrey: [100, 49],
-		bgRedBright: [101, 49],
-		bgGreenBright: [102, 49],
-		bgYellowBright: [103, 49],
-		bgBlueBright: [104, 49],
-		bgMagentaBright: [105, 49],
-		bgCyanBright: [106, 49],
-		bgWhiteBright: [107, 49]
-	}
+//#region src/cli/utils/is-ci-environment.ts
+const CI_ENVIRONMENT_VARIABLES = [
+	"GITHUB_ACTIONS",
+	"GITLAB_CI",
+	"CIRCLECI"
+];
+const CI_PROVIDER_BY_ENVIRONMENT_VARIABLE = [
+	["GITHUB_ACTIONS", "github-actions"],
+	["GITLAB_CI", "gitlab-ci"],
+	["CIRCLECI", "circleci"],
+	["BUILDKITE", "buildkite"],
+	["JENKINS_URL", "jenkins"],
+	["TF_BUILD", "azure-pipelines"],
+	["CODEBUILD_BUILD_ID", "aws-codebuild"],
+	["TEAMCITY_VERSION", "teamcity"],
+	["BITBUCKET_BUILD_NUMBER", "bitbucket"],
+	["TRAVIS", "travis"],
+	["DRONE", "drone"]
+];
+const CODING_AGENT_BY_ENVIRONMENT_VARIABLE = [
+	["CLAUDECODE", "claude-code"],
+	["CLAUDE_CODE", "claude-code"],
+	["CURSOR_AGENT", "cursor"],
+	["CODEX_CI", "codex"],
+	["CODEX_SANDBOX", "codex"],
+	["CODEX_SANDBOX_NETWORK_DISABLED", "codex"],
+	["OPENCODE", "opencode"],
+	["GOOSE_TERMINAL", "goose"],
+	["AMP_THREAD_ID", "amp"]
+];
+const GENERIC_CODING_AGENT_ENVIRONMENT_VARIABLES = ["AGENT_SESSION_ID", "AGENT_THREAD_ID"];
+const CODING_AGENT_ENVIRONMENT_VALUE_VARIABLES = ["AGENT"];
+const CODING_AGENT_ENVIRONMENT_VALUES = { AGENT: ["amp", "goose"] };
+[...CODING_AGENT_BY_ENVIRONMENT_VARIABLE.map(([environmentVariable]) => environmentVariable), ...GENERIC_CODING_AGENT_ENVIRONMENT_VARIABLES];
+const FALSY_CI_FLAG_VALUES = new Set([
+	"",
+	"0",
+	"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 detectCiProvider = () => {
+	for (const [environmentVariable, provider] of CI_PROVIDER_BY_ENVIRONMENT_VARIABLE) if (process.env[environmentVariable]) return provider;
+	return isCiFlagSet(process.env.CI) ? "unknown" : null;
 };
-Object.keys(styles$1.modifier);
-const foregroundColorNames = Object.keys(styles$1.color);
-const backgroundColorNames = Object.keys(styles$1.bgColor);
-[...foregroundColorNames, ...backgroundColorNames];
-function assembleStyles() {
-	const codes = /* @__PURE__ */ new Map();
-	for (const [groupName, group] of Object.entries(styles$1)) {
-		for (const [styleName, style] of Object.entries(group)) {
-			styles$1[styleName] = {
-				open: `\u001B[${style[0]}m`,
-				close: `\u001B[${style[1]}m`
-			};
-			group[styleName] = styles$1[styleName];
-			codes.set(style[0], style[1]);
-		}
-		Object.defineProperty(styles$1, groupName, {
-			value: group,
-			enumerable: false
-		});
+const detectCodingAgentFromValue = () => {
+	for (const environmentVariable of CODING_AGENT_ENVIRONMENT_VALUE_VARIABLES) {
+		const value = process.env[environmentVariable]?.toLowerCase();
+		if (value && CODING_AGENT_ENVIRONMENT_VALUES[environmentVariable].includes(value)) return value;
 	}
-	Object.defineProperty(styles$1, "codes", {
-		value: codes,
-		enumerable: false
-	});
-	styles$1.color.close = "\x1B[39m";
-	styles$1.bgColor.close = "\x1B[49m";
-	styles$1.color.ansi = wrapAnsi16();
-	styles$1.color.ansi256 = wrapAnsi256();
-	styles$1.color.ansi16m = wrapAnsi16m();
-	styles$1.bgColor.ansi = wrapAnsi16(ANSI_BACKGROUND_OFFSET);
-	styles$1.bgColor.ansi256 = wrapAnsi256(ANSI_BACKGROUND_OFFSET);
-	styles$1.bgColor.ansi16m = wrapAnsi16m(ANSI_BACKGROUND_OFFSET);
-	Object.defineProperties(styles$1, {
-		rgbToAnsi256: {
-			value(red, green, blue) {
-				if (red === green && green === blue) {
-					if (red < 8) return 16;
-					if (red > 248) return 231;
-					return Math.round((red - 8) / 247 * 24) + 232;
-				}
-				return 16 + 36 * Math.round(red / 255 * 5) + 6 * Math.round(green / 255 * 5) + Math.round(blue / 255 * 5);
-			},
-			enumerable: false
-		},
-		hexToRgb: {
-			value(hex) {
-				const matches = /[a-f\d]{6}|[a-f\d]{3}/i.exec(hex.toString(16));
-				if (!matches) return [
-					0,
-					0,
-					0
-				];
-				let [colorString] = matches;
-				if (colorString.length === 3) colorString = [...colorString].map((character) => character + character).join("");
-				const integer = Number.parseInt(colorString, 16);
-				return [
-					integer >> 16 & 255,
-					integer >> 8 & 255,
-					integer & 255
-				];
-			},
-			enumerable: false
-		},
-		hexToAnsi256: {
-			value: (hex) => styles$1.rgbToAnsi256(...styles$1.hexToRgb(hex)),
-			enumerable: false
-		},
-		ansi256ToAnsi: {
-			value(code) {
-				if (code < 8) return 30 + code;
-				if (code < 16) return 90 + (code - 8);
-				let red;
-				let green;
-				let blue;
-				if (code >= 232) {
-					red = ((code - 232) * 10 + 8) / 255;
-					green = red;
-					blue = red;
-				} else {
-					code -= 16;
-					const remainder = code % 36;
-					red = Math.floor(code / 36) / 5;
-					green = Math.floor(remainder / 6) / 5;
-					blue = remainder % 6 / 5;
-				}
-				const value = Math.max(red, green, blue) * 2;
-				if (value === 0) return 30;
+	return null;
+};
+const detectCodingAgent = () => {
+	for (const [environmentVariable, agent] of CODING_AGENT_BY_ENVIRONMENT_VARIABLE) if (process.env[environmentVariable]) return agent;
+	const agentFromValue = detectCodingAgentFromValue();
+	if (agentFromValue) return agentFromValue;
+	if (GENERIC_CODING_AGENT_ENVIRONMENT_VARIABLES.some((environmentVariable) => process.env[environmentVariable])) return "unknown";
+	return null;
+};
+const isCodingAgentEnvironment = () => detectCodingAgent() !== null;
+const isCiOrCodingAgentEnvironment = () => isCiEnvironment() || isCodingAgentEnvironment();
+//#endregion
+//#region src/cli/utils/is-non-interactive-environment.ts
+const NON_INTERACTIVE_ENVIRONMENT_VARIABLES = [
+	"CI",
+	"GITHUB_ACTIONS",
+	"GITLAB_CI",
+	"BUILDKITE",
+	"JENKINS_URL",
+	"TF_BUILD",
+	"CODEBUILD_BUILD_ID",
+	"TEAMCITY_VERSION",
+	"BITBUCKET_BUILD_NUMBER",
+	"CIRCLECI",
+	"TRAVIS",
+	"DRONE",
+	"GIT_DIR"
+];
+const isNonInteractiveEnvironment = () => NON_INTERACTIVE_ENVIRONMENT_VARIABLES.some((envVariable) => Boolean(process.env[envVariable])) || isCodingAgentEnvironment();
+//#endregion
+//#region src/cli/utils/constants.ts
+const STAGED_FILES_TEMP_DIR_PREFIX = "react-doctor-staged-";
+const INTERNAL_ERROR_JSON_FALLBACK = "{\"schemaVersion\":1,\"ok\":false,\"error\":{\"message\":\"Internal error\",\"name\":\"Error\",\"chain\":[]}}\n";
+const SENTRY_FLUSH_TIMEOUT_MS = 2e3;
+const NANOSECONDS_PER_SECOND = 1000000000n;
+//#endregion
+//#region src/cli/utils/noop-console.ts
+/**
+* A concrete `Console.Console` whose methods are all no-ops.
+*
+* Used by `--silent` (provided via
+* `Effect.provideService(Console.Console, makeNoopConsole())`) and by
+* `enableJsonMode` (assigned over the relevant slots on
+* `globalThis.console` so imperative legacy callsites that aren't
+* Effect-typed also fall silent). Sourcing both from a single concrete
+* object keeps "what is a no-op console" answered in one place; the
+* earlier `new Proxy({} as Console.Console, { get: () => () => undefined })`
+* combined a cast with a Proxy to do the same thing implicitly.
+*
+* The interface mirrors Effect v4's `Console.Console` shape exactly so
+* `Effect.provideService(Console.Console, makeNoopConsole())` requires
+* no cast.
+*/
+const makeNoopConsole = () => ({
+	assert: () => {},
+	clear: () => {},
+	count: () => {},
+	countReset: () => {},
+	debug: () => {},
+	dir: () => {},
+	dirxml: () => {},
+	error: () => {},
+	group: () => {},
+	groupCollapsed: () => {},
+	groupEnd: () => {},
+	info: () => {},
+	log: () => {},
+	table: () => {},
+	time: () => {},
+	timeEnd: () => {},
+	timeLog: () => {},
+	trace: () => {},
+	warn: () => {}
+});
+//#endregion
+//#region src/cli/utils/version.ts
+const VERSION = "0.2.14-dev.bdb9e36";
+//#endregion
+//#region src/cli/utils/json-mode.ts
+let context = null;
+/**
+* JSON mode writes the report payload to stdout; any incidental log
+* line printed by an Effect program would corrupt the JSON. Effect's
+* `Console` module resolves to `globalThis.console` by default (see
+* `effect/internal/effect.ts` → `ConsoleRef`), so copying the methods
+* from `makeNoopConsole()` onto the global is enough to silence every
+* `yield* Console.log(...)` and `cliLogger.*` call sourced from
+* react-doctor or its services.
+*
+* We use the same `makeNoopConsole()` source as the `--silent` path
+* (which provides the Effect Console via
+* `Effect.provideService(Console.Console, makeNoopConsole())`) — one
+* canonical "no-op console" definition shared by the two silent
+* mechanisms. The two routes still differ in how they install the
+* noop: silent mode swaps the Effect Console reference inside the
+* program; JSON mode patches the global because the surrounding CLI
+* command body is still imperative. Both will collapse into the
+* Effect-typed route once the command body finishes its migration.
+*
+* JSON mode is one-shot per CLI invocation, so we never restore.
+*/
+const installSilentConsole = () => {
+	const noopConsole = makeNoopConsole();
+	const target = globalThis.console;
+	const source = noopConsole;
+	for (const key of [
+		"log",
+		"error",
+		"warn",
+		"info",
+		"debug",
+		"trace"
+	]) target[key] = source[key];
+};
+const enableJsonMode = ({ compact, directory }) => {
+	context = {
+		compact,
+		directory,
+		startTime: performance.now(),
+		mode: "full"
+	};
+	installSilentConsole();
+};
+const isJsonModeActive = () => context !== null;
+const setJsonReportDirectory = (directory) => {
+	if (context) context.directory = directory;
+};
+const setJsonReportMode = (mode) => {
+	if (context) context.mode = mode;
+};
+const writeJsonReport = (report) => {
+	const serialized = context?.compact ? JSON.stringify(report) : JSON.stringify(report, null, 2);
+	process.stdout.write(`${serialized}\n`);
+};
+const writeJsonErrorReport = (error) => {
+	if (!context) return;
+	try {
+		writeJsonReport(buildJsonReportError({
+			version: VERSION,
+			directory: context.directory,
+			error,
+			elapsedMilliseconds: performance.now() - context.startTime,
+			mode: context.mode
+		}));
+	} catch {
+		process.stdout.write(INTERNAL_ERROR_JSON_FALLBACK);
+	}
+};
+//#endregion
+//#region src/cli/utils/scrub-sensitive-text.ts
+const HOME_DIRECTORY = os.homedir();
+const USER_HOME_PATTERNS = [/[A-Za-z]:[\\/]Users[\\/][^\\/]+/gi, /(?:\/Users\/|\/home\/)[^/\\]+/gi];
+/**
+* Replaces the user's home directory (and generic `/Users|/home|C:\Users\<name>`
+* roots) with `~` so absolute paths can't be tied back to an individual. Keeps
+* the path's relative structure intact, which stays useful for debugging while
+* dropping the personally-identifying prefix. Idempotent — re-running on an
+* already-scrubbed `~/...` path is a no-op.
+*/
+const scrubSensitivePaths = (text) => {
+	let scrubbed = text;
+	if (HOME_DIRECTORY.length > 1) scrubbed = scrubbed.split(HOME_DIRECTORY).join("~");
+	for (const pattern of USER_HOME_PATTERNS) scrubbed = scrubbed.replace(pattern, "~");
+	return scrubbed;
+};
+//#endregion
+//#region src/cli/utils/build-run-context.ts
+const ROOT_SUBCOMMANDS = new Set(["install", "setup"]);
+const detectInvokedVia = () => {
+	const userAgent = process.env.npm_config_user_agent;
+	if (!userAgent) return "unknown";
+	return userAgent.split("/", 1)[0]?.trim() || "unknown";
+};
+const detectNodeMajor = () => {
+	const major = Number.parseInt(process.versions.node.split(".", 1)[0] ?? "", 10);
+	return Number.isNaN(major) ? 0 : major;
+};
+const detectOrigin = () => {
+	if (process.env.GIT_DIR) return "git-hook";
+	if (isCodingAgentEnvironment()) return "agent";
+	if (isCiEnvironment()) return "ci";
+	return "cli";
+};
+const detectCommand = (userArguments) => {
+	for (const argument of userArguments) {
+		if (argument === "--") break;
+		if (argument.startsWith("-")) continue;
+		return ROOT_SUBCOMMANDS.has(argument) ? argument : "inspect";
+	}
+	return "inspect";
+};
+/**
+* Snapshot of the current invocation, attached to Sentry events as the
+* `run` context to make crashes triage-able (which version, platform,
+* CI/agent, how it was invoked). Every field is cheap, synchronous, and
+* safe to read at any point — cwd reads fall back, env reads are
+* booleans — so it's rebuilt lazily at capture time when runtime-only
+* signals like `jsonMode` are finally known.
+*/
+const buildRunContext = () => {
+	const userArguments = process.argv.slice(2);
+	return {
+		version: VERSION,
+		origin: detectOrigin(),
+		command: detectCommand(userArguments),
+		argv: scrubSensitivePaths(userArguments.join(" ")),
+		cwd: scrubSensitivePaths(process.cwd()),
+		node: process.version,
+		nodeMajor: detectNodeMajor(),
+		platform: process.platform,
+		arch: process.arch,
+		ci: isCiEnvironment(),
+		ciProvider: detectCiProvider(),
+		codingAgent: detectCodingAgent(),
+		interactive: !isNonInteractiveEnvironment(),
+		jsonMode: isJsonModeActive(),
+		invokedVia: detectInvokedVia()
+	};
+};
+//#endregion
+//#region src/cli/utils/build-sentry-project-context.ts
+/**
+* Projects the {@link ProjectInfo} we already detect during a scan into the
+* Sentry scope shape: a handful of searchable `project.*` tags plus the
+* anonymous project *shape* as a `project` context block. Lets crash/transaction
+* triage answer "which kind of project hit this?" (framework, React/Expo
+* version, TypeScript, size) without sending source code — and deliberately
+* omits `projectName` and `rootDirectory`, the two identifying fields, so the
+* project can't be tied back to a specific company/repo.
+*/
+const buildSentryProjectContext = (projectInfo) => ({
+	tags: {
+		"project.framework": projectInfo.framework,
+		"project.reactMajor": projectInfo.reactMajorVersion,
+		"project.typescript": projectInfo.hasTypeScript,
+		"project.reactCompiler": projectInfo.hasReactCompiler,
+		"project.expo": projectInfo.expoVersion !== null,
+		"project.reactNative": projectInfo.hasReactNativeWorkspace
+	},
+	context: {
+		framework: projectInfo.framework,
+		reactVersion: projectInfo.reactVersion,
+		reactMajorVersion: projectInfo.reactMajorVersion,
+		hasTypeScript: projectInfo.hasTypeScript,
+		hasReactCompiler: projectInfo.hasReactCompiler,
+		hasTanStackQuery: projectInfo.hasTanStackQuery,
+		tailwindVersion: projectInfo.tailwindVersion,
+		zodVersion: projectInfo.zodVersion,
+		preactVersion: projectInfo.preactVersion,
+		hasReactNativeWorkspace: projectInfo.hasReactNativeWorkspace,
+		expoVersion: projectInfo.expoVersion,
+		hasReanimated: projectInfo.hasReanimated,
+		sourceFileCount: projectInfo.sourceFileCount
+	}
+});
+let currentProjectInfo = null;
+const setSentryProjectInfo = (projectInfo) => {
+	currentProjectInfo = projectInfo;
+};
+const getSentryProjectInfo = () => currentProjectInfo;
+//#endregion
+//#region src/cli/utils/build-sentry-scope.ts
+/**
+* Projects a {@link RunContext} snapshot (plus the current run's
+* {@link getSentryProjectInfo project info}, when a scan has discovered it) into
+* the Sentry scope shape — the searchable `tags` that make crashes/transactions
+* filterable (which command, origin, CI provider, coding agent, Node major,
+* package manager, project framework/React major) plus the full `run` and
+* `project` context blocks for deep triage.
+*
+* Shared by `instrument.ts` (seeded as `initialScope` so *every* event,
+* including performance transactions, carries it) and `report-error.ts` (a
+* capture-time refresh, since runtime-only signals like `jsonMode` and the
+* scanned project are only known once a command has begun).
+*/
+const buildSentryScope = (runContext = buildRunContext()) => {
+	const tags = {
+		origin: runContext.origin,
+		command: runContext.command,
+		ci: runContext.ci,
+		ciProvider: runContext.ciProvider,
+		codingAgent: runContext.codingAgent,
+		interactive: runContext.interactive,
+		jsonMode: runContext.jsonMode,
+		invokedVia: runContext.invokedVia,
+		nodeMajor: runContext.nodeMajor
+	};
+	const contexts = { run: { ...runContext } };
+	const projectInfo = getSentryProjectInfo();
+	if (projectInfo) {
+		const project = buildSentryProjectContext(projectInfo);
+		Object.assign(tags, project.tags);
+		contexts.project = project.context;
+	}
+	return {
+		tags,
+		contexts
+	};
+};
+//#endregion
+//#region src/cli/utils/scrub-sentry-event.ts
+const anonymizeText = (text) => redactSensitiveText(scrubSensitivePaths(text));
+/**
+* Recursively rewrites every string within an arbitrary value (object / array /
+* primitive) through {@link anonymizeText}, mutating in place. Used to sweep the
+* unstructured corners of an event (contexts, extra, tags, breadcrumb data,
+* span attributes) where a path or secret could hide.
+*/
+const anonymizeInPlace = (value) => {
+	if (Array.isArray(value)) {
+		for (let index = 0; index < value.length; index += 1) {
+			const item = value[index];
+			if (typeof item === "string") value[index] = anonymizeText(item);
+			else anonymizeInPlace(item);
+		}
+		return;
+	}
+	if (!isPlainObject(value)) return;
+	for (const key of Object.keys(value)) {
+		const inner = value[key];
+		if (typeof inner === "string") value[key] = anonymizeText(inner);
+		else anonymizeInPlace(inner);
+	}
+};
+/**
+* Anonymizes a Sentry event (error or transaction) before it leaves the
+* machine. Strips identity the SDK attaches automatically — the IP-bearing
+* `user`, the `server_name`, and the device `name` (all hostnames) — drops
+* captured local variables (unbounded, un-anonymizable user data), and scrubs
+* home-directory paths + known secrets/emails from every remaining string:
+* messages, stack frames, breadcrumbs, contexts/extra/tags, and span
+* attributes (e.g. the `inspect.directory` path on the bridged `runInspect`
+* span).
+*
+* Wired into both `beforeSend` and `beforeSendTransaction`. If scrubbing ever
+* throws, the event is dropped (`null`) rather than risk sending un-anonymized
+* data — telemetry is best-effort, privacy is not.
+*/
+const scrubSentryEvent = (event) => {
+	try {
+		delete event.server_name;
+		delete event.user;
+		const device = event.contexts?.device;
+		if (device) delete device.name;
+		if (event.contexts) anonymizeInPlace(event.contexts);
+		if (event.extra) anonymizeInPlace(event.extra);
+		if (event.tags) anonymizeInPlace(event.tags);
+		if (typeof event.message === "string") event.message = anonymizeText(event.message);
+		for (const breadcrumb of event.breadcrumbs ?? []) {
+			if (typeof breadcrumb.message === "string") breadcrumb.message = anonymizeText(breadcrumb.message);
+			if (breadcrumb.data) anonymizeInPlace(breadcrumb.data);
+		}
+		for (const exception of event.exception?.values ?? []) {
+			if (typeof exception.value === "string") exception.value = anonymizeText(exception.value);
+			for (const frame of exception.stacktrace?.frames ?? []) {
+				delete frame.vars;
+				if (typeof frame.filename === "string") frame.filename = scrubSensitivePaths(frame.filename);
+				if (typeof frame.abs_path === "string") frame.abs_path = scrubSensitivePaths(frame.abs_path);
+				if (typeof frame.module === "string") frame.module = scrubSensitivePaths(frame.module);
+			}
+		}
+		for (const span of event.spans ?? []) {
+			if (typeof span.description === "string") span.description = anonymizeText(span.description);
+			if (span.data) anonymizeInPlace(span.data);
+		}
+		return event;
+	} catch {
+		return null;
+	}
+};
+//#endregion
+//#region src/instrument.ts
+let isInitialized = false;
+let resolvedTracesSampleRate = 0;
+const shouldEnableSentry = () => {
+	if (process.argv.includes("--no-score") || process.argv.includes("--no-telemetry")) return false;
+	if (process.env.VITEST || process.env.NODE_ENV === "test") return false;
+	return true;
+};
+const isEnvFlagEnabled = (value) => value === "1" || value?.toLowerCase() === "true";
+/**
+* A version is a "dev" build when it's the unbuilt placeholder (`0.0.0`) or
+* carries a prerelease suffix (e.g. the `-dev.<sha>` snapshots published from
+* CI). Everything else is a real, tagged release.
+*/
+const isDevVersion = (version) => version === "0.0.0" || version.includes("-");
+/**
+* Sentry release identifier. `react-doctor@<version>` keeps it unique within
+* the org and — crucially — matches the value `scripts/sentry-sourcemaps.mjs`
+* uploads source-map artifacts under, so stack frames symbolicate. Honors the
+* standard `SENTRY_RELEASE` override.
+*/
+const resolveSentryRelease = () => process.env.SENTRY_RELEASE || `react-doctor@0.2.14-dev.bdb9e36`;
+/**
+* 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.2.14-dev.bdb9e36") ? "development" : "production");
+/**
+* Performance-tracing sample rate in `[0, 1]`. Reads `SENTRY_TRACES_SAMPLE_RATE`
+* (set to `0` to disable tracing) and falls back to
+* {@link SENTRY_DEFAULT_TRACES_SAMPLE_RATE}. Invalid / out-of-range values fall
+* back to the default rather than silently disabling tracing.
+*/
+const resolveTracesSampleRate = () => {
+	const raw = process.env.SENTRY_TRACES_SAMPLE_RATE;
+	if (raw === void 0 || raw.trim() === "") return 1;
+	const parsed = Number(raw);
+	if (Number.isNaN(parsed) || parsed < 0 || parsed > 1) return 1;
+	return parsed;
+};
+/**
+* Whether performance traces will actually be recorded — Sentry is live and the
+* resolved sample rate is above zero. Used to gate the per-run root span and
+* the Effect→Sentry tracer bridge so they're true no-ops when tracing is off.
+*/
+const isSentryTracingEnabled = () => Sentry.isInitialized() && resolvedTracesSampleRate > 0;
+/**
+* Flushes queued Sentry events (errors + transactions) before the CLI exits, so
+* the success-path transaction is delivered. A no-op when Sentry was never
+* initialized, and it swallows transport failures so telemetry can never mask
+* the user's result.
+*/
+const flushSentry = async () => {
+	if (!Sentry.isInitialized()) return;
+	try {
+		await Sentry.flush(SENTRY_FLUSH_TIMEOUT_MS);
+	} catch {}
+};
+/**
+* Initializes the Sentry Node SDK for CLI crash reporting and performance
+* tracing. Invoked as the first statement of the CLI entry (`cli/index.ts`) so
+* the SDK's global `uncaughtException` / `unhandledRejection` handlers and OTel
+* auto-instrumentation are armed before any command runs.
+*
+* Exported as a function rather than a bare side-effecting import because the
+* package declares `"sideEffects": false`, which lets the bundler tree-shake
+* side-effect-only modules. An explicit call keeps the initialization in the
+* published `dist/cli.js`.
+*
+* Scoped to the CLI application only — the programmatic `@react-doctor/api`
+* library never initializes Sentry, so importing `diagnose()` into a consumer
+* app can't hijack their telemetry.
+*
+* Configuration is environment-overridable for self-hosting and tuning:
+* `SENTRY_DSN`, `SENTRY_ENVIRONMENT`, `SENTRY_RELEASE`,
+* `SENTRY_TRACES_SAMPLE_RATE` (`0` disables tracing), and `SENTRY_DEBUG`.
+*/
+const initializeSentry = () => {
+	if (isInitialized || !shouldEnableSentry()) return;
+	isInitialized = true;
+	resolvedTracesSampleRate = resolveTracesSampleRate();
+	const { tags, contexts } = buildSentryScope();
+	Sentry.init({
+		dsn: process.env.SENTRY_DSN || "https://f253d570240a59b8dbd77b7a548ef133@o4510226365743104.ingest.us.sentry.io/4511487817809920",
+		release: resolveSentryRelease(),
+		environment: resolveSentryEnvironment(),
+		sendDefaultPii: false,
+		tracesSampleRate: resolvedTracesSampleRate,
+		debug: isEnvFlagEnabled(process.env.SENTRY_DEBUG),
+		initialScope: {
+			tags,
+			contexts
+		},
+		beforeSend: (event) => scrubSentryEvent(event),
+		beforeSendTransaction: (event) => scrubSentryEvent(event)
+	});
+};
+//#endregion
+//#region src/cli/utils/sentry-tracer.ts
+const toHrTime = (epochNanoseconds) => [Number(epochNanoseconds / NANOSECONDS_PER_SECOND), Number(epochNanoseconds % NANOSECONDS_PER_SECOND)];
+const SPAN_KIND_TO_OTEL = {
+	internal: 0,
+	server: 1,
+	client: 2,
+	producer: 3,
+	consumer: 4
+};
+const toSentryAttributeValue = (value) => {
+	if (value === null || value === void 0) return void 0;
+	if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return value;
+	return String(value);
+};
+const normalizeAttributes = (attributes) => {
+	const normalized = {};
+	if (!attributes) return normalized;
+	for (const [key, value] of Object.entries(attributes)) normalized[key] = toSentryAttributeValue(value);
+	return normalized;
+};
+const isSentryBackedSpan = (span) => span._tag === "Span" && "sentrySpan" in span;
+const spanContextFor = (span) => isSentryBackedSpan(span) ? span.sentrySpan.spanContext() : {
+	traceId: span.traceId,
+	spanId: span.spanId,
+	traceFlags: span.sampled ? 1 : 0
+};
+/**
+* Builds an Effect {@link Tracer.Tracer} that materializes every Effect span
+* (`Effect.withSpan(...)` / `Effect.fn("Service.method")`) as a child Sentry
+* span, producing one unified per-run trace in Sentry. The CLI already
+* instruments `runInspect` and each core service method, so this bridge lights
+* all of that up in Sentry for free.
+*
+* `rootSpan` is the active per-run transaction; Effect spans without an Effect
+* parent attach to it, so nesting is correct even if async-context propagation
+* is interrupted by Effect's fiber scheduler. Provided to a program via
+* `Effect.withTracer(...)`.
+*/
+const makeSentryTracer = (rootSpan, startInactiveSpan = Sentry.startInactiveSpan) => Tracer.make({ span: (options) => {
+	const parentSpan = Option.isSome(options.parent) && isSentryBackedSpan(options.parent.value) ? options.parent.value.sentrySpan : rootSpan;
+	const sentrySpan = startInactiveSpan({
+		name: options.name,
+		startTime: toHrTime(options.startTime),
+		parentSpan,
+		kind: SPAN_KIND_TO_OTEL[options.kind]
+	});
+	const { traceId, spanId } = sentrySpan.spanContext();
+	const attributes = /* @__PURE__ */ new Map();
+	let status = {
+		_tag: "Started",
+		startTime: options.startTime
+	};
+	return {
+		_tag: "Span",
+		sentrySpan,
+		name: options.name,
+		spanId,
+		traceId,
+		parent: options.parent,
+		annotations: options.annotations,
+		links: options.links,
+		sampled: options.sampled,
+		kind: options.kind,
+		get status() {
+			return status;
+		},
+		get attributes() {
+			return attributes;
+		},
+		end: (endTime, exit) => {
+			status = {
+				_tag: "Ended",
+				startTime: options.startTime,
+				endTime,
+				exit
+			};
+			sentrySpan.setStatus({ code: Exit.isSuccess(exit) ? 1 : 2 });
+			sentrySpan.end(toHrTime(endTime));
+		},
+		attribute: (key, value) => {
+			attributes.set(key, value);
+			sentrySpan.setAttribute(key, toSentryAttributeValue(value));
+		},
+		event: (name, startTime, eventAttributes) => {
+			sentrySpan.addEvent(name, normalizeAttributes(eventAttributes), toHrTime(startTime));
+		},
+		addLinks: (links) => {
+			for (const link of links) sentrySpan.addLink({
+				context: spanContextFor(link.span),
+				attributes: normalizeAttributes(link.attributes)
+			});
+		}
+	};
+} });
+//#endregion
+//#region src/cli/utils/apply-observability.ts
+const isOtlpExportConfigured = () => Boolean(process.env.REACT_DOCTOR_OTLP_ENDPOINT) && Boolean(process.env.REACT_DOCTOR_OTLP_AUTH_HEADER);
+const externalSpanFrom = (sentrySpan) => {
+	const { traceId, spanId, traceFlags } = sentrySpan.spanContext();
+	return Tracer.externalSpan({
+		traceId,
+		spanId,
+		sampled: (traceFlags & 1) === 1
+	});
+};
+/**
+* Installs the tracing backend for the inspect program. Effect's tracer is a
+* single reference, so the backends are mutually exclusive — we pick by
+* precedence:
+*
+* 1. **User OTLP backend** (`REACT_DOCTOR_OTLP_*` set) wins; we additionally
+*    parent the Effect trace under the active Sentry trace via an
+*    `ExternalSpan` so a trace exported to the user's backend shares its
+*    `trace_id` with the corresponding Sentry trace.
+* 2. **Sentry tracing active** (and no user OTLP): route Effect's existing
+*    span instrumentation straight into Sentry as one unified per-run trace.
+* 3. **Neither**: provide the (no-op) OTLP layer, leaving Effect's native
+*    in-memory tracer — identical to the prior default behavior.
+*/
+const applyObservability = (program, rootSentrySpan) => {
+	if (isOtlpExportConfigured()) return (rootSentrySpan ? program.pipe(Effect.provideService(Tracer.ParentSpan, externalSpanFrom(rootSentrySpan))) : program).pipe(Effect.provide(layerOtlp));
+	if (rootSentrySpan) return program.pipe(Effect.withTracer(makeSentryTracer(rootSentrySpan)));
+	return program.pipe(Effect.provide(layerOtlp));
+};
+//#endregion
+//#region ../../node_modules/.pnpm/chalk@5.6.2/node_modules/chalk/source/vendor/ansi-styles/index.js
+const ANSI_BACKGROUND_OFFSET = 10;
+const wrapAnsi16 = (offset = 0) => (code) => `\u001B[${code + offset}m`;
+const wrapAnsi256 = (offset = 0) => (code) => `\u001B[${38 + offset};5;${code}m`;
+const wrapAnsi16m = (offset = 0) => (red, green, blue) => `\u001B[${38 + offset};2;${red};${green};${blue}m`;
+const styles$1 = {
+	modifier: {
+		reset: [0, 0],
+		bold: [1, 22],
+		dim: [2, 22],
+		italic: [3, 23],
+		underline: [4, 24],
+		overline: [53, 55],
+		inverse: [7, 27],
+		hidden: [8, 28],
+		strikethrough: [9, 29]
+	},
+	color: {
+		black: [30, 39],
+		red: [31, 39],
+		green: [32, 39],
+		yellow: [33, 39],
+		blue: [34, 39],
+		magenta: [35, 39],
+		cyan: [36, 39],
+		white: [37, 39],
+		blackBright: [90, 39],
+		gray: [90, 39],
+		grey: [90, 39],
+		redBright: [91, 39],
+		greenBright: [92, 39],
+		yellowBright: [93, 39],
+		blueBright: [94, 39],
+		magentaBright: [95, 39],
+		cyanBright: [96, 39],
+		whiteBright: [97, 39]
+	},
+	bgColor: {
+		bgBlack: [40, 49],
+		bgRed: [41, 49],
+		bgGreen: [42, 49],
+		bgYellow: [43, 49],
+		bgBlue: [44, 49],
+		bgMagenta: [45, 49],
+		bgCyan: [46, 49],
+		bgWhite: [47, 49],
+		bgBlackBright: [100, 49],
+		bgGray: [100, 49],
+		bgGrey: [100, 49],
+		bgRedBright: [101, 49],
+		bgGreenBright: [102, 49],
+		bgYellowBright: [103, 49],
+		bgBlueBright: [104, 49],
+		bgMagentaBright: [105, 49],
+		bgCyanBright: [106, 49],
+		bgWhiteBright: [107, 49]
+	}
+};
+Object.keys(styles$1.modifier);
+const foregroundColorNames = Object.keys(styles$1.color);
+const backgroundColorNames = Object.keys(styles$1.bgColor);
+[...foregroundColorNames, ...backgroundColorNames];
+function assembleStyles() {
+	const codes = /* @__PURE__ */ new Map();
+	for (const [groupName, group] of Object.entries(styles$1)) {
+		for (const [styleName, style] of Object.entries(group)) {
+			styles$1[styleName] = {
+				open: `\u001B[${style[0]}m`,
+				close: `\u001B[${style[1]}m`
+			};
+			group[styleName] = styles$1[styleName];
+			codes.set(style[0], style[1]);
+		}
+		Object.defineProperty(styles$1, groupName, {
+			value: group,
+			enumerable: false
+		});
+	}
+	Object.defineProperty(styles$1, "codes", {
+		value: codes,
+		enumerable: false
+	});
+	styles$1.color.close = "\x1B[39m";
+	styles$1.bgColor.close = "\x1B[49m";
+	styles$1.color.ansi = wrapAnsi16();
+	styles$1.color.ansi256 = wrapAnsi256();
+	styles$1.color.ansi16m = wrapAnsi16m();
+	styles$1.bgColor.ansi = wrapAnsi16(ANSI_BACKGROUND_OFFSET);
+	styles$1.bgColor.ansi256 = wrapAnsi256(ANSI_BACKGROUND_OFFSET);
+	styles$1.bgColor.ansi16m = wrapAnsi16m(ANSI_BACKGROUND_OFFSET);
+	Object.defineProperties(styles$1, {
+		rgbToAnsi256: {
+			value(red, green, blue) {
+				if (red === green && green === blue) {
+					if (red < 8) return 16;
+					if (red > 248) return 231;
+					return Math.round((red - 8) / 247 * 24) + 232;
+				}
+				return 16 + 36 * Math.round(red / 255 * 5) + 6 * Math.round(green / 255 * 5) + Math.round(blue / 255 * 5);
+			},
+			enumerable: false
+		},
+		hexToRgb: {
+			value(hex) {
+				const matches = /[a-f\d]{6}|[a-f\d]{3}/i.exec(hex.toString(16));
+				if (!matches) return [
+					0,
+					0,
+					0
+				];
+				let [colorString] = matches;
+				if (colorString.length === 3) colorString = [...colorString].map((character) => character + character).join("");
+				const integer = Number.parseInt(colorString, 16);
+				return [
+					integer >> 16 & 255,
+					integer >> 8 & 255,
+					integer & 255
+				];
+			},
+			enumerable: false
+		},
+		hexToAnsi256: {
+			value: (hex) => styles$1.rgbToAnsi256(...styles$1.hexToRgb(hex)),
+			enumerable: false
+		},
+		ansi256ToAnsi: {
+			value(code) {
+				if (code < 8) return 30 + code;
+				if (code < 16) return 90 + (code - 8);
+				let red;
+				let green;
+				let blue;
+				if (code >= 232) {
+					red = ((code - 232) * 10 + 8) / 255;
+					green = red;
+					blue = red;
+				} else {
+					code -= 16;
+					const remainder = code % 36;
+					red = Math.floor(code / 36) / 5;
+					green = Math.floor(remainder / 6) / 5;
+					blue = remainder % 6 / 5;
+				}
+				const value = Math.max(red, green, blue) * 2;
+				if (value === 0) return 30;
 				let result = 30 + (Math.round(blue) << 2 | Math.round(green) << 1 | Math.round(red));
 				if (value === 2) result += 60;
 				return result;
@@ -14365,49 +15267,6 @@ function ora(options) {
 	return new Ora(options);
 }
 //#endregion
-//#region src/cli/utils/is-ci-environment.ts
-const CI_ENVIRONMENT_VARIABLES = [
-	"GITHUB_ACTIONS",
-	"GITLAB_CI",
-	"CIRCLECI"
-];
-const CODING_AGENT_ENVIRONMENT_VARIABLES = [
-	"CLAUDECODE",
-	"CLAUDE_CODE",
-	"CURSOR_AGENT",
-	"CODEX_CI",
-	"CODEX_SANDBOX",
-	"CODEX_SANDBOX_NETWORK_DISABLED",
-	"OPENCODE",
-	"GOOSE_TERMINAL",
-	"AGENT_SESSION_ID",
-	"AMP_THREAD_ID",
-	"AGENT_THREAD_ID"
-];
-const CODING_AGENT_ENVIRONMENT_VALUE_VARIABLES = ["AGENT"];
-const CODING_AGENT_ENVIRONMENT_VALUES = { AGENT: ["amp", "goose"] };
-const isCiEnvironment = () => CI_ENVIRONMENT_VARIABLES.some((envVariable) => Boolean(process.env[envVariable])) || process.env.CI === "true";
-const isCodingAgentEnvironment = () => CODING_AGENT_ENVIRONMENT_VARIABLES.some((envVariable) => Boolean(process.env[envVariable])) || CODING_AGENT_ENVIRONMENT_VALUE_VARIABLES.some((envVariable) => CODING_AGENT_ENVIRONMENT_VALUES[envVariable].some((value) => process.env[envVariable]?.toLowerCase() === value));
-const isCiOrCodingAgentEnvironment = () => isCiEnvironment() || isCodingAgentEnvironment();
-//#endregion
-//#region src/cli/utils/is-non-interactive-environment.ts
-const NON_INTERACTIVE_ENVIRONMENT_VARIABLES = [
-	"CI",
-	"GITHUB_ACTIONS",
-	"GITLAB_CI",
-	"BUILDKITE",
-	"JENKINS_URL",
-	"TF_BUILD",
-	"CODEBUILD_BUILD_ID",
-	"TEAMCITY_VERSION",
-	"BITBUCKET_BUILD_NUMBER",
-	"CIRCLECI",
-	"TRAVIS",
-	"DRONE",
-	"GIT_DIR"
-];
-const isNonInteractiveEnvironment = () => NON_INTERACTIVE_ENVIRONMENT_VARIABLES.some((envVariable) => Boolean(process.env[envVariable])) || isCodingAgentEnvironment();
-//#endregion
 //#region src/cli/utils/is-spinner-interactive.ts
 const isSpinnerInteractive = (stream = process.stderr) => {
 	if (stream.isTTY !== true) return false;
@@ -14489,9 +15348,8 @@ const buildSpinnerProgressHandle = (text) => {
 * construction and post-scan rendering — layer wiring is its own
 * concern with its own contract.
 *
-* Same shape as `core/src/run-inspect.ts → layerInspectLive`
-* (the default for `@react-doctor/api → diagnose()`) with the
-* differences specific to the CLI path:
+* Same service shape as `@react-doctor/api → diagnose()`'s
+* `buildDiagnoseLayer`, with the differences specific to the CLI path:
 *
 * - **Config**: when the caller passes `configOverride`, the
 *   already-loaded config is provided via `Config.layerOf` instead
@@ -14521,44 +15379,89 @@ const buildRuntimeLayers = (input) => {
 	return input.oxlintConcurrency === void 0 ? baseLayers : Layer.mergeAll(baseLayers, Layer.succeed(OxlintConcurrency, input.oxlintConcurrency));
 };
 //#endregion
-//#region src/cli/utils/noop-console.ts
+//#region src/cli/utils/active-run-trace.ts
+let activeRunTrace = null;
+const setActiveRunTrace = (trace) => {
+	activeRunTrace = trace;
+};
+const getActiveRunTrace = () => activeRunTrace;
+//#endregion
+//#region src/cli/utils/to-span-attributes.ts
 /**
-* A concrete `Console.Console` whose methods are all no-ops.
+* Converts a Sentry tag map (which permits `null` to denote an absent signal)
+* into Sentry/OTel span attributes, which only accept primitives. `null` values
+* are dropped rather than coerced, so an absent signal doesn't become a
+* misleading `"null"` attribute.
+*/
+const toSpanAttributes = (tags) => {
+	const attributes = {};
+	for (const [key, value] of Object.entries(tags)) if (value !== null) attributes[key] = value;
+	return attributes;
+};
+//#endregion
+//#region src/cli/utils/with-sentry-run-span.ts
+/**
+* Clears the module-level run-scoped Sentry state — the current scanned project
+* and the active run trace. `inspect()` calls this at the start of every run and
+* again after a clean one (it's invoked once per project in a workspace scan),
+* so a prior or just-finished scan can't attach its project tags / trace to a
+* later run or to a non-scan error (e.g. inspectAction's post-loop
+* finalize/handoff steps). A thrown scan error skips the post-run reset, leaving
+* the state for the command catch to attribute and link the crash. Safe to call
+* when Sentry is off (the refs are read only when an event is built).
+*/
+const resetSentryRunState = () => {
+	setSentryProjectInfo(null);
+	setActiveRunTrace(null);
+};
+/**
+* Runs an inspect invocation inside a Sentry root span (transaction) so each
+* `react-doctor` run is a first-class trace with timing and the run snapshot as
+* attributes. The span is handed to `run` so the Effect→Sentry tracer bridge
+* can parent its spans under it.
 *
-* Used by `--silent` (provided via
-* `Effect.provideService(Console.Console, makeNoopConsole())`) and by
-* `enableJsonMode` (assigned over the relevant slots on
-* `globalThis.console` so imperative legacy callsites that aren't
-* Effect-typed also fall silent). Sourcing both from a single concrete
-* object keeps "what is a no-op console" answered in one place; the
-* earlier `new Proxy({} as Console.Console, { get: () => () => undefined })`
-* combined a cast with a Proxy to do the same thing implicitly.
+* A no-op pass-through when Sentry performance tracing is off (Sentry disabled,
+* `--no-score`, tests, or `SENTRY_TRACES_SAMPLE_RATE=0`) — `run` receives
+* `undefined` and no transaction is created, so there's no added exit latency.
 *
-* The interface mirrors Effect v4's `Console.Console` shape exactly so
-* `Effect.provideService(Console.Console, makeNoopConsole())` requires
-* no cast.
+* While the span runs, its trace context is recorded as the active run trace so
+* `reportErrorToSentry` can attach a crash thrown during the scan back to this
+* transaction's trace (errors surface in the command catch, after the span has
+* ended). `inspect()` owns clearing it (and the scanned project): it resets the
+* state right after a clean run and at the start of the next one, so the trace
+* is never attached to a non-scan error; on a thrown error the state is left in
+* place for the command catch, then the process exits.
 */
-const makeNoopConsole = () => ({
-	assert: () => {},
-	clear: () => {},
-	count: () => {},
-	countReset: () => {},
-	debug: () => {},
-	dir: () => {},
-	dirxml: () => {},
-	error: () => {},
-	group: () => {},
-	groupCollapsed: () => {},
-	groupEnd: () => {},
-	info: () => {},
-	log: () => {},
-	table: () => {},
-	time: () => {},
-	timeEnd: () => {},
-	timeLog: () => {},
-	trace: () => {},
-	warn: () => {}
-});
+const withSentryRunSpan = (run) => {
+	if (!isSentryTracingEnabled()) return run(void 0);
+	const { tags } = buildSentryScope();
+	const command = typeof tags.command === "string" ? tags.command : "inspect";
+	return Sentry.startSpan({
+		name: `react-doctor ${command}`,
+		op: "cli.inspect",
+		attributes: toSpanAttributes(tags)
+	}, (rootSpan) => {
+		const spanContext = rootSpan.spanContext();
+		setActiveRunTrace({
+			traceId: spanContext.traceId,
+			spanId: spanContext.spanId,
+			sampled: (spanContext.traceFlags & 1) === 1
+		});
+		return run(rootSpan);
+	});
+};
+/**
+* Records the scanned project (discovered in the `beforeLint` hook) for Sentry:
+* remembers it for the lazy error-capture path (`buildSentryScope` folds it into
+* exception events) and, when tracing is live, sets it as attributes on the
+* run's root span so the transaction/trace carries the project shape too.
+* Always cheap — the span attribute set is skipped when `rootSpan` is absent
+* (tracing off), and storing the info is a plain assignment.
+*/
+const recordSentryProjectContext = (projectInfo, rootSpan) => {
+	setSentryProjectInfo(projectInfo);
+	rootSpan?.setAttributes(toSpanAttributes(buildSentryProjectContext(projectInfo).tags));
+};
 //#endregion
 //#region src/cli/utils/build-no-score-message.ts
 const ENTERPRISE_CONTACT_HINT = `Want something custom to your company? Contact us at ${ENTERPRISE_CONTACT_URL}.`;
@@ -14605,8 +15508,10 @@ const compareByRulePriority = (ruleKeyA, ruleKeyB, rulePriority) => {
 	return priorityB - priorityA;
 };
 const sortRuleGroupsByImportance = (diagnosticGroups, rulePriority) => diagnosticGroups.toSorted(([ruleKeyA], [ruleKeyB]) => compareByRulePriority(ruleKeyA, ruleKeyB, rulePriority));
-const FETCH_FIX_RECIPE_LABEL = "Fetch & follow the canonical fix recipe before fixing";
-const formatFixRecipeLine = (diagnostic) => hasPublishedFixRecipe(diagnostic) ? `${FETCH_FIX_RECIPE_LABEL}: ${buildRulePromptUrl(diagnostic.plugin, diagnostic.rule)}` : null;
+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);
@@ -14737,15 +15642,17 @@ const buildVerboseSiteMap = (diagnostics) => {
 	return fileSites;
 };
 const formatSiteCountBadge = (count) => count > 1 ? `×${count}` : "";
+const formatTrailingSiteBadge = (count) => {
+	const badge = formatSiteCountBadge(count);
+	return badge.length > 0 ? ` ${highlighter.gray(badge)}` : "";
+};
 const categoryTopRuleKey = (categoryGroup) => categoryGroup.ruleGroups[0][0];
 const buildCategoryDiagnosticGroups = (diagnostics, rulePriority) => {
-	return [...groupBy(diagnostics, (diagnostic) => diagnostic.category).entries()].map(([category, categoryDiagnostics]) => {
-		return {
-			category,
-			diagnostics: categoryDiagnostics,
-			ruleGroups: sortRuleGroupsByImportance([...groupBy(categoryDiagnostics, (diagnostic) => `${diagnostic.plugin}/${diagnostic.rule}`).entries()], rulePriority)
-		};
-	}).toSorted((categoryGroupA, categoryGroupB) => {
+	return [...groupBy(diagnostics, (diagnostic) => diagnostic.category).entries()].map(([category, categoryDiagnostics]) => ({
+		category,
+		diagnostics: categoryDiagnostics,
+		ruleGroups: buildSortedRuleGroups(categoryDiagnostics, rulePriority)
+	})).toSorted((categoryGroupA, categoryGroupB) => {
 		const priorityDelta = compareByRulePriority(categoryTopRuleKey(categoryGroupA), categoryTopRuleKey(categoryGroupB), rulePriority);
 		if (priorityDelta !== 0) return priorityDelta;
 		return categoryGroupA.category.localeCompare(categoryGroupB.category);
@@ -14761,6 +15668,7 @@ const buildCompactCategoryLine = (categoryGroup) => {
 };
 const TOP_ERROR_DETAIL_INDENT = "    ";
 const pickRepresentativeDiagnostic = (ruleDiagnostics) => ruleDiagnostics.find((diagnostic) => diagnostic.line > 0) ?? ruleDiagnostics[0];
+const isErrorRuleGroup = (ruleDiagnostics) => pickRepresentativeDiagnostic(ruleDiagnostics).severity === "error";
 const FRAME_CONTEXT_REACH_LINES = 3;
 const clusterNearbyDiagnostics = (diagnostics) => {
 	const byFile = groupBy(diagnostics, (diagnostic) => diagnostic.filePath);
@@ -14792,17 +15700,17 @@ const formatClusterLocation = (cluster) => {
 	if (cluster.endLine > cluster.startLine) return `${filePath}:${cluster.startLine}-${cluster.endLine}`;
 	return `${filePath}:${cluster.startLine}`;
 };
-const buildDiagnosticClusterLines = (cluster, resolveSourceRoot) => {
+const buildDiagnosticClusterLines = (cluster, resolveSourceRoot, renderCodeFrame) => {
 	const lead = cluster.diagnostics[0];
 	const isMultiSite = cluster.diagnostics.length > 1;
 	const lines = ["", highlighter.gray(`${TOP_ERROR_DETAIL_INDENT}${formatClusterLocation(cluster)}`)];
-	const codeFrame = buildCodeFrame({
+	const codeFrame = renderCodeFrame ? buildCodeFrame({
 		filePath: lead.filePath,
 		line: cluster.startLine,
 		column: isMultiSite ? 0 : lead.column,
 		endLine: isMultiSite ? cluster.endLine : void 0,
 		rootDirectory: resolveSourceRoot(lead)
-	});
+	}) : null;
 	if (codeFrame) lines.push(indentMultilineText(boxText(codeFrame, 60), TOP_ERROR_DETAIL_INDENT));
 	const seenHints = /* @__PURE__ */ new Set();
 	for (const diagnostic of cluster.diagnostics) if (diagnostic.suppressionHint && !seenHints.has(diagnostic.suppressionHint)) {
@@ -14814,23 +15722,60 @@ const buildDiagnosticClusterLines = (cluster, resolveSourceRoot) => {
 const buildRuleDetailBlock = (ruleKey, ruleDiagnostics, resolveSourceRoot, renderEverySite) => {
 	const representative = pickRepresentativeDiagnostic(ruleDiagnostics);
 	const { severity } = representative;
-	const siteCountBadge = formatSiteCountBadge(ruleDiagnostics.length);
-	const trailingBadge = siteCountBadge.length > 0 ? ` ${highlighter.gray(siteCountBadge)}` : "";
+	const trailingBadge = formatTrailingSiteBadge(ruleDiagnostics.length);
 	const headline = colorizeBySeverity(`${representative.category}: ${representative.title ?? ruleKey}`, severity);
 	const lines = [`  ${colorizeBySeverity(severity === "error" ? "✗" : "⚠", severity)} ${headline}${trailingBadge}`];
 	if (!renderEverySite) for (const explanationLine of wrapTextToWidth(representative.message, 60, { breakLongWords: false })) lines.push(`${TOP_ERROR_DETAIL_INDENT}${explanationLine}`);
 	if (representative.help) for (const fixLine of wrapTextToWidth(`→ ${representative.help}`, 60, { breakLongWords: false })) lines.push(highlighter.dim(`${TOP_ERROR_DETAIL_INDENT}${fixLine}`));
+	const renderCodeFrame = severity === "error";
 	const sites = renderEverySite ? ruleDiagnostics : [representative];
-	for (const cluster of clusterNearbyDiagnostics(sites)) lines.push(...buildDiagnosticClusterLines(cluster, resolveSourceRoot));
+	for (const cluster of clusterNearbyDiagnostics(sites)) lines.push(...buildDiagnosticClusterLines(cluster, resolveSourceRoot, renderCodeFrame));
+	return lines;
+};
+const WARNING_DETAIL_INDENT = "      ";
+const computeRuleNameColumnWidth = (ruleKeys) => ruleKeys.reduce((widest, ruleKey) => Math.max(widest, ruleKey.length), 36);
+const padRuleNameToColumn = (ruleName, columnWidth) => ruleName.length >= columnWidth ? ruleName : ruleName + " ".repeat(columnWidth - ruleName.length);
+const buildWarningHeaderLine = (ruleKey, siteCount, ruleNameColumnWidth) => {
+	const ruleName = formatSiteCountBadge(siteCount).length > 0 ? padRuleNameToColumn(ruleKey, ruleNameColumnWidth) : ruleKey;
+	return `  ${highlighter.warn("⚠")} ${ruleName}${formatTrailingSiteBadge(siteCount)}`;
+};
+const buildWarningRuleBlock = (ruleKey, ruleDiagnostics, ruleNameColumnWidth, isAgentEnvironment) => {
+	const representative = pickRepresentativeDiagnostic(ruleDiagnostics);
+	const lines = [buildWarningHeaderLine(ruleKey, ruleDiagnostics.length, ruleNameColumnWidth)];
+	if (!isAgentEnvironment) {
+		const learnMoreLine = formatLearnMoreLine(representative);
+		if (learnMoreLine) lines.push(`${WARNING_DETAIL_INDENT}${highlighter.info(learnMoreLine)}`);
+	}
+	lines.push(highlighter.gray(indentMultilineText(representative.message, WARNING_DETAIL_INDENT)));
+	if (representative.help) lines.push(highlighter.gray(indentMultilineText(`→ ${representative.help}`, WARNING_DETAIL_INDENT)));
+	if (isAgentEnvironment) {
+		const fixRecipeLine = formatFixRecipeLine(representative);
+		if (fixRecipeLine) lines.push(highlighter.gray(`${WARNING_DETAIL_INDENT}${fixRecipeLine}`));
+	}
+	for (const [filePath, sites] of buildVerboseSiteMap(ruleDiagnostics)) {
+		if (sites.length === 0) {
+			lines.push(highlighter.gray(`${WARNING_DETAIL_INDENT}${filePath}`));
+			continue;
+		}
+		for (const site of sites) {
+			lines.push(highlighter.gray(`${WARNING_DETAIL_INDENT}${filePath}:${site.line}`));
+			if (site.suppressionHint) lines.push(highlighter.gray(`${WARNING_DETAIL_INDENT}  ↳ ${site.suppressionHint}`));
+		}
+	}
 	return lines;
 };
-const selectTopErrorRuleGroups = (diagnostics, limit, rulePriority) => {
-	return sortRuleGroupsByImportance([...groupBy(diagnostics.filter((diagnostic) => diagnostic.severity === "error"), (diagnostic) => `${diagnostic.plugin}/${diagnostic.rule}`).entries()], rulePriority).slice(0, limit);
+const selectErrorRuleGroups = (diagnostics, rulePriority) => buildSortedRuleGroups(diagnostics.filter((diagnostic) => diagnostic.severity === "error"), rulePriority);
+const selectTopErrorRuleGroups = (diagnostics, limit, rulePriority) => selectErrorRuleGroups(diagnostics, rulePriority).slice(0, limit);
+const buildMoreRulesLine = (hiddenRuleCount, severityNoun, accent) => {
+	const ruleNoun = hiddenRuleCount === 1 ? "rule" : "rules";
+	return `  ${highlighter.bold(accent(`+${hiddenRuleCount} more ${ruleNoun}`))} ${highlighter.dim("— run")} ${highlighter.bold(highlighter.info("--verbose"))} ${highlighter.dim(`to view the rest of the ${severityNoun} and details about each`)}`;
 };
 const getTopErrorRuleKeys = (diagnostics, limit, rulePriority) => new Set(selectTopErrorRuleGroups(diagnostics, limit, rulePriority).map(([ruleKey]) => ruleKey));
 const buildTopErrorsLines = (diagnostics, resolveSourceRoot, rulePriority) => {
-	const topRuleGroups = selectTopErrorRuleGroups(diagnostics, 3, rulePriority);
+	const errorRuleGroups = selectErrorRuleGroups(diagnostics, rulePriority);
+	const topRuleGroups = errorRuleGroups.slice(0, 3);
 	if (topRuleGroups.length === 0) return [];
+	const hiddenRuleCount = errorRuleGroups.length - topRuleGroups.length;
 	const lines = [
 		highlighter.dim(`  ${"─".repeat(60)}`),
 		`  ${highlighter.bold(`Top ${topRuleGroups.length} ${topRuleGroups.length === 1 ? "error" : "errors"} you should fix`)}`,
@@ -14840,6 +15785,23 @@ const buildTopErrorsLines = (diagnostics, resolveSourceRoot, rulePriority) => {
 		lines.push(...buildRuleDetailBlock(ruleKey, ruleDiagnostics, resolveSourceRoot, false));
 		lines.push("");
 	}
+	if (hiddenRuleCount > 0) lines.push(buildMoreRulesLine(hiddenRuleCount, "errors", highlighter.error));
+	return lines;
+};
+const buildWarningsListLines = (diagnostics, rulePriority) => {
+	const warningDiagnostics = diagnostics.filter((diagnostic) => diagnostic.severity === "warning");
+	if (warningDiagnostics.length === 0) return [];
+	const sortedRuleGroups = buildSortedRuleGroups(warningDiagnostics, rulePriority);
+	const shownRuleGroups = sortedRuleGroups.slice(0, 10);
+	const hiddenRuleCount = sortedRuleGroups.length - shownRuleGroups.length;
+	const ruleNameColumnWidth = computeRuleNameColumnWidth(shownRuleGroups.map(([ruleKey]) => ruleKey));
+	const lines = [
+		highlighter.dim(`  ${"─".repeat(60)}`),
+		`  ${highlighter.bold(`${warningDiagnostics.length} ${warningDiagnostics.length === 1 ? "warning" : "warnings"}`)}`,
+		""
+	];
+	for (const [ruleKey, ruleDiagnostics] of shownRuleGroups) lines.push(buildWarningHeaderLine(ruleKey, ruleDiagnostics.length, ruleNameColumnWidth));
+	if (hiddenRuleCount > 0) lines.push(buildMoreRulesLine(hiddenRuleCount, "warnings", highlighter.warn));
 	return lines;
 };
 const buildCategoryBreakdownLines = (diagnostics, rulePriority) => buildCategoryDiagnosticGroups(diagnostics, rulePriority).map(buildCompactCategoryLine);
@@ -14866,12 +15828,18 @@ const buildCountsSummaryLines = (diagnostics) => {
 * single Effect.forEach over Console.log so failures or fiber
 * interruption produce predictable partial output.
 */
-const printDiagnostics = (diagnostics, isVerbose, sourceRoot, rulePriority) => Effect.gen(function* () {
+const printDiagnostics = (diagnostics, isVerbose, sourceRoot, rulePriority, isAgentEnvironment = false) => Effect.gen(function* () {
 	const resolveSourceRoot = typeof sourceRoot === "function" ? sourceRoot : () => sourceRoot;
 	let detailLines;
 	if (!isVerbose) detailLines = buildTopErrorsLines(diagnostics, resolveSourceRoot, rulePriority);
-	else detailLines = sortRuleGroupsByImportance([...groupBy(diagnostics, (diagnostic) => `${diagnostic.plugin}/${diagnostic.rule}`).entries()], rulePriority).flatMap(([ruleKey, ruleDiagnostics]) => [...buildRuleDetailBlock(ruleKey, ruleDiagnostics, resolveSourceRoot, true), ""]);
-	const lines = joinSections(buildCategoryBreakdownLines(diagnostics, rulePriority), buildCountsSummaryLines(diagnostics), detailLines);
+	else {
+		const sortedRuleGroups = buildSortedRuleGroups(diagnostics, rulePriority);
+		const warningRuleNameColumnWidth = computeRuleNameColumnWidth(sortedRuleGroups.filter(([, ruleDiagnostics]) => !isErrorRuleGroup(ruleDiagnostics)).map(([ruleKey]) => ruleKey));
+		detailLines = sortedRuleGroups.flatMap(([ruleKey, ruleDiagnostics]) => {
+			return [...isErrorRuleGroup(ruleDiagnostics) ? buildRuleDetailBlock(ruleKey, ruleDiagnostics, resolveSourceRoot, true) : buildWarningRuleBlock(ruleKey, ruleDiagnostics, warningRuleNameColumnWidth, isAgentEnvironment), ""];
+		});
+	}
+	const lines = joinSections(buildCategoryBreakdownLines(diagnostics, rulePriority), buildCountsSummaryLines(diagnostics), detailLines, isVerbose ? [] : buildWarningsListLines(diagnostics, rulePriority));
 	for (const line of lines) yield* Console.log(line);
 });
 const formatElapsedTime = (elapsedMilliseconds) => {
@@ -14921,10 +15889,6 @@ const colorizeByScore = (text, score) => {
 	return highlighter.error(text);
 };
 //#endregion
-//#region src/cli/utils/constants.ts
-const STAGED_FILES_TEMP_DIR_PREFIX = "react-doctor-staged-";
-const INTERNAL_ERROR_JSON_FALLBACK = "{\"schemaVersion\":1,\"ok\":false,\"error\":{\"message\":\"Internal error\",\"name\":\"Error\",\"chain\":[]}}\n";
-//#endregion
 //#region src/cli/utils/render-score-header.ts
 const RAINBOW_HUE_SHIFT_PER_FRAME = 9;
 const RAINBOW_GRADIENT_WIDTH = 80;
@@ -15117,8 +16081,7 @@ const printNoScoreHeader = (noScoreMessage) => Effect.gen(function* () {
 const writeDiagnosticsDirectory = (diagnostics) => {
 	const outputDirectory = join(tmpdir(), `react-doctor-${randomUUID()}`);
 	mkdirSync(outputDirectory, { recursive: true });
-	const sortedRuleGroups = sortRuleGroupsByImportance([...groupBy(diagnostics, (diagnostic) => `${diagnostic.plugin}/${diagnostic.rule}`).entries()]);
-	for (const [ruleKey, ruleDiagnostics] of sortedRuleGroups) writeFileSync(join(outputDirectory, ruleKey.replace(/\//g, "--") + ".txt"), formatRuleSummary(ruleKey, ruleDiagnostics));
+	for (const [ruleKey, ruleDiagnostics] of buildSortedRuleGroups(diagnostics)) writeFileSync(join(outputDirectory, ruleKey.replace(/\//g, "--") + ".txt"), formatRuleSummary(ruleKey, ruleDiagnostics));
 	writeFileSync(join(outputDirectory, "diagnostics.json"), JSON.stringify(diagnostics));
 	return outputDirectory;
 };
@@ -15138,7 +16101,14 @@ const buildShareUrl = (diagnostics, scoreResult, projectName) => {
 };
 const printVerboseTip = (diagnostics, isVerbose) => Effect.gen(function* () {
 	if (isVerbose || diagnostics.length === 0) return;
-	yield* Console.log(highlighter.dim(`  Tip: Run ${highlighter.info("npx react-doctor@latest --verbose")} to list every issue`));
+	const command = highlighter.info("npx react-doctor@latest --verbose");
+	const message = diagnostics.some((diagnostic) => diagnostic.severity === "warning") ? `Run ${command} to see each warning explained with its fix` : `Run ${command} to see each issue explained with its fix`;
+	yield* Console.log(highlighter.dim(`  Tip: ${message}`));
+});
+const printDocsNote = () => Effect.gen(function* () {
+	yield* Console.log("");
+	yield* Console.log(`  ${highlighter.bold("Docs:")} ${highlighter.info(DOCS_URL)}`);
+	yield* Console.log(highlighter.dim("  Set up CI/CD, suppress rules with a config file, and scan diffs or PRs."));
 });
 const printSummary = (input) => Effect.gen(function* () {
 	if (input.scoreResult) {
@@ -15309,9 +16279,6 @@ const resolveOxlintNodeEffect = (isLintEnabled, isQuiet) => Effect.gen(function*
 });
 const resolveOxlintNode = (isLintEnabled, isQuiet) => Effect.runPromise(resolveOxlintNodeEffect(isLintEnabled, isQuiet).pipe(Effect.provide(NodeResolver.layerNode)));
 //#endregion
-//#region src/cli/utils/version.ts
-const VERSION = "0.2.14-dev.bb15252";
-//#endregion
 //#region src/inspect.ts
 const silentConsole = makeNoopConsole();
 const runConsole = (effect) => {
@@ -15336,7 +16303,7 @@ const mergeInspectOptions = (inputOptions, userConfig) => ({
 	customRulesOnly: userConfig?.customRulesOnly ?? false,
 	share: userConfig?.share ?? true,
 	respectInlineDisables: inputOptions.respectInlineDisables ?? userConfig?.respectInlineDisables ?? true,
-	warnings: inputOptions.warnings ?? userConfig?.warnings ?? false,
+	warnings: inputOptions.warnings ?? userConfig?.warnings ?? true,
 	adoptExistingLintConfig: userConfig?.adoptExistingLintConfig ?? true,
 	ignoredTags: buildIgnoredTags(userConfig),
 	outputSurface: inputOptions.outputSurface ?? "cli",
@@ -15345,6 +16312,7 @@ const mergeInspectOptions = (inputOptions, userConfig) => ({
 });
 const inspect = async (directory, inputOptions = {}) => {
 	const startTime = performance.now();
+	resetSentryRunState();
 	const hasConfigOverride = inputOptions.configOverride !== void 0;
 	let scanDirectory;
 	let userConfig;
@@ -15354,7 +16322,7 @@ const inspect = async (directory, inputOptions = {}) => {
 		userConfig = inputOptions.configOverride ?? null;
 		configSourceDirectory = null;
 	} else {
-		const scanTarget = resolveScanTarget(directory);
+		const scanTarget = await resolveScanTarget(directory);
 		scanDirectory = scanTarget.resolvedDirectory;
 		userConfig = scanTarget.userConfig;
 		configSourceDirectory = scanTarget.configSourceDirectory;
@@ -15363,12 +16331,14 @@ const inspect = async (directory, inputOptions = {}) => {
 	const wasSpinnerSilent = isSpinnerSilent();
 	if (options.silent) setSpinnerSilent(true);
 	try {
-		return await runInspectWithRuntime(scanDirectory, options, userConfig, hasConfigOverride, configSourceDirectory, startTime);
+		const result = await withSentryRunSpan((rootSentrySpan) => runInspectWithRuntime(scanDirectory, options, userConfig, hasConfigOverride, configSourceDirectory, startTime, rootSentrySpan));
+		resetSentryRunState();
+		return result;
 	} finally {
 		if (options.silent) setSpinnerSilent(wasSpinnerSilent);
 	}
 };
-const runInspectWithRuntime = async (directory, options, userConfig, hasConfigOverride, configSourceDirectory, startTime) => {
+const runInspectWithRuntime = async (directory, options, userConfig, hasConfigOverride, configSourceDirectory, startTime, rootSentrySpan) => {
 	const isDiffMode = options.includePaths.length > 0;
 	const resolvedNodeBinaryPath = await resolveOxlintNode(options.lint, options.scoreOnly || options.silent);
 	const lintBindingMissing = options.lint && !resolvedNodeBinaryPath;
@@ -15399,6 +16369,7 @@ const runInspectWithRuntime = async (directory, options, userConfig, hasConfigOv
 		resolveLocalGithubViewerPermission: !options.noScore,
 		suppressScanSummary: options.suppressRendering
 	}, { beforeLint: (projectInfo, lintIncludePaths) => Effect.gen(function* () {
+		recordSentryProjectContext(projectInfo, rootSentrySpan);
 		if (options.scoreOnly || options.suppressRendering) return;
 		const lintSourceFileCount = lintIncludePaths?.length ?? projectInfo.sourceFileCount;
 		yield* printProjectDetection({
@@ -15409,7 +16380,7 @@ const runInspectWithRuntime = async (directory, options, userConfig, hasConfigOv
 			lintSourceFileCount
 		});
 	}) });
-	const programWithLayers = options.silent ? program.pipe(Effect.provide(layers), Effect.provideService(Console.Console, silentConsole), Effect.provide(layerOtlp)) : program.pipe(Effect.provide(layers), Effect.provide(layerOtlp));
+	const programWithLayers = applyObservability(options.silent ? program.pipe(Effect.provide(layers), Effect.provideService(Console.Console, silentConsole)) : program.pipe(Effect.provide(layers)), rootSentrySpan);
 	const output = await Effect.runPromise(restoreLegacyThrow(programWithLayers));
 	const didLintFail = lintBindingMissing || output.didLintFail;
 	const lintFailureReason = lintBindingMissing ? `oxlint native binding not found for Node ${process.version}; expected one matching ${OXLINT_NODE_REQUIREMENT}` : output.lintFailureReason;
@@ -15438,15 +16409,15 @@ const runInspectWithRuntime = async (directory, options, userConfig, hasConfigOv
 };
 const finalizeAndRender = (input) => Effect.gen(function* () {
 	const { options, elapsedMilliseconds, diagnostics, score, project, userConfig, didLintFail, lintFailureReason, lintPartialFailures, didDeadCodeFail, deadCodeFailureReason, directory, scannedFileCount, scannedFilePaths, scanElapsedMilliseconds } = input;
-	const skippedChecks = [];
-	if (didLintFail) skippedChecks.push("lint");
-	if (didDeadCodeFail) skippedChecks.push("dead-code");
+	const { skippedChecks, skippedCheckReasons } = buildSkippedChecks({
+		didLintFail,
+		lintFailureReason,
+		lintPartialFailures,
+		didDeadCodeFail,
+		deadCodeFailureReason
+	});
 	const hasSkippedChecks = skippedChecks.length > 0;
 	const noScoreMessage = buildNoScoreMessage(options.noScore);
-	const skippedCheckReasons = {};
-	if (didLintFail && lintFailureReason !== null) skippedCheckReasons.lint = lintFailureReason;
-	else if (lintPartialFailures.length > 0) skippedCheckReasons["lint:partial"] = lintPartialFailures.join("; ");
-	if (didDeadCodeFail && deadCodeFailureReason !== null) skippedCheckReasons["dead-code"] = deadCodeFailureReason;
 	const buildResult = () => ({
 		diagnostics: [...diagnostics],
 		score,
@@ -15482,7 +16453,7 @@ const finalizeAndRender = (input) => Effect.gen(function* () {
 		return buildResult();
 	}
 	yield* Console.log("");
-	yield* printDiagnostics([...surfaceDiagnostics], options.verbose, directory, buildRulePriorityMap([score]));
+	yield* printDiagnostics([...surfaceDiagnostics], options.verbose, directory, buildRulePriorityMap([score]), isCodingAgentEnvironment());
 	if (options.isNonInteractiveEnvironment && options.outputSurface !== "prComment") yield* printAgentGuidance();
 	if (demotedDiagnosticCount > 0) {
 		yield* Console.log(highlighter.gray(`  ${demotedDiagnosticCount} demoted from the ${options.outputSurface} surface (e.g. design cleanup) — run \`npx react-doctor@latest .\` locally for the full list.`));
@@ -15507,6 +16478,7 @@ const finalizeAndRender = (input) => Effect.gen(function* () {
 		yield* Console.warn(highlighter.warn(`  Note: ${skippedLabel} checks failed — score may be incomplete.`));
 	}
 	yield* printVerboseTip([...surfaceDiagnostics], options.verbose);
+	yield* printDocsNote();
 	return buildResult();
 });
 //#endregion
@@ -15551,7 +16523,7 @@ const getErrorReportContext = () => ({
 	isOtlpAuthHeaderConfigured: Boolean(process.env[OTLP_AUTH_HEADER_ENVIRONMENT_VARIABLE])
 });
 const formatConfiguredState = (isConfigured) => isConfigured ? "yes" : "no";
-const buildErrorIssueBody = (error, context) => {
+const buildErrorIssueBody = (error, context, sentryEventId) => {
 	const formattedError = formatErrorForReport(error) || "(empty error)";
 	const isOtlpExporterEnabled = context.isOtlpEndpointConfigured && context.isOtlpAuthHeaderConfigured;
 	return [
@@ -15568,6 +16540,7 @@ const buildErrorIssueBody = (error, context) => {
 		`- platform: ${context.platform} ${context.architecture}`,
 		`- cwd: ${context.cwd}`,
 		`- command: ${context.command}`,
+		...sentryEventId ? [`- Sentry reference: ${sentryEventId}`] : [],
 		"",
 		"## OpenTelemetry",
 		"",
@@ -15581,12 +16554,12 @@ const buildErrorIssueBody = (error, context) => {
 		"Please add reproduction steps and any relevant repository details."
 	].join("\n");
 };
-const buildErrorIssueUrl = (error) => {
+const buildErrorIssueUrl = (error, sentryEventId) => {
 	const formattedError = formatSingleLine(formatErrorForReport(error));
 	const issueUrl = new URL(`${CANONICAL_GITHUB_URL}/issues/new`);
 	issueUrl.searchParams.set("title", formattedError ? `CLI error: ${formattedError}` : "CLI error");
 	issueUrl.searchParams.set("labels", "bug");
-	issueUrl.searchParams.set("body", buildErrorIssueBody(error, getErrorReportContext()));
+	issueUrl.searchParams.set("body", buildErrorIssueBody(error, getErrorReportContext(), sentryEventId));
 	return issueUrl.toString();
 };
 /**
@@ -15596,10 +16569,12 @@ const buildErrorIssueUrl = (error) => {
 * red-highlighted (matches the historical `consoleLogger.error`
 * contract) so the user sees a clearly distinguished error block.
 */
-const handleErrorEffect = (error) => Effect.gen(function* () {
+const handleErrorEffect = (error, sentryEventId) => Effect.gen(function* () {
 	yield* Console.error("");
 	yield* Console.error(highlighter.error("Something went wrong. Please check the error below for more details."));
-	yield* Console.error(highlighter.error(`If the problem persists, please open this prefilled issue: ${buildErrorIssueUrl(error)}`));
+	yield* Console.error(highlighter.error(`If the problem persists, please open this prefilled issue: ${buildErrorIssueUrl(error, sentryEventId)}`));
+	yield* Console.error(highlighter.error(`You can also ask for help in Discord: ${CANONICAL_DISCORD_URL}`));
+	if (sentryEventId) yield* Console.error(highlighter.error(`Reference (mention this when reporting): ${sentryEventId}`));
 	yield* Console.error("");
 	yield* Console.error(highlighter.error(formatErrorForReport(error)));
 	yield* Console.error("");
@@ -15609,15 +16584,15 @@ const handleErrorEffect = (error) => Effect.gen(function* () {
 * aren't yet Effect-typed). Bridges via `Effect.runSync` so the
 * underlying Console writes happen exactly like the Effect path.
 */
-const handleError = (error, options = { shouldExit: true }) => {
-	Effect.runSync(handleErrorEffect(error));
+const handleError = (error, options = {}) => {
+	Effect.runSync(handleErrorEffect(error, options.sentryEventId));
 	if (options.shouldExit !== false) process.exit(1);
 	process.exitCode = 1;
 };
 //#endregion
 //#region src/cli/utils/build-handoff-payload.ts
 const buildHandoffPayload = (input) => {
-	const topGroups = sortRuleGroupsByImportance([...groupBy([...input.diagnostics], (diagnostic) => `${diagnostic.plugin}/${diagnostic.rule}`)]).slice(0, 3);
+	const topGroups = buildSortedRuleGroups(input.diagnostics).slice(0, 3);
 	let diagnosticsDirectory = null;
 	try {
 		diagnosticsDirectory = writeDiagnosticsDirectory([...input.diagnostics]);
@@ -15860,7 +16835,7 @@ const CURSOR_HOOKS_RELATIVE_PATH = ".cursor/hooks.json";
 const CURSOR_HOOK_RELATIVE_PATH = ".cursor/hooks/react-doctor.sh";
 const CURSOR_HOOK_MATCHER = "Write|Edit|MultiEdit|ApplyPatch";
 const CURSOR_HOOKS_SCHEMA_VERSION = 1;
-const JSON_INDENT_SPACES = 2;
+const JSON_INDENT_SPACES$1 = 2;
 const isSupportedAgent = (agent) => agent === CLAUDE_AGENT || agent === CURSOR_AGENT;
 const readJsonFile = (filePath, fallback) => {
 	if (!existsSync(filePath)) return fallback;
@@ -15870,7 +16845,7 @@ const readJsonFile = (filePath, fallback) => {
 };
 const writeJsonFile = (filePath, value) => {
 	mkdirSync(path.dirname(filePath), { recursive: true });
-	writeFileSync(filePath, `${JSON.stringify(value, null, JSON_INDENT_SPACES)}\n`);
+	writeFileSync(filePath, `${JSON.stringify(value, null, JSON_INDENT_SPACES$1)}\n`);
 };
 const writeHookScript = (filePath) => {
 	mkdirSync(path.dirname(filePath), { recursive: true });
@@ -16636,6 +17611,29 @@ const getSkillSourceDirectory = () => {
 	const distDirectory = path.dirname(fileURLToPath(import.meta.url));
 	return path.join(distDirectory, "skills", SKILL_NAME);
 };
+const findBundledSiblingSkills = (primarySkillDir) => {
+	const skillsParent = path.dirname(primarySkillDir);
+	if (!existsSync(skillsParent)) return [];
+	const resolvedPrimary = path.resolve(primarySkillDir);
+	return readdirSync(skillsParent, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => ({
+		name: entry.name,
+		source: path.join(skillsParent, entry.name)
+	})).filter((sibling) => path.resolve(sibling.source) !== resolvedPrimary && existsSync(path.join(sibling.source, SKILL_MANIFEST_FILE)));
+};
+const installBundledSiblingSkills = async (primarySkillDir, agents, projectRoot) => {
+	const installedSkillNames = [];
+	for (const sibling of findBundledSiblingSkills(primarySkillDir)) {
+		const result = await installSkillsFromSource({
+			source: sibling.source,
+			agents: [...agents],
+			cwd: projectRoot,
+			mode: "copy"
+		});
+		if (result.failed.length > 0) throw new Error(result.failed.map((failure) => `${getSkillAgentConfig(failure.agent).displayName}: ${failure.error}`).join("\n"));
+		if (result.skills.length > 0) installedSkillNames.push(sibling.name);
+	}
+	return installedSkillNames;
+};
 const canInstallNativeAgentHooks = (agents) => agents.some((agent) => agent === "claude-code" || agent === "cursor");
 const buildWorkflowContent = () => [
 	"name: React Doctor",
@@ -16742,6 +17740,7 @@ const runInstallReactDoctor = async (options = {}) => {
 		cliLogger.log(`Dry run — would install ${SKILL_NAME} skill for:`);
 		for (const agent of selectedAgents) cliLogger.dim(`  - ${getSkillAgentConfig(agent).displayName}`);
 		cliLogger.dim(`  Source: ${sourceDir}`);
+		for (const sibling of findBundledSiblingSkills(sourceDir)) cliLogger.dim(`  Also installs skill: ${sibling.name}`);
 		cliLogger.dim("  Package script: doctor (or react-doctor if doctor exists)");
 		cliLogger.dim("  Dev dependency: react-doctor");
 		if (shouldInstallGitHook) cliLogger.dim(`  Git hook: ${gitHookPath}`);
@@ -16764,6 +17763,12 @@ const runInstallReactDoctor = async (options = {}) => {
 		installSpinner.fail(`Failed to install ${SKILL_NAME} skill.`);
 		throw error;
 	}
+	try {
+		const installedSiblingSkills = await installBundledSiblingSkills(sourceDir, selectedAgents, projectRoot);
+		if (installedSiblingSkills.length > 0) cliLogger.dim(`  Also installed the ${installedSiblingSkills.join(", ")} skill.`);
+	} catch {
+		cliLogger.dim("  Skipped bundled sibling skills (install error).");
+	}
 	await installReactDoctorPackageSetup(projectRoot, options.installDependencyRunner);
 	if (shouldInstallGitHook && gitHookTarget !== null && gitHookTarget !== void 0) {
 		const hookSpinner = spinner("Installing React Doctor pre-commit hook...").start();
@@ -16917,107 +17922,100 @@ const handoffToAgent = async (input) => {
 		],
 		initial: 0
 	}, { onCancel: () => true });
-	if (handoffTarget === void 0 || handoffTarget === SKIP_CHOICE) return;
-	const payload = buildHandoffPayload({
-		diagnostics: input.diagnostics,
-		projectName: input.projectName
-	});
-	if (handoffTarget === PRINT_CHOICE) {
-		printPayload(payload);
-		return;
-	}
-	if (handoffTarget === CLIPBOARD_CHOICE) {
-		if (await copyToClipboard(payload)) cliLogger.log("Copied the prompt to your clipboard.");
-		else printPayload(payload);
-		return;
-	}
-	const agentId = handoffTarget;
-	const displayName = getSkillAgentConfig(agentId).displayName;
-	const skillSpinner = spinner(`Installing the /react-doctor skill for ${displayName}...`).start();
-	try {
-		if (await installReactDoctorSkillForAgent(agentId, input.rootDirectory)) skillSpinner.succeed(`Installed the /react-doctor skill for ${displayName}.`);
-		else skillSpinner.stop();
-	} catch {
-		skillSpinner.stop();
-	}
-	cliLogger.log(highlighter.dim(`Handing off to ${displayName}...`));
-	try {
-		await launchCliAgent(agentId, payload, input.rootDirectory);
-	} catch {
-		cliLogger.warn(`Couldn't launch ${CLI_AGENT_BINARIES[agentId]}. Here's the prompt instead:`);
-		printPayload(payload);
-	}
-};
-//#endregion
-//#region src/cli/utils/json-mode.ts
-let context = null;
-/**
-* JSON mode writes the report payload to stdout; any incidental log
-* line printed by an Effect program would corrupt the JSON. Effect's
-* `Console` module resolves to `globalThis.console` by default (see
-* `effect/internal/effect.ts` → `ConsoleRef`), so copying the methods
-* from `makeNoopConsole()` onto the global is enough to silence every
-* `yield* Console.log(...)` and `cliLogger.*` call sourced from
-* react-doctor or its services.
-*
-* We use the same `makeNoopConsole()` source as the `--silent` path
-* (which provides the Effect Console via
-* `Effect.provideService(Console.Console, makeNoopConsole())`) — one
-* canonical "no-op console" definition shared by the two silent
-* mechanisms. The two routes still differ in how they install the
-* noop: silent mode swaps the Effect Console reference inside the
-* program; JSON mode patches the global because the surrounding CLI
-* command body is still imperative. Both will collapse into the
-* Effect-typed route once the command body finishes its migration.
-*
-* JSON mode is one-shot per CLI invocation, so we never restore.
-*/
-const installSilentConsole = () => {
-	const noopConsole = makeNoopConsole();
-	const target = globalThis.console;
-	const source = noopConsole;
-	for (const key of [
-		"log",
-		"error",
-		"warn",
-		"info",
-		"debug",
-		"trace"
-	]) target[key] = source[key];
-};
-const enableJsonMode = ({ compact, directory }) => {
-	context = {
-		compact,
-		directory,
-		startTime: performance.now(),
-		mode: "full"
-	};
-	installSilentConsole();
-};
-const isJsonModeActive = () => context !== null;
-const setJsonReportDirectory = (directory) => {
-	if (context) context.directory = directory;
-};
-const setJsonReportMode = (mode) => {
-	if (context) context.mode = mode;
-};
-const writeJsonReport = (report) => {
-	const serialized = context?.compact ? JSON.stringify(report) : JSON.stringify(report, null, 2);
-	process.stdout.write(`${serialized}\n`);
+	if (handoffTarget === void 0 || handoffTarget === SKIP_CHOICE) return;
+	const payload = buildHandoffPayload({
+		diagnostics: input.diagnostics,
+		projectName: input.projectName
+	});
+	if (handoffTarget === PRINT_CHOICE) {
+		printPayload(payload);
+		return;
+	}
+	if (handoffTarget === CLIPBOARD_CHOICE) {
+		if (await copyToClipboard(payload)) cliLogger.log("Copied the prompt to your clipboard.");
+		else printPayload(payload);
+		return;
+	}
+	const agentId = handoffTarget;
+	const displayName = getSkillAgentConfig(agentId).displayName;
+	const skillSpinner = spinner(`Installing the /react-doctor skill for ${displayName}...`).start();
+	try {
+		if (await installReactDoctorSkillForAgent(agentId, input.rootDirectory)) skillSpinner.succeed(`Installed the /react-doctor skill for ${displayName}.`);
+		else skillSpinner.stop();
+	} catch {
+		skillSpinner.stop();
+	}
+	cliLogger.log(highlighter.dim(`Handing off to ${displayName}...`));
+	try {
+		await launchCliAgent(agentId, payload, input.rootDirectory);
+	} catch {
+		cliLogger.warn(`Couldn't launch ${CLI_AGENT_BINARIES[agentId]}. Here's the prompt instead:`);
+		printPayload(payload);
+	}
 };
-const writeJsonErrorReport = (error) => {
-	if (!context) return;
+//#endregion
+//#region src/cli/utils/read-object-file.ts
+/**
+* Reads a JSON / JSONC file as a plain object, or `null` when it is missing,
+* unparseable, or not an object. JSON5 parsing tolerates comments and
+* trailing commas so hand-edited config files round-trip.
+*/
+const readObjectFile = (filePath) => {
 	try {
-		writeJsonReport(buildJsonReportError({
-			version: VERSION,
-			directory: context.directory,
-			error,
-			elapsedMilliseconds: performance.now() - context.startTime,
-			mode: context.mode
-		}));
+		const parsed = parseJSON5(readFileSync(filePath, "utf-8"));
+		return isPlainObject(parsed) ? parsed : null;
 	} catch {
-		process.stdout.write(INTERNAL_ERROR_JSON_FALLBACK);
+		return null;
+	}
+};
+//#endregion
+//#region src/cli/utils/serialize-ts-object-literal.ts
+const SAFE_IDENTIFIER_PATTERN = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const INDENT_UNIT = "  ";
+const serializeKey = (key) => SAFE_IDENTIFIER_PATTERN.test(key) ? key : JSON.stringify(key);
+/**
+* Serializes a JSON-compatible value as an idiomatic TypeScript literal:
+* identifier-shaped object keys stay unquoted, two-space indented, no blank
+* lines. Intended for JSON-sourced config values (string / number / boolean /
+* null / array / plain object); any other type falls back to its JSON form.
+*/
+const serializeTsObjectLiteral = (value, depth = 0) => {
+	const indent = INDENT_UNIT.repeat(depth);
+	const childIndent = INDENT_UNIT.repeat(depth + 1);
+	if (Array.isArray(value)) {
+		if (value.length === 0) return "[]";
+		return `[\n${value.map((item) => `${childIndent}${serializeTsObjectLiteral(item, depth + 1)}`).join(",\n")}\n${indent}]`;
+	}
+	if (isPlainObject(value)) {
+		const keys = Object.keys(value);
+		if (keys.length === 0) return "{}";
+		return `{\n${keys.map((key) => `${childIndent}${serializeKey(key)}: ${serializeTsObjectLiteral(value[key], depth + 1)}`).join(",\n")}\n${indent}}`;
 	}
+	return JSON.stringify(value);
+};
+//#endregion
+//#region src/cli/utils/migrate-legacy-config.ts
+const MIGRATED_CONFIG_FILENAME = "doctor.config.ts";
+/**
+* Renames a pre-migration `react-doctor.config.json` to a typed
+* `doctor.config.ts`, preserving the user's settings as the default export.
+* `$schema` is dropped — the `ReactDoctorConfig` type supersedes it for
+* editor autocomplete. Returns the new file's absolute path, or `null` when
+* the legacy file can't be parsed as an object (left untouched so the user
+* can resolve it by hand).
+*/
+const migrateLegacyConfig = (legacy) => {
+	const parsed = readObjectFile(legacy.legacyFilePath);
+	if (!parsed) return null;
+	const config = { ...parsed };
+	delete config.$schema;
+	const targetPath = path.join(legacy.directory, MIGRATED_CONFIG_FILENAME);
+	writeFileSync(targetPath, `import type { ReactDoctorConfig } from "react-doctor/api";
+
+export default ${serializeTsObjectLiteral(config)} satisfies ReactDoctorConfig;
+`);
+	rmSync(legacy.legacyFilePath, { force: true });
+	return targetPath;
 };
 //#endregion
 //#region src/cli/utils/annotation-encoding.ts
@@ -17049,6 +18047,45 @@ const printBrandedHeader = Effect.gen(function* () {
 	yield* Console.log("");
 });
 //#endregion
+//#region src/cli/utils/report-error.ts
+/**
+* Sends an error to Sentry — enriched with a fresh snapshot of the current run
+* (version, platform, CI/agent, invocation, scanned project) and, when a run
+* transaction is in flight, linked to its trace via the scope's propagation
+* context so the crash and its transaction share a `trace_id` — then waits for
+* delivery before the caller exits. The CLI tears down synchronously after
+* rendering an error, so the awaited `flush` is what actually gets the event
+* (and any in-flight transaction) off the machine.
+*
+* Returns the Sentry event id so the caller can surface it as a reference the
+* user can quote when reporting the bug; returns `undefined` when Sentry was
+* never initialized (`--no-score`, tests, or a missing DSN) or delivery failed.
+* Swallows any transport failure so telemetry can never mask the user's
+* original error.
+*/
+const reportErrorToSentry = async (error) => {
+	if (!Sentry.isInitialized()) return void 0;
+	try {
+		const { tags, contexts } = buildSentryScope();
+		const runTrace = getActiveRunTrace();
+		const eventId = Sentry.withScope((scope) => {
+			for (const [name, context] of Object.entries(contexts)) scope.setContext(name, context);
+			scope.setTags(tags);
+			if (runTrace) scope.setPropagationContext({
+				traceId: runTrace.traceId,
+				parentSpanId: runTrace.spanId,
+				sampled: runTrace.sampled,
+				sampleRand: Math.random()
+			});
+			return Sentry.captureException(error);
+		});
+		await Sentry.flush(SENTRY_FLUSH_TIMEOUT_MS);
+		return eventId;
+	} catch {
+		return;
+	}
+};
+//#endregion
 //#region src/cli/utils/path-format.ts
 const toForwardSlashes = (filePath) => filePath.replaceAll("\\", "/");
 //#endregion
@@ -17116,7 +18153,7 @@ const printMultiProjectSummary = (input) => Effect.gen(function* () {
 	yield* Console.log(`${highlighter.success("✔")} Scanned ${totalScannedFileCount} ${totalScannedFileCount === 1 ? "file" : "files"} in ${formatElapsedTime(totalScanElapsedMilliseconds)}`);
 	if (surfaceDiagnostics.length > 0) {
 		yield* Console.log("");
-		yield* printDiagnostics(surfaceDiagnostics, verbose, resolveDiagnosticSourceRoot, buildRulePriorityMap(completedScans.map((scan) => scan.result.score)));
+		yield* printDiagnostics(surfaceDiagnostics, verbose, resolveDiagnosticSourceRoot, buildRulePriorityMap(completedScans.map((scan) => scan.result.score)), isCodingAgentEnvironment());
 	}
 	const lowestScoredScan = findLowestScoredScan(completedScans);
 	const aggregateScore = lowestScoredScan?.result.score ?? null;
@@ -17146,6 +18183,7 @@ const printMultiProjectSummary = (input) => Effect.gen(function* () {
 	for (const entry of entries) yield* Console.log(buildSummaryLine(entry, longestProjectNameLength));
 	yield* Console.log("");
 	yield* printVerboseTip(surfaceDiagnostics, verbose);
+	yield* printDocsNote();
 });
 //#endregion
 //#region src/cli/utils/prompt-install-setup.ts
@@ -17243,7 +18281,7 @@ const resolveCliInspectOptions = (flags, userConfig) => {
 		respectInlineDisables: flags.respectInlineDisables,
 		warnings: flags.warnings ?? (wantsWarningGate ? true : void 0),
 		scoreOnly: flags.score === true,
-		noScore: flags.score === false || (userConfig?.noScore ?? false),
+		noScore: flags.score === false || flags.telemetry === false || (userConfig?.noScore ?? false),
 		isCi: isCiEnvironment(),
 		silent: Boolean(flags.json),
 		outputSurface: flags.prComment ? "prComment" : "cli",
@@ -17512,6 +18550,7 @@ const validateModeFlags = (flags) => {
 	if (exclusiveModes.length > 1) throw new Error(`Cannot combine ${exclusiveModes.join(" and ")}; pick one mode.`);
 	if (flags.yes && flags.full) throw new Error("Cannot combine --yes and --full; pick one.");
 	if (flags.score && flags.json) throw new Error("Cannot combine --score and --json; pick one output mode.");
+	if (flags.score && flags.telemetry === false) throw new Error("Cannot combine --score with --no-telemetry; --score prints the score that --no-telemetry disables.");
 	if (flags.prComment && (flags.json || flags.score)) throw new Error("--pr-comment cannot be combined with --json or --score.");
 	if (flags.annotations && flags.score) throw new Error("--annotations cannot be combined with --score.");
 	if (flags.explain !== void 0 && flags.why !== void 0) throw new Error("Use --explain or --why, not both — they're aliases of the same flag.");
@@ -17545,6 +18584,24 @@ const buildChangedFilesDiffInfo = (changedFiles) => ({
 	changedFiles,
 	isCurrentChanges: false
 });
+/**
+* On an interactive human run, rename a pre-migration
+* `react-doctor.config.json` to `doctor.config.ts` before config is loaded,
+* so the scan reads the renamed file and the user is told once. CI, coding
+* agents, JSON/score output, pre-commit (`--staged`) hooks, and non-TTY runs
+* are left untouched — the loader's warning still nudges them — so a scan
+* never mutates the repo unattended.
+*/
+const maybeMigrateLegacyConfig = (requestedDirectory, { isQuiet, isStaged }) => {
+	if (!(!isQuiet && !isStaged && process.stdout.isTTY === true && !isCiOrCodingAgentEnvironment())) return;
+	const legacyConfig = findLegacyConfig(requestedDirectory);
+	if (!legacyConfig) return;
+	const migratedPath = migrateLegacyConfig(legacyConfig);
+	if (!migratedPath) return;
+	cliLogger.success("Migrated react-doctor.config.json → doctor.config.ts");
+	cliLogger.dim(`  Your settings were preserved. Review ${toRelativePath(migratedPath, requestedDirectory)} and commit it.`);
+	cliLogger.break();
+};
 const inspectAction = async (directory, flags) => {
 	const isScoreOnly = Boolean(flags.score);
 	const isJsonMode = Boolean(flags.json);
@@ -17557,7 +18614,11 @@ const inspectAction = async (directory, flags) => {
 	});
 	try {
 		validateModeFlags(flags);
-		const scanTarget = resolveScanTarget(requestedDirectory, { allowAmbiguous: true });
+		maybeMigrateLegacyConfig(requestedDirectory, {
+			isQuiet,
+			isStaged: Boolean(flags.staged)
+		});
+		const scanTarget = await resolveScanTarget(requestedDirectory, { allowAmbiguous: true });
 		const userConfig = scanTarget.userConfig;
 		const resolvedDirectory = scanTarget.resolvedDirectory;
 		setJsonReportDirectory(resolvedDirectory);
@@ -17731,12 +18792,13 @@ const inspectAction = async (directory, flags) => {
 			})) printAgentInstallHint();
 		}
 	} catch (error) {
+		const sentryEventId = await reportErrorToSentry(error);
 		if (isJsonMode) {
 			writeJsonErrorReport(error);
 			process.exitCode = 1;
 			return;
 		}
-		handleError(error);
+		handleError(error, { sentryEventId });
 	}
 };
 //#endregion
@@ -17752,8 +18814,570 @@ const installAction = async (options, command) => {
 			projectRoot: options.cwd ?? process.cwd()
 		});
 	} catch (error) {
-		handleError(error);
+		handleError(error, { sentryEventId: await reportErrorToSentry(error) });
+	}
+};
+//#endregion
+//#region src/cli/utils/rule-catalog.ts
+const buildRuleCatalog = () => REACT_DOCTOR_RULES.map((entry) => ({
+	key: entry.key,
+	id: entry.id,
+	category: entry.rule.category ?? "Other",
+	defaultSeverity: entry.rule.severity,
+	framework: entry.rule.framework ?? "global",
+	tags: entry.rule.tags ?? [],
+	recommendation: entry.rule.recommendation,
+	defaultEnabled: entry.rule.defaultEnabled !== false
+}));
+/**
+* Resolves a user-supplied rule reference to a catalog entry. Accepts the
+* fully-qualified key (`react-doctor/no-danger`), the bare id (`no-danger`),
+* and legacy plugin keys (`react/no-danger`) via the shared alias map.
+*/
+const findRuleInCatalog = (catalog, ruleQuery) => {
+	const normalizedQuery = ruleQuery.trim();
+	if (normalizedQuery.length === 0) return void 0;
+	const directMatch = catalog.find((entry) => entry.key === normalizedQuery || entry.id === normalizedQuery);
+	if (directMatch) return directMatch;
+	return catalog.find((entry) => isSameRuleKey(entry.key, normalizedQuery));
+};
+const listRuleCategories = (catalog) => [...new Set(catalog.map((entry) => entry.category))].sort();
+const listRuleTags = (catalog) => [...new Set(catalog.flatMap((entry) => [...entry.tags]))].sort();
+//#endregion
+//#region src/cli/utils/render-rule-catalog.ts
+const SEVERITY_COLUMN_WIDTH_CHARS = 6;
+const colorizeSeverity = (severity, text) => {
+	if (severity === "error") return highlighter.error(text);
+	if (severity === "warn") return highlighter.warn(text);
+	return highlighter.gray(text);
+};
+const formatSourceNote = (effective) => effective.source === "default" ? highlighter.dim("(default)") : highlighter.dim(`(${effective.source})`);
+const renderRuleCatalog = (rows) => {
+	if (rows.length === 0) return highlighter.dim("No rules match the given filters.");
+	const rowsByCategory = /* @__PURE__ */ new Map();
+	for (const row of rows) {
+		const bucket = rowsByCategory.get(row.entry.category) ?? [];
+		bucket.push(row);
+		rowsByCategory.set(row.entry.category, bucket);
+	}
+	const lines = [];
+	for (const category of [...rowsByCategory.keys()].sort()) {
+		const categoryRows = (rowsByCategory.get(category) ?? []).sort((leftRow, rightRow) => leftRow.entry.key.localeCompare(rightRow.entry.key));
+		lines.push(highlighter.bold(`${category} ${highlighter.dim(`(${categoryRows.length})`)}`));
+		for (const row of categoryRows) {
+			const severityBadge = colorizeSeverity(row.effective.value, row.effective.value.padEnd(SEVERITY_COLUMN_WIDTH_CHARS));
+			const tagSuffix = row.entry.tags.length > 0 ? highlighter.dim(`  [${row.entry.tags.join(", ")}]`) : "";
+			lines.push(`  ${severityBadge} ${row.entry.key} ${formatSourceNote(row.effective)}${tagSuffix}`);
+		}
+		lines.push("");
+	}
+	lines.push(highlighter.dim(`${rows.length} rule${rows.length === 1 ? "" : "s"} shown.`));
+	return lines.join("\n");
+};
+const DETAIL_LABEL_COLUMN_WIDTH_CHARS = 18;
+const formatDetailRow = (label, value) => `  ${highlighter.dim(label.padEnd(DETAIL_LABEL_COLUMN_WIDTH_CHARS))}${value}`;
+const renderRuleExplanation = (row) => {
+	const { entry, effective } = row;
+	const lines = [highlighter.bold(entry.key), ""];
+	lines.push(formatDetailRow("Category", entry.category));
+	lines.push(formatDetailRow("Default severity", entry.defaultSeverity));
+	lines.push(formatDetailRow("Current severity", `${colorizeSeverity(effective.value, effective.value)} ${formatSourceNote(effective)}`));
+	lines.push(formatDetailRow("Framework", entry.framework));
+	lines.push(formatDetailRow("Tags", entry.tags.length > 0 ? entry.tags.join(", ") : "none"));
+	lines.push(formatDetailRow("Default enabled", entry.defaultEnabled ? "yes" : "no (opt-in)"));
+	lines.push("");
+	lines.push(highlighter.bold("Why it matters"));
+	lines.push(`  ${entry.recommendation ?? "No additional guidance recorded for this rule yet."}`);
+	lines.push("");
+	lines.push(highlighter.bold("Configure"));
+	lines.push(highlighter.dim(`  react-doctor rules disable ${entry.key}`));
+	lines.push(highlighter.dim(`  react-doctor rules enable ${entry.key} --severity error`));
+	lines.push(highlighter.dim(`  react-doctor rules set ${entry.key} warn`));
+	lines.push("");
+	lines.push(highlighter.bold("Learn more"));
+	lines.push(highlighter.dim(`  ${buildRuleDocsUrl("react-doctor", entry.id)}`));
+	return lines.join("\n");
+};
+//#endregion
+//#region src/cli/utils/rule-config-file.ts
+const NEW_CONFIG_FILENAME = "doctor.config.json";
+const PACKAGE_JSON_CONFIG_KEY = "reactDoctor";
+const JSON_INDENT_SPACES = 2;
+const MANAGED_KEYS = [
+	"rules",
+	"categories",
+	"ignore"
+];
+/**
+* Decides where a rule-config mutation should be written. Discovery
+* reuses `loadConfigWithSource` (the loader the scan uses) so edits land
+* in the file the scan reads — `doctor.config.{ts,js,…}` is preferred,
+* then `package.json#reactDoctor`. When nothing exists, a fresh
+* `doctor.config.json` is targeted at `projectRoot`. Data configs are
+* re-read raw so unrelated fields round-trip untouched.
+*/
+const resolveRuleConfigTarget = async (projectRoot) => {
+	clearConfigCache();
+	const loaded = await loadConfigWithSource(projectRoot);
+	if (loaded) {
+		if (loaded.format === "package-json") {
+			const embedded = (readObjectFile(loaded.configFilePath) ?? {})[PACKAGE_JSON_CONFIG_KEY];
+			return {
+				format: "package-json",
+				filePath: loaded.configFilePath,
+				directory: loaded.sourceDirectory,
+				exists: true,
+				config: isPlainObject(embedded) ? embedded : {}
+			};
+		}
+		if (loaded.format === "json") return {
+			format: "json",
+			filePath: loaded.configFilePath,
+			directory: loaded.sourceDirectory,
+			exists: true,
+			config: readObjectFile(loaded.configFilePath) ?? {}
+		};
+		return {
+			format: "module",
+			filePath: loaded.configFilePath,
+			directory: loaded.sourceDirectory,
+			exists: true,
+			config: loaded.config
+		};
+	}
+	return {
+		format: "json",
+		filePath: path.join(projectRoot, NEW_CONFIG_FILENAME),
+		directory: projectRoot,
+		exists: false,
+		config: {}
+	};
+};
+const writeJsonConfig = (filePath, nextConfig) => {
+	const { $schema, ...rest } = nextConfig;
+	writeFileSync(filePath, `${JSON.stringify({
+		$schema: $schema ?? "https://react.doctor/schema/config.json",
+		...rest
+	}, null, JSON_INDENT_SPACES)}\n`);
+};
+const writePackageJsonConfig = (filePath, nextConfig) => {
+	const packageJson = readObjectFile(filePath) ?? {};
+	writeFileSync(filePath, `${JSON.stringify({
+		...packageJson,
+		[PACKAGE_JSON_CONFIG_KEY]: nextConfig
+	}, null, JSON_INDENT_SPACES)}\n`);
+};
+const syncManagedKeys = (target, nextConfig) => {
+	for (const key of MANAGED_KEYS) {
+		const value = nextConfig[key];
+		if (value === void 0) {
+			if (target[key] !== void 0) delete target[key];
+		} else target[key] = value;
+	}
+};
+const assignNodeSource = (owner, key, code) => {
+	owner[key] = code;
+};
+const editVariableDeclarationConfig = (declaration, config, nextConfig) => {
+	syncManagedKeys(config, nextConfig);
+	const initializer = declaration.init;
+	if (!initializer) return false;
+	const generatedSource = generateCode(config).code;
+	if (initializer.type === "ObjectExpression") {
+		assignNodeSource(declaration, "init", generatedSource);
+		return true;
+	}
+	if (initializer.type === "TSSatisfiesExpression" && initializer.expression.type === "ObjectExpression") {
+		assignNodeSource(initializer, "expression", generatedSource);
+		return true;
+	}
+	return false;
+};
+const writeModuleConfig = async (filePath, nextConfig) => {
+	try {
+		const module = await loadFile(filePath);
+		if (module.exports.default?.$type === "identifier") {
+			const { declaration, config } = getConfigFromVariableDeclaration(module);
+			if (!config || !editVariableDeclarationConfig(declaration, config, nextConfig)) return false;
+		} else syncManagedKeys(getDefaultExportOptions(module), nextConfig);
+		await writeFile(module, filePath);
+		return true;
+	} catch {
+		return false;
+	}
+};
+const writeRuleConfig = async (target, nextConfig) => {
+	if (target.format === "module") {
+		const written = await writeModuleConfig(target.filePath, nextConfig);
+		if (written) clearConfigCache();
+		return { written };
+	}
+	if (target.format === "package-json") writePackageJsonConfig(target.filePath, nextConfig);
+	else writeJsonConfig(target.filePath, nextConfig);
+	clearConfigCache();
+	return { written: true };
+};
+//#endregion
+//#region src/cli/utils/resolve-effective-rule-severity.ts
+/**
+* Resolves what a rule will actually do under the current config without
+* running a scan. `ignore.tags` is a pre-lint gate: a rule carrying an
+* ignored tag is dropped (via `shouldEnableRule`) before any severity is
+* read, so it wins over every override. Among rules that survive the gate,
+* the scanner's order is `rules` > `categories` > `buckets` > the registry
+* default.
+*/
+const resolveEffectiveRuleSeverity = (config, entry) => {
+	const ignoredTags = config?.ignore?.tags ?? [];
+	if (entry.tags.some((tag) => ignoredTags.includes(tag))) return {
+		value: "off",
+		source: "tag"
+	};
+	const ruleOverrides = config?.rules ?? {};
+	for (const equivalentKey of getEquivalentRuleKeys(entry.key)) {
+		const override = ruleOverrides[equivalentKey];
+		if (override !== void 0) return {
+			value: override,
+			source: "rule"
+		};
 	}
+	const categoryOverride = config?.categories?.[entry.category];
+	if (categoryOverride !== void 0) return {
+		value: categoryOverride,
+		source: "category"
+	};
+	if (COMPILER_CLEANUP_RULE_KEYS.has(entry.key)) {
+		const bucketOverride = config?.buckets?.[COMPILER_CLEANUP_BUCKET];
+		if (bucketOverride !== void 0) return {
+			value: bucketOverride,
+			source: "bucket"
+		};
+	}
+	return {
+		value: entry.defaultEnabled ? entry.defaultSeverity : "off",
+		source: "default"
+	};
+};
+//#endregion
+//#region src/cli/utils/update-rule-config.ts
+/**
+* Sets a per-rule severity, replacing any existing entry for the same
+* rule (including legacy-aliased keys, so a config still targeting
+* `react/no-danger` is rewritten to the canonical key instead of
+* leaving a dead duplicate).
+*/
+const setRuleSeverity = (config, ruleKey, severity) => {
+	const equivalentKeys = new Set(getEquivalentRuleKeys(ruleKey));
+	const nextRules = {};
+	for (const [existingKey, existingSeverity] of Object.entries(config.rules ?? {})) if (!equivalentKeys.has(existingKey)) nextRules[existingKey] = existingSeverity;
+	nextRules[ruleKey] = severity;
+	return {
+		...config,
+		rules: nextRules
+	};
+};
+const setCategorySeverity = (config, category, severity) => ({
+	...config,
+	categories: {
+		...config.categories,
+		[category]: severity
+	}
+});
+const addIgnoredTag = (config, tag) => {
+	const currentTags = config.ignore?.tags ?? [];
+	if (currentTags.includes(tag)) return config;
+	return {
+		...config,
+		ignore: {
+			...config.ignore,
+			tags: [...new Set([...currentTags, tag])].sort()
+		}
+	};
+};
+const removeIgnoredTag = (config, tag) => {
+	const currentTags = config.ignore?.tags ?? [];
+	if (!currentTags.includes(tag)) return config;
+	const remainingTags = currentTags.filter((existingTag) => existingTag !== tag);
+	const { tags: _removed, ...remainingIgnore } = config.ignore ?? {};
+	if (remainingTags.length === 0) {
+		if (Object.keys(remainingIgnore).length === 0) {
+			const { ignore: _ignore, ...configWithoutIgnore } = config;
+			return configWithoutIgnore;
+		}
+		return {
+			...config,
+			ignore: remainingIgnore
+		};
+	}
+	return {
+		...config,
+		ignore: {
+			...remainingIgnore,
+			tags: remainingTags
+		}
+	};
+};
+//#endregion
+//#region src/cli/commands/rules.ts
+const SEVERITY_VALUES = [
+	"off",
+	"warn",
+	"error"
+];
+const resolveProjectRoot = (options) => {
+	const requestedDirectory = path.resolve(options.cwd ?? process.cwd());
+	return findNearestPackageDirectory(requestedDirectory) ?? requestedDirectory;
+};
+const parseSeverity = (value) => SEVERITY_VALUES.includes(value) ? value : null;
+const reportInvalidSeverity = (value) => {
+	cliLogger.error(`Invalid severity "${value}". Expected one of: ${SEVERITY_VALUES.join(", ")}.`);
+	process.exitCode = 1;
+};
+const reportRuleNotFound = (ruleQuery) => {
+	cliLogger.error(`Unknown rule "${ruleQuery}".`);
+	cliLogger.dim("  Run `react-doctor rules list` to see every available rule.");
+	process.exitCode = 1;
+};
+const describeTargetPath = (target) => {
+	const relativePath = path.relative(process.cwd(), target.filePath);
+	const displayPath = relativePath.length > 0 && !relativePath.startsWith("..") ? relativePath : target.filePath;
+	return target.exists ? displayPath : `${displayPath} ${highlighter.dim("(created)")}`;
+};
+const applyConfigChange = async (options, change) => {
+	const target = await resolveRuleConfigTarget(resolveProjectRoot(options));
+	const nextConfig = change(target.config);
+	const { written } = await writeRuleConfig(target, nextConfig);
+	return {
+		target,
+		nextConfig,
+		written
+	};
+};
+const reportManualEdit = (target, nextConfig) => {
+	const managed = {};
+	for (const key of [
+		"rules",
+		"categories",
+		"ignore"
+	]) if (nextConfig[key] !== void 0) managed[key] = nextConfig[key];
+	cliLogger.error(`Couldn't automatically edit ${describeTargetPath(target)} (dynamic config).`);
+	cliLogger.dim("  Apply this to your config's default export, then re-run:");
+	for (const line of JSON.stringify(managed, null, 2).split("\n")) cliLogger.dim(`  ${line}`);
+	process.exitCode = 1;
+};
+const rulesListAction = async (options) => {
+	const catalog = buildRuleCatalog();
+	const config = validateConfigTypes((await resolveRuleConfigTarget(resolveProjectRoot(options))).config);
+	const categoryFilter = options.category?.toLowerCase();
+	const frameworkFilter = options.framework?.toLowerCase();
+	const rows = catalog.filter((entry) => {
+		if (categoryFilter && entry.category.toLowerCase() !== categoryFilter) return false;
+		if (frameworkFilter && entry.framework.toLowerCase() !== frameworkFilter) return false;
+		if (options.tag && !entry.tags.includes(options.tag)) return false;
+		return true;
+	}).map((entry) => ({
+		entry,
+		effective: resolveEffectiveRuleSeverity(config, entry)
+	})).filter((row) => options.configured ? row.effective.source !== "default" : true);
+	if (options.json) {
+		const payload = rows.map((row) => ({
+			key: row.entry.key,
+			id: row.entry.id,
+			category: row.entry.category,
+			framework: row.entry.framework,
+			tags: row.entry.tags,
+			defaultSeverity: row.entry.defaultSeverity,
+			defaultEnabled: row.entry.defaultEnabled,
+			severity: row.effective.value,
+			source: row.effective.source
+		}));
+		cliLogger.log(JSON.stringify(payload, null, 2));
+		return;
+	}
+	cliLogger.log(renderRuleCatalog(rows));
+};
+const rulesExplainAction = async (ruleQuery, options) => {
+	const entry = findRuleInCatalog(buildRuleCatalog(), ruleQuery);
+	if (!entry) {
+		reportRuleNotFound(ruleQuery);
+		return;
+	}
+	const effective = resolveEffectiveRuleSeverity(validateConfigTypes((await resolveRuleConfigTarget(resolveProjectRoot(options))).config), entry);
+	if (options.json) {
+		cliLogger.log(JSON.stringify({
+			key: entry.key,
+			id: entry.id,
+			category: entry.category,
+			framework: entry.framework,
+			tags: entry.tags,
+			defaultSeverity: entry.defaultSeverity,
+			defaultEnabled: entry.defaultEnabled,
+			severity: effective.value,
+			source: effective.source,
+			recommendation: entry.recommendation ?? null,
+			learnMoreUrl: buildRuleDocsUrl("react-doctor", entry.id)
+		}, null, 2));
+		return;
+	}
+	cliLogger.log(renderRuleExplanation({
+		entry,
+		effective
+	}));
+};
+const setRuleSeverityAndReport = async (entry, severity, options) => {
+	const { target, nextConfig, written } = await applyConfigChange(options, (config) => setRuleSeverity(config, entry.key, severity));
+	if (!written) {
+		reportManualEdit(target, nextConfig);
+		return;
+	}
+	cliLogger.success(`Set ${entry.key} → ${severity}`);
+	cliLogger.dim(`  Updated ${describeTargetPath(target)}`);
+};
+const rulesSetAction = async (ruleQuery, severityValue, options) => {
+	const severity = parseSeverity(severityValue);
+	if (!severity) {
+		reportInvalidSeverity(severityValue);
+		return;
+	}
+	const entry = findRuleInCatalog(buildRuleCatalog(), ruleQuery);
+	if (!entry) {
+		reportRuleNotFound(ruleQuery);
+		return;
+	}
+	await setRuleSeverityAndReport(entry, severity, options);
+};
+const rulesEnableAction = async (ruleQuery, options) => {
+	const entry = findRuleInCatalog(buildRuleCatalog(), ruleQuery);
+	if (!entry) {
+		reportRuleNotFound(ruleQuery);
+		return;
+	}
+	if (options.severity === void 0) {
+		await setRuleSeverityAndReport(entry, entry.defaultSeverity, options);
+		return;
+	}
+	const severity = parseSeverity(options.severity);
+	if (!severity) {
+		reportInvalidSeverity(options.severity);
+		return;
+	}
+	if (severity === "off") {
+		cliLogger.error("`enable` cannot set a rule to off. Use `react-doctor rules disable` instead.");
+		process.exitCode = 1;
+		return;
+	}
+	await setRuleSeverityAndReport(entry, severity, options);
+};
+const rulesDisableAction = async (ruleQuery, options) => {
+	const entry = findRuleInCatalog(buildRuleCatalog(), ruleQuery);
+	if (!entry) {
+		reportRuleNotFound(ruleQuery);
+		return;
+	}
+	await setRuleSeverityAndReport(entry, "off", options);
+};
+const rulesCategoryAction = async (categoryQuery, severityValue, options) => {
+	const severity = parseSeverity(severityValue);
+	if (!severity) {
+		reportInvalidSeverity(severityValue);
+		return;
+	}
+	const knownCategories = listRuleCategories(buildRuleCatalog());
+	const matchedCategory = knownCategories.find((category) => category.toLowerCase() === categoryQuery.toLowerCase());
+	if (!matchedCategory) {
+		cliLogger.error(`Unknown category "${categoryQuery}".`);
+		cliLogger.dim(`  Known categories: ${knownCategories.join(", ")}`);
+		process.exitCode = 1;
+		return;
+	}
+	const { target, nextConfig, written } = await applyConfigChange(options, (config) => setCategorySeverity(config, matchedCategory, severity));
+	if (!written) {
+		reportManualEdit(target, nextConfig);
+		return;
+	}
+	cliLogger.success(`Set category "${matchedCategory}" → ${severity}`);
+	cliLogger.dim(`  Updated ${describeTargetPath(target)}`);
+};
+const rulesIgnoreTagAction = async (tag, options) => {
+	const knownTags = listRuleTags(buildRuleCatalog());
+	if (!knownTags.includes(tag)) {
+		cliLogger.error(`Unknown tag "${tag}".`);
+		cliLogger.dim(`  Known tags: ${knownTags.join(", ")}`);
+		process.exitCode = 1;
+		return;
+	}
+	const { target, nextConfig, written } = await applyConfigChange(options, (config) => addIgnoredTag(config, tag));
+	if (!written) {
+		reportManualEdit(target, nextConfig);
+		return;
+	}
+	cliLogger.success(`Ignoring tag "${tag}" (rules with this tag are skipped before linting)`);
+	cliLogger.dim(`  Updated ${describeTargetPath(target)}`);
+};
+const rulesUnignoreTagAction = async (tag, options) => {
+	const target = await resolveRuleConfigTarget(resolveProjectRoot(options));
+	if (!(target.config.ignore?.tags ?? []).includes(tag)) {
+		cliLogger.dim(`Tag "${tag}" was not being ignored; nothing to change.`);
+		return;
+	}
+	const nextConfig = removeIgnoredTag(target.config, tag);
+	const { written } = await writeRuleConfig(target, nextConfig);
+	if (!written) {
+		reportManualEdit(target, nextConfig);
+		return;
+	}
+	cliLogger.success(`Tag "${tag}" is no longer ignored`);
+	cliLogger.dim(`  Updated ${describeTargetPath(target)}`);
+};
+//#endregion
+//#region src/cli/commands/version.ts
+/**
+* oclif-style version line. 12-factor CLI Apps (#3, "What version am I
+* on?"): the `version` command is the primary place users grab debugging
+* info, so it carries the Node runtime and platform alongside the CLI
+* version. The `-v` / `-V` / `--version` flags stay terse (just the
+* number) so scripts can parse them.
+*/
+const buildVersionString = () => `react-doctor/${VERSION} ${process.platform}-${process.arch} node-${process.version}`;
+const versionAction = () => {
+	process.stdout.write(`${buildVersionString()}\n`);
+};
+//#endregion
+//#region src/cli/utils/apply-color-preference.ts
+/**
+* Resolve an explicit color preference from `--color` / `--no-color` or the
+* app-specific `REACT_DOCTOR_NO_COLOR` / `REACT_DOCTOR_FORCE_COLOR` env vars
+* (clig.dev Output; 12-factor #6), overriding picocolors' own
+* `NO_COLOR` / `FORCE_COLOR` / `TERM` / TTY detection. Flags win over env
+* vars; with neither set, picocolors' detection stands.
+*
+* A resolved preference is mirrored onto the standard `NO_COLOR` /
+* `FORCE_COLOR` env vars in addition to our picocolors highlighter, so
+* libraries with their own color stacks (the `ora` spinner, `prompts`)
+* honor it too rather than only the scan report. Scanning argv directly
+* (not Commander's parsed options) applies the preference before Commander
+* parses, so it reaches every later path. The scan stops at `--`.
+*/
+const applyColorPreference = (argv, env = process.env) => {
+	let enabled;
+	for (const argument of argv) {
+		if (argument === "--") break;
+		if (argument === "--no-color") enabled = false;
+		else if (argument === "--color") enabled = true;
+	}
+	if (enabled === void 0) {
+		if (env.REACT_DOCTOR_NO_COLOR) enabled = false;
+		else if (env.REACT_DOCTOR_FORCE_COLOR) enabled = true;
+	}
+	if (enabled === void 0) return;
+	if (enabled) {
+		env.FORCE_COLOR = "1";
+		delete env.NO_COLOR;
+	} else {
+		env.NO_COLOR = "1";
+		delete env.FORCE_COLOR;
+	}
+	setColorEnabled(enabled);
 };
 //#endregion
 //#region src/cli/utils/exit-gracefully.ts
@@ -17765,21 +19389,54 @@ const exitGracefully = () => {
 	process.exit(130);
 };
 //#endregion
+//#region src/cli/utils/normalize-help-command.ts
+/**
+* 12-factor CLI Apps (#1, "Great help is essential"): `mycli help` and
+* `mycli help <command>` must display help. Commander doesn't wire this
+* up once the root command has its own default action plus a positional
+* argument — it treats a leading `help` as the `[directory]` to scan,
+* which then errors with "No React project found in ./help".
+*
+* We rewrite the argv up front so the existing `--help` paths handle it:
+*   `react-doctor help`         -> `react-doctor --help`
+*   `react-doctor help install` -> `react-doctor install --help`
+*
+* Only a *leading* `help` token is rewritten, so a flag value such as
+* `--project help` is never mistaken for the help command. The target is
+* the first non-flag token after `help`, so intervening flags like
+* `help --no-color install` still resolve to `install`. An unknown target
+* (`help bogus`) falls back to root help rather than erroring.
+*/
+const normalizeHelpInvocation = (argv, knownCommands) => {
+	const nodeArguments = argv.slice(0, 2);
+	const userArguments = argv.slice(2);
+	if (userArguments[0] !== "help") return [...argv];
+	const target = userArguments.slice(1).find((argument) => !argument.startsWith("-"));
+	if (target !== void 0 && knownCommands.includes(target)) return [
+		...nodeArguments,
+		target,
+		"--help"
+	];
+	return [...nodeArguments, "--help"];
+};
+//#endregion
 //#region src/cli/utils/strip-unknown-cli-flags.ts
-const NODE_ARGUMENT_COUNT = 2;
 const ROOT_FLAG_SPEC = {
 	longOptionsWithoutValues: new Set([
 		"--annotations",
+		"--color",
 		"--dead-code",
 		"--full",
 		"--help",
 		"--json",
 		"--json-compact",
 		"--lint",
+		"--no-color",
 		"--no-dead-code",
 		"--no-lint",
 		"--no-respect-inline-disables",
 		"--no-score",
+		"--no-telemetry",
 		"--no-warnings",
 		"--pr-comment",
 		"--respect-inline-disables",
@@ -17808,8 +19465,10 @@ const ROOT_FLAG_SPEC = {
 const INSTALL_FLAG_SPEC = {
 	longOptionsWithoutValues: new Set([
 		"--agent-hooks",
+		"--color",
 		"--dry-run",
 		"--help",
+		"--no-color",
 		"--yes"
 	]),
 	longOptionsWithRequiredValues: new Set(["--cwd"]),
@@ -17817,7 +19476,40 @@ const INSTALL_FLAG_SPEC = {
 	shortOptionsWithoutValues: new Set(["-h", "-y"]),
 	shortOptionsWithRequiredValues: new Set(["-c"])
 };
-const COMMAND_FLAG_SPECS = new Map([["install", INSTALL_FLAG_SPEC], ["setup", INSTALL_FLAG_SPEC]]);
+const COMMAND_FLAG_SPECS = new Map([
+	["install", INSTALL_FLAG_SPEC],
+	["setup", INSTALL_FLAG_SPEC],
+	["version", {
+		longOptionsWithoutValues: new Set([
+			"--color",
+			"--help",
+			"--no-color"
+		]),
+		longOptionsWithRequiredValues: /* @__PURE__ */ new Set(),
+		longOptionsWithOptionalValues: /* @__PURE__ */ new Set(),
+		shortOptionsWithoutValues: new Set(["-h"]),
+		shortOptionsWithRequiredValues: /* @__PURE__ */ new Set()
+	}],
+	["rules", {
+		longOptionsWithoutValues: new Set([
+			"--color",
+			"--configured",
+			"--help",
+			"--json",
+			"--no-color"
+		]),
+		longOptionsWithRequiredValues: new Set([
+			"--category",
+			"--cwd",
+			"--framework",
+			"--severity",
+			"--tag"
+		]),
+		longOptionsWithOptionalValues: /* @__PURE__ */ new Set(),
+		shortOptionsWithoutValues: new Set(["-h"]),
+		shortOptionsWithRequiredValues: new Set(["-c"])
+	}]
+]);
 const isFlagLike = (argument) => argument.startsWith("-") && argument !== "-";
 const getLongOptionName = (argument) => {
 	const equalsIndex = argument.indexOf("=");
@@ -17871,8 +19563,8 @@ const stripUnknownFlags = (userArguments, flagSpec) => {
 	return sanitizedArguments;
 };
 const stripUnknownCliFlags = (argv) => {
-	const nodeArguments = argv.slice(0, NODE_ARGUMENT_COUNT);
-	const userArguments = argv.slice(NODE_ARGUMENT_COUNT);
+	const nodeArguments = argv.slice(0, 2);
+	const userArguments = argv.slice(2);
 	const commandIndex = findCommandIndex(userArguments);
 	if (commandIndex === null) return [...nodeArguments, ...stripUnknownFlags(userArguments, ROOT_FLAG_SPEC)];
 	const commandName = userArguments[commandIndex];
@@ -17886,30 +19578,83 @@ const stripUnknownCliFlags = (argv) => {
 };
 //#endregion
 //#region src/cli/index.ts
+initializeSentry();
 process.on("SIGINT", exitGracefully);
 process.on("SIGTERM", exitGracefully);
 unrefStdin();
-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("--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("--full", "force a full scan (overrides any `diff` value in config or `--diff`)").option("--experimental-parallel [workers]", "experimental: lint with N parallel workers (default: auto-detect CPU cores) — speeds up large repos").option("--project <name>", "select workspace project (comma-separated for multiple)").option("--diff [base]", "scan only files changed vs base branch (pass `false` to disable; overridden by --full)").option("--changed-files-from <file>", "internal: scan source files listed in a newline-delimited changed-files file").option("--no-score", "skip the score API and the share URL").option("--staged", "scan only staged (git index) files for pre-commit hooks").option("--fail-on <level>", "exit with error code on diagnostics: error, warning, none (default: none)").option("--annotations", "output diagnostics as GitHub Actions annotations").option("--pr-comment", "tune CLI output for sticky PR comments (drops weak-signal rule families like `design` from the printed list and the fail-on gate; configure via config.surfaces)").option("--explain <file:line>", "diagnose why a rule fired or why a suppression didn't apply at a specific location").option("--why <file:line>", "alias for --explain").option("--respect-inline-disables", "respect inline `// eslint-disable*` / `// oxlint-disable*` comments (default)").option("--no-respect-inline-disables", "audit mode: neutralize inline lint suppressions before scanning").option("--warnings", "show warning-severity diagnostics (errors always show)").option("--no-warnings", "hide warning-severity diagnostics (default)").addHelpText("after", `
+const formatExampleLines = (examples) => {
+	const width = Math.max(...examples.map(([command]) => command.length));
+	return examples.map(([command, description]) => `  $ ${command.padEnd(width)}  ${highlighter.dim(`# ${description}`)}`).join("\n");
+};
+const renderRootHelpEpilog = () => `
+${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 --staged", "scan staged files (pre-commit hook)"],
+	["react-doctor --fail-on warning", "exit non-zero on warnings (CI gate)"],
+	["react-doctor --json > report.json", "write a machine-readable report"],
+	["react-doctor --explain src/App.tsx:42", "explain why a rule fired there"],
+	["react-doctor install", "set up the agent skill and git hook"]
+])}
+
 ${highlighter.dim("Configuration:")}
-  Place a ${highlighter.info("react-doctor.config.json")} (or ${highlighter.info("\"reactDoctor\"")} key in your package.json) in the project root.
-  CLI flags always override config values. See the README for the full schema.
+  Add a ${highlighter.info("doctor.config.ts")} (or .js/.mjs/.json — or a ${highlighter.info("\"reactDoctor\"")} key in your package.json) in the project root.
+  Use ${highlighter.info("react-doctor rules")} to list, explain, and configure rules. CLI flags always override config values.
+
+${highlighter.dim("Feedback & bug reports:")}
+  ${highlighter.info(`${CANONICAL_GITHUB_URL}/issues`)}
 
 ${highlighter.dim("Learn more:")}
   ${highlighter.info(CANONICAL_GITHUB_URL)}
-`);
+`;
+const renderInstallHelpEpilog = () => `
+${highlighter.dim("Examples:")}
+${formatExampleLines([
+	["react-doctor install", "interactive setup"],
+	["react-doctor install --yes", "non-interactive; all detected agents"],
+	["react-doctor install --dry-run", "preview without writing files"],
+	["react-doctor install --agent-hooks", "also install native agent hooks"]
+])}
+
+${highlighter.dim("Learn more:")}
+  ${highlighter.info(CANONICAL_GITHUB_URL)}
+`;
+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("--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("--full", "force a full scan (overrides any `diff` value in config or `--diff`)").option("--experimental-parallel [workers]", "experimental: lint with N parallel workers (default: auto-detect CPU cores) — speeds up large repos").option("--project <name>", "select workspace project (comma-separated for multiple)").option("--diff [base]", "scan only files changed vs base branch (pass `false` to disable; overridden by --full)").option("--changed-files-from <file>", "internal: scan source files listed in a newline-delimited changed-files file").option("--no-score", "skip the score API, the share URL, and crash reporting").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("--fail-on <level>", "exit with error code on diagnostics: error, warning, none (default: none)").option("--annotations", "output diagnostics as GitHub Actions annotations").option("--pr-comment", "tune CLI output for sticky PR comments (drops weak-signal rule families like `design` from the printed list and the fail-on gate; configure via config.surfaces)").option("--explain <file:line>", "diagnose why a rule fired or why a suppression didn't apply at a specific location").option("--why <file:line>", "alias for --explain").option("--respect-inline-disables", "respect inline `// eslint-disable*` / `// oxlint-disable*` comments (default)").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("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()).action(installAction);
+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);
+program.command("version").description("show the version with Node and platform info").option("--color", "force colored output").option("--no-color", "disable colored output (also honors NO_COLOR)").action(versionAction);
+const rules = program.command("rules").description("List, explain, and configure which React Doctor rules run");
+rules.command("list").description("List rules and the severity they run at under your config").option("--category <name>", "only show rules in a category (e.g. Performance)").option("--tag <name>", "only show rules with a tag (e.g. design, test-noise)").option("--framework <name>", "only show rules for a framework (e.g. global, nextjs)").option("--configured", "only show rules your config has changed from the default").option("--json", "output a structured JSON array").option("-c, --cwd <cwd>", "working directory", process.cwd()).action((_options, command) => rulesListAction(command.optsWithGlobals()));
+rules.command("explain <rule>").description("Explain why a rule matters, its current severity, and how to configure it").option("--json", "output a structured JSON object").option("-c, --cwd <cwd>", "working directory", process.cwd()).action((rule, _options, command) => rulesExplainAction(rule, command.optsWithGlobals()));
+rules.command("set <rule> <severity>").description("Set a rule's severity: off, warn, or error").option("-c, --cwd <cwd>", "working directory", process.cwd()).action((rule, severity, _options, command) => rulesSetAction(rule, severity, command.optsWithGlobals()));
+rules.command("enable <rule>").description("Enable a rule at its recommended severity (or pass --severity)").option("--severity <level>", "severity to enable at: warn or error").option("-c, --cwd <cwd>", "working directory", process.cwd()).action((rule, _options, command) => rulesEnableAction(rule, command.optsWithGlobals()));
+rules.command("disable <rule>").description("Disable a rule so it never runs").option("-c, --cwd <cwd>", "working directory", process.cwd()).action((rule, _options, command) => rulesDisableAction(rule, command.optsWithGlobals()));
+rules.command("category <category> <severity>").description("Set the severity for a whole category (off, warn, error)").option("-c, --cwd <cwd>", "working directory", process.cwd()).action((category, severity, _options, command) => rulesCategoryAction(category, severity, command.optsWithGlobals()));
+rules.command("ignore-tag <tag>").description("Skip a whole rule family by tag before linting (e.g. design)").option("-c, --cwd <cwd>", "working directory", process.cwd()).action((tag, _options, command) => rulesIgnoreTagAction(tag, command.optsWithGlobals()));
+rules.command("unignore-tag <tag>").description("Stop ignoring a tag previously skipped via ignore-tag").option("-c, --cwd <cwd>", "working directory", process.cwd()).action((tag, _options, command) => rulesUnignoreTagAction(tag, command.optsWithGlobals()));
 process.stdout.on("error", (error) => {
 	if (error.code === "EPIPE") process.exit(0);
 });
-program.parseAsync(stripUnknownCliFlags(process.argv)).catch((error) => {
+const knownCommands = program.commands.flatMap((command) => [command.name(), ...command.aliases()]);
+const strippedArgv = stripUnknownCliFlags(process.argv);
+if (process.argv.includes("-V") && !strippedArgv.includes("-V")) {
+	process.stdout.write(`${VERSION}\n`);
+	process.exit(0);
+}
+applyColorPreference(strippedArgv);
+const argv = normalizeHelpInvocation(strippedArgv, knownCommands);
+program.parseAsync(argv).then(() => flushSentry()).catch(async (error) => {
+	const sentryEventId = await reportErrorToSentry(error);
 	if (isJsonModeActive()) {
 		writeJsonErrorReport(error);
 		process.exit(1);
 	}
-	handleError(error);
+	handleError(error, { sentryEventId });
 });
 //#endregion
 export {};
 
-//# sourceMappingURL=cli.js.map
+//# sourceMappingURL=cli.js.map
+//# debugId=d012dbb2-27e9-5092-9eab-c7fa4573f0b2