v0.0.33 - Implement in-place mnemonic entry grid with staged prefix selection and fix stage-3 candidate rendering

documents/QUBES_OS.md

@@ -160,6 +160,58 @@ Includes:
 - missing policy -> deny path
 - missing `QREXEC_REMOTE_DOMAIN` -> fallback identity path
 
+## 5.5 USB keyboard firmware workflows in a PCI-USB-controller qube
+
+When a full USB controller is assigned directly to a qube via PCI passthrough, HID input does **not** flow through `sys-usb` input proxy policy. In this setup, keyboard-class USB blocking is usually caused by `usbguard` inside the owning qube.
+
+### Scope check (dom0)
+
+```bash
+qvm-prefs AI klass
+```
+
+- `StandaloneVM`: service state changes in the qube root filesystem persist.
+- `AppVM`: root filesystem state resets at reboot; use `/rw/config/rc.local` for per-qube persistence.
+
+### Disable usbguard immediately (inside AI qube)
+
+```bash
+sudo systemctl disable --now usbguard
+sudo systemctl mask usbguard
+```
+
+### Persist behavior across reboot
+
+- **StandaloneVM**: the mask persists as-is.
+- **AppVM**: persist with `/rw/config/rc.local`:
+
+```bash
+sudo tee /rw/config/rc.local >/dev/null <<'EOF'
+#!/bin/sh
+systemctl stop usbguard 2>/dev/null || true
+systemctl mask usbguard 2>/dev/null || true
+EOF
+sudo chmod +x /rw/config/rc.local
+```
+
+### Restart + verify
+
+```bash
+# dom0
+qvm-shutdown --wait AI && qvm-start AI
+
+# inside AI qube
+systemctl is-enabled usbguard
+lsusb
+ls /dev/ttyACM*
+```
+
+Expected result: `usbguard` is `masked`, the keyboard-class device enumerates, and serial/WebUSB workflows remain usable.
+
+### Security trade-off
+
+Disabling `usbguard` removes an important BadUSB defense for that qube. Keep this configuration limited to a dedicated hardware-development qube and avoid using it for general browsing or untrusted USB devices.
+
 ---
 
 ## 6. Security requirements