# Clawdie ISO publish/deployer protocol

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**.
- `scripts/write-artifact-manifest.sh` writes `tmp/output/<image>.manifest.json`.
- `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.

## Good final report shape

```text
Published:
- Image: https://osa.smilepowered.org/downloads/iso/<image>.img.gz
- SHA256: https://osa.smilepowered.org/downloads/iso/<image>.img.gz.sha256
- Index: https://osa.smilepowered.org/downloads/iso/

Commit: <short-sha>
Checksum: <sha256>
Size: <bytes> bytes
Notes: <permission/symlink/verification issues or "none">
```

## Future repo improvements to suggest

- Add an explicit **Hermes USB/IMG Deployer** role to `Clawdie-ISO/AGENTS.md`.
- Keep `skills/iso-publish/SKILL.md` as the canonical human-readable publish runbook.
- Add a manifest creation step to `iso-publish` or a helper script that writes `tmp/output/<image>.manifest.json`; no build-system change is required.
- Publish `.img.gz`, `.img.gz.sha256`, and `.manifest.json` together.
- End the FreeBSD publish with a copy-paste block:

```text
HERMES_USB_DEPLOY_READY=1
IMAGE_URL=
SHA256_URL=
MANIFEST_URL=
COMMIT=
SIZE_BYTES=
SHA256=
EXPECTED_USB_MODEL=
EXPECTED_USB_SIZE=
USB_ATTACHED_TO=
```

- Add a deterministic script such as `scripts/publish-latest-output.sh` once the manual runbook stabilizes.
- In Clawdie-AI, consider a narrow hostd operation such as `publish_iso` that only touches the ISO webroot and logs every change.