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

[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

# 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 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

[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

[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

# 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

[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

[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

[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):

#!/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:

#!/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:

# 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)

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

System Monitor Shortcut

Location: ~/Desktop/Clawdie-Admin.lnk

[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

# 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.