Sam & Claude
61683eeb42
Convert US/ISO prose dates to EU format across iso docs (CHANGELOG, plans, handoffs, wiki-linked docs). Left as-is (data, not prose): the sample log lines in FIRSTBOOT.md and the ADMIN-PANEL.md UI mockup (timestamps/snapshot names); ISO is correct for machine output. Markdown format gate clean.
283 lines
12 KiB
Markdown
283 lines
12 KiB
Markdown
# 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:
|
||
|
||
```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"">
|
||
<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
|
||
```
|