skills/AGENTS.md
back to source
# NumericalOS - agent build protocol
Instructions for an autonomous agent, or a coordinated set of agents, building
NumericalOS targets **on a user's machine** or **via Cloudflare remote Linux**
when the host has no WSL/local Linux ISO tools.
These skills do not ship prebuilt OS images as the primary path. Local skills
tell your agent how to build on hardware you control. The Cloudflare skill
orchestrates a **Linux container under Cloudflare** (Sandbox + R2); it does not
pretend a Worker isolate can run `xorriso`. Nothing here silently installs WSL.
## The seven 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 (local Linux) | `cpio.gz` whose `/init` is the bootstrap |
| `numericalos-build-iso` | bootable media (local Linux) | hybrid BIOS/UEFI ISO, USB-writable |
| `numericalos-build-iso-cf` | bootable media (Cloudflare) | same artifacts via Sandbox + R2, no WSL |
| `numericalos-verify-boot` | the gate | a boot observation, PASS or FAIL |
| `numericalos-publish-site` | self-hosted site | full rebuild of numericalos.com (Pages `main`) |
## Flow
```
numericalos-target-classifier
(probe the real machine)
|
+------------+-----------+------------+------------------+
| | | | |
OCI builder? Linux+cpio? ISO tools+ CF auth + no nothing?
| | kernel? local Linux tools? |
build-oci build-initramfs build-iso build-iso-cf stop
| | | | |
| +-----+-----+ | |
| | | |
| verify-boot download from R2 |
| (may claim boot) | |
run+report verify-boot |
(no boot claim) (may claim 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 build skills to see which succeeds.
3. **`build-iso` subsumes `build-initramfs`.** It runs it as stage one. Do not
run both as siblings.
4. **`build-iso-cf` is the no-WSL bridge.** Prefer local `build-iso` when the
host already has Linux + xorriso. Prefer CF when Windows (or any host)
lacks those tools and the user does not want WSL installed.
5. **Only `verify-boot` may claim a boot.** Build skills produce artifacts and
say exactly that. CF build success is not a boot.
6. **Containers (OCI) never reach `verify-boot`.** They share the host kernel;
there is no boot to observe. Their run step lives in `build-oci`.
7. **Never install WSL without explicit user approval.** Offer CF ISO builder
or documented alternatives instead.
8. **Self-hosted site has no git remote.** After docs/status/skills content
changes that should go live, run `numericalos-publish-site` (or
`scripts/publish-site.ps1`). Pages deploy on `--branch main` is the publish
path; do not wait for a forge push.
## 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; x86_64 QEMU
self-init PASS (degraded=0) on kernel+initrd and hybrid ISO/GRUB serial; fleet
bare-QEMU PASS-degraded; metal and non-x86_64 unverified`. The shell and Python
logic are covered by the unittest suite. Self-init under QEMU 10.2.2 reached
`boot complete degraded=0` on both kernel+initrd and `-cdrom` ISO/GRUB serial;
fleet on bare QEMU still degrades. That does **not** license a boot claim for
any other artifact, arch, or host. When your agent builds a new target, run
`numericalos-verify-boot` before asserting anything about that build. Prefer
`--profile self-init` for offline complete boots;
`py -m numos.export_state --profile self-init --seed-only`.
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.
- **Cloudflare Workers are not Linux packers.** Only the Sandbox/container leg
may run `cpio`/`xorriso`. Say which leg produced the bytes.
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 (local or CF) | artifact path or R2 keys + sha256 + what was *not* proven |
| **Verifier** | `numericalos-verify-boot` | boot verdict + full serial log |
| **Reporter** | assembling the final account | one report, failures included |
| **Publisher** | `numericalos-publish-site` after content changes | live URL + probe codes |
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.**
- **Installing WSL or Docker** when the user asked for Cloudflare instead.
- **One-time Docker for publishing the CF builder image** — ask if Docker is not
already present; do not install it silently.
## Getting the repository
```sh
git clone https://numericalos.com/numericalos.git
cd numericalos
python3 -m unittest discover -s tests # stdlib only; 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.
Cloudflare builder scaffold (optional, for no-WSL ISO production):
```
deploy/cloudflare-iso-builder/
```
## 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