clawdie-iso/docs/ISO-MANIFESTS.md

ISO Workflow Manifest Conventions

This repo is the producer of operator-USB workflow artifacts. Colibri and operator dashboards consume the JSON manifests, summaries, and referenced logs; they do not scrape terminal scrollback as the contract.

Common rules

All ISO workflow manifests SHOULD include these top-level fields:

Field	Meaning
schema	Stable schema id, for example clawdie.iso.publish.v1
project	clawdie-iso
workflow	Skill or script name that produced the manifest
run_id	Unique run id; include UTC time and commit or artifact stem when possible
status	pass, fail, warn, or skipped
actor	Responsible role or operator-visible identity
host	Host that performed the workflow
branch / commit	ISO repo branch and commit when a checkout is available
started_at / completed_at	UTC ISO-8601 timestamps; use null when unknown
inputs	Artifact URLs, image paths, package lists, device ids, or report paths consumed
checks	Array or object of named checks with pass/fail status and concise details
outputs	Manifest path, public URLs, copied reports, or produced artifact paths
logs	Paths to raw logs. Do not inline large logs.
summary	Short human-readable result suitable for Colibri activity text

Secrets, API keys, auth keys, private SSH keys, and full unredacted environment dumps MUST NOT be written into manifests. If a workflow uses a secret, record a boolean such as tailscale_auth_key_baked: true or a public fingerprint only.

Canonical schema ids and paths

Workflow	Schema	Canonical output path
ISO build	clawdie.iso.build.v1	tmp/colibri/iso-build/<run_id>.json and tmp/colibri/iso-build/latest.json
ISO publish	clawdie.iso.publish.v1	tmp/output/<image>.manifest.json
Flash verification	clawdie.iso.flash.v1	tmp/colibri/iso-flash/<run_id>.json and tmp/colibri/iso-flash/latest.json
Mounted validation	clawdie.iso.validation.v1	tmp/colibri/iso-validation/<run_id>.json and tmp/colibri/iso-validation/latest.json
Hardware report ingest	clawdie.iso.hardware.v1	tmp/colibri/iso-hardware/<run_id>.json and tmp/colibri/iso-hardware/latest.json
Package audit	clawdie.iso.package-audit.v1	tmp/colibri/iso-package-audit/<run_id>.json and tmp/colibri/iso-package-audit/latest.json

tmp/colibri/ is repo-local scratch/output state. It is intentionally not committed. When a result must survive across hosts, commit a concise handoff summary under doc/ or publish the manifest with the image artifact.

Workflow-specific fields

clawdie.iso.build.v1

Use for the build result, not for the embedded image manifest alone. Include:

• build command and flags
• FreeBSD version/architecture
• source branch/commit/dirty state
• Colibri staging mode and artifact directory when FEATURE_COLIBRI=YES
• output image path, compressed image path when present, checksum path when present
• static checks run before build (sh -n, markdown format, Colibri preflight)
• build log path under tmp/

The image itself also carries /usr/local/share/clawdie-iso/build-manifest.json; that file is for runtime inspection from the live USB and does not replace the workflow result manifest.

clawdie.iso.publish.v1

Produced by scripts/write-artifact-manifest.sh. Include:

• compressed image, checksum file, and manifest names
• SHA256 of the compressed image
• raw and compressed sizes when known
• public URLs when published
• checksum verification status
• publish host, actor, branch, and commit

clawdie.iso.flash.v1

Use for Hermes USB/IMG Deployer verification and flashing. Include:

• consumed publish manifest URL/path
• downloaded image/checksum paths
• checksum and gzip -t results
• selected whole-disk device, model, serial when available, and size
• explicit confirmation that the target is a whole disk, not a partition
• flash command summary and post-flash sync/eject result

clawdie.iso.validation.v1

Use for static or mounted-image validation on the FreeBSD build host. Include:

• image path and mount device/slices inspected
• SDDM, clawdie-live-gpu, mdo, CLI, seed-slice, no-blank, power, and panel asset checks
• validation limitations, especially that mounted inspection is not graphical hardware proof

clawdie.iso.hardware.v1

Use for real-machine live USB reports. Include:

• hardware model, BIOS/UEFI version when collected, CPU, GPU, network, audio, input summary
• /var/log/clawdie-live-gpu.log outcome
• GL renderer, SDDM/XFCE status, power/no-blank status
• hw-report output path and public hw-probe URL if the operator uploaded it
• operator-observed pass/fail notes for touchpad, Wi-Fi, audio, and display

clawdie.iso.package-audit.v1

Use for package-list hygiene. Include:

• package list file audited
• package category (boot-critical, operator-workflow, diagnostic, or candidate-to-defer)
• package size and flat size from the FreeBSD package database or archive metadata
• reason kept and deferral risk

Handoff expectations

• Skills should print the manifest path and a concise summary when they finish.
• If a workflow is manual-only, write the manifest from the collected facts before handing off to another role.
• Raw logs stay in tmp/ or with the published artifact; markdown handoffs should quote only the exact failure lines needed for follow-up.
• Build, publish, and mounted validation remain FreeBSD-owner workflows. Flashing remains Hermes-owned. Live hardware proof remains operator/Codex hardware validation, not static inspection.