From 09220186ffe7c294cc423f2b72cca391e03fb30f Mon Sep 17 00:00:00 2001
From: Sam & Claude <hello@clawdie.si>
Date: Sun, 17 May 2026 07:33:52 +0200
Subject: [PATCH] Expand operator USB rebuild and runtime checks
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Document head verification before builds, add post-flash filesystem and XKB runtime probes, and include the read-write root/no tmpfs overlay expectations in the hardware acceptance checklist.

---

Build: pass — sh -n build.sh

Tests: pass — git diff --check
---
 BUILD.md   |  4 ++++
 TESTING.md | 44 +++++++++++++++++++++++++++++++++++++++++---
 2 files changed, 45 insertions(+), 3 deletions(-)

diff --git a/BUILD.md b/BUILD.md
index 4aa44cfd..90b1d03c 100644
--- a/BUILD.md
+++ b/BUILD.md
@@ -47,6 +47,10 @@ and other keys are available.
 ## Quick Start
 
 ```sh
+# Confirm you are building the intended branch/head first.
+git status --short --branch
+git log --oneline -5
+
 # Full build: fetch + assemble.
 sudo ./build.sh
 ```
diff --git a/TESTING.md b/TESTING.md
index d359affa..63f3c392 100644
--- a/TESTING.md
+++ b/TESTING.md
@@ -213,6 +213,10 @@ From the live desktop or a tty:
 
 ```sh
 id clawdie
+mount | egrep ' on / | on /tmp | on /var '
+df -h / /tmp /var
+egrep 'root_rw_mount|tmpmfs|varmfs|lightdm|display_manager|clawdie_live_gpu|kld_list|zfs' /etc/rc.conf /etc/rc.conf.local 2>/dev/null
+ls -ld /var/lib/xkb /tmp /var/tmp /usr/local/share/X11/xkb /usr/local/share/X11/xkb/keycodes
 service dbus onestatus
 service lightdm onestatus
 cat /usr/local/etc/lightdm/lightdm.conf.d/50-clawdie-live.conf
@@ -220,6 +224,12 @@ cat /var/log/clawdie-live-gpu.log
 kldstat | egrep 'i915|amdgpu|radeon|vmwgfx|nvidia|linux|zfs'
 ```
 
+Expected filesystem state:
+
+- `/` is mounted read-write from `/dev/ufs/FreeBSD_Install`
+- `/tmp` and `/var` are **not** separate tmpfs mounts
+- `/var/lib/xkb` exists and is writable for XKB cache generation
+
 Then verify operator tools:
 
 ```sh
@@ -274,16 +284,42 @@ cat /var/log/clawdie-live-gpu.log
 ls -ld /usr/local/share/X11
 ls -ld /usr/local/share/X11/xkb
 ls -ld /usr/local/share/X11/xkb/keycodes
+ls -ld /var/lib/xkb /tmp /var/tmp
 ls -l /usr/local/share/X11/xkb/keycodes/xfree86
 pkg info -e xkeyboard-config xkbcomp xorg-server xorg-minimal
 ```
 
+If X is already running, compile the active keymap:
+
+```sh
+setxkbmap -print | xkbcomp -w 10 -xkm - /tmp/clawdie-xkb-test.xkm
+echo $?
+rm -f /tmp/clawdie-xkb-test.xkm
+```
+
+If X is not running, compile a default keymap against the installed XKB tree:
+
+```sh
+cat > /tmp/clawdie-xkb-default-test.xkb <<'EOF'
+xkb_keymap {
+  xkb_keycodes { include "xfree86+aliases(qwerty)" };
+  xkb_types { include "complete" };
+  xkb_compat { include "complete" };
+  xkb_symbols { include "pc+us+inet(evdev)" };
+  xkb_geometry { include "pc(pc105)" };
+};
+EOF
+xkbcomp -w 10 -R/usr/local/share/X11/xkb /tmp/clawdie-xkb-default-test.xkb /tmp/clawdie-xkb-default-test.xkm
+echo $?
+rm -f /tmp/clawdie-xkb-default-test.xkb /tmp/clawdie-xkb-default-test.xkm
+```
+
 ### Check the actual running config
 
 ```sh
-egrep 'lightdm|display_manager|clawdie_live_gpu|kld_list|zfs' /etc/rc.conf
-mount
-df -h
+egrep 'root_rw_mount|tmpmfs|varmfs|lightdm|display_manager|clawdie_live_gpu|kld_list|zfs' /etc/rc.conf /etc/rc.conf.local 2>/dev/null
+mount | egrep ' on / | on /tmp | on /var '
+df -h / /tmp /var
 ```
 
 ### Manual X session probe
@@ -313,6 +349,8 @@ Mark the image good only when all of these are true:
 - [ ] image boots from USB on real hardware
 - [ ] LightDM autologins as `clawdie`
 - [ ] XFCE panel and desktop appear
+- [ ] `/` is read-write and `/tmp`/`/var` are not installer tmpfs overlays
+- [ ] `/var/lib/xkb` exists and XKB keymap compilation succeeds
 - [ ] `clawdie_live_gpu` log shows a sensible path or a clear fallback
 - [ ] NetworkMgr tray icon appears
 - [ ] Chromium opens