feat(shortcuts): default to hold Right Alt (push-to-talk) for new installs (#648)

* feat(shortcuts): default to hold Right Alt push-to-talk on first install

Double-tap Ctrl conflicts with many desktop and app shortcuts, so new
installs now use hold Right Alt (Option) in push-to-talk mode. Existing
config.json values are preserved unchanged.

Updates README, user guide, AGENTS.md, first-run dialog, website copy,
and tests to match the new defaults.

* refactor(shortcuts): trim redundant default-change test and comments

Drop the fresh-install assertion that duplicated DEFAULT_CONFIG coverage,
remove the duplicated Right-Alt rationale from config_manager, and drop a
vacuous source-string check from the settings shortcuts test.

* fix(shortcuts): align install.sh seeds and preserve legacy toggle mode

install.sh still wrote ctrl+ctrl without mode, so merges with the new
push_to_talk default became hold-Ctrl. Seed right_alt + push_to_talk for
new installs, and migrate existing shortcut-only configs to mode=toggle
so prior behavior is unchanged.

* style(config): fix black formatting after shortcuts migration

* fix(shortcuts): preserve legacy defaults when shortcuts section is missing

Existing config files without a shortcuts section previously inherited
ctrl+ctrl toggle from DEFAULT_CONFIG. Pin those historical defaults on
upgrade so the new first-install Right Alt push-to-talk defaults do not
silently change behavior.

* docs(agents): unwrap hard-broken dictation control paragraph

Keep the AGENTS.md paragraph as a single line like the surrounding prose.

web/src/app/faq/page.tsx

@@ -83,7 +83,7 @@ const faqCategories = [
     questions: [
       {
         q: "How do I start and stop dictation?",
-        a: "By default, toggle mode uses double-tap Ctrl to start/stop dictation. You can also switch to push-to-talk mode (hold key to speak, release to stop) in Settings.",
+        a: "By default, hold Right Alt (Option on Mac-layout keyboards) to speak and release to stop (push-to-talk). You can switch to toggle mode (double-tap a key to start/stop) or change the key in Settings.",
       },
       {
         q: "Does Vocalinux work with Wayland?",

web/src/app/install/[distro]/page.tsx

@@ -56,7 +56,7 @@ const distroConfig: Record<DistroSlug, DistroConfig> = {
     ],
     postInstallChecks: [
       "Run vocalinux and confirm the tray indicator appears.",
-      "Use toggle mode (double-tap Ctrl) or push-to-talk mode and verify dictation starts.",
+      "Hold Right Alt (Option) to dictate, or switch to toggle mode in Settings and verify dictation starts.",
       "Set language and model size in the settings panel for your workload.",
     ],
   },
@@ -264,7 +264,7 @@ export default async function DistroInstallPage({
       {
         "@type": "HowToStep",
         name: "Start dictating",
-        text: "Launch vocalinux and use toggle mode or push-to-talk mode to begin dictation.",
+        text: "Launch vocalinux and hold Right Alt (Option) to begin dictation, or choose toggle mode in Settings.",
         url: absoluteUrl(`/install/${distro}`),
       },
     ],

web/src/app/install/page.tsx

@@ -114,8 +114,7 @@ export default function InstallGuidesPage() {
             .
           </li>
           <li>
-            Use toggle mode (double-tap Ctrl) or push-to-talk to control
-            dictation in any text field.
+            Hold Right Alt (Option) to dictate, or switch to toggle mode in Settings.
           </li>
           <li>
             Choose whisper.cpp for speed, Whisper for maximum model

web/src/app/page.tsx

@@ -162,7 +162,7 @@ const homeJsonLd = [
       {
         "@type": "HowToStep",
         name: "Start dictating",
-        text: "Launch vocalinux and use toggle or push-to-talk shortcut mode to begin dictation.",
+        text: "Launch vocalinux and hold Right Alt (Option) to begin dictation, or choose toggle mode in Settings.",
         url: "https://vocalinux.com/#install",
       },
     ],

web/src/app/shortcuts/page.tsx

@@ -10,11 +10,19 @@ const shortcutCategories = [
     icon: Mic,
     iconColor: "text-primary",
     shortcuts: [
-      { keys: ["Ctrl", "Ctrl"], action: "Toggle mode: start/stop dictation", note: "Default mode" },
-      { keys: ["Hold Ctrl"], action: "Push-to-talk mode: speak while held", note: "Release to stop" },
+      {
+        keys: ["Hold Right Alt"],
+        action: "Push-to-talk (default): speak while held",
+        note: "Release to stop · Option on Mac-layout keyboards",
+      },
+      {
+        keys: ["Double-tap key"],
+        action: "Toggle mode: start/stop dictation",
+        note: "Optional — switch in Settings",
+      },
       {
         keys: ["Settings"],
-        action: "Choose Left Ctrl vs Right Ctrl in Settings for more control",
+        action: "Choose Left/Right Ctrl, Alt, or Shift in Settings",
         note: "Modifier key side selection",
       },
       {
@@ -144,8 +152,9 @@ export default function ShortcutsPage() {
           Keyboard Shortcuts & Voice Commands
         </h1>
         <p className="mb-8 max-w-4xl text-lg text-muted-foreground">
-          Master Vocalinux with keyboard shortcuts and voice commands. Use toggle mode (double-tap)
-          or push-to-talk mode, then apply voice commands for editing and formatting.
+          Master Vocalinux with keyboard shortcuts and voice commands. New installs default to
+          push-to-talk (hold Right Alt), or switch to toggle mode (double-tap), then apply voice
+          commands for editing and formatting.
         </p>
       </section>
 
@@ -155,19 +164,15 @@ export default function ShortcutsPage() {
         <div className="flex flex-wrap items-center gap-4">
           <div className="flex items-center gap-2">
             <kbd className="rounded-lg border border-border bg-muted px-3 py-1.5 font-mono text-sm font-semibold">
-              Ctrl
-            </kbd>
-            <span className="text-muted-foreground">+</span>
-            <kbd className="rounded-lg border border-border bg-muted px-3 py-1.5 font-mono text-sm font-semibold">
-              Ctrl
+              Hold Right Alt
             </kbd>
           </div>
           <span className="text-muted-foreground">→</span>
-          <span className="font-medium">Toggle Mode: Start/Stop Dictation</span>
+          <span className="font-medium">Push-to-Talk: Speak While Held</span>
         </div>
         <p className="mt-3 text-sm text-muted-foreground">
-          Push-to-talk mode is also available: hold your configured key to dictate, release to stop.
-          You can switch modes in Settings.
+          Right Alt is the Option key on Mac-layout keyboards. Toggle mode is also available:
+          double-tap your configured key to start/stop. You can switch modes and keys in Settings.
         </p>
         <p className="mt-2 text-sm text-muted-foreground">
           Voice commands can be enabled or disabled from Settings depending on your workflow.