clawdie-iso/README.md

# Clawdie Shell

**Unified installer and human operator interface for Clawdie-AI on FreeBSD**

A single-step deployment platform that combines:
- **FreeBSD 15.0** (ZFS, jails, rc.d, pkg)
- **Lumina Desktop** (lightweight, FreeBSD-native, from PC-BSD heritage)
- **Shell modules** (modular, portable, POSIX-compliant)
- **Admin panel** (bsddialog UI for jails, snapshots, system health)

**Standing on the shoulders of giants:** We don't reinvent. We inherit wisdom from FreeBSD, PC-BSD's Lumina, and proven shell patterns.

---

## What Is Clawdie Shell?

Boot a USB, answer a 3-screen wizard, and you have a fully configured Clawdie-AI workstation running on FreeBSD with:

- ✅ Lumina desktop (ready to use)
- ✅ Bastille jails (worker, db, cms) provisioned
- ✅ PostgreSQL + pgvector seeded
- ✅ Clawdie-AI agent running
- ✅ Admin panel accessible from taskbar
- ✅ All offline (no internet required during install)

**One reboot. That's it.**

---

## Quick Start

### Build the USB Image

```bash
# Requirements: FreeBSD 15.0+, pkg, curl, 30 GB free disk space

git clone https://codeberg.org/Clawdie/Clawdie-ISO.git
cd Clawdie-ISO

# Fetch FreeBSD memstick + all packages (non-root)
./build.sh --fetch-only

# Assemble ISO (requires root for mdconfig/mount)
doas ./build.sh

# Output: tmp/output/clawdie-iso-<variant>-DD.mmm.YYYY.img (~50 GB, configurable in build.cfg)
```

### Install on Hardware

1. **Write to USB:**
   ```bash
   doas dd if=tmp/output/clawdie-iso-<variant>-DD.mmm.YYYY.img of=/dev/da0 bs=1M
   # (replace da0 with your USB device)
   ```

2. **Boot from USB** on target machine (BIOS/EFI)

3. **Run bsdinstall** (standard FreeBSD installer)
   - Choose disk, partitioning, root password
   - Create `clawdie` user

4. **First boot from HDD** (reboot 1)
   - rc.firstboot wizard appears
   - Answer: assistant name, public domain, timezone
   - Optional: local LLM runtime (Ollama or llama-cpp)
   - Optional: SSH public key (for later Ansible/jail SSH baselines)
   - Optional: enable Forgejo web git UI (adds disk usage)
   - Setup runs automatically (5–10 min)

5. **Lumina desktop boots**
   - Login as `clawdie` user
   - Agent running in background
   - Admin panel: right-click taskbar → "Clawdie Admin"

---

## Documentation

- **[CLAWDIE-SHELL.md](CLAWDIE-SHELL.md)** — Specification (overview, features, design)
- **[SHELL-ARCHITECTURE.md](SHELL-ARCHITECTURE.md)** — Technical deep-dive (shell modules, patterns)
- **[LUMINA-INTEGRATION.md](LUMINA-INTEGRATION.md)** — Desktop configuration
- **[ADMIN-PANEL.md](ADMIN-PANEL.md)** — Admin UI specification
- **[REFACTOR-SUMMARY.md](REFACTOR-SUMMARY.md)** — Why Lumina-only, not multi-DE

---

## Philosophy: Standing on Giants' Shoulders

| Giant | Contribution |
|-------|--------------|
| **FreeBSD** | ZFS, jails, rc.d, pkg, stability |
| **PC-BSD** | Lumina desktop, installer patterns |
| **POSIX shell** | Portability, simplicity, proven patterns |
| **bsddialog** | Native FreeBSD UI (no GTK/Qt bloat) |
| **Bastille** | Jail orchestration |

---

## Features

### 🖥️ Lumina Desktop
- Lightweight (~150 MB RAM)
- Designed for FreeBSD (from PC-BSD)
- Openbox window manager, stable, simple

### 🛠️ Admin Panel
Right-click Lumina taskbar → "Clawdie Admin":
- System Health (CPU, RAM, ZFS pool)
- Jails (start/stop, console)
- ZFS Snapshots (create, restore)
- Logs, Configuration

### 📦 Shell Modules
Modular, reusable, testable:
- `clawdie-shell-env.sh` — Identity + secrets
- `clawdie-shell-pkg.sh` — Repositories
- `clawdie-shell-gpu.sh` — GPU detection
- `clawdie-shell-system.sh` — System config
- `clawdie-shell-clawdie.sh` — AI setup + jails

### 🧰 Local Git (Forgejo-ready)
- Plain git jail by default
- Optional Forgejo web UI (runs in `{agent}-git` on port `3000`, internal only)

### 🔒 Offline-First
- All packages bundled on USB
- Reproducible deploys
- Falls back to online if connected

---

## System Requirements

- **CPU:** 2 cores (4 recommended)
- **RAM:** 4 GB (8 GB recommended)
- **Disk:** 50 GB
- **GPU:** Intel, AMD, NVIDIA, or VESA fallback

---

## Version History

- **v0.9.0-rc1** (23.mar.2026) — Initial "Shell" branding, Lumina, modular architecture
- **v0.9.0** (planned) — Stable release
- **v1.0.0** (planned) — Multi-arch support

---

## Known Limitations

- Single desktop (Lumina only)
- X11 only (no Wayland)
- Interactive deployment (no cloud-init)

---

## Contributing

- **Issues:** [Codeberg Issues](https://codeberg.org/Clawdie/Clawdie-ISO/issues)
- **Philosophy:** Keep focused (one DE, one purpose). Inherit, don't reinvent.

---

## Building

```bash
git clone https://codeberg.org/Clawdie/Clawdie-ISO.git
cd Clawdie-ISO

# Fetch packages (non-root)
./build.sh --fetch-only

# Build ISO (requires root)
doas ./build.sh

# Output: tmp/output/clawdie-iso-<variant>-DD.mmm.YYYY.img
```

See [CLAWDIE-SHELL.md](CLAWDIE-SHELL.md) for full specification.

---

**Last updated:** 23.mar.2026
**Standing on:** FreeBSD, Lumina, PC-BSD wisdom