2026-06-02 09:00:35 +02:00
8 changed files with 520 additions and 2 deletions
--- a/docs/ISO-MANIFESTS.md
+++ b/docs/ISO-MANIFESTS.md
@ -0,0 +1,128 @@
+# 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.
--- a/scripts/write-artifact-manifest.sh
+++ b/scripts/write-artifact-manifest.sh
@ -140,8 +140,16 @@ _gz_size="$(file_size "${_gz}")"

 _branch="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo unknown)"
 _commit="$(git rev-parse --short HEAD 2>/dev/null || echo unknown)"
+_repo_dirty="null"
+if git diff --quiet 2>/dev/null && git diff --cached --quiet 2>/dev/null; then
+    _repo_dirty="false"
+elif git rev-parse --git-dir >/dev/null 2>&1; then
+    _repo_dirty="true"
+fi
 _host="$(hostname 2>/dev/null || echo unknown)"
 _written_at="$(date -u '+%Y-%m-%dT%H:%M:%SZ')"
+_run_stamp="$(date -u '+%Y%m%dT%H%M%SZ')"
+_run_id="${_run_stamp}-${_stem##*/}"
 _freebsd="$(freebsd-version -kru 2>/dev/null | tr '\n' ' ' | sed 's/[[:space:]]*$//')"
 _builder="${BUILT_BY:-Codex ISO Builder}"
 _build_command="${BUILD_COMMAND:-unknown}"
@ -159,11 +167,20 @@ fi
 _tmp="${_manifest}.tmp.$$"
 cat > "${_tmp}" <<EOF
 {
-  "schema": "clawdie.iso-artifact.v1",
+  "schema": "clawdie.iso.publish.v1",
+  "legacy_schema": "clawdie.iso-artifact.v1",
  "project": "clawdie-iso",
-  "artifact_type": "operator-usb-image",
+  "workflow": "iso-publish",
+  "run_id": "$(json_escape "${_run_id}")",
+  "status": "pass",
+  "actor": "$(json_escape "${_builder}")",
+  "host": "$(json_escape "${_host}")",
  "branch": "$(json_escape "${_branch}")",
  "commit": "$(json_escape "${_commit}")",
+  "repo_dirty": ${_repo_dirty},
+  "started_at": null,
+  "completed_at": "$(json_escape "${_written_at}")",
+  "artifact_type": "operator-usb-image",
  "build_host": "$(json_escape "${_host}")",
  "built_by": "$(json_escape "${_builder}")",
  "image": "$(json_escape "${_raw_base}")",
@ -179,6 +196,25 @@ cat > "${_tmp}" <<EOF
  "image_url": $(json_string_or_null "${_image_url}"),
  "sha256_url": $(json_string_or_null "${_sha_url}"),
  "manifest_url": $(json_string_or_null "${_manifest_url}"),
+  "inputs": {
+    "compressed_image_path": "$(json_escape "${_gz}")",
+    "sha256_path": "$(json_escape "${_sha}")"
+  },
+  "checks": [
+    {
+      "name": "checksum_file_matches_compressed_image",
+      "status": "pass",
+      "sha256": "$(json_escape "${_gz_hash}")"
+    }
+  ],
+  "outputs": {
+    "manifest_path": "$(json_escape "${_manifest}")",
+    "image_url": $(json_string_or_null "${_image_url}"),
+    "sha256_url": $(json_string_or_null "${_sha_url}"),
+    "manifest_url": $(json_string_or_null "${_manifest_url}")
+  },
+  "logs": [],
+  "summary": "Published artifact manifest is ready for Hermes checksum/gzip verification and flashing.",
  "notes": "Built on FreeBSD; ready for Hermes USB/IMG Deployer after checksum and gzip verification."
 }
 EOF
--- a/skills/iso-build/SKILL.md
+++ b/skills/iso-build/SKILL.md
@ -39,6 +39,14 @@ Keep the real paths as-is, but speak about them clearly:
 - `tmp/cache/FreeBSD-*.img` = cached memstick base image
 - `tmp/packages` = fetched package archives

+## Manifest contract
+
+The build workflow should emit or hand off `clawdie.iso.build.v1` results under
+`tmp/colibri/iso-build/` when Colibri ingestion is part of the task. The image
+itself also embeds `/usr/local/share/clawdie-iso/build-manifest.json` for live
+runtime inspection. See `docs/ISO-MANIFESTS.md` for the schema fields and path
+conventions.
+
 ## Preconditions

 - Run on the FreeBSD build host, from the repo root
--- a/skills/iso-flash-verify/SKILL.md
+++ b/skills/iso-flash-verify/SKILL.md
@ -0,0 +1,106 @@
+---
+name: iso-flash-verify
+description: Verify a published Clawdie operator USB artifact manifest, download and checksum the image, confirm the whole-disk USB target, flash it, and emit a Colibri flash manifest.
+---
+
+# iso-flash-verify
+
+Use this skill for the Hermes USB/IMG Deployer lane. It consumes a published
+`clawdie.iso.publish.v1` manifest and produces a `clawdie.iso.flash.v1`
+manifest. Do not run it from this ISO developer host unless the operator
+explicitly reassigns flashing.
+
+## Safety rules
+
+- Never flash from terminal scrollback alone; start from a manifest URL or path.
+- Verify the SHA256 and run `gzip -t` before writing bytes.
+- Flash only a whole disk such as `/dev/sdX` or `/dev/daX`, never a partition
+  such as `/dev/sdX1`.
+- Record the selected device model, serial, and size before flashing.
+- Abort if the target is smaller than the raw image size in the manifest.
+
+## Manifest output
+
+Write the result to:
+
+```sh
+tmp/colibri/iso-flash/<run_id>.json
+tmp/colibri/iso-flash/latest.json
+```
+
+Schema: `clawdie.iso.flash.v1`. See `docs/ISO-MANIFESTS.md`.
+
+## 1. Select the publish manifest
+
+Set one of these:
+
+```sh
+MANIFEST_URL="https://osa.smilepowered.org/downloads/iso/<image>.manifest.json"
+```
+
+or:
+
+```sh
+MANIFEST_PATH="tmp/output/<image>.manifest.json"
+```
+
+## 2. Download artifacts
+
+For a URL-based handoff:
+
+```sh
+mkdir -p tmp/flash-downloads
+curl -fL -o tmp/flash-downloads/publish.manifest.json "$MANIFEST_URL"
+```
+
+Read the manifest and download the `image_url` and `sha256_url` it names. If
+`jq` is available:
+
+```sh
+IMAGE_URL="$(jq -r .image_url tmp/flash-downloads/publish.manifest.json)"
+SHA_URL="$(jq -r .sha256_url tmp/flash-downloads/publish.manifest.json)"
+curl -fL -O --output-dir tmp/flash-downloads "$IMAGE_URL"
+curl -fL -O --output-dir tmp/flash-downloads "$SHA_URL"
+```
+
+## 3. Verify checksum and gzip integrity
+
+```sh
+cd tmp/flash-downloads
+sha256sum -c "$(basename "$SHA_URL")"
+gzip -t "$(basename "$IMAGE_URL")"
+cd -
+```
+
+If the checksum file is in FreeBSD `sha256(1)` format, compare manually:
+
+```sh
+sha256sum tmp/flash-downloads/*.img.gz
+cat tmp/flash-downloads/*.img.gz.sha256
+```
+
+## 4. Identify the whole-disk target
+
+On Linux:
+
+```sh
+lsblk -o NAME,TYPE,SIZE,MODEL,SERIAL,TRAN,RM,MOUNTPOINTS
+```
+
+Unmount any mounted partitions from the selected removable disk. Confirm the
+whole-disk path with the operator before writing.
+
+## 5. Flash
+
+Example for Linux, replacing `/dev/sdX` with the confirmed whole disk:
+
+```sh
+gzip -dc tmp/flash-downloads/<image>.img.gz | sudo dd of=/dev/sdX bs=4M status=progress conv=fsync
+sync
+```
+
+## 6. Emit flash manifest
+
+Record pass/fail checks, the artifact URLs, selected target disk facts, flash
+command summary, and completion time in `clawdie.iso.flash.v1`. Print the
+manifest path and a one-line summary for Colibri ingestion.
--- a/skills/iso-hardware-report-ingest/SKILL.md
+++ b/skills/iso-hardware-report-ingest/SKILL.md
@ -0,0 +1,72 @@
+---
+name: iso-hardware-report-ingest
+description: Ingest real-machine live USB hw-report evidence into a structured Colibri hardware manifest without treating static inspection as hardware proof.
+---
+
+# iso-hardware-report-ingest
+
+Use this skill after the operator or Codex ISO Builder collects live USB evidence
+from real hardware. It produces a `clawdie.iso.hardware.v1` manifest for Colibri
+and dashboard consumers.
+
+## Manifest output
+
+Write the result to:
+
+```sh
+tmp/colibri/iso-hardware/<run_id>.json
+tmp/colibri/iso-hardware/latest.json
+```
+
+Schema: `clawdie.iso.hardware.v1`. See `docs/ISO-MANIFESTS.md`.
+
+## Inputs to collect from the live USB
+
+Prefer files copied from the live session over paraphrased observations:
+
+```sh
+hw-report > /tmp/clawdie-hw-report.txt
+pciconf -lv > /tmp/clawdie-pciconf-lv.txt
+ifconfig -a > /tmp/clawdie-ifconfig-a.txt
+cat /var/log/clawdie-live-gpu.log > /tmp/clawdie-live-gpu.log
+```
+
+When debugging GUI/input/audio issues, also collect the relevant exact command
+output named in `PLAN-OPERATOR-USB-NEXT.md`, for example:
+
+```sh
+xinput list
+xfconf-query -c pointers -lv
+cat /dev/sndstat
+sysctl hw.snd.default_unit
+mixer
+```
+
+If `hw-probe` upload is intentionally run, record only the public probe URL in
+the manifest. Do not upload private operator data without approval.
+
+## Ingest checklist
+
+Record these as manifest checks or evidence fields:
+
+- machine vendor/model and firmware version when available
+- CPU model
+- GPU PCI IDs, selected KMS module, and reason from `clawdie-live-gpu.log`
+- GL renderer if collected
+- SDDM login result and XFCE session result
+- internal display and external display behavior if tested
+- touchpad, keyboard, webcam, audio, Wi-Fi, and USB Ethernet observations
+- Tailscale status if it was part of the test
+- no-blank/power behavior observed during the session
+- image filename or commit shown by the live build manifest
+
+## Finish
+
+Write a concise summary such as:
+
+```text
+AMD ASUS UX325UA: pass for SDDM/XFCE/AMD KMS/USB Ethernet/webcam; touchpad needs follow-up.
+```
+
+Attach paths to raw captured files under `logs` or `outputs`. Keep the manifest
+small enough for Colibri to ingest directly.
--- a/skills/iso-package-audit/SKILL.md
+++ b/skills/iso-package-audit/SKILL.md
@ -0,0 +1,80 @@
+---
+name: iso-package-audit
+description: Categorize operator USB package-list entries, capture package size/flat-size evidence on FreeBSD, and emit a Colibri package-audit manifest.
+---
+
+# iso-package-audit
+
+Use this skill for Track B package-list hygiene. It classifies package-list
+entries and records size evidence before any removal is proposed. Do not remove
+packages during the audit commit.
+
+## Manifest output
+
+Write the result to:
+
+```sh
+tmp/colibri/iso-package-audit/<run_id>.json
+tmp/colibri/iso-package-audit/latest.json
+```
+
+Schema: `clawdie.iso.package-audit.v1`. See `docs/ISO-MANIFESTS.md`.
+
+## Categories
+
+Use exactly one primary category per package:
+
+- `boot-critical` — kernel/firmware/X/SDDM/network/power pieces needed for the
+  live USB to boot and present a usable session.
+- `operator-workflow` — tools the operator intentionally uses from the live USB,
+  such as browser, CLIs, terminal/editor, or remote access.
+- `diagnostic` — hardware/debug/reporting tools such as `btop`, `hw-probe`,
+  `dmidecode`, or graphics/audio diagnostics.
+- `candidate-to-defer` — rarely used or replaceable packages that may be removed
+  later after build/hardware evidence supports it.
+
+## FreeBSD evidence commands
+
+Run on the FreeBSD build host with the target package branch configured. Fetch
+before reporting repo state:
+
+```sh
+git fetch origin
+git status --short --branch
+git rev-parse --short HEAD
+```
+
+For installed packages on a mounted image or host package DB:
+
+```sh
+pkg info -s <pkgname>
+pkg info -f <pkgname> | egrep '^(Name|Version|Installed size|Flat size)'
+```
+
+For packages present only in the offline repo, inspect package metadata from the
+archive under `tmp/packages` and record the exact command used.
+
+## Audit output expectations
+
+For each package-list entry, record:
+
+- package name
+- package-list file path and line number when practical
+- category
+- package archive size and flat/installed size
+- reason kept
+- deferral risk if categorized as `candidate-to-defer`
+- evidence command or metadata source
+
+If editing a package list, add comments only. Do not remove packages in the same
+change as the first audit pass.
+
+## Finish
+
+Write the `clawdie.iso.package-audit.v1` manifest and a concise human summary
+with totals per category and total size by category. If markdown package-list
+comments were edited, run:
+
+```sh
+./scripts/check-format.sh
+```
--- a/skills/iso-publish/SKILL.md
+++ b/skills/iso-publish/SKILL.md
@ -18,6 +18,14 @@ public download target.
 - Public webroot: `/usr/local/www/osa/downloads/iso`
 - Public base URL: `https://osa.smilepowered.org/downloads/iso`

+## Manifest contract
+
+`scripts/write-artifact-manifest.sh` writes the canonical
+`clawdie.iso.publish.v1` manifest beside the image as
+`tmp/output/<image>.manifest.json`. Hermes consumes that file for
+`iso-flash-verify`; Colibri can ingest it directly. See
+`docs/ISO-MANIFESTS.md` for shared fields and handoff rules.
+
 ## Preconditions

 Run from the repo root on the FreeBSD host. Use one command at a time.
--- a/skills/iso-validate-image/SKILL.md
+++ b/skills/iso-validate-image/SKILL.md
@ -0,0 +1,80 @@
+---
+name: iso-validate-image
+description: Inspect a freshly built Clawdie operator USB image or mounted root to validate static runtime contracts and emit a Colibri validation manifest.
+---
+
+# iso-validate-image
+
+Use this skill on the FreeBSD build host after an image exists and the operator
+has assigned mounted-image validation. This is static validation only; it does
+not replace real hardware proof that SDDM/XFCE/input/audio work.
+
+## Manifest output
+
+Write the result to:
+
+```sh
+tmp/colibri/iso-validation/<run_id>.json
+tmp/colibri/iso-validation/latest.json
+```
+
+Schema: `clawdie.iso.validation.v1`. See `docs/ISO-MANIFESTS.md`.
+
+## Preconditions
+
+Run from the repo root on FreeBSD. Fetch before reporting repo state:
+
+```sh
+git fetch origin
+git status --short --branch
+git rev-parse --short HEAD
+ls -lh tmp/output
+```
+
+If an image is already mounted under `tmp/cache/mnt`, inspect it cautiously. If
+mount state is stale or unclear, use `iso-build-cleanup` before retrying.
+
+## Validation checklist
+
+Record each item as a named check in the manifest:
+
+- `/etc/rc.conf` enables `sddm`.
+- `/etc/rc.conf` enables `clawdie_live_gpu`.
+- `/etc/rc.conf` enables `powerdxx` and the expected no-blank power/session
+  policy files are present.
+- `/usr/local/bin/mdo` exists and is executable; `sudo` is not required by live
+  operator-facing paths.
+- Operator CLIs expected by the current plan are present (`pi`, `codex`, and any
+  intentionally retained package-list CLIs).
+- `/usr/local/share/clawdie-iso/build-manifest.json` exists inside the image.
+- `CLAWDIESEED` slice 3 exists when inspecting the full disk image.
+- `clawdie-live-gpu` and hardware report scripts are present and executable.
+- Intel and AMD KMS modules/firmware expected by the package lists are present;
+  NVIDIA packages are staged/offline but not forced to load by default.
+- XFCE panel/session assets referenced by the live session are present.
+- Colibri binaries and `colibri_daemon` rc.d script are present when
+  `FEATURE_COLIBRI=YES` was used.
+
+## Suggested inspection commands
+
+Use exact device names from `mdconfig`/`gpart` on the build host; do not paste
+these blindly if another build is active.
+
+```sh
+IMG="tmp/output/<image>.img"
+md=$(mdconfig -a -t vnode -f "$IMG")
+gpart show -p "/dev/$md"
+```
+
+Mount the root partition read-only when possible, then inspect files under the
+mountpoint. Clean up the md device before finishing.
+
+## Finish
+
+Write a `clawdie.iso.validation.v1` manifest with:
+
+- image path and checksum/manifest inputs when available
+- mount devices and mountpoint used
+- pass/fail status for each checklist item
+- cleanup status for unmounts and `mdconfig -d`
+- an explicit limitation note: mounted validation is not graphical hardware proof