docs: capture agent workflow decisions

docs/00 INBOX/ai/caps-escape-design.md

@@ -0,0 +1,39 @@
+# Caps Escape Design
+
+## Facts
+
+- Commit `250b0b71f` removed `services.xserver.xkb.options` from the shared host module.
+- The removed option was `caps:escape_shifted_capslock`.
+- That XKB option maps Caps Lock to Escape.
+- Shift+Caps Lock still enables Caps Lock.
+- The shared host module configures Neogaia, Zeus, and Pikachu.
+- Zeus has QMK firmware that provides equivalent keyboard behavior.
+- Neogaia and Zeus enable `modules.host.cachyos` and `modules.desktop`.
+- Pikachu enables neither module.
+- `configs/nixos/hosts/neogaia/default.nix` directly sets Neogaia-specific hardware, networking, desktop application, and Waybar settings.
+- The current configuration has no Caps Lock or Escape remapping.
+- This session runs on Zeus, not Neogaia.
+
+## Design Tree
+
+- Restore Caps Lock behavior
+  - Scope the configuration
+    - Configure Neogaia only. ✓
+  - Select the mapping behavior.
+    - Restore `caps:escape_shifted_capslock`. ✓
+    - Set `services.xserver.xkb.options` in `configs/nixos/hosts/neogaia/default.nix`. ✓
+  - Define validation for Neogaia.
+    - Run static checks and manually verify both keys after deployment. ✓
+    - Stop after source and static validation. ✓
+
+## Settled Decisions
+
+1. Configure the mapping on Neogaia only.
+2. Restore `caps:escape_shifted_capslock`.
+3. Set `services.xserver.xkb.options` directly in Neogaia's host configuration.
+4. Run static checks and manually verify both keys on Neogaia after deployment.
+5. Stop after source and static validation.
+
+## Frontier
+
+None.