Sam & Claude b163cf1014 Merge xfce-operator-usb: Track F Colibri, DeepSeek smoke, LLM provider harness

2026-06-04 20:04:23 +02:00

10 KiB

Raw Blame History

Clawdie v0.9.0 Release Notes

Historical release note. This documents the earlier unified-ISO / Lumina / LightDM era and is not the current xfce-operator-usb operator-USB path. Use README.md, BUILD.md, and TESTING.md for the current live USB flow.

Release Date: April 6, 2026
Codename: Unified Architecture
Attribution: Sam & ZAI

Executive Summary

Clawdie v0.9.0 introduces a unified ISO architecture that eliminates build-time decisions and enables a single image to work across VPS, baremetal, and cloud deployments. This release includes critical bug fixes, new runtime detection capabilities, and comprehensive documentation improvements.

Breaking Changes

1. Unified ISO (No Build-Time Target Selection)

Before:

./build.sh --target vps
./build.sh --target baremetal --gpu-driver nvidia-590

After:

./build.sh  # Single unified ISO

Impact:

✅ Simpler build process (no flags needed)
✅ One ISO to test and maintain
✅ Runtime detection handles configuration
⚠️ ISO size increased by ~650MB (includes all packages)
⚠️ Removes --target and --gpu-driver flags

2. Sudo Standardization (No More doas)

Before:

doas ./build.sh
doas service clawdie restart

After:

sudo ./build.sh
sudo service clawdie restart

Impact:

✅ Consistent privilege escalation across all documentation
✅ Better operator familiarity (sudo is more common)
✅ Updated AGENTS.md with system configuration guidelines
✅ All 8 documentation files updated

Critical Bug Fixes

GPU Driver Installation Gap (FIXED)

Problem:

NVIDIA drivers were detected and configured in /etc/rc.conf
Drivers were never actually installed via pkg install
Result: System had GPU config but no driver → broken

Solution:

Added clawdie_shell_nvidia_install() function to shell-nvidia.sh
Drivers now install via pkg install immediately after detection
Works offline (USB packages) or online (pkg repository)

Affected Files:

firstboot/shell-nvidia.sh (+33 lines)

Testing:

# Build ISO
./build.sh

# Install on NVIDIA hardware
# After firstboot:
pkg info | grep nvidia-driver  # Should show installed version
kldstat | grep nvidia          # Should show loaded modules

New Features

1. Desktop Detection Module

File: firstboot/shell-desktop.sh (NEW)

Purpose: Detect display hardware at firstboot and configure desktop accordingly

Behavior:

VPS/Cloud (no display): lightdm_enable=NO (headless mode)
Baremetal (display detected): lightdm_enable=YES (Lumina desktop)

Implementation:

# Detects display controller via pciconf
# class=0x030000 = VGA compatible controller
display_device=$(pciconf -lv | grep -i "class=0x030000" | head -1)

if [ -n "$display_device" ]; then
    sysrc lightdm_enable=YES  # Desktop mode
else
    sysrc lightdm_enable=NO   # Headless mode
fi

2. All GPU Drivers Included

File: packages/pkg-list-nvidia-all.txt (NEW)

Contents:

nvidia-driver-390    # Kepler (GTX 600/700 series)
nvidia-driver-470    # Maxwell (GTX 750/900 series)
nvidia-driver-590    # Turing/Ampere/Ada (RTX 20/30/40 series)
nvidia-settings
nvidia-xconfig

Benefit: No build-time GPU selection needed. All drivers available for runtime detection.

3. Modular Firstboot Architecture

Modules: 12 POSIX-compliant shell scripts

shell-gpu.sh: GPU detection
shell-nvidia.sh: NVIDIA version selection + installation
shell-pkg.sh: Package repository setup
shell-env.sh: Environment configuration
shell-system.sh: System configuration
shell-ssh.sh: SSH setup
shell-pf.sh: PF firewall
shell-tailscale.sh: Tailscale setup
shell-zfs.sh: ZFS pool detection
shell-deploy.sh: Deployment
shell-desktop.sh: Desktop enablement (NEW)
integration-test.sh: Test coverage

Documentation Improvements

New Documentation (8 files)

REQUIREMENTS.md - Pre-install checklist
BUILD.md - Build instructions
NETWORKING.md - PF firewall, Tailscale, glasspane
ADMIN-PANEL.md - Admin UI specification
Obsolete Lumina integration notes - historical desktop configuration
SHELL-ARCHITECTURE.md - Module architecture
SHELL-MODULES.md - Module documentation
MODULE-MANIFEST.md - Dependency graph

Updated Documentation (8 files)

PLAN-UNIFY.md - Step 3 updated for unified approach
AGENTS.md - Added system configuration section (sudo)
README.md - Updated installation instructions
CLAWDIE-SHELL.md - Updated example commands
CLAWDIE-ISO-REFACTORED.md - Updated access paths
REFACTOR-SUMMARY.md - Updated permissions section
CLAWDIE-ISO.md - Updated for unified ISO
TESTING.md - Updated test procedures

Changes Summary

Statistics

Files Changed: 62 files
Lines Added: 11,436
Lines Removed: 924
Net Change: +10,512 lines

Core System (15 files)

File	Changes	Description
`build.sh`	-56 lines	Removed target logic, unified package selection
`build.cfg`	-2 vars	Removed GPU_DRIVER, TARGET defaults
`firstboot/firstboot.sh`	+3 lines	Added desktop module
`firstboot/shell-nvidia.sh`	+33 lines	Added package installation
`firstboot/shell-desktop.sh`	NEW	Display detection and desktop enablement
`packages/pkg-list-nvidia-all.txt`	NEW	All three NVIDIA driver versions

Architecture

Before: Build-Time Decisions

Build Time:
  --target vps → minimal packages (no desktop)
  --target baremetal → desktop + GPU packages
  --gpu-driver nvidia-590 → specific NVIDIA version

Result: Multiple ISO variants, target-specific images

After: Runtime Detection

Build Time:
  ./build.sh → unified ISO (all packages)

Firstboot:
  Detect display → lightdm_enable=YES/NO
  Detect GPU → install correct driver
  Detect hardware → configure services

Result: Single ISO, universal compatibility

Testing

Test Matrix

Scenario	Display	GPU	Expected Result
VPS/Cloud	None	None	lightdm=NO, headless, wayvnc available
VPS w/GPU	None	NVIDIA	lightdm=NO, driver installed, VNC
Baremetal	Detected	Intel	lightdm=YES, i915kms loaded
Baremetal	Detected	AMD	lightdm=YES, amdgpu loaded
Baremetal	Detected	NVIDIA	lightdm=YES, nvidia-driver installed

Testing Checklist

# 1. Build unified ISO
./build.sh
# Expected: tmp/output/clawdie-iso-unified-DD.MMM.YYYY.img (~50GB)

# 2. Test on VPS (no display)
# After install:
sysrc lightdm_enable  # Should be "NO"
pkg info | grep lumina  # Should be installed

# 3. Test on baremetal (display)
# After install:
sysrc lightdm_enable  # Should be "YES"
service lightdm status  # Should be running

# 4. Test on NVIDIA hardware
pkg info | grep nvidia-driver  # Should show version
kldstat | grep nvidia  # Should show modules

# 5. Test sudo
sudo pkg audit  # Should work without password

Migration Guide

From v0.8.x to v0.9.0

For Operators:

No action required for existing deployments
- v0.8.x systems continue to work
- Migration happens on next ISO install

New builds use unified ISO

# Old (v0.8.x):
./build.sh --target baremetal --gpu-driver nvidia-590

# New (v0.9.0):
./build.sh

Documentation updated
- Replace doas with sudo in your notes
- No more target-specific ISOs

For Developers:

Update build scripts
- Remove --target and --gpu-driver flags
- Use single ./build.sh command
Update documentation
- Replace doas with sudo
- Remove target-specific instructions

Known Issues

ISO Size Increase

Issue: Unified ISO is ~650MB larger than target-specific ISOs

Cause: Includes all packages (desktop + all GPU drivers)

Mitigation:

650MB = 1-2% of 50GB disk (acceptable overhead)
No runtime overhead on VPS (services disabled)
Future: Consider package deduplication

NVIDIA Driver Selection

Issue: All three NVIDIA drivers installed, only one needed

Cause: Runtime detection selects correct version