layered-soul/skills/bootable-usb-images/references/clawdie-iso-publish-deployer.md

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:

<image>.img.gz
<image>.img.gz.sha256
<image>.manifest.json

The manifest should carry at least:

{
  "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:

SHA256 (tmp/output/file.img.gz) = b22e...

Linux verification must normalize this before using sha256sum:

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

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:

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.