layered-soul/skills/bootable-usb-images/references/xfce-icon-theme-branding-failures.md

# XFCE Icon Theme / Branding Failures on FreeBSD Live USB

Use this when the desktop starts (XFCE session, panel, window manager visible) but icons, wallpaper, or
branded panel elements are wrong: missing Start-button icon, default wallpaper instead of branding,
blank launcher icons in panel or Whisker menu.

This is a different failure class from Xorg/XKB/session startup — the desktop is running, but the
visual contract is broken.

## Live-session diagnostics

On the running USB, capture these first:

```sh
# What icon themes exist and have cached?
ls -d /usr/local/share/icons/*/
for d in /usr/local/share/icons/*/; do
  echo "$d: $(ls "$d"icon-theme.cache 2>/dev/null && echo cached || echo NO_CACHE)"
done

# Are the brand icons in hicolor?
find /usr/local/share/icons/hicolor -name 'clawdie*' 2>/dev/null
ls -l /usr/local/share/clawdie-iso/icons/ 2>/dev/null

# What icon theme is XFCE actually using?
xfconf-query -c xsettings -p /Net/IconThemeName 2>/dev/null
xfconf-query -c xfce4-panel -p /plugins/plugin-1/button-icon 2>/dev/null

# Is the branded wallpaper present?
ls -l /usr/local/share/clawdie-iso/wallpapers/clawdie-operator-bg.png 2>/dev/null
xfconf-query -c xfce4-desktop -l 2>/dev/null | grep 'last-image'
```

## Root cause patterns

### 1. XFCE plugins reject absolute icon paths

Symptom: Whiskermenu Start button shows a broken/missing icon glyph despite the PNG existing on disk.

Root cause: XFCE panel plugins (whiskermenu, launcher) do **not** reliably load absolute icon paths
like `/usr/local/share/clawdie-iso/icons/clawdie-start.png`. They resolve icons by themed name
through the standard icon-theme lookup chain (hicolor → Adwaita → Papirus → ...).

Fix in build.sh:

- Set `button-icon` to a themed name: `clawdie-start` (not an absolute path)
- Install the icon PNG+SVG into `hicolor/48x48/apps/`, `hicolor/64x64/apps/`, and `hicolor/scalable/apps/`
- Run `gtk-update-icon-cache -f -t /usr/local/share/icons/hicolor` after installing

### 2. Brand icons not in the icon theme search path

Symptom: themed icon name resolves to nothing — icon appears blank — even though the file exists
at a custom absolute path.

Root cause: Installing icons only into a custom directory like `/usr/local/share/clawdie-iso/icons/`
places them outside the icon theme search path. XFCE looks up themed names by scanning
`/usr/local/share/icons/<theme>/<size>/<category>/`. hicolor is the fallback theme.

Fix in build.sh:

```sh
mkdir -p /usr/local/share/icons/hicolor/48x48/apps
mkdir -p /usr/local/share/icons/hicolor/64x64/apps
mkdir -p /usr/local/share/icons/hicolor/scalable/apps
install -m 0644 clawdie-start.png /usr/local/share/icons/hicolor/48x48/apps/clawdie-start.png
install -m 0644 clawdie-start.png /usr/local/share/icons/hicolor/64x64/apps/clawdie-start.png
install -m 0644 clawdie-start.svg /usr/local/share/icons/hicolor/scalable/apps/clawdie-start.svg
gtk-update-icon-cache -f -t /usr/local/share/icons/hicolor
```

Also keep the original absolute-path copy in `/usr/local/share/clawdie-iso/icons/` for diagnostic
inspection; it just can't be the primary resolution path.

### 3. XFCE creates monitor-specific keys after xfdesktop starts

Symptom: wallpaper defaulting to stock (or missing) instead of the Clawdie branding defined in the
panel-skel XML — even though the XML is correct and the wallpaper file exists.

Root cause: On first boot, xfdesktop creates monitor-specific backdrop keys (e.g.
`/backdrop/screen0/monitorDP-1/workspace0/last-image`) that don't exist in the pre-seeded skeleton
XML. The skeleton only has `workspace0` and `workspace1` keys, which xfdesktop may ignore in favor
of monitor-specific ones it creates at runtime.

Fix: Add a post-login visual guard script that runs from XDG autostart and re-applies theme, panel
branding, and wallpaper at 3, 7, and 15 seconds after login. This catches monitor-specific keys
created during the startup race and writes the correct values into whichever keys exist at each tick.

Guard script pattern (best-effort, never fails the session):

```sh
# Run at 3s, 7s, 15s after login via XDG autostart
xfconf-query -c xfce4-desktop -p "${base}/last-image" -s "$WALLPAPER" 2>/dev/null || \
  xfconf-query -c xfce4-desktop -p "${base}/last-image" -n -t string -s "$WALLPAPER" 2>/dev/null || true
```

### 4. Icon caches stale for rarely-used themes

Symptom: application launcher icons (pcmanfm, xfce4-terminal, firefox) blank in panel launchers
or Whisker menu despite applications installed correctly.

Root cause: `gtk-update-icon-cache` was only run for a fixed list of known themes. Applications
install icons into hicolor (or other themes) during pkg install, but their directories weren't
in the hardcoded list.

Fix: scan ALL directories under `/usr/local/share/icons/` dynamically:

```sh
for _icon_theme_dir in /usr/local/share/icons/*/; do
    [ -d "$_icon_theme_dir" ] || continue
    _theme_name=$(basename "$_icon_theme_dir")
    gtk-update-icon-cache -f -t "/usr/local/share/icons/${_theme_name}" || true
done
```

## Build-time checks (before flashing)

When building the image, verify the icon contract:

```sh
# Icon caches exist for all themes
for d in /mnt/usr/local/share/icons/*/; do
  ls "$d"icon-theme.cache >/dev/null 2>&1 || echo "MISSING CACHE: $d"
done

# Brand icon installed into hicolor
ls -l /mnt/usr/local/share/icons/hicolor/48x48/apps/clawdie-start.png
ls -l /mnt/usr/local/share/icons/hicolor/scalable/apps/clawdie-start.svg

# Panel XML uses themed name, not absolute path
grep button-icon /mnt/home/clawdie/.config/xfce4/xfconf/xfce-perchannel-xml/xfce4-panel.xml

# Visual guard installed and executable
ls -l /mnt/usr/local/bin/clawdie-xfce-visuals-guard.sh
ls -l /mnt/usr/local/etc/xdg/autostart/clawdie-xfce-visuals-guard.desktop
```