skills/AGENTS.md

# NumericalOS - agent build protocol

Instructions for an autonomous agent, or a coordinated set of agents, building
NumericalOS targets **on a user's machine**.

These skills do not generate images and do not host them. They tell your agent
how to build a target locally, on hardware you control, from a repository you can
clone and inspect. Nothing here phones home and nothing here ships you a binary
blob you did not fetch yourself.

## The five skills

| Skill | Role | Produces |
|---|---|---|
| `numericalos-target-classifier` | probe + route | a decision, and exactly one downstream skill |
| `numericalos-build-oci` | container target | OCI image (Docker/Podman/containerd) |
| `numericalos-build-initramfs` | userspace half | `cpio.gz` whose `/init` is the bootstrap |
| `numericalos-build-iso` | bootable media | hybrid BIOS/UEFI ISO, USB-writable |
| `numericalos-verify-boot` | the gate | a boot observation, PASS or FAIL |

## Flow

```
numericalos-target-classifier
(probe the real machine)
|
+---------------------+---------------------+
| | |
OCI builder? Linux + cpio? + ISO tools + kernel?
| | |
build-oci build-initramfs build-iso
| | |
| +----------+----------+
| |
run + report numericalos-verify-boot
(no boot claim) (may claim a boot)
```

Rules the flow encodes:

1. **Classification comes first, always.** No build skill may run without probe
results. Assuming Docker exists is the most common failure in this family.
2. **Exactly one build skill per run.** The classifier picks one. Do not fan out
across all three to see which succeeds.
3. **`build-iso` subsumes `build-initramfs`.** It runs it as stage one. Do not
run both as siblings.
4. **Only `verify-boot` may claim a boot.** Build skills produce artifacts and
say exactly that.
5. **Containers never reach `verify-boot`.** They share the host kernel; there is
no boot to observe. Their run step lives in `build-oci`.

## The honesty contract

This is the non-negotiable part, and it is stricter than usual for a reason.

The NumericalOS repository states `Status: bootstrap logic tested; boot
unverified`. Its authors built it on a machine with no compiler, no container
runtime, and no WSL - so the shell and Python logic are tested (141 tests) while
the boot itself has never been observed by anyone. When your agent builds a
target, it may well be producing the first real boot of this system.

That imposes obligations:

- **Never report success you did not observe.** "The ISO built" and "the ISO
boots" are different claims with different evidence.
- **Scope every claim.** A PASS from `verify-boot` covers one artifact, one
architecture, one emulator version. It does not cover other arches and it does
not cover real hardware.
- **Report failures with their output.** Quote the `numos:` lines verbatim. A
summarized failure is a failure someone has to reproduce to understand.
- **Do not retry silently.** If a step fails and you change something and it then
works, report both the failure and the change.
- **A fail-closed halt is not a bug.** `numos: HALT:` means the system refused to
proceed on input it could not verify. Report it as correct behavior with a
named reason, not as breakage.
- **Distinguish "does not suit this environment" from "broken".** A seeded state
whose units run `mount -t proc` and `ntpd` will halt inside a bare emulated
machine. The state is wrong for the environment; the init is working.

If your agent framework rewards reporting success, this contract overrides it.

## Multi-agent decomposition

For a coordinated run, these are the natural boundaries. Each is independently
verifiable, which is what makes them safe to split.

| Agent | Owns | Hands off |
|---|---|---|
| **Prober** | Step 1 of the classifier - the raw capability survey | probe results; makes no decision |
| **Router** | classification and target choice | `ARCH`, `REPO`, `STATE`, chosen target |
| **Builder** | exactly one build skill | artifact path + sha256 + what was *not* proven |
| **Verifier** | `numericalos-verify-boot` | boot verdict + full serial log |
| **Reporter** | assembling the final account | one report, failures included |

Two rules that keep this from degrading:

- **The Verifier must not be the Builder.** An agent that built an artifact has
an interest in it working. Separating them is the cheapest available guard
against motivated reporting.
- **The Reporter may not upgrade a verdict.** It aggregates; it does not
reinterpret a FAIL as a partial success or a HALT as a pass.

Serial execution is fine and usually better. The decomposition exists to keep
roles honest, not to make the build faster.

## Where a human must decide

Do not proceed past these without explicit confirmation:

- **Writing to a USB device.** `dd` to the wrong `/dev/sdX` destroys a disk. The
user names the device; you never infer it.
- **Registering `binfmt_misc` for cross-arch builds.** It modifies host state.
- **Shipping an unverified third-party busybox into PID 1.** Offer the
checksum-verified path or a from-source build; if neither is available, say
plainly what is being trusted.
- **Anything requiring root that the user did not ask for.**

## Getting the repository

```sh
git clone https://numericalos.com/numericalos.git
cd numericalos
python3 -m unittest discover -s tests # 141 tests, no third-party deps
```

The clone is served as static files over dumb-HTTP - no forge, no account, no
server-side code. You can verify what you got against its history before you run
any of it, which is the property that matters when the artifact you are about to
build becomes PID 1.

## Related

- Documentation: https://numericalos.com/docs/
- Whitepaper: https://numericalos.com/whitepaper
- Skill index (machine-readable): https://numericalos.com/index.json
- Skill bundle: https://numericalos.com/skills.zip