feat(cli): make JetBrains warning more specific (#19687)

packages/core/src/utils/compatibility.ts

@@ -75,9 +75,6 @@ export function supportsTrueColor(): boolean {
   return false;
 }
 
-/**
- * Returns a list of compatibility warnings based on the current environment.
- */
 export enum WarningPriority {
   Low = 'low',
   High = 'high',
@@ -89,7 +86,12 @@ export interface StartupWarning {
   priority: WarningPriority;
 }
 
-export function getCompatibilityWarnings(): StartupWarning[] {
+/**
+ * Returns a list of compatibility warnings based on the current environment.
+ */
+export function getCompatibilityWarnings(options?: {
+  isAlternateBuffer?: boolean;
+}): StartupWarning[] {
   const warnings: StartupWarning[] = [];
 
   if (isWindows10()) {
@@ -101,11 +103,18 @@ export function getCompatibilityWarnings(): StartupWarning[] {
     });
   }
 
-  if (isJetBrainsTerminal()) {
+  if (isJetBrainsTerminal() && options?.isAlternateBuffer) {
+    const platformTerminals: Partial<Record<NodeJS.Platform, string>> = {
+      win32: 'Windows Terminal',
+      darwin: 'iTerm2 or Ghostty',
+      linux: 'Ghostty',
+    };
+    const suggestion = platformTerminals[os.platform()];
+    const suggestedTerminals = suggestion ? ` (e.g., ${suggestion})` : '';
+
     warnings.push({
       id: 'jetbrains-terminal',
-      message:
-        'Warning: JetBrains terminal detected. You may experience rendering or scrolling issues. Using an external terminal (e.g., Windows Terminal, iTerm2) is recommended.',
+      message: `Warning: JetBrains mouse scrolling is unreliable. Disabling alternate buffer mode in settings or using an external terminal${suggestedTerminals} is recommended.`,
       priority: WarningPriority.High,
     });
   }