layered-soul/skills/clawdie-iso-build/SKILL.md

---
name: clawdie-iso-build
description: Build the Clawdie operator USB ISO — command-line flags, cache management, pre-flight checks, and pitfalls. Covers the operational surface of build.sh (not the shell implementation).
category: freebsd
triggers:
  - "build iso"
  - "rebuild iso"
  - "clawdie image"
  - "operator usb"
---

# Clawdie ISO Build

Use this when building or rebuilding the Clawdie operator USB image. This skill
covers the **operational surface** — flags, caches, pre-reqs, pitfalls. For
implementation details, read `build.sh` directly.

## Repo

```
/home/clawdie/ai/clawdie-iso
```

## Canonical build command

```bash
cd /home/clawdie/ai/clawdie-iso
sudo FEATURE_COLIBRI=YES ./build.sh --live-default-password
```

This produces a bootable XFCE ISO with:
- `clawdie` user (password: `quindecim` — the FreeBSD 15 codename)
- Colibri daemon + zot agent staged and ready
- `START-HERE.txt` auto-opened in Mousepad on first login (bootstrap autostart)
- BW secrets instructions already in START-HERE.txt

## Build flags

| Flag | Effect | Cache required |
|------|--------|---------------|
| *(none)* | Full build: fetch memstick + packages + assemble | Nothing |
| `--skip-memstick-fetch` | Skip step 1 (1.5G FreeBSD download) | `tmp/cache/FreeBSD-*.img` |
| `--skip-fetch` | Skip steps 2+4 (packages + clawdie-ai tarball) | `tmp/packages/` + `tmp/cache/clawdie-ai-*.tar.gz` |
| `--live-default-password` | Set clawdie password to `quindecim` | — |
| `--clawdie-password <pw>` | Set explicit clawdie password | — |
| `--root-password <pw>` | Set explicit root password | — |
| `--fetch-only` | Download only, no assembly (no root needed) | — |

**Fastest rebuild** (after first build populates caches):

```bash
sudo FEATURE_COLIBRI=YES ./build.sh --live-default-password \
    --skip-memstick-fetch --skip-fetch
```

Skips all downloads — goes directly to image assembly (step 5).

## FEATURE_COLIBRI gate

`FEATURE_COLIBRI=YES` enables the full agent stack. Default is `NO` (basic
XFCE ISO without agents). When YES:

| What gets staged | Source |
|-----------------|--------|
| `colibri-daemon` | `COLIBRI_REPO/target/release/` (default: `/home/clawdie/ai/colibri/target/release/`) |
| `colibri`, `colibri-mcp` | same |
| `colibri-test-agent` | same (if `COLIBRI_STAGE_TEST_AGENT=YES`) |
| `zot` binary | `ZOT_REPO/bin/` (default: `/home/clawdie/ai/zot/bin/`) |
| `colibri_daemon` rc.d | `packaging/freebsd/colibri_daemon.in` |
| `provider.env` template | auto-generated with Vaultwarden URL |

Related vars in `build.cfg`:
- `COLIBRI_REPO` — path to colibri checkout (default: `/home/clawdie/ai/colibri`)
- `ZOT_REPO` — path to zot checkout (default: `/home/clawdie/ai/zot`)
- `ZOT_VERSION` — zot git tag (default: `v0.2.29`)
- `COLIBRI_STAGE_AGENT` — stage agent (default: `YES`)
- `COLIBRI_STAGE_TEST_AGENT` — stage test agent (default: `NO`)

## Pre-flight checklist

Before running the build, verify:

```bash
# 1. Colibri release binaries exist (needed only if FEATURE_COLIBRI=YES)
ls -la /home/clawdie/ai/colibri/target/release/colibri-daemon \
       /home/clawdie/ai/colibri/target/release/colibri \
       /home/clawdie/ai/colibri/target/release/colibri-mcp

# If missing, build them:
# cd /home/clawdie/ai/colibri && cargo build --workspace --release

# 2. zot at correct version
cd /home/clawdie/ai/zot && git checkout v0.2.29 && make build

# 3. Disk space (need ~12G for build)
df -h / | grep -v Filesystem  # should show >15G avail

# 4. Repo clean (required for BUILD_CHANNEL=release, optional for dev)
cd /home/clawdie/ai/clawdie-iso && git status -sb
```

## Build steps overview

Build takes 30-60 minutes. Steps:

| Step | What | Skipped by |
|------|------|-----------|
| 1/7 | Fetch FreeBSD memstick (1.5G) | `--skip-memstick-fetch` |
| 2/7 | Fetch packages to `tmp/packages/` | `--skip-fetch` |
| 3/7 | Generate pkg repo metadata | `--skip-fetch` |
| 4/7 | Fetch clawdie-ai tarball | `--skip-fetch` |
| 5/7 | Prepare working image (mdconfig, mount) | — |
| 6/7 | Inject payload (packages, configs, agent stack) | — |
| 7/7 | Write output to `tmp/output/` | — |

Output: `tmp/output/clawdie-quindecim-<version>.img` (+ `.sha256` + manifest)

## Running the build

Build requires root (mdconfig, mount, pkg). Always use `sudo`. The build takes
30-60 minutes — use tmux, not `terminal(background=true)` (doesn't work on
FreeBSD).

```bash
# Start in tmux window 1:3 (the dedicated iso window)
tmux send-keys -t 1:3 'cd /home/clawdie/ai/clawdie-iso && sudo FEATURE_COLIBRI=YES ./build.sh --live-default-password' Enter

# Monitor progress
tmux capture-pane -t 1:3 -p | tail -10
```

Tmux window `1:3` is named "iso" and is pre-configured for builds.

## After build

The output image is in `tmp/output/`. The bootstrap experience:
1. Boots to XFCE desktop
2. `clawdie` user auto-logged in (password: `quindecim`)
3. `START-HERE.txt` opens in Mousepad — contains BW secrets setup instructions
4. Colibri daemon starts via rc.d
5. User adds 3 BW secrets to `/usr/local/etc/colibri/provider.env`, restarts daemon

## Pitfalls

- **Must run as root.** `sudo` required. The build uses mdconfig, mount, pkg.
- **Use tmux, not background.** `terminal(background=true)` doesn't work on
  FreeBSD. Use `tmux send-keys -t 1:3` for long builds.
- **`--skip-fetch` needs cached packages.** If `tmp/packages/All/` is empty
  or stale, the build fails at step 3. Run without `--skip-fetch` first to
  populate caches.
- **`--skip-memstick-fetch` needs cached memstick.** If `tmp/cache/FreeBSD-*.img`
  is missing, build fails. The memstick rarely changes between builds.
- **zot version matters.** `build.sh` preflight checks for `-x zot`. If the
  binary exists but is stale (wrong version), it won't catch it — the version
  is only recorded in the manifest. Always `git checkout v0.2.29 && make build`
  before building.
- **Colibri binaries must be in `target/release/`.** Debug builds won't work.
  Run `cargo build --workspace --release` first.
- **Password flag is easy to forget.** Without `--live-default-password`, the
  clawdie account has no password set — requires root to fix.