---
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 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:**

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

**Optional runtime/manual panel wiring:**

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

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

**Preferred base wallpaper:**

```text
/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:

```bash
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:**

```text
┌────────────────────────────────────┐
│                                    │
│          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:**

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

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

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