layered-soul/skills/iso-visuals/SKILL.md

name	description	triggers
iso-visuals	Out-of-box visual experience for Clawdie ISO — panel health indicator, identity wallpaper, and one-click Join Hive launcher. Integrates into Xfce desktop on first boot.	iso visuals out of box experience desktop wallpaper panel indicator join hive launcher first boot appearance clawdie desktop

ISO Visuals — Out-of-Box Desktop Experience

Three improvements that replace the "boot to a terminal" feeling with a calm, informative desktop: a panel health indicator helper, a machine-identity wallpaper helper, and a one-click Join Hive launcher.

Keep this skill honest: scripts can be staged before every script is wired into the default panel/session. Do not claim default-panel or first-login behavior until it is proven in the live ISO or by mounted-image plus runtime checks.

1. Panel Health Indicator Helper

Shows Colibri daemon status as Xfce genmon markup. When wired into a Generic Monitor panel item, it displays a green/red dot with agent count and started-task count; clicking opens a terminal with full colibri status output.

Script: scripts/colibri-panel-indicator.sh

ISO staging:

install -m 755 scripts/colibri-panel-indicator.sh \
  "${LIVE_ROOT}/usr/local/bin/colibri-panel-indicator"

Optional runtime/manual panel wiring:

# Requires xfce4-genmon-plugin. Add manually from Panel → Add New Items → Generic Monitor,
# or wire into seeded panel XML only after that plugin is in the ISO package list.
xfconf-query -c xfce4-panel -p /plugins/plugin-20 -n -t string -s genmon
xfconf-query -c xfce4-panel -p /plugins/plugin-20/command -n -t string -s /usr/local/bin/colibri-panel-indicator

The indicator uses <txt>/<tool>/<txtclick> genmon markup. It depends on nc and python3; warns with ⚠ missing deps if either is absent instead of failing silently. Socket-down and no-response states are distinct, each with actionable tooltip text.

2. Identity Wallpaper Helper

Generates a desktop background with machine identity overlaid: hostname, Tailscale IP when available, Colibri socket/port status, and FreeBSD release.

Script: scripts/clawdie-wallpaper-gen.sh

ISO staging:

install -m 755 scripts/clawdie-wallpaper-gen.sh \
  "${LIVE_ROOT}/usr/local/bin/clawdie-wallpaper-gen"

Preferred base wallpaper:

/usr/local/share/clawdie-iso/wallpapers/clawdie-operator-bg.png

The helper falls back to the stock XFCE background, then to a generated dark solid background under project-local tmp/ when a checkout is available. On the live USB, where there is usually no project root, it uses an app-owned cache directory such as $XDG_CACHE_HOME/clawdie or $HOME/.cache/clawdie. It should not try to create files under /usr/local/share at runtime unless explicitly requested by the operator.

Optional runtime/session wiring: the helper prints the output path it chose on stdout (human note goes to stderr), so callers capture it rather than guessing a path. XFCE keys backdrops by connector name (monitorHDMI-1, monitoreDP-1, …), not a fixed monitor0, so set every */last-image property:

WP=$(/usr/local/bin/clawdie-wallpaper-gen)
for p in $(xfconf-query -c xfce4-desktop -l | grep '/last-image$'); do
  xfconf-query -c xfce4-desktop -p "$p" -s "$WP"
done

Requires ImageMagick (ImageMagick7 in the ISO package list; magick or convert command accepted). Tailscale is optional; absence should produce tailscale offline, not an error.

Format:

┌────────────────────────────────────┐
│                                    │
│          Clawdie OS                │
│                                    │
│   hostname    osa                  │
│   tailscale   ${OSA_TS_IP}        │
│   colibri     socket 9190          │
│   jail        15.0-RELEASE-p4      │
│                                    │
└────────────────────────────────────┘

3. Join Hive Launcher

Desktop icon that runs agent registration in a visible terminal: check daemon → check Vaultwarden bootstrap fields without printing secrets → detect capabilities → register → pause for operator review.

Script: scripts/clawdie-join-hive.sh

Desktop entry: scripts/clawdie-join-hive.desktop

ISO staging:

install -m 755 scripts/clawdie-join-hive.sh \
  "${LIVE_ROOT}/usr/local/bin/clawdie-join-hive"
install -m 644 scripts/clawdie-join-hive.desktop \
  "${LIVE_ROOT}/usr/local/share/applications/Clawdie Join Hive.desktop"
install -m 644 scripts/clawdie-join-hive.desktop \
  "${LIVE_ROOT}/home/clawdie/Desktop/Join Hive.desktop"

The desktop entry must call the installed binary path, without a .sh suffix:

Exec=xfce4-terminal --title "Join Hive" --geometry=80x24 --command "/usr/local/bin/clawdie-join-hive"

The launcher runs in xfce4-terminal with geometry 80x24 and pauses on "Press Enter" so the operator reads the result before the window closes.

Idempotency expectations:

• safe to double-click multiple times;
• treats already-registered / UNIQUE constraint agent-name responses as an idempotent success;
• does not fail just because /usr/local/etc/colibri/provider.env is mode 0600;
• uses mdo -u root for privileged checks/start where available;
• on success, generates the identity wallpaper at the generator's chosen path (no host-global /tmp) and applies it across all monitors as visual confirmation;
• never prints Vaultwarden credentials or provider keys.

Build integration (clawdie-iso build.sh)

Current staging pattern:

install -m 755 scripts/colibri-panel-indicator.sh  "${LIVE_ROOT}/usr/local/bin/colibri-panel-indicator"
install -m 755 scripts/clawdie-wallpaper-gen.sh     "${LIVE_ROOT}/usr/local/bin/clawdie-wallpaper-gen"
install -m 755 scripts/clawdie-join-hive.sh         "${LIVE_ROOT}/usr/local/bin/clawdie-join-hive"
install -m 644 scripts/clawdie-join-hive.desktop    "${LIVE_ROOT}/usr/local/share/applications/Clawdie Join Hive.desktop"
install -m 644 scripts/clawdie-join-hive.desktop    "${LIVE_ROOT}/home/clawdie/Desktop/Join Hive.desktop"

Add/keep ImageMagick7 in the ISO package list for the wallpaper generator.

Verification

After booting the ISO:

1. Mounted-image: /usr/local/bin/clawdie-join-hive, /usr/local/bin/clawdie-wallpaper-gen, and /usr/local/bin/colibri-panel-indicator exist and are executable.
2. Desktop launcher: Join Hive.desktop exists; its Exec= points to /usr/local/bin/clawdie-join-hive with no .sh suffix.
3. Join Hive: double-click opens a terminal, starts/checks colibri_daemon, reports provider.env status without exposing secrets, registers or reports already registered, then waits for Enter.
4. Wallpaper helper: running /usr/local/bin/clawdie-wallpaper-gen writes an image under project-local tmp/ when run from a checkout, or an app-owned live cache directory when no project root exists, using the Clawdie wallpaper as base, and prints that path on stdout (the human Wallpaper: … note goes to stderr).
5. Panel indicator helper: running /usr/local/bin/colibri-panel-indicator prints genmon XML. Only claim panel visibility after genmon is packaged and wired into the seeded panel or configured manually.