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 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`; the Clawdie ISO stages Python 3.12 and creates `python3` /
`python` symlinks.

## 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 `/tmp`. It should not try to create files under `/usr/local/share`
at runtime unless explicitly requested by the operator.

**Optional runtime/session wiring:**

```bash
/usr/local/bin/clawdie-wallpaper-gen /tmp/clawdie-wallpaper.png
xfconf-query -c xfce4-desktop -p /backdrop/screen0/monitor0/workspace0/last-image \
  -s /tmp/clawdie-wallpaper.png
```

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   100.72.229.63        │
│   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;
- 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 to `/tmp/clawdie-wallpaper.png` using the Clawdie wallpaper as base.
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.