clawdie-iso/FLASHING.md

# Flashing the Clawdie Operator USB

Published Clawdie operator USB artifacts are compressed:

```text
clawdie-quindecim-0.11.0.img.xz
```

Default policy:

```text
Downloaded .img.xz  -> stream xz directly into dd
Build-local .img    -> plain dd is OK
Always write to the whole USB disk, never to a partition
```

The compressed streaming path avoids storing both the 6+ GB compressed image and
the much larger 28 GB raw image.

---

## Safety Checklist

Before writing:

1. Verify the checksum.
2. Identify the USB disk carefully.
3. Unmount any mounted partitions from that USB stick.
4. Write to the whole disk device:
   - Linux: `/dev/sdX`, `/dev/nvmeXnY`, etc.
   - FreeBSD: `/dev/daX`, etc.
5. Do **not** write to a partition such as `/dev/sdX1`, `/dev/da0p1`, or `/dev/da0s1`.

A wrong device name can destroy the host OS or another data disk.

---

## Linux: Flash a Downloaded `.img.xz`

Find the USB disk:

```sh
lsblk -o NAME,SIZE,MODEL,TRAN,MOUNTPOINTS
```

Download with resume and retries:

```sh
curl -fL --continue-at - --retry 5 --retry-delay 5 --progress-bar -O \
  https://osa.smilepowered.org/downloads/iso/clawdie-quindecim-0.11.0.img.xz
curl -fL --retry 5 --retry-delay 5 -O \
  https://osa.smilepowered.org/downloads/iso/clawdie-quindecim-0.11.0.img.xz.sha256
```

Verify the downloaded artifact:

```sh
sha256sum -c clawdie-quindecim-0.11.0.img.xz.sha256
```

Unmount mounted USB partitions if needed:

```sh
sudo umount /dev/sdX* 2>/dev/null
```

Flash by streaming xz into `dd`:

```sh
set -o pipefail 2>/dev/null || true
xz -dc clawdie-quindecim-0.11.0.img.xz | dd of=/dev/sdX bs=4M status=progress conv=fsync && sync
sync
```

Replace `/dev/sdX` with the actual whole USB disk.

---

## FreeBSD: Flash a Downloaded `.img.xz`

Find the USB disk:

```sh
camcontrol devlist
gpart show
```

Download with resume and retries:

```sh
curl -fL --continue-at - --retry 5 --retry-delay 5 --progress-bar -O \
  https://osa.smilepowered.org/downloads/iso/clawdie-quindecim-0.11.0.img.xz
curl -fL --retry 5 --retry-delay 5 -O \
  https://osa.smilepowered.org/downloads/iso/clawdie-quindecim-0.11.0.img.xz.sha256
```

Verify the downloaded artifact:

```sh
HASH=$(awk '{print $1}' clawdie-quindecim-0.11.0.img.xz.sha256)
sha256 -c "$HASH" clawdie-quindecim-0.11.0.img.xz
```

If `sha256sum` is installed, this GNU-style form is also OK:

```sh
sha256sum -c clawdie-quindecim-0.11.0.img.xz.sha256
```

Unmount mounted USB partitions if needed:

```sh
sudo umount /dev/daXs* 2>/dev/null
```

Flash by streaming xz into `dd`:

```sh
xz -dc clawdie-quindecim-0.11.0.img.xz | dd of=/dev/daX bs=1M status=progress conv=fsync && sync
sync
```

Replace `/dev/daX` with the actual whole USB disk.

---

## Windows: Flash with Rufus or balenaEtcher

No decompression step needed — both tools read `.img.xz` directly.

1. Download both files (same folder):
   - `clawdie-quindecim-0.11.0.img.xz`
   - `clawdie-quindecim-0.11.0.img.xz.sha256`
2. (Recommended) verify the checksum in PowerShell:
   ```powershell
   (Get-FileHash .\clawdie-quindecim-0.11.0.img.xz -Algorithm SHA256).Hash.ToLower()
   # compare against the value in the .sha256 file
   ```
3. **Rufus:** open Rufus → **SELECT** the `.img.xz` → choose the USB drive under "Device" → **START**. Rufus decompresses and writes in one step. (Use "DD Image" mode if prompted.)
   **balenaEtcher:** Flash from file → pick the `.img.xz` → Select target → Flash.
4. Write to the **whole USB device**, not a partition. This erases the drive.

> If your flasher is old and rejects `.xz`, extract first with 7-Zip (≥21.07) to
> get the raw `.img`, then flash that.

---

## If You Already Have an Uncompressed `.img`

For a local build artifact that already exists as a raw image:

### Linux

```sh
dd if=clawdie-quindecim-0.11.0.img of=/dev/sdX bs=4M status=progress conv=fsync && sync
sync
```

### FreeBSD

```sh
dd if=clawdie-quindecim-0.11.0.img of=/dev/daX bs=1M status=progress conv=fsync && sync
sync
```

Only unxz first if you specifically need the raw file for inspection or reuse:

```sh
unxz -k clawdie-quindecim-0.11.0.img.xz
```

---

## Optional: Wipe Old Labels Before Reflashing

Old images can leave stale metadata near the end of the USB stick. If the live
USB later reports unexpected labels, wipe the whole stick before reflashing.

### Linux

Inspect first:

```sh
sudo wipefs -n /dev/sdX
sudo fdisk -l /dev/sdX
```

Then wipe only after confirming `/dev/sdX` is the USB stick:

```sh
sudo sgdisk --zap-all /dev/sdX
dd if=/dev/zero of=/dev/sdX bs=16M status=progress conv=fsync
sync
```

### FreeBSD

Inspect first:

```sh
gpart show /dev/daX
```

Then wipe only after confirming `/dev/daX` is the USB stick:

```sh
sudo gpart destroy -F /dev/daX
dd if=/dev/zero of=/dev/daX bs=16M status=progress conv=fsync
sync
```

Some sticks may not have a partition table at inspection time; that is fine.
The important rule is to confirm the target disk before destructive commands.