clawdie-iso/LUMINA-INTEGRATION.md

# Lumina Integration for Clawdie-ISO

**Purpose:** Lumina desktop configuration, branding, and Clawdie-specific customization

---

## Why Lumina for Clawdie

1. **FreeBSD heritage** — Built by PC-BSD, designed for BSD from the start
2. **Minimal overhead** — No D-Bus complexity, simple compositor
3. **Lightweight** — ~1GB RAM footprint (vs KDE's 3GB+)
4. **Single-purpose** — Pairs naturally with an AI agent workstation
5. **No Linux assumptions** — No systemd, udev, or Linux-specific libraries

---

## Lumina Package Selection

### Core Packages (pkg-list-lumina.txt)

```
# Lumina desktop environment
lumina-core              # Window manager + session manager (Openbox)
lumina-themes            # Built-in themes (glass, dark, light)
lumina-calculator        # Built-in calculator app
lumina-archiver          # Archive manager (tar, zip, 7z)
lumina-filemanager       # Simple file manager
lumina-screenshot        # Screenshot tool
lumina-open              # Default file association handler

# Dependencies (already in base)
openbox                  # Window manager (Lumina's default)
libxcb                   # X11 C bindings
libxdg-basedir           # XDG directory spec
pcmanfm-qt               # File manager (if filemanager pkg pulls it)

# Display server
xorg-minimal             # X11 base (from pkg-list-desktop-base.txt)
xf86-input-libinput      # Input device handler (from base)

# Login manager
lightdm                  # Display manager (keeps XFCE's choice)
lightdm-gtk-greeter      # Login screen (from base)

# Session management
dbus                     # Inter-process communication (from base)
hal                      # Hardware abstraction (from base)
```

**Total size:** ~200 MB (installed) vs XFCE's ~400 MB, KDE's ~1.2 GB

---

## Configuration Files

### 1. luminarc (Lumina Main Config)

**Location:** `/home/clawdie/.config/lumina/luminarc`

```ini
[General]
# Session and theming
session=default
theme=glass
color_scheme=dark
icon_theme=oxygen
numthumbnails=5
audiofiles=.mp3;.wav;.flac;.m4a;.ogg
videofiles=.mp4;.mkv;.avi;.mov;.webm

# Window behavior
single_click_launch=true
show_desktop_icons=false

[Panels]
# Single taskbar at bottom
panels=1
panel1_align=center
panel1_autohide=false
panel1_height=28
panel1_length=100
panel1_location=bottom

# Panel contents (left → right)
panel1_items=["menu", "taskbar", "systray", "clock"]

[Keyboard]
# Keybinds
super=lumina-open
alt_f2=lumina-open -application
alt_f4=lumina-killwindow

[Desktop]
# Background
background=/usr/local/share/pixmaps/clawdie-wallpaper.png
background_mode=scale  # fit, tile, scale, stretch
background_color=#0a0e27  # Dark blue fallback
desktop_icons=false
show_trashcan=false
show_start_here=false

[Theme]
# Dark theme for agent workstation
window_color=rgb(40, 44, 60)
text_color=rgb(220, 220, 220)
accent_color=rgb(100, 150, 255)  # Clawdie blue
button_color=rgb(60, 65, 85)
```

### 2. panel.conf (Panel Layout Details)

**Location:** `/home/clawdie/.config/lumina/panel.conf`

```ini
# Taskbar layout
[Item-0]
name=menu
plugin=lumina-menu

[Item-1]
name=taskbar
plugin=lumina-taskbar
use_icons=true
max_item_width=150

[Item-2]
name=spacer
type=spacer
width=flexible

[Item-3]
name=systray
plugin=lumina-systray
size=24

[Item-4]
name=clock
plugin=lumina-clock
format=%H:%M  # 24-hour time
showseconds=false
```

### 3. Openbox Config (Lumina's WM)

**Location:** `/home/clawdie/.config/openbox/lxde-rc.xml` (Lumina uses Openbox via lxde-rc.xml)

```xml
<?xml version="1.0" encoding="UTF-8"?>
<openbox_config xmlns="http://openbox.org/3.4/rc">
  <resistance>
    <strength>10</strength>
    <screen_edge_strength>20</screen_edge_strength>
  </resistance>

  <focus>
    <focusNew>yes</focusNew>
    <focusLast>yes</focusLast>
    <followMouse>no</followMouse>
    <underMouse>no</underMouse>
    <focusDelay>200</focusDelay>
    <raiseOnFocus>no</raiseOnFocus>
  </focus>

  <placement>
    <policy>Smart</policy>
    <monitor>Primary</monitor>
  </placement>

  <margins>
    <top>0</top>
    <bottom>28</bottom>
    <left>0</left>
    <right>0</right>
  </margins>

  <keyboard>
    <keybind key="Super_L">
      <action name="Execute">
        <command>/usr/local/bin/lumina-open -application</command>
      </action>
    </keybind>
    <keybind key="Super_L-Tab">
      <action name="NextWindow"/>
    </keybind>
    <keybind key="Super_L-Shift-Tab">
      <action name="PreviousWindow"/>
    </keybind>
    <!-- Alt+F4 close handled by Openbox internally -->
  </keyboard>

  <mouse>
    <dragThreshold>8</dragThreshold>
    <doubleClickTime>500</doubleClickTime>
  </mouse>
</openbox_config>
```

---

## Desktop Files (Launcher Integration)

### Clawdie Admin Launcher

**Location:** `~/.local/share/applications/clawdie-admin.desktop`

```ini
[Desktop Entry]
Type=Application
Name=Clawdie Admin
Comment=System and jail administration panel
Exec=/usr/local/bin/clawdie-admin
Icon=system-run
Categories=System;Administration;Utility
Terminal=false
NoDisplay=false
```

### Alternative: Clawdie Web Console

**Location:** `~/.local/share/applications/clawdie-web.desktop`

```ini
[Desktop Entry]
Type=Application
Name=Clawdie Console
Comment=Web-based agent console
Exec=xdg-open http://localhost:8080
Icon=internet-web-browser
Categories=Utility;WebBrowser
Terminal=false
```

---

## Wallpaper Setup

### Clawdie Wallpaper (Optional)

**Location:** `/usr/local/share/pixmaps/clawdie-wallpaper.png`

**Design:** Dark gradient background with subtle "Clawdie" watermark and FreeBSD mascot integration

```bash
# Build-time: generate minimal wallpaper
# During firstboot: copy to ~/.config/lumina/wallpaper.png

# Simple solid color fallback if image missing:
# background_color=#0a0e27  (dark blue)
```

---

## Login Manager Integration (lightdm)

### lightdm.conf Updates

**Location:** `/etc/lightdm/lightdm.conf`

```ini
[LightDM]
logind-check-gio=false
sessions-directory=/usr/local/share/xsessions

[SeatDefaults]
session=lumina
user-session=lumina
greeter-session=lightdm-gtk-greeter
greeter-hide-users=false
allow-user-switching=true
```

### lightdm-gtk-greeter.conf

**Location:** `/etc/lightdm/lightdm-gtk-greeter.conf`

```ini
[greeter]
theme-name=Adwaita-dark
icon-theme-name=oxygen
background=/usr/local/share/pixmaps/clawdie-wallpaper.png
logo=/usr/local/share/pixmaps/clawdie-logo.png
position=center
```

---

## Session File (Lumina xsession)

**Location:** `/usr/local/share/xsessions/lumina.desktop`

```ini
[Desktop Entry]
Type=Application
Encoding=UTF-8
Name=Lumina
Exec=startlumina
Icon=lumina
Comment=Lightweight, FreeBSD-native desktop
```

**Note:** Lumina ships this; we verify it exists in firstboot.sh.

---

## Startup Script

### ~/.xinitrc or ~/.xsession

**For manual X start (not needed in lightdm, but good to have):**

```bash
#!/bin/sh
# ~/.xinitrc — manual X start with Lumina

# Start D-Bus daemon (optional, some apps need it)
if [ -x /usr/local/bin/dbus-launch ]; then
    eval $(dbus-launch --sh-syntax)
fi

# Start Lumina session
exec startlumina
```

---

## Clawdie Status Tray Applet (New)

### Implementation

**Binary:** `/usr/local/libexec/clawdie-tray-applet`

**Function:** Polls clawdie service status every 5 seconds, updates tray icon.

**Code:**

```bash
#!/bin/sh
# Clawdie status tray applet for Lumina

RUNNING_ICON="/usr/local/share/icons/clawdie-running.png"
STOPPED_ICON="/usr/local/share/icons/clawdie-stopped.png"

while true; do
  if service clawdie status > /dev/null 2>&1; then
    # Clawdie running
    echo "ICON:$RUNNING_ICON"
    echo "LABEL:Clawdie (running)"
  else
    # Clawdie stopped
    echo "ICON:$STOPPED_ICON"
    echo "LABEL:Clawdie (stopped)"
  fi

  # Wait 5 seconds
  sleep 5
done
```

**Integration:** Called by Lumina systray plugin if available; falls back to panel menu.

---

## Fonts and Internationalization

### Font Setup

**Default fonts in Lumina:**

```ini
# System font (UI elements)
[Fonts]
fixed_font=Liberation Mono 10
general_font=Liberation Sans 10
menu_font=Liberation Sans 10
```

**Included in pkg-list-host.txt:**
- `liberation-fonts` (metric-compatible with Arial/Times)
- `dejavu` (already required, provides Unicode coverage)

**Cyrillic support for SR language pages:** Cormorant Garamond provides Cyrillic; DM Mono has limited but workable Cyrillic.

---

## Desktop Shortcuts (Optional)

### File Manager Shortcut

**Location:** `~/Desktop/Home.lnk` (if desktop icons enabled; disabled by default)

```ini
[Desktop Entry]
Type=Link
Name=Home Folder
URL=file:///home/clawdie
Icon=system-file-manager
```

### System Monitor Shortcut

**Location:** `~/Desktop/Clawdie-Admin.lnk`

```ini
[Desktop Entry]
Type=Link
Name=Clawdie Admin
URL=exec:///usr/local/bin/clawdie-admin
Icon=system-run
```

**Note:** Desktop icons are disabled by default. Users can enable via `luminarc`: `show_desktop_icons=true`.

---

## Accessibility Options

### High Contrast Mode (Optional)

**Location:** `~/.config/lumina/luminarc.hc`

```ini
# High contrast variant
[Theme]
window_color=rgb(50, 50, 50)
text_color=rgb(255, 255, 255)
button_color=rgb(100, 100, 100)
accent_color=rgb(255, 200, 0)  # High contrast yellow
```

**Enable from Lumina menu:** Settings → Appearance → "High Contrast"

---

## Performance Tuning

### Memory and CPU

| Setting | Value | Rationale |
|---------|-------|-----------|
| Compositing | Enabled (simple) | Smooth window transitions, no heavyweight effects |
| Animations | Fast (100ms) | Responsive feel without slowdown |
| Thumbnail cache | 5 items | File manager preview performance |
| CPU polling interval | 5 seconds | Tray updates without excessive CPU |

### Startup Time

**Goal:** Lumina session ready in <2 seconds from lightdm login

**Optimization:**
- No background services pre-start (dbus on-demand)
- Panel auto-layout (no manual positioning)
- Taskbar lazy-loads thumbnails
- No startup scripts or autostart folder clutter

---

## Verification Checklist

- [ ] `lumina-core`, `lumina-themes` installed from pkg
- [ ] `~/.config/lumina/luminarc` written during firstboot
- [ ] `~/.config/openbox/lxde-rc.xml` present
- [ ] `/usr/local/share/xsessions/lumina.desktop` exists
- [ ] `lightdm` configured to use Lumina session
- [ ] Login → desktop in <2 seconds
- [ ] Taskbar visible, clock working
- [ ] Application launcher opens (Super key or menu button)
- [ ] Right-click → Clawdie Admin accessible
- [ ] Wallpaper loads without errors

---

## Known Limitations

1. **Wayland support** — Lumina doesn't support Wayland; X11 only. FreeBSD's Wayland support is experimental anyway.
2. **Multi-monitor** — Lumina supports multiple monitors but panel duplicates. Acceptable for single-monitor target.
3. **Themes** — Lumina's theme engine is basic. Custom themes require manual Qt CSS editing.
4. **Audio** — Uses OSS (FreeBSD native). PulseAudio optional; not bundled.

---

## Comparison: Lumina vs XFCE on FreeBSD

| Aspect | Lumina | XFCE |
|--------|--------|------|
| **First release** | 2014 (PC-BSD) | 1996 (Linux) |
| **Target OS** | FreeBSD-native | Linux-first, ported to BSD |
| **Dependencies** | Minimal | Medium (glib, X11) |
| **Boot speed** | ~1.5 sec | ~2.5 sec |
| **RAM footprint** | 150 MB | 250 MB |
| **Customization** | Limited (simple) | High (panel placement, plugins) |
| **Community** | Small, stable | Large, active |
| **Long-term support** | Stable releases (~6 months) | Active development |
| **GPU acceleration** | Basic (OpenGL ES) | Full (DRI2/DRI3) |

**For Clawdie:** Lumina wins on simplicity + philosophy; XFCE wins on ecosystem. We choose Lumina for focus.