clawdie-iso/docs/BUILDER-INSTRUCTIONS.md

ISO Builder Instructions — Live USB Desktop Layout (04.jun.2026)

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 <property name="panel-1" type="empty"> block, after <property name="plugin-ids" type="array">:

<property name="output-name" type="string" value="eDP"/>

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 <property name="screen0" type="empty">, after the existing monitoreDP block, add:

<property name="monitorHDMI-A-0" type="empty">
  <property name="workspace0" type="empty">
    <property name="color-style" type="int" value="0"/>
    <property name="image-path" type="string" value="/usr/local/share/clawdie-iso/wallpapers/clawdie-operator-bg.png"/>
    <property name="image-show" type="bool" value="true"/>
    <property name="image-style" type="int" value="5"/>
    <property name="last-image" type="string" value="/usr/local/share/clawdie-iso/wallpapers/clawdie-operator-bg.png"/>
  </property>
</property>

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:  <property … type="string" value="/path/to/wallpaper"/>
BAD:   <property … type="array">  ← 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 version="1.1" encoding="UTF-8"?>

<channel name="displays" version="1.0">
  <property name="ActiveProfile" type="string" value="Default"/>
  <property name="Notify" type="int" value="1"/>
  <property name="AutoEnableProfiles" type="int" value="3"/>
  <property name="Default" type="empty">
    <property name="HDMI-A-0" type="string" value="Philips Consumer Electronics Company 58&quot;">
      <property name="Active" type="bool" value="true"/>
      <property name="EDID" type="string" value="eb3a88b3e924dff0eef60b51ede5d142f7854918"/>
      <property name="DuplicateEDID" type="bool" value="false"/>
      <property name="Resolution" type="string" value="1920x1080"/>
      <property name="RefreshRate" type="double" value="60"/>
      <property name="ModeFlags" type="uint64" value="5"/>
      <property name="Rotation" type="int" value="270"/>
      <property name="Reflection" type="string" value="0"/>
      <property name="Primary" type="bool" value="false"/>
      <property name="Scale" type="double" value="1"/>
      <property name="Position" type="empty">
        <property name="X" type="int" value="0"/>
        <property name="Y" type="int" value="0"/>
      </property>
    </property>
    <property name="eDP" type="string" value="Laptop">
      <property name="Active" type="bool" value="true"/>
      <property name="EDID" type="string" value="094c68e1cb71ed69083c70a30d0d951ed88f1a73"/>
      <property name="DuplicateEDID" type="bool" value="false"/>
      <property name="Resolution" type="string" value="1920x1080"/>
      <property name="RefreshRate" type="double" value="60.003425830763959"/>
      <property name="ModeFlags" type="uint64" value="9"/>
      <property name="Rotation" type="int" value="0"/>
      <property name="Reflection" type="string" value="0"/>
      <property name="Primary" type="bool" value="true"/>
      <property name="Scale" type="double" value="1"/>
      <property name="Position" type="empty">
        <property name="X" type="int" value="1080"/>
        <property name="Y" type="int" value="840"/>
      </property>
    </property>
  </property>
</channel>

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:

- 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

- 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:

- 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

- #   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).

3g. xkb keyboard plugin — show flag instead of text label

File: live/operator-session/panel-skel/.config/xfce4/xfconf/xfce-perchannel-xml/xfce4-panel.xml

The xkb plugin (plugin-10) was showing the language code "si" as text. Change display-type from 1 (text label) to 0 (image/flag only):

-      <property name="display-type" type="uint" value="1"/>
+      <property name="display-type" type="uint" value="0"/>

3h. Clock format — 2-digit year

File: live/operator-session/panel-skel/.config/xfce4/xfconf/xfce-perchannel-xml/xfce4-panel.xml

Truncate the 4-digit year (2026) to 2 digits (26):

-      <property name="digital-format" type="string" value="%H:%M %d.%b.%Y"/>
+      <property name="digital-format" type="string" value="%H:%M %d.%b.%y"/>

3i. Icon cache note

After build, all icon caches regenerate automatically via the package post-install scripts. On the live system, if icons appear dotted/broken after updating icon files, run:

for theme in Papirus Papirus-Dark Papirus-Light hicolor Adwaita; do
    gtk-update-icon-cache -f /usr/local/share/icons/$theme
done
pkill xfce4-panel; DISPLAY=:0 xfce4-panel &

---

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	clearly rendered, not fuzzy/misplaced
8	xkb plugin	shows flag icon, not "si" text
9	Clock format	shows 2-digit year (e.g., 06:23 04.Jun.26)
10	Visuals guard	absent (/usr/local/bin/clawdie-xfce-visuals-guard.sh → no such file)
11	No-blank guard	runs (check ~/.clawdie-noblank-guard.log)
12	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, xkb flag, 2-digit year)
  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

# 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