From 53d3d3b0c6276c26c3cebe19ff2da75665e4b047 Mon Sep 17 00:00:00 2001 From: Christian Colglazier Date: Thu, 29 Oct 2026 17:37:24 -0400 Subject: [PATCH] docs(agents): document macos keyboard pitfalls --- AGENTS.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 2add3bb..4271bca 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -130,6 +130,11 @@ python3 -m py_compile ./home/bin/homeassistant.py - **requests** - HTTP library - **dateutil** - Date utilities +## Common Pitfalls + +- **Physical keys are not necessarily logical modifiers on macOS.** The physical Control key is mapped to Command in this setup, so Ghostty shortcuts using that key need `super`, not `ctrl`. Do not assume the user means Caps Lock when they ask for Control-key shortcuts. +- Before changing keyboard shortcuts, inspect the active mappings with `defaults -currentHost read -g` (look for `com.apple.keyboard.modifiermapping.*`) and `~/.config/karabiner/karabiner.json`. Mappings can vary by keyboard; verify locally instead of asking the user to identify them or relying only on repository presets. + ## Development Notes - This is a personal configuration repository, not a library