docs: add hotkey troubleshooting guide

[alexdcesm]

Description

Adds a concise hotkey troubleshooting guide for two common setup failures:

• Mouse utilities such as Logitech G HUB or Logi Options+ intercepting a side button before FluidVoice receives it.
• F13–F19 shortcuts requiring a device or remapping tool that can emit the actual function-key event.

The guide includes reset steps, a quick isolation test, and Karabiner-Elements/Stream Deck workarounds.

Type of Change

• 🐞 Bug fix
• ✨ New feature
• 💥 Breaking change
• 🧹 Chore
• 📝 Documentation update

Related Issue or Discussion

Related to #622 and #411.

Testing

• Ran git diff --check.
• Reviewed the rendered Markdown structure and instructions.

Screenshots / Video

• No UI/visual changes; screenshots/video are not applicable.

Notes

Documentation-only change based on reproduced setup issues with a remapped Logitech mouse button and an F18/F19 Stream Deck workflow.

[greptile-apps]

Greptile Summary

This PR adds docs/HOTKEY_TROUBLESHOOTING.md, a new user-facing guide covering two reproducible hotkey setup failures: mouse utility software (e.g. Logitech G HUB, Logi Options+) intercepting side buttons before FluidVoice receives them, and F13–F19 keys requiring a physical device or remapping tool that actually emits the function-key event.

• The mouse side-button section provides a clear 5-step resolution flow plus an isolation test (quitting the utility to confirm interception).
• The F13–F19 section covers Karabiner-Elements and Stream Deck workarounds; the Stream Deck bullet references "the remapped key" without explicitly linking back to the Karabiner step, which could confuse users who jump straight to that option.
• The guide is not linked from README.md or any other entry point, making it effectively undiscoverable for users hitting these issues.

Confidence Score: 4/5

Documentation-only change with no code modifications; safe to merge as-is, though discoverability would improve with a README link.

The guide content is technically accurate and the step-by-step instructions are sound. The two observations are minor: one bullet in the F13–F19 section uses 'the remapped key' without an explicit back-reference to the Karabiner step, and the file has no entry point from README.md, so users affected by these issues are unlikely to find it without browsing the docs directory directly.

README.md would benefit from a link to the new guide; docs/HOTKEY_TROUBLESHOOTING.md has one minor clarity gap in the Stream Deck bullet.

Prompt To Fix All With AI

Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
docs/HOTKEY_TROUBLESHOOTING.md:23
The third bullet references "the remapped key" without anchoring it to the Karabiner-Elements setup described in the preceding bullet. A user who skips straight to the Stream Deck option (or who uses a different remapping tool) will not know what "the remapped key" refers to. Making the phrase self-contained removes that ambiguity.

```suggestion
- To use `F18` with Stream Deck, first follow the Karabiner-Elements step above to create a key that emits `F18`, then use that key to enter `F18` in Stream Deck's Hotkey action field, and finally press that Stream Deck button while FluidVoice is recording its shortcut.
```

_{Reviews (1): Last reviewed commit: "docs: add hotkey troubleshooting guide" | Re-trigger Greptile}

[greptile-apps]

The third bullet references "the remapped key" without anchoring it to the Karabiner-Elements setup described in the preceding bullet. A user who skips straight to the Stream Deck option (or who uses a different remapping tool) will not know what "the remapped key" refers to. Making the phrase self-contained removes that ambiguity.

Suggested change

	- To use `F18` with Stream Deck, use the remapped key to enter `F18` in Stream Deck's Hotkey action field, then press that Stream Deck button while FluidVoice is recording its shortcut.
	- To use `F18` with Stream Deck, first follow the Karabiner-Elements step above to create a key that emits `F18`, then use that key to enter `F18` in Stream Deck's Hotkey action field, and finally press that Stream Deck button while FluidVoice is recording its shortcut.

Prompt To Fix With AI

This is a comment left during a code review.
Path: docs/HOTKEY_TROUBLESHOOTING.md
Line: 23

Comment:
The third bullet references "the remapped key" without anchoring it to the Karabiner-Elements setup described in the preceding bullet. A user who skips straight to the Stream Deck option (or who uses a different remapping tool) will not know what "the remapped key" refers to. Making the phrase self-contained removes that ambiguity.

```suggestion
- To use `F18` with Stream Deck, first follow the Karabiner-Elements step above to create a key that emits `F18`, then use that key to enter `F18` in Stream Deck's Hotkey action field, and finally press that Stream Deck button while FluidVoice is recording its shortcut.
```

How can I resolve this? If you propose a fix, please make it concise.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[postoso]

The docs gap here is real — README Quick Start step 3 just says "pick a global hotkey," and there's no troubleshooting entry point, so users hitting this have nowhere to land. Some notes from reading the PR against current main:

1. Worth linking Discussion #538. That's the live, still-unanswered Q&A thread (Logitech M720, side button not detectable) that this guide's first section answers directly. Both issues currently linked are closed — #411 shipped, and #622 was auto-closed by the stale bot on 2026-07-23 without a resolution — so #538 is the only open thread this is anchored to. Suggest Related to #411, #538, and #622. in the PR body.

2. Concrete version of Greptile's discoverability point — one line in README Quick Start step 3:

3. Set your hotkey — pick a global hotkey in settings that triggers voice capture from anywhere. If a mouse button or function key won't register, see Hotkey Troubleshooting.

Without it the guide is only reachable by browsing docs/, which today holds one internal engineering plan.

3. The F13–F19 section's premise may be inverted. HotkeyShortcut.keyCodeToString has no cases for the function keys, so it falls through to characterForKeyCode (UCKeyTranslate) and then the QWERTY fallback table — neither covers them. Probing that same UCKeyTranslate path locally, it returns nothing usable for the F13–F19 keycodes (and for F1–F12/F20 as well), so displayString falls through to the literal "?".

If that holds, a physical F18 press during capture is accepted and stored — matches() compares keycode and flags, not the label — it just renders in the settings pill as ? (or 🌐 + ?) rather than F18. That would be a display bug being documented as intended behavior. Fixing the label is a handful of cases in keyCodeToString, covering F1–F20; happy to open that separately if it's wanted. @alexdcesm, could you confirm what the pill shows after you capture F18 on your Stream Deck setup? You have the hardware and I don't.

4. The closing line may promise more than the app delivers. "After FluidVoice records F18, any device configured to emit the same F18 event can trigger dictation" — #622, linked from this PR, reports exactly that not holding (SteerMouse emitting the configured combination didn't trigger, while the keyboard and System Events keystroke did), and it was closed as stale rather than fixed. Matching also requires identical modifier flags, and .function is derived from maskSecondaryFn; I haven't tested whether a Stream Deck-posted F18 carries that bit. I'd soften the sentence to note it depends on the emitting tool.

Mouse section looks accurate against the capture path, and +1 to Greptile's Stream Deck wording fix.