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

name	description	category	triggers
clawdie-iso-build	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).	freebsd	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

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):

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:

# 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).

# 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.