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, Cloudflare remote ISO (no WSL), or nothing buildable here. Triggers - "build NumericalOS", "make a NumericalOS image", "boot NumericalOS", "which NumericalOS target", "NumericalOS on my machine", "ISO without WSL", "Cloudflare ISO", 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
x86_64 under QEMU: self-init has completed (`degraded=0`); fleet bare-QEMU is
PASS-degraded. Metal and other arches have not been observed. When you build a
target you still produce an unproven artifact until `numericalos-verify-boot`
runs on **that** artifact and arch.
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.
- **Do not install WSL without explicit user approval.** Prefer
`numericalos-build-iso-cf` when the user wants ISO artifacts without WSL.
## 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
command -v wrangler npx # Cloudflare CLI path
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. **Do not run `wsl --install` unless the user
explicitly asked for WSL.**
Cloudflare availability (for the no-WSL ISO path):
```sh
npx wrangler whoami 2>&1 | head -20
# optional: HEAD the deployed builder if known
# curl -sS -o /dev/null -w "%{http_code}" https://numericalos-iso-builder.<sub>.workers.dev/health
```
Also note whether the checkout contains `deploy/cloudflare-iso-builder/`.
## Step 2 - classify
Evaluate in order. First match wins. Do not present a menu of all options.
| # | Condition | Target | Route to |
|---|---|---|---|
| 1 | User explicitly asked for **Cloudflare / no-WSL ISO** AND (`wrangler whoami` works OR builder already deployed OR user accepts one-time Docker to deploy builder) | **CF hybrid ISO/initramfs** | `numericalos-build-iso-cf` |
| 2 | An OCI builder exists (`docker`, `podman`, or `nerdctl`) AND user did **not** demand bootable media | **OCI image** | `numericalos-build-oci` |
| 3 | User wants bootable media AND Kernel is Linux AND `cpio`+`gzip`+`find` AND ISO builder AND kernel image present | **hybrid ISO/USB** | `numericalos-build-iso` |
| 4 | Kernel is Linux AND `cpio` + `gzip` + `find` exist (no ISO tools / no kernel) | **initramfs** | `numericalos-build-initramfs` |
| 5 | User wants bootable media (or ISO was implied by MegaPraxis verify path) AND local rows 3–4 failed AND Cloudflare is available (whoami OR deployable scaffold) AND WSL is not installed / not wanted | **CF hybrid ISO/initramfs** | `numericalos-build-iso-cf` |
| 6 | None of the above | **nothing buildable here** | stop - see below |
Refinements:
- **Row 1 honors explicit CF / no-WSL intent** even if Docker exists for OCI.
- **Row 2 before local ISO deliberately** when the user did not ask for bootable
media: OCI is the fastest honest feedback loop.
- **Row 3 subsumes initramfs** when the user asked for bootable media and the
machine can do local ISO.
- **Row 5 is the Windows default for ISO** when QEMU/verify is the goal and WSL
is absent: do not propose silent WSL install; route to CF.
- **Local Docker for OCI ≠ Linux ISO tools.** Docker alone does not unlock
`build-iso` unless you use it as a Linux environment deliberately; prefer
named CF skill over improvising a one-off container.
**If the user explicitly named a target**, honor it, but still run the probe and
tell them plainly if their machine cannot do it. Silently substituting is not
allowed — except offering `build-iso-cf` as the documented substitute when they
asked for ISO and local tools are missing.
## 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>
WSL: <not installed | real distro | stub only>
CF: <whoami ok | no auth | builder URL if known>
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 6 - 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:
- Deploy or use `numericalos-build-iso-cf` (Cloudflare Sandbox + R2) — **preferred
over WSL when the user wants ISO without local Linux**
- Install one of: Docker Desktop / Podman (for OCI or one-time CF image publish)
- Run the build on a Linux host or VM and bring the artifact back
- Install WSL2 **only if the user explicitly wants WSL** (never silent)
A machine with no container runtime, no Linux kernel tools, no Cloudflare auth,
and no remote builder 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
- For CF: whether `deploy/cloudflare-iso-builder` exists and any known Worker URL
## Related skills
- `numericalos-build-oci` - OCI/Docker/Podman image
- `numericalos-build-initramfs` - cpio initramfs (local Linux)
- `numericalos-build-iso` - hybrid ISO/USB local, builds initramfs first
- `numericalos-build-iso-cf` - hybrid ISO/initramfs via Cloudflare (no WSL)
- `numericalos-verify-boot` - QEMU smoke test; the only skill that may claim a boot