# 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/modified 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 `xz -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.
