From 57df438ae39483746e600d857adc9f6d7246e723 Mon Sep 17 00:00:00 2001 From: Zuckerberg Date: Tue, 24 Mar 2026 21:58:58 -0700 Subject: [PATCH] Update readme --- README.md | 30 +++++++++++++++++++++++------- 1 file changed, 23 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index df8c861..874ad22 100644 --- a/README.md +++ b/README.md @@ -21,24 +21,36 @@ Four modes, indicated by RGB flash color: | Input (Linux muscle memory) | Output (macOS) | Action | |---|---|---| -| Ctrl+C/V | Cmd+C/V | Copy/Paste | +| Ctrl+C/V | Cmd+C/V | Copy/Paste (skipped in Terminal — Ctrl+C = SIGINT) | | Ctrl+Shift+C/V | Cmd+C/V | Terminal copy/paste | | Ctrl+X/A/S/F | Cmd+X/A/S/F | Cut, Select All, Save, Find | +| Ctrl+D | Cmd+D | Bookmark / select next occurrence (skipped in Terminal) | +| Ctrl+Shift+F | Cmd+Shift+F | Find in files | +| Ctrl+P | Cmd+Shift+O (Xcode) / Cmd+P (other) | Quick open | +| Ctrl+Shift+P | Cmd+Shift+A (Xcode) / Cmd+Shift+P (other) | Command palette / Quick Actions | | Ctrl+W/L/R | Cmd+W/L/R | Close tab, Address bar, Reload | | Ctrl+Z/T/N | Cmd+Z/T/N | Undo, New tab, New window | | Ctrl+Shift+Z/T/N | Cmd+Shift+Z/T/N | Redo, Reopen tab, Incognito | | Ctrl+Left/Right | Alt+Left/Right | Word navigation | +| Ctrl+Shift+Left/Right | Alt+Shift+Left/Right | Word selection | | Ctrl+Alt+Left/Right | Ctrl+Left/Right | Switch workspace | | Ctrl+Backspace | Alt+Backspace | Delete word | -| Home/End | Cmd+Left/Right | Line start/end | +| Home/End | Ctrl+A/E (Terminal) / Cmd+Left/Right (other) | Line start/end | | Alt+F4 | Cmd+Q | Quit app | | Alt+Tab | Cmd+Tab | App switcher | | Super tap | Cmd+Space | Spotlight | | Super+Up | Ctrl+Up | Mission Control | +| Ctrl hold (Xcode/VSCode) | Cmd hold | Ctrl-as-Cmd for mouse clicks (e.g. jump to symbol) | -#### Layer Override +#### App-Aware Remaps -When any modifier is held (in any mode except None), the FN layer is bypassed — keys always resolve from Layer 0. This allows bypassing shortcut rewrites when wanted. For example, if you want to send Ctrl+c on mac (which is normally rewritten to cmd+c), simply use fn+Ctrl+c instead. +Some rules are per-app: Terminal.app and iTerm2 let Ctrl+C/V/D pass through so signals and shell shortcuts work, while Xcode and VSCode get IDE-specific bindings for Ctrl+P and Ctrl+Shift+P. + +App awareness requires the **mac-agent** ([`mac-agent/`](mac-agent/)) running on the host. It sends the focused app name to the keyboard over Raw HID. Without it, all apps are treated as "unknown" and generic rules apply. + +#### NOREMAP Key + +The right FN key has been replaced with a dedicated **NOREMAP** key. Hold it to bypass all shortcut remaps — the keypress is sent exactly as typed. Useful when you need the original Ctrl+key behavior on macOS. ### Layer 1 (FN Layer) @@ -48,11 +60,10 @@ When any modifier is held (in any mode except None), the FN layer is bypassed | F1/F2/F3 | Mute / Vol Down / Vol Up | | 1/2/3 | Play-Pause / Prev / Next | | 0/-/= | LED Toggle / LED Down / LED Up | +| Backspace | Cycle RGB Effect | | Del | Cycle OS Mode | | Arrows | Home / PgDn / PgUp / End | -Modifier keys (Shift, Ctrl, GUI, Alt) cannot be rebound on Layer 1 due to the layer override behavior. - ## Building Requires [Nix](https://nixos.org/) with flakes enabled. @@ -79,10 +90,15 @@ qmk compile -kb system76/launch_3 -km custom ``` keymaps/custom/ -├── keymap.c # Keymaps, shortcut rewrites, layer override +├── keymap.c # Keymaps, remap rules engine, process_record_user ├── os_detect.c # OS auto-detection, RGB flash indicator ├── os_mode.h # OS mode enum and shared state +├── app_focus.c # Raw HID handler for focused-app notifications +├── app_focus.h # Focused app enum and extern +├── config.h # RGB matrix effect enables └── rules.mk # QMK build flags +mac-agent/ # macOS daemon that sends focused app to keyboard (see mac-agent/README.md) +patches/ # Patches applied to QMK submodule at build time qmk_firmware/ # System76 QMK fork (git submodule) flake.nix # Nix build system ```