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

---
name: iso-visuals
description: 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.
triggers:
  - "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, a machine-identity wallpaper,
and a one-click Join Hive launcher.

## 1. Panel Health Indicator

Shows Colibri daemon status in the Xfce panel. Green/red dot with agent count.
Click to open a terminal with full `colibri status` output.

**Script:** `scripts/colibri-panel-indicator.sh`

**ISO integration:**

```bash
# Copy the script into the live filesystem
cp scripts/colibri-panel-indicator.sh /usr/local/bin/colibri-panel-indicator
chmod 755 /usr/local/bin/colibri-panel-indicator

# Add to Xfce panel via xfconf (or manually: Panel → Add New Items → Generic Monitor)
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 polls every 30s, uses `<txt>`/`<tool>`/`<txtclick>` genmon markup.
Zero dependencies beyond `nc` and `python3` (both in the base jail bootstrap).

## 2. Identity Wallpaper

Generates a desktop background with machine identity overlaid:
hostname, Tailscale IP, Colibri port, and FreeBSD release.

**Script:** `scripts/clawdie-wallpaper-gen.sh`

**ISO integration:**

```bash
# Run on first boot, set as wallpaper
cp scripts/clawdie-wallpaper-gen.sh /usr/local/bin/clawdie-wallpaper-gen
chmod 755 /usr/local/bin/clawdie-wallpaper-gen

# In clawdie-bootstrap-launch.sh or xfce-session:
/usr/local/bin/clawdie-wallpaper-gen /usr/local/share/backgrounds/clawdie-default.png

# Set as wallpaper (Xfce):
xfconf-query -c xfce4-desktop -p /backdrop/screen0/monitor0/workspace0/last-image \
    -s /usr/local/share/backgrounds/clawdie-default.png
```

Requires ImageMagick (`pkg install ImageMagick` — add to ISO package list).
Falls back to a solid dark background if no default wallpaper exists.

**Format:**
```
┌────────────────────────────────────┐
│                                    │
│          Clawdie OS                │
│                                    │
│   hostname    osa                  │
│   tailscale   100.72.229.63        │
│   colibri     9190                 │
│   jail        15.0-RELEASE-p4      │
│                                    │
└────────────────────────────────────┘
```

## 3. Join Hive Launcher

Desktop icon that runs the full agent registration flow in a visible terminal:
check daemon → verify vault creds → detect capabilities → register → done.

**Script:** `scripts/clawdie-join-hive.sh`
**Desktop entry:** `scripts/clawdie-join-hive.desktop`

**ISO integration:**

```bash
cp scripts/clawdie-join-hive.sh /usr/local/bin/clawdie-join-hive.sh
cp scripts/clawdie-join-hive.desktop /usr/local/share/applications/
cp scripts/clawdie-join-hive.desktop /home/clawdie/Desktop/
chmod 755 /usr/local/bin/clawdie-join-hive.sh
```

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

**Idempotent** — safe to double-click multiple times. Already-registered agents
are detected and skipped.

## Build integration (clawdie-iso build.sh)

Add these lines to the ISO build script:

```bash
# --- ISO Visuals ---
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/"
install -m 644 scripts/clawdie-join-hive.desktop    "${LIVE_ROOT}/home/clawdie/Desktop/"
```

And add `ImageMagick` to the ISO package list for the wallpaper generator.

## Verification

After booting the ISO:

1. **Panel:** green dot with agent count visible in the Xfce panel.
   Clicking opens `colibri status` in a terminal.
2. **Wallpaper:** identity text in the bottom-left corner.
3. **Desktop:** "Join Hive" icon present. Double-click → terminal opens,
   walks through registration, pauses for operator to read.