Add KVM switch documentation for Mac/Nobara setup

- DDC/CI monitor switching (Dell U3821DW)
- HID++ Logitech peripheral switching (MX Keys S, MX Master 3S)
- Scripts for bidirectional switching
- Troubleshooting guide and reference

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

docs/wip/KVM-SWITCH-MAC-NOBARA.md

@@ -0,0 +1,177 @@
+# One-Key KVM: Mac ↔ Nobara
+
+**Status:** WIP - Scripts created, needs testing  
+**Hardware:** Dell U3821DW, MX Keys S, MX Master 3S  
+**Updated:** 2026-02-01
+
+## Overview
+
+Software KVM solution to switch the Dell U3821DW ultrawide monitor and Logitech MX peripherals between Mac (MacBook Pro M3) and Nobara Linux using DDC/CI and HID++ commands.
+
+## Hardware Mapping
+
+### Monitor Inputs
+| Input | Code | Port | Computer |
+|-------|------|------|----------|
+| USB-C | 27 | USB-C | Mac |
+| HDMI 2 | 18 | HDMI 2 | Nobara |
+
+### Peripheral Channels
+| Channel | Code | Connection | Computer |
+|---------|------|------------|----------|
+| 1 | 0x00 | Bluetooth | Mac |
+| 2 | 0x01 | Logi Bolt USB | Nobara |
+
+### Devices
+- **Monitor:** Dell U3821DW (38" Ultrawide, DDC/CI enabled)
+- **Keyboard:** Logitech MX Keys S (Easy-Switch capable)
+- **Mouse:** Logitech MX Master 3S (Easy-Switch capable)
+- **Receiver:** Logi Bolt USB (PID: 046d:c548)
+
+## Prerequisites
+
+### Mac
+```bash
+# Install m1ddc (DDC control for Apple Silicon)
+brew install m1ddc
+
+# Install hidapitester (HID control)
+curl -sL https://github.com/todbot/hidapitester/releases/latest/download/hidapitester-macos-arm64.zip -o /tmp/hidapitester.zip
+unzip -o /tmp/hidapitester.zip -d ~/bin/
+chmod +x ~/bin/hidapitester
+```
+
+### Nobara (Linux)
+```bash
+# Install ddcutil
+sudo dnf install ddcutil
+
+# Add user to i2c group (requires reboot)
+sudo usermod -aG i2c $USER
+
+# Install hidapitester
+curl -sL https://github.com/todbot/hidapitester/releases/latest/download/hidapitester-linux-amd64.zip -o /tmp/hidapitester.zip
+unzip -o /tmp/hidapitester.zip -d ~/bin/
+chmod +x ~/bin/hidapitester
+
+# Udev rule for non-root HID access
+echo 'SUBSYSTEM=="usb", ATTRS{idVendor}=="046d", ATTRS{idProduct}=="c548", MODE="0666"' | \
+  sudo tee /etc/udev/rules.d/99-logitech-bolt.rules
+sudo udevadm control --reload-rules && sudo udevadm trigger
+```
+
+## Scripts
+
+### Switch to Nobara (Run on Mac)
+**Location:** `~/scripts/to_nobara.sh`
+
+```bash
+#\!/bin/bash
+# KVM Switch: Mac → Nobara
+set -e
+
+echo "Switching to Nobara..."
+
+# Switch Monitor to HDMI 2
+m1ddc set input 18
+
+# Switch Mouse to Bolt (Channel 2)
+~/bin/hidapitester --vid 046d --pid c548 --usage 0x0001 --usagePage 0xff00 \
+    --open --length 7 --send-output "0x10,0x01,0x09,0x1b,0x01,0x00,0x00"
+
+# Switch Keyboard to Bolt (Channel 2)
+~/bin/hidapitester --vid 046d --pid c548 --usage 0x0001 --usagePage 0xff00 \
+    --open --length 7 --send-output "0x10,0x02,0x09,0x1b,0x01,0x00,0x00"
+
+echo "Done\!"
+```
+
+### Switch to Mac (Run on Nobara)
+**Location:** `~/scripts/to_mac.sh`
+
+```bash
+#\!/bin/bash
+# KVM Switch: Nobara → Mac
+set -e
+
+echo "Switching to Mac..."
+
+# Switch Monitor to USB-C
+ddcutil setvcp 60 27
+
+# Switch Mouse to Bluetooth (Channel 1)
+~/bin/hidapitester --vid 046d --pid c548 --usage 0x0001 --usagePage 0xff00 \
+    --open --length 7 --send-output "0x10,0x01,0x09,0x1b,0x00,0x00,0x00"
+
+# Switch Keyboard to Bluetooth (Channel 1)
+~/bin/hidapitester --vid 046d --pid c548 --usage 0x0001 --usagePage 0xff00 \
+    --open --length 7 --send-output "0x10,0x02,0x09,0x1b,0x00,0x00,0x00"
+
+echo "Done\!"
+```
+
+## Keyboard Shortcuts
+
+### Mac (Logi Options+)
+1. Logi Options+ → MX Keys S → Smart Actions
+2. Create "KVM Switch" action
+3. Trigger: F12
+4. Action: System → Open File → `~/scripts/to_nobara.sh`
+
+### Nobara (GNOME)
+1. Settings → Keyboard → Custom Shortcuts
+2. Command: `/home/USER/scripts/to_mac.sh`
+3. Shortcut: F12
+
+## Troubleshooting
+
+### Monitor doesn't switch
+- **DDC/CI disabled:** Monitor Menu → Others → DDC/CI → On
+- **USB-C hub blocking DDC:** Connect monitor directly to Mac USB-C port
+- **Linux permissions:** Ensure user in `i2c` group, reboot after adding
+
+### Peripherals don't switch
+- **Wrong device index:** The 0x01/0x02 values depend on Bolt pairing order
+  ```bash
+  # Find correct indices on machine with Bolt receiver
+  hidapitester --vid 046d --pid c548 --list-detail
+  ```
+- **Different Bolt PID:** Some receivers have different product IDs
+  ```bash
+  hidapitester --list | grep 046d
+  ```
+
+### HID++ Command Reference
+| Byte | Purpose | Values |
+|------|---------|--------|
+| 0x10 | Report ID (short) | Fixed |
+| 0x01/0x02 | Device index | Mouse=0x01, Keyboard=0x02 (may vary) |
+| 0x09 | Feature index | Change Host feature |
+| 0x1b | Function | Set host |
+| 0x00/0x01 | Channel | 0x00=Ch1, 0x01=Ch2, 0x02=Ch3 |
+
+## DDC Input Codes (Dell U3821DW)
+
+| Input | Code | Hex |
+|-------|------|-----|
+| DisplayPort 1 | 15 | 0x0F |
+| DisplayPort 2 | 16 | 0x10 |
+| HDMI 1 | 17 | 0x11 |
+| HDMI 2 | 18 | 0x12 |
+| USB-C | 27 | 0x1B |
+
+## Files Location
+
+Scripts are stored on Mac at `~/scripts/`:
+- `to_nobara.sh` - Switch to Nobara (run on Mac)
+- `to_mac.sh` - Switch to Mac (copy to Nobara)
+- `debug_kvm.sh` - Diagnostic script
+- `setup_nobara.sh` - Nobara setup script
+
+## TODO
+
+- [ ] Test monitor switching with DDC/CI enabled
+- [ ] Verify Bolt receiver PID on Nobara
+- [ ] Confirm device indices for keyboard/mouse
+- [ ] Set up keyboard shortcuts on both machines
+- [ ] Test bidirectional switching