Use when Sam asks Hermes to act as the Clawdie IMG/ISO deployer after a FreeBSD build has already produced an image.
## Role boundary
Hermes can own **USB/IMG deployment and verification** when explicitly assigned, but should not silently become the ISO builder.
- Pi ISO Developer role: writes/pushes source code and docs.
- Codex ISO Builder role: FreeBSD build host runs `./build.sh`, mounted-image inspection, publishes build artifacts, and reports exact logs/output.
- Hermes USB/IMG Deployer role: from Linux/Telegram, downloads the published artifact, verifies manifest/checksum/gzip integrity, identifies the USB target, unmounts mounted partitions, flashes the whole disk when permitted, or gives Sam the exact copy-paste command if the runtime blocks raw-device writes.
- Claude role: reviews, plans, and XFCE polish; marks runtime claims as speculative unless proven on hardware.
- Operator role: Sam decides release/test hardware acceptance and confirms destructive USB target selection.
## Current repo/runbook anchors
- Canonical repo: `Clawdie/Clawdie-ISO` on Codeberg.
- Clawdie-AI may be relevant for hostd/deployment primitives, but ISO build/publish runbook lives in Clawdie-ISO.
-`Clawdie-ISO` branch `xfce-operator-usb` contains `skills/iso-publish/SKILL.md` as of commit `f8b370d Add ISO publish skill (Sam & Pi)`.
- Public download base seen in the runbook: `https://osa.smilepowered.org/downloads/iso/`.
- Public webroot seen in the runbook: `/usr/local/www/osa/downloads/iso`.
## Access model
- Codeberg access is optional for the Hermes USB/IMG Deployer. The deployer can work from a published artifact URL plus `.sha256` plus `.manifest.json` handoff.
- HTTPS read access is enough for inspection and planning when repo context is needed.
- SSH write access is useful for git-coordinated handoffs and small docs/skill commits, but should be least-privilege and repo-scoped.
- Prefer a dedicated deploy identity such as `hermes-deployer` rather than using a broad personal key.
- For actual webroot mutation, prefer running Hermes on the FreeBSD host or invoking a narrow hostd/deploy operation instead of granting broad SSH/root.
- For USB flashing from Linux, prefer stable `/dev/disk/by-id/usb-*` identities plus `lsblk -o NAME,PATH,SIZE,MODEL,SERIAL,TRAN,RM,HOTPLUG,MOUNTPOINTS`, then flash the whole disk path only (`/dev/sdX`, never `/dev/sdX1`).
## Artifact manifest contract
FreeBSD publish output should include three public artifacts:
```text
<image>.img.gz
<image>.img.gz.sha256
<image>.manifest.json
```
The manifest should carry at least:
```json
{
"project": "clawdie-iso",
"artifact_type": "operator-usb-image",
"commit": "f8b370d",
"branch": "xfce-operator-usb",
"compressed_image": "<image>.img.gz",
"sha256_file": "<image>.img.gz.sha256",
"sha256": "<hash>",
"raw_size_bytes": 0,
"compressed_size_bytes": 0,
"build_finished_at": "2026-05-22T00:00:00Z",
"freebsd_version": "<version>"
}
```
Do not rely on `gzip -l` for raw size on large images; use manifest `raw_size_bytes`.
## FreeBSD `.sha256` compatibility
Clawdie currently emits FreeBSD-style SHA files:
```text
SHA256 (tmp/output/file.img.gz) = b22e...
```
Linux verification must normalize this before using `sha256sum`:
```bash
HASH="$(awk '{print $NF}' file.img.gz.sha256)"
echo "${HASH} file.img.gz" | sha256sum -c -
```
If manifest exists, verify the downloaded file against the manifest `sha256` field and confirm it matches the `.sha256` trailing field.
## Publish checklist
1. Load this skill and inspect `Clawdie-ISO/skills/iso-publish/SKILL.md` from the current branch before publishing.
2. Fetch latest repo state and report current branch/commit.
3. Confirm the image filename in `tmp/output` includes the current commit suffix.
4. Refuse or ask Sam if the repo is dirty, the suffix does not match, the image is missing, or the `.gz` looks stale.
5. Compress raw `.img` to `.img.gz` only if needed.
6. Generate `.sha256` from the final `.img.gz`.
7. Rotate only old Clawdie public symlinks in the ISO webroot; do not delete `tmp/output` artifacts or unrelated webroot files.
8. Link the new `.img.gz` and `.sha256`, update `index.html`, and set expected ownership/permissions.
9. Verify local webroot and public index/checksum/image URLs.
10. Report image URL, checksum URL, index URL, SHA256, compressed size, commit, and any permission hiccups.
## Accepted implementation checkpoint
As of `Clawdie-ISO` commit `91cc0ef Add artifact manifest handoff for Hermes (Sam & Pi)`, the repo implements this contract:
-`AGENTS.md` includes **Hermes USB/IMG Deployer**.
-`skills/iso-publish/SKILL.md` publishes `.img.gz`, `.img.gz.sha256`, and `.manifest.json`.
- Publish reports a `HERMES_USB_DEPLOY_READY=1` block containing `IMAGE_URL`, `SHA256_URL`, `MANIFEST_URL`, `COMMIT`, `SIZE_BYTES`, `SHA256`, expected USB model/size, and attachment location.
When this block is pasted into chat, treat it as the formal handoff to start Linux-side download/verify/USB flashing. Codeberg access is not required for that handoff.
