[hetaoBackend]

Change

When macOS/Ghostty sends µ for Option+M, the TUI receives text instead of the permission shortcut. Document how to configure macos-option-as-alt, inspect the loaded configuration, or use the existing /permission command and /hotkeys customization. Include a profile-aware keybindings.json example using Ctrl+X and steps to verify the resulting permission mode.

The guide distinguishes permission cycling (composer.cycle-permission, Alt+M) from Plan mode (Shift+Tab), corrects the layout-dependent Ghostty default using the official reference, and explains the difference between legacy Alt and negotiated keyboard reports. Literal µ input and runtime bindings are unchanged. Refs #214.

Validation

On commit f75527909ecff1039a1f1beb7593c2102687bfb3:

• PASS: git diff --check; changed paths classify as documentation only.
• PASS: pnpm verify --profile docs on clean committed HEAD, macOS: all 4 applicable gates; release-tool tests 20 passed, 1 Windows-only test skipped.
• PASS: focused Vitest run of tui-keybindings.test.ts and hotkeys-picker.test.ts: 2 files, 16 tests.
• PASS: temporary offline source replay of legacy Alt+M, CSI-u, modifyOtherKeys, key-release filtering, literal µ text input, Shift+Tab, and persisted Ctrl+X replacement/alias configurations under both keyboard-protocol modes. Temporary scripts and reports remain outside the repository.
• NOT RUN: real Ghostty GUI keyboard/configuration acceptance (Ghostty is not installed), tmux/SSH, live services, Linux/Windows runtime tests, or the full build/runtime profile. This is a documentation-only change, with no claim of reproducing the reporter's effective configuration.

Publication and contribution checks

• I have permission to contribute these changes under the existing applicable licenses; no community patch was imported.
• No credentials, account data, internal history, or private review material is included.
• No added/removed files or new Vitest files; inventory regeneration is unnecessary.
• English documentation updated; no shared README translation or runtime capability changes. Offline results are not described as live acceptance.

Maintainer handoff

Publication scope and licenses unchanged. Shared-source port: not needed (public installation guide only).

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}