From 9cd011b2af844b3778bdc0e41eed3b64a6bdddb5 Mon Sep 17 00:00:00 2001
From: Brennan Benson <79079362+brennanb2025@users.noreply.github.com>
Date: Fri, 31 Jul 2026 17:04:28 -0700
Subject: [PATCH] Refine voice dictation tip instructions

---
 .../VoiceDictationTipDialog.test.tsx            |  4 +++-
 .../feature-tips/VoiceDictationTipDialog.tsx    | 17 +++++++++++++++--
 src/renderer/src/i18n/locales/en.json           |  3 ++-
 src/shared/feature-tips.ts                      |  2 +-
 4 files changed, 21 insertions(+), 5 deletions(-)

diff --git a/src/renderer/src/components/feature-tips/VoiceDictationTipDialog.test.tsx b/src/renderer/src/components/feature-tips/VoiceDictationTipDialog.test.tsx
index 28aa78bcd58..e8b87266fb4 100644
--- a/src/renderer/src/components/feature-tips/VoiceDictationTipDialog.test.tsx
+++ b/src/renderer/src/components/feature-tips/VoiceDictationTipDialog.test.tsx
@@ -64,7 +64,7 @@ describe('VoiceDictationTipDialog', () => {
 
     expect(html).toContain('TIP')
     expect(html).toContain('Dictate into any pane')
-    expect(html).toContain('Turn speech into text wherever')
+    expect(html).not.toContain('Turn speech into text wherever')
     expect(html).not.toContain('is here')
   })
 
@@ -73,6 +73,8 @@ describe('VoiceDictationTipDialog', () => {
 
     expect(html).toContain('⌘')
     expect(html).toContain('E')
+    expect(html).toContain('to start voice dictation. Press')
+    expect(html).toContain('again to stop.')
     expect(html).toContain('Settings → Voice')
   })
 
diff --git a/src/renderer/src/components/feature-tips/VoiceDictationTipDialog.tsx b/src/renderer/src/components/feature-tips/VoiceDictationTipDialog.tsx
index 2408d646be5..aa1cd3a41e2 100644
--- a/src/renderer/src/components/feature-tips/VoiceDictationTipDialog.tsx
+++ b/src/renderer/src/components/feature-tips/VoiceDictationTipDialog.tsx
@@ -56,7 +56,6 @@ export function VoiceDictationTipDialog({
                 {tip.title}
               </DialogTitle>
               <DialogDescription className="mt-3 max-w-2xl space-y-3 text-sm leading-relaxed">
-                <span className="block">{tip.description}</span>
                 <span className="block">
                   {translate(
                     'featureTips.voice.focusPaneInstruction',
@@ -72,7 +71,21 @@ export function VoiceDictationTipDialog({
                   ) : (
                     translate('featureTips.voice.theShortcut', 'the dictation shortcut')
                   )}{' '}
-                  {translate('featureTips.voice.startStopInstruction', 'to start or stop.')}
+                  {translate(
+                    'featureTips.voice.startInstruction',
+                    'to start voice dictation. Press'
+                  )}{' '}
+                  {displayShortcut && displayShortcut.keys.length > 0 ? (
+                    <ShortcutKeyCombo
+                      keys={displayShortcut.keys}
+                      doubleTap={displayShortcut.doubleTap}
+                      className="mx-1 align-middle"
+                      keyCapClassName="min-w-0 bg-card px-1.5 py-0 text-[11px] text-foreground shadow-none"
+                    />
+                  ) : (
+                    translate('featureTips.voice.theShortcut', 'the dictation shortcut')
+                  )}{' '}
+                  {translate('featureTips.voice.stopInstruction', 'again to stop.')}
                 </span>
                 <span className="block text-muted-foreground">
                   {translate(
diff --git a/src/renderer/src/i18n/locales/en.json b/src/renderer/src/i18n/locales/en.json
index 44f4b138a61..a3310e6c540 100644
--- a/src/renderer/src/i18n/locales/en.json
+++ b/src/renderer/src/i18n/locales/en.json
@@ -14695,7 +14695,8 @@
       "listening": "Listening...",
       "focusPaneInstruction": "Focus a terminal, editor, or agent prompt, then press",
       "theShortcut": "the dictation shortcut",
-      "startStopInstruction": "to start or stop.",
+      "startInstruction": "to start voice dictation. Press",
+      "stopInstruction": "again to stop.",
       "settingsInstruction": "Change the model, dictation mode, or shortcut anytime in",
       "settingsLink": "Settings → Voice"
     }
diff --git a/src/shared/feature-tips.ts b/src/shared/feature-tips.ts
index 888ca2a8f34..991991dac22 100644
--- a/src/shared/feature-tips.ts
+++ b/src/shared/feature-tips.ts
@@ -57,7 +57,7 @@ export const FEATURE_TIPS = [
     priority: 'unseen',
     eyebrow: 'Tip',
     title: 'Dictate into any pane',
-    description: "Turn speech into text wherever you're working.",
+    description: 'Start voice dictation in any focused pane, then use the shortcut again to stop.',
     action: 'enable-voice',
     ctaLabel: 'Set up voice',
     completedByFeatureInteractions: ['voice-dictation']