diff --git a/docs/BUILDER-INSTRUCTIONS.md b/docs/BUILDER-INSTRUCTIONS.md new file mode 100644 index 00000000..b994ad23 --- /dev/null +++ b/docs/BUILDER-INSTRUCTIONS.md @@ -0,0 +1,243 @@ +# ISO Builder Instructions — Live USB Desktop Layout (2026-06-04) + +## Overview + +These changes bake the tested operator desktop layout into the ISO so it ships +ready-to-use with dual-monitor support, a locked panel on the laptop display, +branded wallpaper on all monitors, correct 48px icons, a DNS-ready hostname, +and no ASUS ACPI noise. + +All of this was live-tested across multiple reboots on the operator laptop +(ASUS + Philips 58" HDMI rotated 270°). Three companion branches already exist, +and the remaining XFCE skel / rc.conf changes are described below. + +--- + +## Branch 1: `fix/remove-xfce-visuals-guard` (already pushed) + +Removes the runtime visuals guard that masked static config problems. + + commit c525e4e — Remove XFCE visuals runtime guard + + Files removed: + live/operator-session/clawdie-xfce-visuals-guard.sh + live/operator-session/autostart/clawdie-xfce-visuals-guard.desktop + build.sh — 4 lines (two install blocks) + hw-report — 1 line (log capture) + + Live-tested: guard gone across reboots, no-blank guard still runs. + +## Branch 2: `fix/xfce-start-icon-48` (already pushed) + +Fixes duplicate 64×64 PNG masquerading as the 48×48 Whiskermenu icon. + + commit fa72fdd — Install native 48px start icon + + New file: + live/operator-session/icons/clawdie-start-48.png (1364 bytes, 48×48) + + build.sh change: + Installs clawdie-start-48.png → hicolor/48x48/apps/clawdie-start.png + (was previously copying the 64px PNG into the 48px slot) + + Hashes differ: + 48x48: 651799521d6bc12eaf39339cfe3327a9 + 64x64: 1b9380231934417f49bcbe4237c29aa5 + + Live-tested: icon cache regenerated, panel picks up proper sizes. + +--- + +## Branch 3 (new): Desktop layout, hostname, and ACPI cleanup + +### 3a. XFCE panel — lock to laptop display + +**File:** `live/operator-session/panel-skel/.config/xfce4/xfconf/xfce-perchannel-xml/xfce4-panel.xml` + +Add one line inside the `` block, after +``: + + + +This keeps the taskbar on the laptop display when an external monitor is +connected, regardless of which monitor XFCE considers "first". + +### 3b. Desktop wallpaper — both monitors + +**File:** `live/operator-session/panel-skel/.config/xfce4/xfconf/xfce-perchannel-xml/xfce4-desktop.xml` + +Inside ``, after the existing +`monitoreDP` block, add: + +```xml + + + + + + + + + +``` + +**CRITICAL:** Ensure all wallpaper property values are **scalars**, not arrays. +xfdesktop silently ignores array-typed values. The symptom is a monitor +falling back to the default XFCE background. In the XML this means: + + GOOD: + BAD: ← use type="string" instead + +### 3c. Displays layout — dual-monitor with rotated HDMI + +**New file:** `live/operator-session/panel-skel/.config/xfce4/xfconf/xfce-perchannel-xml/displays.xml` + +```xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +``` + +Layout summary: +- HDMI-A-0: 1920×1080, rotated 270° (vertical), position (0,0), NOT primary +- eDP (laptop): 1920×1080, rotation 0°, PRIMARY, position (1080,840) +- The laptop sits to the right of the rotated HDMI, centered vertically. + +### 3d. build.sh — copy displays.xml to system location + +**File:** `build.sh`, in the panel-skel seeding block (~line 1549) + +The existing loop copies xsettings.xml, xfwm4.xml, xfce4-desktop.xml, and +xfce4-power-manager.xml. Add `displays.xml` to that list: + +```diff +- for _xfconf_xml in xsettings.xml xfwm4.xml xfce4-desktop.xml xfce4-power-manager.xml; do ++ for _xfconf_xml in xsettings.xml xfwm4.xml xfce4-desktop.xml xfce4-power-manager.xml displays.xml; do +``` + +### 3e. Hostname — set to `usb.clawdie.home.arpa` + +**File:** `build.sh`, around line 1361 + +```diff +- set_config_line "${MOUNT_POINT}/etc/rc.conf" 'hostname="clawdie-live"' ++ set_config_line "${MOUNT_POINT}/etc/rc.conf" 'hostname="usb.clawdie.home.arpa"' +``` + +Also update the grep check on the next line: +```diff +- if ! grep -Eq '^hostname="clawdie-live"' "${MOUNT_POINT}/etc/rc.conf"; then ++ if ! grep -Eq '^hostname="usb.clawdie.home.arpa"' "${MOUNT_POINT}/etc/rc.conf"; then +``` + +### 3f. Remove ASUS ACPI modules from kld_list + +**File:** `build.sh`, around line 1401 + +```diff +- # acpi_asus / acpi_asus_wmi — ASUS-laptop fn-keys, hotkeys, fan control. No-op on non-ASUS hardware. + append_rc_list_values "${MOUNT_POINT}/etc/rc.conf" kld_list \ + linux linux64 zfs \ + cuse \ + hidbus iichid hms hmt hkbd \ +- acpi_video acpi_asus acpi_asus_wmi ++ acpi_video +``` + +Also remove the comment line about acpi_asus/acpi_asus_wmi. + +These modules cause ~50 lines of `AE_AML_BUFFER_LIMIT` ACPI errors per boot +on the operator laptop. Removing them eliminates the spam with no functional +loss (fn-keys continue to work via the standard acpi_video module). + +--- + +## Verification checklist (post-build boot) + +| # | Test | Expected | +|---|---|---| +| 1 | `dmesg \| grep -c AE_AML_BUFFER_LIMIT` | 0 | +| 2 | `kldstat \| grep asus` | (empty) | +| 3 | `hostname` | `usb.clawdie.home.arpa` | +| 4 | Panel on laptop display | taskbar on eDP, not HDMI | +| 5 | Wallpaper on both monitors | clawdie-operator-bg.png on laptop + TV | +| 6 | HDMI rotation | 270° (vertical) | +| 7 | Clawdie-start icon | isn't fuzzy/misplaced | +| 8 | Visuals guard | absent (`/usr/local/bin/clawdie-xfce-visuals-guard.sh` → no such file) | +| 9 | No-blank guard | runs (check `~/.clawdie-noblank-guard.log`) | +| 10 | `xfconf-query -c xfce4-desktop -p /backdrop/screen0 -lv` | All `image-path`/`last-image` values are **scalars** (no `[...]` brackets) | + +--- + +## File summary + +``` +Files to create: + live/operator-session/panel-skel/.config/xfce4/xfconf/xfce-perchannel-xml/displays.xml + +Files to modify: + build.sh (hostname, kld_list, displays.xml loop) + live/operator-session/panel-skel/.config/xfce4/xfconf/xfce-perchannel-xml/xfce4-panel.xml (+output-name) + live/operator-session/panel-skel/.config/xfce4/xfconf/xfce-perchannel-xml/xfce4-desktop.xml (+monitorHDMI-A-0 block) + +Already on branches: + live/operator-session/icons/clawdie-start-48.png (branch fix/xfce-start-icon-48) + live/operator-session/clawdie-xfce-visuals-guard.sh (deleted on fix/remove-xfce-visuals-guard) + live/operator-session/autostart/clawdie-xfce-visuals-guard.desktop (deleted) +``` + +--- + +## Build and test + +```sh +# 1. Merge all three branches into a release branch +git checkout main +git merge fix/xfce-start-icon-48 +git merge fix/remove-xfce-visuals-guard +git merge fix/desktop-layout-and-hostname # the new branch with 3a-3f + +# 2. Build ISO as usual +./build.sh + +# 3. Flash to USB and boot on operator laptop +# 4. Run the verification checklist above +```