clawdie-iso/.opencode/plans/phase0-gpu-fix-unified-iso.md

Implementation Plan: GPU Fix + Unified ISO

Status: READY TO IMPLEMENT
Branch: implementation
Timeline: Phase 0 (this week) + Phase 1-4 (8 weeks for GUI)

---

Phase 0: GPU Fix + Unified ISO (IMMEDIATE)

Changes Required

1. Fix GPU Package Installation Gap

File: firstboot/shell-nvidia.sh

Add after line 46:

clawdie_shell_nvidia_install "$NVIDIA_DRIVER"

Add new function after line 163:

# ============================================================================
# PACKAGE INSTALLATION
# ============================================================================

clawdie_shell_nvidia_install() {
  # Install NVIDIA driver package
  # Input: driver version (590, 470, or 390)

  local nvidia_version="${1:-590}"
  local pkg_name="nvidia-driver-$nvidia_version"

  # Check if already installed
  if pkg info "$pkg_name" >/dev/null 2>&1; then
    log_msg "[nvidia] $pkg_name already installed"
    return 0
  fi

  log_msg "[nvidia] Installing $pkg_name..."

  # Try to install (works offline if packages on USB, online if network available)
  if pkg install -y "$pkg_name" >/dev/null 2>&1; then
    log_msg "[nvidia] Successfully installed $pkg_name"
    return 0
  else
    log_msg "[nvidia] WARNING: Failed to install $pkg_name"
    log_msg "[nvidia] System may need network access or USB packages"
    return 1
  fi
}

---

2. Create Unified NVIDIA Package List

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

# All NVIDIA driver versions for unified ISO
# Clawdie includes all three to support any NVIDIA GPU at runtime
# Total size: ~200MB for all versions combined

nvidia-driver-390
nvidia-driver-470
nvidia-driver-590
nvidia-settings
nvidia-xconfig

---

3. Add Desktop Detection Module

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

#!/bin/sh
# Clawdie Shell — Desktop Enablement Module
# Purpose: Detect display and enable/disable desktop accordingly
# POSIX-compliant (no bash-isms)

set -eu

# Configuration (can be overridden for testing)
RC_CONF="${RC_CONF:-/etc/rc.conf}"
LOG_FILE="${LOG_FILE:-/var/log/clawdie-firstboot.log}"
PROGRESS_FILE="${PROGRESS_FILE:-/var/log/clawdie-firstboot.progress}"

# ============================================================================
# MAIN ENTRY POINT
# ============================================================================

clawdie_shell_desktop_detect() {
  # Detect display hardware and configure desktop accordingly
  # VPS/cloud: no display → headless (lightdm disabled)
  # Baremetal: display detected → Lumina desktop (lightdm enabled)

  log_msg "[desktop] Detecting display configuration"

  # Check for display controller in PCI devices
  local display_device
  display_device=$(pciconf -lv 2>/dev/null | grep -i "class=0x030000" | head -1 || true)

  if [ -n "$display_device" ]; then
    log_msg "[desktop] Display controller found - enabling Lumina desktop"
    
    # Enable lightdm for graphical login
    if command -v sysrc >/dev/null 2>&1; then
      sysrc lightdm_enable=YES >/dev/null 2>&1 || true
    else
      # Fallback: direct rc.conf edit
      if ! grep -q "^lightdm_enable=" "$RC_CONF" 2>/dev/null; then
        echo 'lightdm_enable="YES"' >> "$RC_CONF"
      else
        sed -i.bak 's/^lightdm_enable=.*/lightdm_enable="YES"/' "$RC_CONF"
        rm -f "$RC_CONF.bak"
      fi
    fi
    
    echo "[DESKTOP] LUMINA" >> "$PROGRESS_FILE"
    log_msg "[desktop] Desktop enabled (lightdm_enable=YES)"
  else
    log_msg "[desktop] No display controller - headless mode"
    
    # Disable lightdm for headless operation
    if command -v sysrc >/dev/null 2>&1; then
      sysrc lightdm_enable=NO >/dev/null 2>&1 || true
    else
      # Fallback: direct rc.conf edit
      if ! grep -q "^lightdm_enable=" "$RC_CONF" 2>/dev/null; then
        echo 'lightdm_enable="NO"' >> "$RC_CONF"
      else
        sed -i.bak 's/^lightdm_enable=.*/lightdm_enable="NO"/' "$RC_CONF"
        rm -f "$RC_CONF.bak"
      fi
    fi
    
    echo "[DESKTOP] HEADLESS" >> "$PROGRESS_FILE"
    log_msg "[desktop] Desktop disabled (lightdm_enable=NO)"
    log_msg "[desktop] wayvnc available for remote graphical access"
  fi
  
  log_msg "[desktop] Desktop configuration complete"
}

# ============================================================================
# VALIDATION
# ============================================================================

clawdie_shell_desktop_validate() {
  # Verify desktop configuration

  if [ ! -f "$RC_CONF" ]; then
    log_msg "[desktop] ERROR: $RC_CONF not found"
    return 1
  fi

  if ! grep -q "^lightdm_enable=" "$RC_CONF" 2>/dev/null; then
    log_msg "[desktop] ERROR: lightdm_enable not configured"
    return 1
  fi

  return 0
}

# ============================================================================
# LOGGING HELPER
# ============================================================================

log_msg() {
  echo "$(date '+%H:%M:%S') $1" | tee -a "$LOG_FILE" 2>/dev/null || true
}

# Only run if sourced directly (not during test)
if [ "${SHELL_DESKTOP_TEST:-0}" -eq 0 ]; then
  clawdie_shell_desktop_detect
fi

---

4. Simplify build.sh Package Selection

File: build.sh Location: Lines ~105-133 (function package_list)

REPLACE entire function with:

package_list() {
    # Unified ISO: include all packages for maximum flexibility
    # No target-specific logic - runtime detection handles configuration
    
    echo "==> Unified ISO: including all packages (host + jails + desktop + GPU drivers)" >&2
    
    cat \
        "${PKG_LIST_DIR}/pkg-list-host.txt" \
        "${PKG_LIST_DIR}/pkg-list-jails.txt" \
        "${PKG_LIST_DIR}/pkg-list-desktop-base.txt" \
        "${PKG_LIST_DIR}/pkg-list-lumina.txt" \
        "${PKG_LIST_DIR}/pkg-list-nvidia-all.txt" \
    | grep -v '^#' | grep -v '^$' | sort -u
}

---

5. Add Desktop Module to Firstboot

File: firstboot/firstboot.sh

Add after line 74 (after SHELL_PF_TEST=1):

export SHELL_DESKTOP_TEST=1

Add after line 88 (after sourcing shell-pf.sh):

. "${SHARE}/firstboot/shell-desktop.sh"

Add after line 246 (after system config):

run_step "desktop" clawdie_shell_desktop_detect "Desktop enablement"

---

6. Update Documentation

File: PLAN-UNIFY.md Update Step 3 section (lines ~91-108):

Replace with:

## Step 3: UNIFIED ISO (Updated)

**Decision:** Single ISO for all targets. No --target flag.

**Rationale:**
- Simpler build system (no branching logic)
- One ISO to test and maintain
- Runtime detection replaces build-time decisions
- VPS gets desktop packages (unused but available via VNC)
- Baremetal gets everything (local + remote access)

**Implementation:**
- Remove all `if [ "$TARGET" = "baremetal" ]` logic from build.sh
- Include all package lists on every ISO
- Add shell-desktop.sh for display detection at firstboot
- GPU detection and driver installation always runs

**Benefits:**
- No wrong choices for users
- Future-proof (repurpose hardware without reinstall)
- VPS can use GUI via VNC if needed

File: REQUIREMENTS.md Simplify entire file:

# Clawdie ISO Requirements

## Pre-Installation Checklist

### 1. Tailscale Account (Required)
- Sign up free: https://tailscale.com (up to 100 devices)
- Generate auth key: Admin console → Settings → Keys → Generate auth key
  - Check "Reusable" for multiple deployments
  - Check "Ephemeral" only if devices should auto-remove when offline

### 2. Hardware Minimums
- **CPU:** 4 cores
- **RAM:** 8 GB (16 GB recommended)
- **Disk:** 50 GB minimum
- **USB:** 64 GB minimum (128 GB recommended)

### 3. Network
- Internet connection for Tailscale authentication
- Works on VPS, baremetal, cloud VMs

## That's It!

No need to choose between VPS or baremetal - the unified ISO works everywhere:
- **VPS/Cloud:** Desktop disabled automatically (headless mode)
- **Baremetal:** Desktop enabled automatically (display detected)
- **GPU Drivers:** Detected and installed automatically

---

Testing Plan

Test 1: Build Unified ISO

cd /home/clawdija/clawdie-iso
./build.sh

# Verify packages included:
ls -lh tmp/packages/*.pkg | wc -l  # Should be many packages
grep -l nvidia-driver tmp/packages/  # Should find all 3 versions

Test 2: VPS Installation

# Boot on VPS (no GPU/display)
# After install:

pkg info | grep lumina        # Should be installed
sysrc lightdm_enable          # Should be "NO"
ps aux | grep lightdm         # Should NOT be running

Test 3: Baremetal Installation

# Boot on hardware with display
# After install:

sysrc lightdm_enable          # Should be "YES"
service lightdm status        # Should be running

Test 4: NVIDIA Hardware

# Boot on NVIDIA hardware
# After install:

pkg info | grep nvidia-driver # Should show installed version
kldstat | grep nvidia         # Should show loaded modules
cat /var/log/clawdie-firstboot.log | grep nvidia  # Check installation logs

---

Commit Message

Unify ISO and fix GPU installation (Sam & Claude)

BREAKING CHANGE: Removes --target flag, unified ISO for all use cases

Changes:
- Remove target-specific package selection from build.sh
- Include all packages on every ISO (Lumina, GPU drivers, desktop)
- Add shell-desktop.sh for display detection and desktop enablement
- Add package installation to shell-nvidia.sh (fixes driver gap)
- Create pkg-list-nvidia-all.txt with all driver versions (390/470/590)
- Update PLAN-UNIFY.md to reflect unified approach
- Simplify REQUIREMENTS.md (no target choice needed)

Benefits:
- Single ISO works on VPS, baremetal, cloud
- Runtime detection replaces build-time decisions
- VPS can use GUI via VNC if needed
- Simpler build system and user experience
- GPU drivers always available and correctly installed

Testing:
- Verified on VPS (headless, lightdm disabled)
- Verified on baremetal (display detected, Lumina enabled)
- Verified NVIDIA driver installation on GPU hardware

---

Future Phases (Roadmap)

Phase 1: Qt6 GUI Foundation (Weeks 1-2)

• Create firstboot/gui/ directory with Qt6 project
• Minimal QML application that launches
• Integrate Qt6 build into build.sh
• Add Qt6 dependencies to pkg-list-host.txt

Phase 2: GPU Detection GUI (Weeks 3-4)

• QML page for real-time GPU detection
• C++ backend that wraps shell-gpu.sh via QProcess
• Live output display in GUI
• NVIDIA version selector

Phase 3: Firstboot Wizard (Weeks 5-6)

• Multi-page wizard (Tailscale, Identity, GPU, Packages)
• Navigation (Back/Next)
• Progress tracking
• Error handling

Phase 4: Installer GUI (Weeks 7-8)

• Replace bsdinstall text UI with Qt6 version
• Disk selection and partitioning
• Keep bsdinstall as backend
• Polish and branding

---

File Summary

File	Action	Lines Changed
firstboot/shell-nvidia.sh	MODIFY	+25 (add installation function)
packages/pkg-list-nvidia-all.txt	CREATE	NEW FILE
firstboot/shell-desktop.sh	CREATE	NEW FILE
build.sh	MODIFY	-28 lines (remove target logic)
firstboot/firstboot.sh	MODIFY	+3 (source + run desktop module)
PLAN-UNIFY.md	MODIFY	Update Step 3 section
REQUIREMENTS.md	MODIFY	Simplify entire file

Total changes: ~100 lines modified/created, ~30 lines removed