From 129ae0849d7a2410f27139ef59951b0004aade1f Mon Sep 17 00:00:00 2001
From: Sam Rolfe <samuelrolfe@gmail.com>
Date: Thu, 4 Jun 2026 20:09:35 +1000
Subject: [PATCH] skill: add keyboard troubleshooting section (VIA Web, udev,
 caps lock)

---
 skills/nixos-workflow/SKILL.md | 36 ++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/skills/nixos-workflow/SKILL.md b/skills/nixos-workflow/SKILL.md
index 921c97b..3ec5a11 100644
--- a/skills/nixos-workflow/SKILL.md
+++ b/skills/nixos-workflow/SKILL.md
@@ -35,3 +35,39 @@ When the user asks for a new tool or skill, you MUST follow these steps exactly:
 ## ❄ NIXOS INTEGRATION
 The ONLY time you reference Nix is for the **Global Settings**. Confirm the user's `home.nix` contains a `settings.json` that points to the Gitea source:
 `"source": "git:https://gitea.lab.audasmedia.com.au/sam/pi-config"`
+
+## 🖥 PI INSTALLATION CONTEXT
+On this system, `pi` is a shell script wrapper defined in `home.nix`:
+```
+${pkgs.nodejs_24}/bin/npx @mariozechner/pi-coding-agent "$@"
+```
+- **`pi update --self` will always fail** — npx manages freshness automatically; `pi update --extensions` works fine.
+- **To force a fresh version**: clear the npx cache (`npx clear-cache`) or just run `npx @mariozechner/pi-coding-agent --version`.
+- **Global npm install does NOT apply here** — NixOS manages the wrapper, not `npm install -g`.
+- **Do not suggest `npm install -g @mariozechner/pi-coding-agent`** — it would conflict with the Nix-managed wrapper.
+- **The binary runs from**: `/home/sam/.npm/_npx/<cache-hash>/node_modules/.bin/pi` (npx cache, not a managed install).
+
+## ⌨ KEYBOARD TROUBLESHOOTING (Corne/QMK)
+
+The user has a Corne-like QMK keyboard. These are critical things to remember:
+
+### Caps lock stuck ON
+If all letters output uppercase and Shift inverts to lowercase, the Lower/Raise layer keys may be reversed in the keymap. **Do NOT suggest hardware resets or firmware flashing.**
+
+**Fix**: Use VIA Web at https://usevia.app — it works immediately in Chrome via WebHID (no install needed). The user can identify and remap misconfigured keys there.
+
+### udev setup for VIA/Vial Web
+Required in `configuration.nix`:
+```nix
+services.udev.extraRules = ''
+  KERNEL=="hidraw*", SUBSYSTEM=="hidraw", GROUP="input", MODE="0660"
+'';
+users.users.sam.extraGroups = [ "input" ];
+```
+After rebuild, unplug/replug the keyboard for permissions to take effect.
+
+### Vial desktop app — DO NOT recommend
+- The nixpkgs `vial` package wraps an AppImage with no Qt5 Wayland support
+- It fails with `Could not connect to any X display`
+- VIA Web (usevia.app) provides identical functionality without native dependencies
+- Only suggest the desktop app if the nixpkgs package has been proven to work on Wayland