clawdie-iso/IMPLEMENTATION-PLAN.md

Clawdie Shell v0.9.0 Implementation Plan

Status: In Progress (implementation branch) Started: 24.mar.2026 Target Completion: v0.9.0-stable

---

Overview

This branch implements the specifications from v0.9.0-rc2. Work is done in parallel with main branch (which stays stable for review).

Merge strategy: When implementation is stable + tested, merge to main and tag v0.9.0-stable.

---

Phase 1: Shell Modules (Core)

Task 1.1: clawdie-shell-env.sh

Purpose: Identity + .env generation Status: TODO Effort: 2–3 hours

Deliverables:

• clawdie_shell_env_generate() — Main entry point
• clawdie_shell_env_gen_secrets() — 9 random secrets (openssl)
• clawdie_shell_env_derive_names() — AGENT_NAME derivation
• clawdie_shell_env_derive_ips() — Jail subnet allocation
• clawdie_shell_env_validate() — .env sanity check
• Progress logging + error handling (POSIX-safe)
• .env created with chmod 600

Testing:

. firstboot/clawdie-shell-env.sh
export ASSISTANT_NAME="TestAgent"
export AGENT_DOMAIN="test.local"
clawdie_shell_env_generate
# Verify: /home/clawdie/clawdie-ai/.env exists, 600 perms, 65 vars present

Task 1.2: clawdie-shell-pkg.sh

Purpose: Package repo configuration Status: TODO Effort: 2 hours

Deliverables:

• clawdie_shell_pkg_setup() — Main orchestrator
• clawdie_shell_pkg_detect_abi() — Query system ABI
• clawdie_shell_pkg_write_config() — Write repo configs
• clawdie_shell_pkg_seed_cache() — Copy USB packages to cache
• Progress logging, error handling

Testing:

. firstboot/clawdie-shell-pkg.sh
clawdie_shell_pkg_setup
# Verify: /etc/pkg/repos/FreeBSD.conf exists
# Verify: /etc/pkg/repos/Clawdie-USB.conf exists
# Verify: packages seeded to /var/cache/pkg/bastille

Task 1.3: clawdie-shell-gpu.sh

Purpose: GPU detection + kernel module loading Status: TODO Effort: 1–2 hours

Deliverables:

• clawdie_shell_gpu_detect() — Main entry point
• clawdie_shell_gpu_detect_pci() — Query pciconf
• clawdie_shell_gpu_match_driver() — Lookup table (Intel, AMD, NVIDIA, VMware, VESA)
• clawdie_shell_gpu_write_rcconf() — Write kld_list to rc.conf
• clawdie_shell_gpu_load_live() — Optional kldload on first boot

Testing:

. firstboot/clawdie-shell-gpu.sh
clawdie_shell_gpu_detect
# Verify: rc.conf has kld_list="i915kms" (or correct driver)
# Verify: X11 starts correctly on next boot

Task 1.4: clawdie-shell-system.sh

Purpose: System-level config (rc.conf, hostname, services) Status: TODO Effort: 1–2 hours

Deliverables:

• clawdie_shell_system_config() — Main orchestrator
• clawdie_shell_system_write_rcconf() — Update /etc/rc.conf
• clawdie_shell_system_set_hostname() — Set hostname + /etc/hostname
• clawdie_shell_system_setup_env() — /etc/profile.d/clawdie.sh
• clawdie_shell_system_enable_services() — dbus, hald, lightdm, etc.

Testing:

. firstboot/clawdie-shell-system.sh
export TZ="Europe/Ljubljana"
clawdie_shell_system_config
# Verify: /etc/rc.conf has timezone, kld_list, services
# Verify: /etc/hostname set to $AGENT_DOMAIN

Task 1.5: clawdie-shell-clawdie.sh

Purpose: Clawdie-AI extraction, npm install, jails, service Status: TODO Effort: 2–3 hours

Deliverables:

• clawdie_shell_clawdie_setup() — Main orchestrator
• clawdie_shell_clawdie_extract() — Extract tarball
• clawdie_shell_clawdie_npm_install() — npm install (offline)
• clawdie_shell_clawdie_install_all() — Run npm run install-all
• clawdie_shell_clawdie_verify() — Check jails, pg, nginx

Testing:

. firstboot/clawdie-shell-clawdie.sh
clawdie_shell_clawdie_setup
# Verify: /home/clawdie/clawdie-ai extracted
# Verify: jails running (jls -N)
# Verify: pg responding (psql ...)
# Verify: rc.d clawdie service enabled

---

Phase 2: Firstboot Wizard Rewrite

Task 2.1: firstboot.sh (3-tier wizard orchestrator)

Purpose: Main installer entry point Status: TODO Effort: 2 hours

Deliverables:

• Parse command-line args (--resume, --reset)
• Tier 1: Identity (name, domain, timezone)
• Tier 2: Optional (LLM provider, Telegram)
• Summary: Review + confirm
• Non-interactive setup: Call all 5 modules in sequence
• Progress checkpoints, error handling, recovery logic

Testing:

# Full wizard flow
/usr/local/libexec/firstboot.sh

# Resume from failure
clawdie-firstboot --resume

# Reset and start over
clawdie-firstboot --reset

---

Phase 3: Admin Panel Implementation

Task 3.1: clawdie-admin.sh (bsddialog UI)

Purpose: System management interface Status: TODO Effort: 3–4 hours

Deliverables:

• Main menu (System Health, Jails, Snapshots, Logs, Config, Hardware, Quit)
• System Health submenu (CPU, RAM, ZFS, service status)
• Jails submenu (list, start/stop, console via jexec)
• Snapshots submenu (create, list, restore with confirmation)
• Logs submenu (service, jails, system, tail mode)
• Config submenu (name, timezone, provider, export .env)
• Hardware submenu (audio, network, WiFi firmware suggestions)
• Tray applet status indicator

Testing:

clawdie-admin
# Navigate all menus
# Test jail operations
# Test snapshot create/restore
# Verify bsddialog UX is intuitive

---

Phase 4: Build System Updates

Task 4.1: Update build.cfg

Status: TODO Changes:

• Verify FreeBSD version (15.0-RELEASE)
• Verify ISO size (~26 GB)
• Add Lumina packages to lists

Task 4.2: Update build.sh

Status: TODO Changes:

• Update pkg_list_all() to use lumina list (not xfce/kde/mate)
• Copy shell modules to installerconfig payload
• Copy lumina-config defaults
• Update artifact naming (clawdie-shell-YYYYMMDD.img)

Task 4.3: Update installerconfig

Status: TODO Changes:

• Copy shell modules to /mnt/usr/local/libexec/
• Copy lumina config defaults
• Install rc.d clawdie-firstboot service
• Ensure permissions 755 on shell scripts

---

Phase 5: Testing & Validation

Task 5.1: Unit Test (Shell Modules)

Status: TODO Effort: 2–3 hours

Test each module independently:

# Test env module
. firstboot/clawdie-shell-env.sh
clawdie_shell_env_generate
# Verify: .env exists, 600 perms, all 65 vars

# Test pkg module
. firstboot/clawdie-shell-pkg.sh
clawdie_shell_pkg_setup
# Verify: repos configured, cache seeded

# Test gpu module
. firstboot/clawdie-shell-gpu.sh
clawdie_shell_gpu_detect
# Verify: kld_list in rc.conf, GPU driver correct

# Etc.

Task 5.2: Integration Test (Full Firstboot)

Status: TODO Effort: 3–4 hours

Boot ISO in bhyve, run complete flow:

# Boot bhyve VM from clawdie-shell-*.img
# Run bsdinstall (disk layout, user)
# First boot from HDD → rc.firstboot triggers
# Answer 3 wizard questions
# Verify: Setup completes without error
# Verify: Lumina boots
# Verify: Agent service running
# Login as clawdie user
# Right-click → "Clawdie Admin" works

Task 5.3: Hardware Testing

Status: TODO Effort: 4–6 hours (real hardware)

Test on 3+ hardware configurations:

1. Intel Core i5 + integrated GPU
   - Boot USB
   - Install to SSD
   - GPU driver loads
   - Lumina renders
   - Audio works

2. AMD Ryzen + Radeon GPU
   - Same flow
   - amdgpu loads correctly

3. NVIDIA GeForce GTX 1660
   - Boot, install
   - nvidia-driver loads
   - 3D rendering works (if needed)

---

Branch Workflow

Commit Strategy

# Commit each task as completed
git add firstboot/clawdie-shell-env.sh
git commit -m "impl: Add clawdie-shell-env.sh module

- clawdie_shell_env_generate() main entry
- Secret generation (9 random 32-char base64)
- Name/IP derivation from wizard inputs
- .env file creation with chmod 600
- POSIX-safe error handling

Tested with unit test.
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>"

Pull Request to Main

When implementation is stable + tested:

# Merge implementation into main
git checkout main
git merge implementation --no-ff -m "Merge v0.9.0 implementation

Completes v0.9.0-stable release with:
- 5 shell modules (env, pkg, gpu, system, clawdie)
- 3-tier firstboot wizard with recovery mode
- clawdie-admin bsddialog UI
- Hardware detection (audio, WiFi, network)
- POSIX compliance, OSS audio, API key security
- Tested on bhyve + 3 hardware configs

Fixes: [issues if any]"

git tag v0.9.0-stable
git push origin main --tags

---

Timeline Estimate

Task	Hours	Status
1.1 clawdie-shell-env.sh	2–3	TODO
1.2 clawdie-shell-pkg.sh	2	TODO
1.3 clawdie-shell-gpu.sh	1–2	TODO
1.4 clawdie-shell-system.sh	1–2	TODO
1.5 clawdie-shell-clawdie.sh	2–3	TODO
Phase 1 Total	8–12 hours
2.1 firstboot.sh	2	TODO
Phase 2 Total	2 hours
3.1 clawdie-admin.sh	3–4	TODO
Phase 3 Total	3–4 hours
4.1–4.3 Build system	1–2	TODO
Phase 4 Total	1–2 hours
5.1 Unit tests	2–3	TODO
5.2 Integration test	3–4	TODO
5.3 Hardware testing	4–6	TODO
Phase 5 Total	9–13 hours
Grand Total	23–31 hours

---

Success Criteria for v0.9.0-stable

• All 5 shell modules complete + tested
• firstboot.sh wizard working (3-tier, recovery mode)
• clawdie-admin.sh UI functional (all menus)
• Build system updated (build ISO successfully)
• Unit tests passing (each module)
• Integration test passing (bhyve VM)
• Hardware testing passing (3+ configs)
• POSIX compliance validated
• API key security verified (.env 600)
• Audio + hardware detection working
• Documentation updated (no orphaned refs)
• All commits signed + descriptive

---

Remaining Questions / Open Items

1. Offline npm cache — How to bundle npm modules on USB for offline install?

   • Current: npm cache pre-filled during build.sh
   • Alternative: Use npm ci --offline with package-lock.json

2. Lumina theme customization — Should we pre-bake a Clawdie-themed Lumina config?

   • Current plan: Use Lumina defaults (glass, dark)
   • v1.0: Custom wallpaper + theme

3. Jail provisioning hooks — Any special needs for PostgreSQL seeding, nginx config?

   • Current: Let npm run install-all handle it
   • Should work as-is, but verify in testing

4. Audio card detection — Which packages for snd-hda-generic, snd-usb-audio?

   • Current: Add to pkg-list-host.txt (pre-bundled)
   • Verify sizes + dependencies don't bloat ISO

---

Notes for Implementation Phase

• Always test locally first (bhyve) before real hardware
• Keep git history clean — One logical change per commit
• Document as you go — Don't wait for the end
• POSIX-first always — No bash-isms, no Linux assumptions
• Error messages are user-facing — Make them helpful
• Recovery mode is critical — Test failures + resumption early

---

Ready to start? Pick a task from Phase 1 and dive in! 🚀

Last updated: 24.mar.2026