skills/numericalos-target-classifier/SKILL.md

back to source

---
name: numericalos-target-classifier
description: Use FIRST, before any NumericalOS build skill, to decide which target the user's machine can actually produce - OCI container image, initramfs, hybrid ISO/USB, or nothing buildable here. Triggers - "build NumericalOS", "make a NumericalOS image", "boot NumericalOS", "which NumericalOS target", "NumericalOS on my machine", or any request to produce NumericalOS bootable media or a container image. Probes the real toolchain rather than assuming, and routes to exactly one build skill.
---

# NumericalOS target classifier

You are about to build NumericalOS on someone else's machine. You do not know
what is installed. Probe first, classify second, route third.

**Never skip the probe.** The single most common failure in this family is an
agent that assumes Docker exists, writes a Containerfile, and hands the user a
build command that fails on the first line.

## What NumericalOS is, in one paragraph

A Linux userspace whose init is a graph export. `boot/bootstrap.sh` resolves the
CPU architecture from a generated table, hash-verifies its inputs, and execs
`boot/numinit.sh`, which walks boot phases in ordinal order, resolves a unit
dependency DAG, applies per-phase failure policy, and supervises units. The
entire configuration is one file, `numos.state`. There are no unit files.

## Honesty contract - applies to every skill in this family

The NumericalOS repository has **never been booted**, on hardware or in
emulation, by its authors. The shell logic is tested; the boot is not. When you
build a target you are producing the first real boot of this system on the
user's machine.

Therefore:

- Never tell the user something booted unless you watched it boot.
- Report what actually happened, including failures, including partial success.
- If a step fails, say which step and show the output. Do not retry silently and
report the retry.
- `numericalos-verify-boot` is the only skill that may make a boot claim, and
only about the specific run it observed on the specific arch it observed.

## Step 1 - probe the machine

Run these and record every answer. Do not infer one from another.

```sh
uname -s # kernel: Linux / Darwin / MINGW* / MSYS*
uname -m # arch: x86_64 / aarch64 / ...
id -u # 0 = root
command -v docker podman nerdctl # OCI builders
command -v busybox # may already be present
command -v cpio gzip find # initramfs essentials
command -v xorriso mkisofs genisoimage # ISO builders
command -v qemu-system-x86_64 # emulation for verification
command -v zig gcc clang musl-gcc # static build fast path
command -v git curl wget sha256sum # fetch + verify
ls /boot/vmlinuz* /boot/Image* 2>/dev/null # a kernel to pair with initramfs
```

On Windows, also check whether WSL is real rather than a stub:

```sh
wsl.exe --status
```

`wsl.exe` existing on PATH proves nothing - Windows ships a stub that reports
"not installed". Read the output.

## Step 2 - classify

Evaluate in order. First match wins. Do not present a menu of all four.

| # | Condition | Target | Route to |
|---|---|---|---|
| 1 | An OCI builder exists (`docker`, `podman`, or `nerdctl`) | **OCI image** | `numericalos-build-oci` |
| 2 | Kernel is Linux AND `cpio` + `gzip` + `find` exist | **initramfs** | `numericalos-build-initramfs` |
| 3 | initramfs is possible AND an ISO builder exists AND a kernel image is present | **hybrid ISO/USB** | `numericalos-build-iso` |
| 4 | None of the above | **nothing buildable here** | stop - see below |

Two refinements that change the answer rather than decorate it:

- **Row 1 before row 2 deliberately.** An OCI image is the fastest honest
feedback loop and needs no kernel. Prefer it even on a Linux host that could
do more, unless the user explicitly asked for bootable media.
- **Row 3 subsumes row 2.** If the user asked for bootable media and the machine
can do ISO, go straight to `numericalos-build-iso` - it builds the initramfs
as its first stage.

**If the user explicitly named a target**, honor it, but still run the probe and
tell them plainly if their machine cannot do it. "You asked for an ISO; this
machine has no `xorriso` and no kernel image, so I can produce an initramfs
instead, or an OCI image" is useful. Silently substituting is not.

## Step 3 - state the classification before building

Tell the user, in this shape:

```
Probed: <kernel> <arch>, root=<yes/no>
Found: <the tools that exist>
Absent: <the tools that do not>
Target: <chosen target> because <the row that matched>
Not doing: <targets ruled out and why>
```

Then invoke exactly one build skill. Do not invoke two.

## Row 4 - when nothing is buildable

Say so directly and stop. Do not improvise a partial artifact to have something
to show.

The honest options to offer:

- Install one of: Docker Desktop, Podman, or WSL2 with a Linux distribution
- Run the build on a Linux host or VM and bring the artifact back
- Use a cloud shell or CI runner that provides a Linux userspace

A machine with no container runtime, no Linux kernel, and no cpio cannot produce
a NumericalOS target. That is a fact about the machine, not a failure of the
build.

## What every build skill needs from you

Hand the chosen skill:

- `ARCH` - canonical architecture from the repo's `ArchTarget` registry, not raw
`uname -m`. Resolve it with `boot/lib/arch_table.sh`'s `numos_canonical_arch`,
which is generated from that registry.
- `REPO` - path to a checkout, or the clone URL if there is none yet
- `STATE` - path to a `numos.state`, or a note that one must be exported first
with `py -m numos.export_state --out dist` (or `python3` on POSIX)
- The probe results, so the next skill does not re-probe

## Related skills

- `numericalos-build-oci` - OCI/Docker/Podman image
- `numericalos-build-initramfs` - cpio initramfs
- `numericalos-build-iso` - hybrid ISO/USB, builds initramfs first
- `numericalos-verify-boot` - QEMU smoke test; the only skill that may claim a boot