clawdie-iso/PHASE4-TESTING-INSTRUCTIONS.md

Phase 4 Testing Instructions for FreeBSD Agent

Date: 6 Apr 2026 Status: Implementation complete, ready for testing Estimated Time: 1-2 hours (unit tests + compilation)

---

What Was Built

Phase 4 completes the GUI → Shell integration pipeline:

GUI Installer → Config File → firstboot.sh → Progress Tracking

Components:

1. Config Writer (C++)

   • Writes user selections to /tmp/clawdie-install.conf
   • Shell-compatible format (can be sourced)
   • Includes all user, installation, and feature settings

2. Shell Integration

   • firstboot.sh sources GUI config if present
   • Skips text wizard when GUI config exists
   • Compatible with existing shell modules

3. Package Selection

   • 4 new properties: installDesktop, installDevTools, installNvidia, installLLM
   • Saved to backend when user clicks "Next" on PackagesPage
   • Written to config file on installation start

4. Execution Flow

   • ProgressPage calls backend.startInstall() on load
   • Config file created, firstboot.sh executed in background
   • ProgressTracker polls /var/log/clawdie-firstboot.progress

---

Testing Checklist

✅ Test 1: Config File Format (5 min)

Purpose: Verify config format is shell-compatible

cd /home/clawdija/clawdie-iso/firstboot/gui
./test-config-format.sh

Expected:

=== Testing GUI Config File Format ===
✓ Created test config file
✓ Config sourced successfully

=== Verifying Variables ===
[... all variables listed ...]

=== Validating Values ===
✓ ASSISTANT_NAME correct
✓ FEATURE_DESKTOP correct
✓ LOCAL_LLM_PROVIDER correct

=== All Tests Passed ===

If Fails:

• Check shell syntax in main.cpp startInstall() method
• Verify variable quoting (all values must be quoted)
• Check for special characters that need escaping

---

✅ Test 2: Compile QML Installer (10 min)

Purpose: Verify C++ code compiles cleanly

cd /home/clawdija/clawdie-iso/firstboot/gui/qml-installer

# Clean build
rm -f Makefile *.o moc_*.cpp clawdie-qml-installer

# Build
qmake6
make

Expected:

[1/3] clang++ -c -pipe -O2 -Wall -Wextra -fPIC ... -o main.o main.cpp
[2/3] moc main.cpp -> moc_main.cpp
[3/3] clang++ -pthread ... -o clawdie-qml-installer main.o moc_main.o

Success Criteria:

• No compiler errors
• Binary clawdie-qml-installer created
• Binary size ~100-150 KB

If Fails:

• Check Qt6 packages installed: pkg info | grep qt6
• Verify includes: qt6-base, qt6-declarative
• Check for syntax errors in main.cpp

---

✅ Test 3: Run QML Installer (15 min)

Purpose: Verify GUI launches and config is created

Requires X11 display (local or SSH with -X)

cd /home/clawdija/clawdie-iso/firstboot/gui/qml-installer

# Local display
DISPLAY=:0 ./clawdie-qml-installer

# Or SSH with X forwarding
ssh -X user@freebsd-host
./clawdie-qml-installer

Test Flow:

1. WelcomePage displays with FreeBSD version
2. Click "Next" → LicensePage
3. Accept license → Click "Next"
4. DiskPage shows available disks → Select one → Click "Next"
5. UserPage → Enter username/password → Click "Next"
6. GPUPage → Auto-detects GPU → Click "Next"
7. PackagesPage → Toggle checkboxes → Click "Next"
8. ProgressPage → This triggers installation

Verify on ProgressPage:

# In another terminal, check config file was created
cat /tmp/clawdie-install.conf

Expected Config:

# Clawdie GUI Installer Configuration
# Generated by QML installer

# User settings
ASSISTANT_NAME="your_username"
AGENT_DOMAIN="your_username.home.arpa"
CLAWDIE_PASSWORD="your_password"

# Installation settings
INSTALL_DISK="da0"  # Or whatever you selected
GPU_DRIVER_VERSION="0"

# Feature flags
FEATURE_DESKTOP="YES"
FEATURE_DEVTOOLS="YES"
FEATURE_NVIDIA="YES"
LOCAL_LLM_PROVIDER="none"

# Defaults
AGENT_GENDER="f"
TZ="UTC"
FEATURE_TAILSCALE="YES"
...

If Config Not Created:

• Check backend.startInstall() was called (ProgressPage.qml:114)
• Look for QML console errors: console.error("Failed to start installation")
• Verify /tmp is writable

---

✅ Test 4: firstboot.sh Integration (10 min)

Purpose: Verify firstboot.sh sources GUI config correctly

# Create test config
cat > /tmp/clawdie-install.conf << 'EOF'
ASSISTANT_NAME="testuser"
AGENT_DOMAIN="testuser.home.arpa"
CLAWDIE_PASSWORD="testpass"
INSTALL_DISK="da0"
GPU_DRIVER_VERSION="0"
FEATURE_DESKTOP="YES"
FEATURE_DEVTOOLS="YES"
FEATURE_NVIDIA="YES"
LOCAL_LLM_PROVIDER="none"
AGENT_GENDER="f"
TZ="UTC"
FEATURE_TAILSCALE="YES"
FEATURE_GIT="YES"
FEATURE_GITEA="NO"
CODE_HOSTING_MODE="git"
EOF

# Test sourcing
cd /home/clawdija/clawdie-iso/firstboot

# Set test mode (don't actually run modules)
export SHARE=/home/clawdija/clawdie-iso
export SHELL_GPU_TEST=1
export SHELL_NVIDIA_TEST=1
export SHELL_PKG_TEST=1
export SHELL_ENV_TEST=1
export SHELL_DEPLOY_TEST=1

# Verify script syntax
bash -n firstboot.sh && echo "✓ Script syntax OK"

# Test sourcing (dry run)
bash -c '
  set -e
  . /tmp/clawdie-install.conf
  echo "ASSISTANT_NAME=$ASSISTANT_NAME"
  echo "FEATURE_DESKTOP=$FEATURE_DESKTOP"
  echo "LOCAL_LLM_PROVIDER=$LOCAL_LLM_PROVIDER"
  [ "$ASSISTANT_NAME" = "testuser" ] && echo "✓ Config sourced correctly"
'

Expected:

✓ Script syntax OK
ASSISTANT_NAME=testuser
FEATURE_DESKTOP=YES
LOCAL_LLM_PROVIDER=none
✓ Config sourced correctly

If Fails:

• Check config file syntax (all values must be quoted)
• Verify no special characters in values
• Check firstboot.sh sourcing logic (lines 95-100)

---

⚠️ Test 5: Full Installation (Optional, 30+ min)

Purpose: Verify complete installation flow in VM

Prerequisites:

• Full ISO built with make release
• bhyve or other VM available
• Test hardware with GPU (for GPU detection)

# Build ISO (13 min)
cd /home/clawdija/clawdie-iso
make release

# Boot in bhyve (or VirtualBox, etc.)
# Note: This is advanced testing, skip if time-limited

Test in VM:

1. Boot ISO
2. Login as root
3. GUI installer should auto-launch
4. Complete all 8 pages
5. Verify installation completes
6. Reboot and verify system works

Skip If:

• Time-limited
• No VM available
• Tests 1-4 all pass

---

Known Issues

1. Password in Plaintext

Location: /tmp/clawdie-install.conf Impact: Low (temp file, deleted after install) Fix: Future - use encrypted storage or pipe

2. Disk Selection Not Used

Issue: INSTALL_DISK written but firstboot.sh doesn't use it Reason: bsdinstall handles disk partitioning (runs before firstboot.sh) Fix: Phase 5 - Replace bsdinstall with GUI partitioner

3. GPU Driver Override

Issue: GPU_DRIVER_VERSION written but shell-nvidia.sh auto-detects Reason: Auto-detection is more reliable Fix: Future - add "Override GPU Detection" checkbox

---

Open Questions

Critical (must answer before marking Phase 4 complete):

1. firstboot.sh Path:

   • Is path /usr/local/share/clawdie-iso/firstboot/firstboot.sh correct?
   • Or should it be /usr/local/bin/clawdie-firstboot.sh?
   • Check build.sh to see where firstboot.sh is installed

2. Progress File Format:

   • Current: PROGRESS=N (N=0-8)
   • But firstboot.sh uses step names (e.g., "gpu", "pkg", "deploy")
   • Need to align formats or add step counter to firstboot.sh

3. Privilege Escalation:

   • firstboot.sh requires root
   • QML installer runs as regular user
   • Need sudo wrapper or run installer as root?

4. Display Detection:

   • How does installer know to use GUI vs text mode?
   • Need display detection in rc.d script
   • Or separate clawdie-gui-installer service

---

Files to Check

Modified:

• firstboot/gui/qml-installer/main.cpp — startInstall() method (lines 359-421)
• firstboot/gui/qml-installer/pages/PackagesPage.qml — Save selections (lines 90-98)
• firstboot/gui/qml-installer/pages/ProgressPage.qml — Call startInstall() (lines 113-120)
• firstboot/firstboot.sh — Source GUI config (lines 95-100)

Created:

• firstboot/gui/test-config-format.sh — Config format test
• firstboot/gui/PHASE4-INTEGRATION-COMPLETE.md — Full documentation

Read These:

• firstboot/gui/PHASE4-INTEGRATION-COMPLETE.md — Complete implementation details
• firstboot/gui/qml-installer/README.md — Updated with Phase 4 status
• QT6-IMPLEMENTATION-PLAN.md — Overall roadmap

---

Success Criteria

Phase 4 Complete When:

• Config file written by C++ backend
• Config format compatible with shell sourcing
• firstboot.sh loads GUI config
• Progress tracking wired to ProgressPage
• Tests 1-4 pass on FreeBSD ← You are here
• Paths verified (firstboot.sh location, progress file format)
• Privilege escalation resolved

After Testing:

• Report results for Tests 1-4
• Note any failures with error messages
• Answer open questions above
• Recommend next steps

---

Quick Start (Minimal Testing)

If time is limited, run just these two tests:

# Test 1: Config format (5 min)
cd /home/clawdija/clawdie-iso/firstboot/gui
./test-config-format.sh

# Test 2: Compilation (10 min)
cd /home/clawdija/clawdie-iso/firstboot/gui/qml-installer
qmake6 && make

# If both pass, Phase 4 is 80% complete

---

Contact Points

Questions? Issues?

• Check PHASE4-INTEGRATION-COMPLETE.md for detailed docs
• Review main.cpp:startInstall() for config writer logic
• Check firstboot.sh:95-100 for config sourcing
• Test script: firstboot/gui/test-config-format.sh

Next Phase (Phase 5):

• Error recovery UI
• Retry logic
• Full log viewer
• Hardware testing

---

Good luck! Report back with test results and answers to open questions.