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

```xml
<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
<?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:

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

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

```diff
-      <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`):

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

```sh
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

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