# Your AI's Guide to Building With JefeOS

**Audience:** an AI coding agent helping a human build and run software on JefeOS 1.1.2.
**Read this before you build.** Everything below is grounded in what JefeOS actually does today. Items you cannot rely on yet are explicitly tagged **(roadmap)**.

---

## 1. What JefeOS is

JefeOS is a from-scratch x86_64 operating system: a native C++ kernel (Limine-booted, 4-level paging, per-process page tables, preemptive round-robin scheduler) with its own libc, ELF64 loader, NTFS read/write, a full TCP/IP + TLS 1.3 + SSH network stack, a framebuffer GUI, and an 80+ command shell. It reached **1.1.2 stable** and ships a bootable ISO on jefeos.com. A parallel Rust kernel (**JefeRust**) tracks feature parity but is a separate build/VM — unless the human says "JefeRust," assume you are targeting the **C++ kernel**.

### The mental model (three layers, one machine)

1. **Native JefeOS** — the real OS. Native programs are x86_64 ELF binaries that talk to the kernel over **`INT 0x80`**. This is the first-class citizen.
2. **Linux ABI compat (JSL-1)** — a WSL1-style translation layer. Real Linux x86_64 binaries use the **`SYSCALL`** instruction, which the CPU routes via the LSTAR MSR to a separate handler. 142 Linux syscalls are implemented today (up from 28 at the start of 2026). This coexists with `INT 0x80`; it is *translation*, not a Linux kernel.
3. **POSIX 1003.1-2024 (Issue 8)** — the *measured standard* the libc/kernel aim at (~83% strict coverage). This is a coverage yardstick, not a runtime layer.

These are three independent tracks, not a hierarchy. A program can be native (best-supported), a Linux ELF run under `exec_linux` (compat), or evaluated against POSIX for portability. Know which one you're targeting before writing a line.

Key process-model note: the first-class native primitive is **`sys_spawn`** (async spawn-with-child), and **`fork()` now works too** — implemented as an *eager full-address-space copy* (`task::fork_current`), with two caveats: there is **no copy-on-write yet** (forking a large heap copies every present page), and it is **UP-only** (it fails closed under SMP — but SMP is off by default). Because fork + in-place `execve` + `chroot(2)` all landed, a busybox shell under `chroot` now forks and execs on-VM. The remaining wall for the deepest Linux workloads is **Tier-5 Alpine-init depth** (orphan-reaping into init, `tcsetpgrp` job control, a `getty`/console login path) — no longer `fork()` itself. See §5 and §10.

---

## Quickstart — boot JefeOS in about a minute

JefeOS has no installer — you point a virtual machine at the ISO and boot. Grab [`jefeos-1.1.2.iso`](downloads/jefeos-1.1.2.iso), and optionally the writable examples disk [`jefeos-examples.vhd.zip`](downloads/jefeos-examples.vhd.zip) (unzip it to `jefeos-examples.vhd` — it carries ~19 native programs under `/programs`). Then pick your hypervisor. Each recipe below uses 512 MB of RAM, no hard disk of its own, and a NIC JefeOS has a driver for so networking comes up on boot.

### QEMU (Linux/macOS/Windows)

Most portable — one command, and the kernel's serial log streams straight to your terminal:

```bash
qemu-system-x86_64 -cdrom jefeos-1.1.2.iso -m 512M -serial stdio \
  -netdev user,id=net0 -device e1000,netdev=net0 \
  -drive file=jefeos-examples.vhd,format=raw,if=ide
```

- `-serial stdio` mirrors the kernel serial log into your terminal.
- `-netdev user` gives NAT plus a built-in DHCP server, so JefeOS's DHCP client gets an address.
- `-device e1000` matches JefeOS's E1000 NIC driver.
- The `-drive …examples.vhd` line is **optional** — drop it entirely to boot the ISO on its own.

### VirtualBox (GUI)

- **New** → Type **Other**, Version **Other/Unknown (64-bit)** → **512 MB** RAM → **Do not add a virtual hard disk**.
- **Settings → Storage** → attach `jefeos-1.1.2.iso` to the optical drive.
- **Settings → Network → Adapter 1** → **NAT**, then **Advanced → Adapter Type → Intel PRO/1000 MT Desktop (82540EM)** (this is the E1000 the driver binds).
- **Start.**

### Hyper-V (Windows)

Save this as `quickstart-jefeos.ps1` and run it from an **elevated (Administrator)** PowerShell with the **Hyper-V feature enabled**:

```powershell
#Requires -RunAsAdministrator
# quickstart-jefeos.ps1 — create and boot a JefeOS VM on Windows Hyper-V.
# Usage:  .\quickstart-jefeos.ps1 -IsoPath .\jefeos-1.1.2.iso
param(
  [string]$IsoPath     = ".\jefeos-1.1.2.iso",
  [string]$VmName      = "JefeOS",
  [int64] $MemoryBytes = 512MB,
  [string]$SwitchName  = "Default Switch"
)
$ErrorActionPreference = "Stop"
if (-not (Test-Path $IsoPath)) { throw "ISO not found: $IsoPath" }

# Gen 1 VM (JefeOS boots via BIOS/Limine), no hard disk — it boots straight from the ISO.
New-VM -Name $VmName -Generation 1 -MemoryStartupBytes $MemoryBytes -SwitchName $SwitchName -NoVHD | Out-Null
Set-VMDvdDrive -VMName $VmName -Path $IsoPath

# The default synthetic NIC has no JefeOS driver. Swap in a Legacy adapter so networking + DHCP work.
Get-VMNetworkAdapter -VMName $VmName | Remove-VMNetworkAdapter
Add-VMNetworkAdapter -VMName $VmName -IsLegacy $true -SwitchName $SwitchName

# Boot from CD first.
Set-VMBios -VMName $VmName -StartupOrder @("CD","IDE","LegacyNetworkAdapter","Floppy")

Start-VM -Name $VmName
Write-Host "JefeOS '$VmName' is booting. Open Hyper-V Manager and connect to the VM for the console."
```

Prefer the GUI? In **Hyper-V Manager**: create a **Generation 1** VM with no hard disk, attach the ISO, replace the network adapter with a **Legacy Network Adapter**, and start it.
### OpenStack (1.1.2, validated)

JefeOS 1.1.2 is validated as an ordinary **Nova-managed guest**: upload the ISO through **Glance**, schedule and launch it with **Nova**, and manage the instance and serial console through **Horizon**. At boot, JefeOS reads Nova's ISO 9660 `config-2` config-drive, applies the instance hostname and authorized SSH keys, discovers `network_data.json`, and brings up its E1000 NIC with DHCP.

Keep the image properties conservative: **BIOS boot, IDE storage, and E1000 networking**. Native virtio-net/virtio-blk are not supported yet; arbitrary static network configuration from `network_data.json` is not applied; and this proves OpenStack managing JefeOS as a guest, not JefeOS acting as an OpenStack controller or REST client.

Once booted you land in the JefeOS shell — type `gui` for the desktop or `help` to explore.

---

## 2. Connecting to JefeOS (SSH / plink)

JefeOS runs in Hyper-V as a DHCP client on the **Default Switch**. Two gotchas dominate:

- **The IP changes every host reboot.** The Default Switch picks a new random `172.x.x.x/20` subnet. There is no stable static address.
- **The SSH host key regenerates on every JefeOS boot.** The Ed25519 host key is not persisted yet, so it is different after each rebuild.

### The connection contract: `jefeos-targets.json`

Run the discovery script once per session; it uses `ssh-keyscan` to grab the fresh key and writes a targets file:

```powershell
C:\jefeshare\dev\JefeOS\scripts\restore-network.ps1
# add -RestartVMs to force JefeOS to re-DHCP after a rebuild
```

Output — `$env:LOCALAPPDATA\JefeOS\jefeos-targets.json`:

```json
{ "JefeOS": { "ip": "172.21.252.151", "hostkey_sha256": "SHA256:..." } }
```

### Connect with `plink` (not OpenSSH `ssh`)

`plink` uses its own host-key cache, so you pass the scraped fingerprint directly with `-hostkey`. From PowerShell:

```powershell
$t = Get-Content $env:LOCALAPPDATA\JefeOS\jefeos-targets.json | ConvertFrom-Json
plink -ssh -batch -pw jefe -hostkey $t.JefeOS.hostkey_sha256 "jefe@$($t.JefeOS.ip)" "help"
```

From bash (Claude Code default shell):

```bash
JEFEOS_IP=$(jq -r '.JefeOS.ip' "$LOCALAPPDATA/JefeOS/jefeos-targets.json")
JEFEOS_FP=$(jq -r '.JefeOS.hostkey_sha256' "$LOCALAPPDATA/JefeOS/jefeos-targets.json")
plink -ssh -batch -pw jefe -hostkey "$JEFEOS_FP" jefe@$JEFEOS_IP "id"
```

Default login is `jefe` / password `jefe`. Each `plink … "cmd"` is a **one-shot exec** — it opens a channel, runs one command, prints output, and disconnects. That is your primary automation primitive: drive JefeOS by firing one shell command at a time and parsing text.

### Do NOT

- Use Windows OpenSSH `ssh` — it prompts for a password interactively and hangs `-batch` automation.
- Use `echo password | ssh …` — does not work on Windows OpenSSH.
- Hardcode `192.168.156.200` or any static IP — those subnets are gone; retries against dead IPs have tripped outbound-scan IDS alerts. Harness scripts now **fail closed** unless `$env:JEFEOS_IP` / `$env:JEFEOS_HOSTKEY` / `$env:JEFEOS_SSH_PASSWORD` are set, and `bench/run-bench.ps1` defaults to `-DryRun` unless `-Force` is passed.

### Troubleshooting

| Symptom | Fix |
|---|---|
| plink "host key not cached" | Re-run `restore-network.ps1` — the key changed since last boot |
| Connection times out / unreachable | JefeOS may be wedged: `restore-network.ps1 -RestartVMs` |
| `ssh.exe` prompts for password | Use `plink -pw`, not OpenSSH |
| VM not discovered | Confirm it's on the Default Switch: `Get-VMNetworkAdapter -VMName JefeOS` |

**JefeRust note:** its serial console (COM1 named pipe `\\.\pipe\jeferust_serial`) is **output-only** — you can read boot logs from it but cannot drive the shell through it. Use SSH for interaction; use serial for boot-time proof capture.

---

## 3. The shell and key commands

The shell is a monolithic if/else dispatcher. It supports **pipes (`|`)**, **output redirection (`>`, `>>`)**, and **input redirection (`<`)** end-to-end. It has cross-platform aliases (Linux + Windows + some Cisco), so `ls`/`dir`, `cat`/`type`, `clear`/`cls` all work. It does **not** support `&&` (see §9).

Commands, grouped:

**File ops**
`ls` `dir` · `cd` · `pwd` · `mkdir` · `rmdir` · `rm` · `cp` · `mv` · `ln` · `touch` · `cat`/`type` · `less` · `stat` · `chmod` · `chown` · `du` · `df`

**Text utilities** (POSIX-style, regex where noted)
`grep` (regex) · `head` · `tail` · `wc` · `cut` · `sort` · `uniq` · `tee` · `tr` · `hexdump` · `basename` · `dirname` · `seq`

**Process / identity**
`ps` / `tasks` · `kill` · `su` · `whoami` · `id` · `sleep` · `time`

**System / info**
`reboot`/`restart`/`reload` · `halt` · `poweroff` · `sysinfo` · `uptime` · `date` · `clock` · `uname` · `lsdev` · `free` · `memory`/`mem` · `cpus`/`lscpu`

**Networking**
`ping` · `dns`/`nslookup` · `dhcp` · `ifconfig`/`ipconfig` · `netstat`/`ss` · `ssh` · `sftp` · `curl` · `tlstest` · `ntp` · `nts` · `wsconnect` (WebSocket client)

**Program execution**
`exec <file>` — run a **native** JefeOS ELF · `exec_linux <file>` — run a **Linux** musl/glibc ELF · `elftest` · `lcompat` (Linux compat status)

**GUI**
`gui` (launch desktop) · `theme list` · `theme set <name>`

Verified idioms:

```bash
echo "hello world" | grep world        # pipes work
ps | grep shell                         # pipe-to-filter
curl https://www.cloudflare.com/        # full TLS 1.3 GET
theme set modern                        # aliases: win31 win95 mac amiga modern (or dark)
```

---

## 4. Filesystems and path conventions

JefeOS uses forward-slash, root-anchored paths (`/programs/foo`, `/tmp/x`). Key surfaces:

| Mount / area | Backing | R/W | Notes |
|---|---|---|---|
| `/tmp` | **NTFS data VHD** | read/write | **Not tmpfs.** Persists across reboots. |
| `/run` | **RAM tmpfs** | read/write | Volatile; cleared on reboot. |
| NTFS data disk (e.g. `/programs`) | NTFS | read/write | Multi-block dir-index grow + non-resident `$DATA` extend both work. |
| `/alpine` (when staged) | NTFS | read/write | chroot rootfs for Linux workloads (§5). |
| FAT32 volumes | FAT32 | **read-only** | BPB, LFN, cluster chains parse; write **(roadmap)**. |
| JefeFS | native kernel FS | read/write | Native filesystem. |

**NTFS is production-grade for this OS.** The historical "`/tmp` write wedges the VM" blocker is fixed: non-resident `$DATA` grows past its initial allocation, directory indexes grow across multiple blocks, and grown volumes pass `chkdsk /f` exit 0. Round-trip write/read is verified (`synctest` 6/6, `trunctest` 5/5).

Practical rules for an AI building here:

- Write scratch that must survive reboot to `/tmp`. Write ephemeral runtime state to `/run`.
- NTFS lookup/unlink is **case-sensitive** (POSIX interop) while on-disk `$INDEX` collation stays case-insensitive for Windows-mount/chkdsk compatibility. `Makefile`, `makefile`, and `MAKEFILE` are three distinct files.
- Disk I/O uses the **ATA PIO** driver as the canonical block backend. AHCI is detected and can do DMA reads/writes but is **not yet wired as the mount backend (roadmap)**.

---

## 5. Getting a program onto JefeOS and running it

There are two paths. Pick based on what you're shipping.

### Path A — Native JefeOS ELF (best-supported)

Native programs are x86_64 ELFs that call the kernel via `INT 0x80`. The canonical distribution vehicle is the **examples disk**: `jefeos-examples.vhd.zip` (writable NTFS, ~19 native ELFs under `/programs`), published on jefeos.com alongside `BUILD-FOR-JEFEOS.md` (the syscall-ABI + disk-attachment build guide).

Workflow:

1. Build your ELF against the native `INT 0x80` ABI (see `BUILD-FOR-JEFEOS.md` and §6). Existing regression programs (e.g. `userspace/programs/tmpgrow`, `wstest`) are working references.
2. Get it onto an NTFS disk JefeOS can see — either drop it into the examples VHD, or `sftp`/`scp` it in over SSH, or write it via the shell.
3. Run it:

```bash
exec /programs/yourprog
```

Constraint: an `exec`-spawned child has a **~10-second foreground timeout**. Anything long-lived (a server, a bot) must be launched in the background — see §8.

### Path B — Linux ELF via the compat layer (`exec_linux`)

Real Linux x86_64 binaries run through the `SYSCALL`/LSTAR path. Cross-compile on a Linux host, copy to a JefeOS-visible NTFS disk, then:

```bash
exec_linux /hello
lcompat            # show compat status: supported syscalls + stats
```

Unimplemented syscalls **log to serial with their number**, so when a Linux binary misbehaves, read the serial log to see exactly which syscall is missing.

**Linux workload maturity (the honest ladder):**

| Tier | Workload | Status |
|---|---|---|
| 1 | Static **musl** binaries | **GREEN** |
| 2 | Static **glibc** binaries (full auxv + FS_BASE) | **GREEN** |
| 3 | **Dynamic linker** (`ld-musl-x86_64.so.1` loads `hello`) | **GREEN** |
| 4 | `chroot` + busybox / Alpine rootfs | **GREEN** (2026-07-06) — busybox shell inside `chroot(2)` forks+execs jailed programs; CI-locked |
| 5 | Alpine `/sbin/init` + job control | **(roadmap)** ~60% — fork/execve/chroot present; remaining = orphan-reaping into init, `tcsetpgrp`, getty/console |

**Alpine `apk` under chroot works partially today.** Under `chroot(/alpine)`, real dynamic `apk-tools` runs (READ path: `apk info` lists packages), and some real packages (`tree`, `jq`) **install and run** — using `--no-scripts`, because dropping `--no-scripts` and full Alpine init need Tier 5 init depth. Do not promise "runs Alpine" as a finished capability; four of five tiers are green, a busybox shell now forks and execs under `chroot`, and the remaining gate is **Tier-5 Alpine-init depth**, not `fork()`.

---

## 6. Syscall surfaces

### Native INT 0x80 (first-class)

The native ABI is the primary interface. It covers process/exec (`sys_spawn` async-with-child), file I/O, memory (`sbrk`/brk), time, sleep, yield, getpid, and a **WebSocket block at numbers 327–331** (`ws_connect` / `ws_send` / `ws_recv` / `ws_status` / `ws_close`), added so ring-3 userspace can do WebSockets natively.

**Do not hardcode "next free syscall number."** The authoritative reservation map is `kernel/src/syscall.cpp`; native syscalls run through the WebSocket block at 331, and the next-free number moves as features land. Read the map before adding one.

### Linux SYSCALL compat (142 implemented)

`SYSCALL` → LSTAR MSR → `linux_syscall_entry` (asm) → `linux_syscall_handler` (C++). Returns via **`IRETQ`** (not `SYSRET`, to sidestep GDT reordering and Intel CVE-2012-0217). Per-task state: 64-fd table, brk pointer, TLS (FS base via `arch_prctl`).

The 142-call surface is too large to list here; the table below is the **core**. Beyond it, the process-model and threading calls that unblocked real Linux userspace all landed in early-to-mid 2026: **`fork`(57) / `clone`(56) / `execve`(59) / `wait4`(61)**, **`futex`(202)** (core WAIT/WAKE — this is what lets glibc/libuv pthreads run), **`chroot`(161)**, **`pipe`(22) / `dup2`(33)**, `epoll` / `eventfd` / `signalfd`, and **16 socket syscalls** bridged to the native BSD layer.

| Category | Syscalls (Linux numbers) |
|---|---|
| File I/O | `read`(0) `write`(1) `open`(2) `close`(3) `fstat`(5) `lseek`(8) `ioctl`(16) `writev`(20) `access`(21) `openat`(257) |
| Memory | `mmap`(9) `mprotect`(10) `munmap`(11) `brk`(12) |
| Process | `exit`(60) `exit_group`(231) `getpid`(39) `gettid`(186) `arch_prctl`(158) `set_tid_address`(218) |
| Time | `clock_gettime`(228) `nanosleep`(35) |
| Info | `uname`(63) `getcwd`(79) |

**Not supported (compat layer) — treat as absent (roadmap):** `clone3`(435) → `ENOSYS` (musl uses `clone`; only glibc needs `clone3`), `io_uring`, `aio_*`, `inotify`, `pidfd`, `splice`/`sendfile`/`vmsplice`. If a Linux binary needs any of these, it will fail; check serial for the syscall number.

**POSIX note:** against IEEE 1003.1-2024 the libc measures ~83% strict. `posix_spawn` is functional (libc thunk over native `SYS_SPAWN`); `symlink`/`readlink` exist on NTFS but are not fully wired to syscalls; full realtime signal-queue ordering, ICU-grade locale, and `aio_*` are gaps **(roadmap)**.

---

## 7. Networking

The stack is one of JefeOS's strongest areas and is fully usable from the shell.

**Layers implemented:** Ethernet, ARP (IPv4 + IPv6 link-local), IPv4 (ICMP, DHCP client), IPv6 link-local + NDP + ICMPv6, UDP, TCP (client + server, RFC 6528 CSPRNG ISN seeding, congestion control). DNS resolver (A + AAAA), NTP (SNTP RFC 4330), NTS (RFC 8915), TLS 1.3 (full handshake, ALPN, RFC 5705 exporter, post-handshake KeyUpdate rekey, non-blocking recv + partial-record buffering), HTTPS client (GET + POST, chunked decode), SSH server + client, SFTP server + client, WebSocket-over-TLS (RFC 6455 framer, live TLS transport). Crypto: ChaCha20-Poly1305, Ed25519, Curve25519, X25519, SHA-256/512, HMAC, HKDF, AES-128/256, AES-CMAC, AES-SIV-CMAC-256, plus RSA-PSS / RSA-PKCS1v15 / ECDSA-P256/P384 for cert verify.

Everyday commands:

```bash
ping 8.8.8.8                                   # ICMP round-trips
dns google.com                                 # A/AAAA resolution
curl https://www.cloudflare.com/               # TLS 1.3 + HTTP GET
ssh jefe@<host>                                # outbound SSH client
sftp jefe@<host>                               # interactive SFTP
ntp time.cloudflare.com                        # SNTP time sync
nts time.cloudflare.com                        # authenticated (NTS) time sync
wsconnect wss://gateway.discord.gg/?v=10&encoding=json   # WebSocket over TLS
tlstest <host>                                 # TLS handshake probe
```

**NIC drivers:** E1000 (QEMU/VMware) and Tulip/DEC 21140 (Hyper-V). The `drivers::nic` dispatcher picks the right one at boot.

**Hyper-V Gen1 gotcha:** you must attach a **Legacy Network Adapter**. A synthetic NIC gives no DHCP, and the VM will appear to have no IP. If `restore-network.ps1` can't find the VM's address, check the NIC type first.

**IPv6 caveat (roadmap):** link-local + NDP + ICMPv6 + AAAA DNS exist, but there is **no SLAAC-derived global address and no IPv6 socket binding** — do not plan v6-only services.

**Inbound services:** the SSH server is always-on, and a kernel-resident HTTP server (port 80, auto-started once the network is up and NTFS is mounted; `Connection: close`, GET/HEAD only, file serving jailed to `/posix/`) serves the static `/posix/` compliance dashboard **and a live `GET /api/status` JSON endpoint**. `/api/status` returns a real runtime snapshot assembled from kernel state — `uptime_ms`, task `current`/`max`, network `configured`+`ip`, `ntfs_mounted`, and httpd `connections_served`/`last_error_code`. Beyond that endpoint, the finer-grained live state (`ps`, `free`, `ifconfig`, `netstat`, `uptime`) is **text over SSH exec**, parseable but not yet JSON — widening `/api/status` into a fuller `/status.json` is **(roadmap)**.

---

## 8. Worked example: a Node.js Discord bot running on the OS

This is the flagship "real workload" and the template for any long-lived networked userspace app. It is a **Node.js userspace program**, not a kernel feature — the architectural decision was: kernel provides minimal TCP/TLS + a reusable WebSocket primitive; Discord logic lives in userspace and is updated like an npm package, not re-engineered into the kernel.

How the pieces stack:

1. **Kernel WebSocket ABI** — native `INT 0x80` syscalls 327–331 (`ws_connect`/`ws_send`/`ws_recv`/`ws_status`/`ws_close`) plus a kernel receive-frame queue (`RxRing`). Ring-3 code opens a WS-over-TLS connection and pushes/pulls frames through syscalls.
2. **TLS 1.3 transport** with ALPN, non-blocking recv, partial-record buffering, and **KeyUpdate rekey** so a long-lived gateway connection doesn't die.
3. **The bot itself** — `nodebot.js`, a Node.js program doing the Discord gateway dance: Hello (op:10) → IDENTIFY (op:2) → heartbeat (op:1) / ACK (op:11) → READY, then a 24/7 heartbeat loop. Verified live: `op:1` sent via the `ws_send` syscall, `op:11` ACK in ~200 ms; connected with 0 reconnects.

Operational rules learned the hard way:

- **Launch it in the background (`-bg`), never foreground `exec`.** A foreground `exec` child is killed at ~10 s; the bot must run detached (it soaks as a background task, e.g. PID 5, state OPEN).
- **The Discord token is per-platform and never committed.** It lives in a gitignored app config (`userspace/pv-apps/nodebot/app/config`), user-provided, never in the repo and never in the Vault dump. If you build a bot, take the token from the human at runtime; do not print, log, or commit it.
- **Commands it answers:** `!status` (HTTP health-polls other services), `!jefeos` (version / uptime / whoami / latest git commit), and a model-aware system prompt so it reports its actual LLM instead of hallucinating one.

The takeaway for you: to run a persistent networked service on JefeOS, ship it as a userspace program, connect outbound over the TLS/WS stack, run it `-bg`, and drive/observe it over SSH.

---

## 9. Known limitations and gotchas

Internalize these before you generate commands or programs — several will silently eat your work if you don't.

- **No `&&` operator.** The shell drops everything after the first `&&`. `cmd1 && cmd2` runs only `cmd1`. Run commands **one per `plink` exec** (or one per line). This has burned multi-session test suites — pipes (`|`) and redirection (`>`,`>>`,`<`) *do* work; `&&`/`||`/`;` chaining does not.
- **No Ctrl+C.** There is no shell interrupt/job-control signal to a running foreground command. Design around it; don't launch something you can't cleanly exit.
- **`exec` foreground children time out at ~10 s.** Long-lived programs must run in the background.
- **`fork()` works, with caveats.** It is a real *eager full-address-space copy* — but there is **no copy-on-write yet** (forking a large heap copies every present page), and it is **UP-only** (fails closed under SMP; SMP is off by default). Fork/exec and fork-per-connection patterns run; the remaining wall is Tier-5 Alpine-init depth, not `fork()` itself.
- **Mouse disabled by default** (PS/2 driver exists but is off for Hyper-V Gen1 safety). GUI is keyboard-driven unless explicitly enabled.
- **SSH host key regenerates every boot** — re-scrape with `restore-network.ps1` each session; plink caches keys in its own registry store, not OpenSSH `known_hosts`.
- **IP changes every host reboot** (DHCP on Default Switch). Never hardcode it.
- **Hyper-V Gen1 requires a Legacy NIC** or there is no networking.
- **HTTP server is GET/HEAD only, file-serving jailed to `/posix/`.** There *is* a live `GET /api/status` JSON endpoint (uptime, tasks, net, NTFS, httpd stats); finer state (`ps`/`free`/`ifconfig`/`netstat`) is text over SSH, not JSON.
- **JefeRust serial is output-only** — read boot proof from it; you cannot type into the shell through it.
- **FAT32 is read-only; AHCI is not the mount backend; SMP is not the default** — all **(roadmap)**.
- **Shell dispatch is monolithic** — known tech debt; command behavior is literal and unforgiving of shell metacharacters it doesn't implement.

---

## 10. Capabilities matrix: works-today vs roadmap

| Area | Works today (1.1.2, verified) | Roadmap / not yet |
|---|---|---|
| **Kernel/memory** | 4-level paging, per-process page tables, preemptive scheduler, 64 KB boot + per-task stacks, global memory accountant + OOM killer, demand-paged anon memory | SMP default (arch exists, deferred) |
| **Native ABI** | `INT 0x80` incl. WS syscalls 327–331, `sys_spawn` async-with-child, `fork`/`clone`/`execve`/`wait` (eager full-copy, UP-only), ELF64 loader, ring-3 | copy-on-write + SMP-safe fork |
| **Linux ABI** | 142 syscalls; Tiers 1–4 GREEN (musl static, glibc static, dynamic linker, busybox under chroot); `fork`/`clone`/`execve`/`wait4`, `futex`, 16 socket calls, `chroot`, `pipe`/`dup2`, `epoll`/`eventfd`/`signalfd`; `apk` READ + some pkgs under chroot | `io_uring`, `sendfile`/`splice`, `inotify`, `pidfd`; Tier-5 Alpine-init depth |
| **POSIX 1003.1-2024** | ~83% strict; `posix_spawn` functional | remaining 17%: full RT signals, ICU locale, `aio_*`, symlink syscalls |
| **Filesystems** | NTFS r/w (grows, chkdsk-clean), `/tmp` persistent, `/run` tmpfs, JefeFS, FAT32 **read** | FAT32 write, AHCI mount backend |
| **Networking** | Eth/ARP/IPv4/ICMP/DHCP/DNS/UDP/TCP, IPv6 link-local, TLS 1.3, HTTPS, SSH (srv+cli), SFTP, NTP, NTS, WS-over-TLS | IPv6 global/SLAAC + v6 socket binding |
| **Crypto** | ChaCha20-Poly1305, Ed25519, X25519/Curve25519, SHA-256/512, HMAC/HKDF, AES-128/256, AES-CMAC/SIV, RSA/ECDSA verify | — |
| **GUI** | 5 themes (Win31/Win95/Mac Classic/Amiga/Modern Dark), framebuffer WM, text editor | mouse-on-by-default, theme parity in JefeRust |
| **Security** | Vault (ChaCha20-Poly1305 + PBKDF2), permission bitmask, `su`/`chmod`/`perms`, TLS cert + hostname enforcement | — |
| **Real workloads** | Node.js Discord bot live over WS/TLS; `curl` real HTTPS; SSH peering | — |
| **Workload supervision (Xylem)** | In-place snapshot → reap → respawn of a wedged process-group, **no VM reboot** (demonstrated on the live Discord bot over a multi-hour soak: ~10 cycles, flat memory, 0 panics) | Cross-node membership/failover, cell migration, service-as-kernel-object |
| **Telemetry** | Live `GET /api/status` JSON (uptime, tasks, net, NTFS, httpd stats) + static `/posix/` dashboard; finer state as text via SSH (`ps`/`free`/`ifconfig`/`netstat`) | widened `/status.json`, cluster telemetry |
| **Kernels** | C++ (primary), JefeRust (parity-tracking, live TLS 1.3 verified) | full JefeRust parity |

---

## 11. Differentiation: Xylem (climbing real rungs)

JefeOS's stated long-term identity is a **natively-clustered OS** codenamed **Xylem** — the "cluster-as-organism" model where every component is an isolated, live-replaceable, self-healing cell, with the OS itself doing membership, replica supervision, failover, and self-scaling. The near-term on-ramp is "a great Linux host (WSL-2.0-style)"; the differentiator is native clustering. This is still mostly a **long-arc direction**, but it has now climbed two real rungs.

**What ships today:**

- **1.0.0 — membership + failure detection.** A SWIM-style gossip protocol, demonstrated 2-node and converging headless on *both* the C++ and Rust kernels.
- **1.1.0 — in-place workload supervision (the headline).** The kernel watches a userspace workload for **real forward progress** (not a naive heartbeat), so a silent wedge is caught where a health check would be fooled. On a wedge it **snapshots diagnostic state before reaping**, then tears the whole process-group down — threads, memory, sockets, even parked-worker `futex` slots — and **respawns it in place under a crash-loop guard, with no VM reboot**. Demonstrated live on the Discord bot that runs on JefeOS 24/7: reaped and reborn ~10 times over a multi-hour soak, flat memory across every cycle, 0 panics, answering commands throughout.

**Honest framing:** supervision *harvests* the bot's periodic wedge (an upstream Node/libuv-runtime bug the JefeOS kernel has been cleared of) — it keeps the service alive and preserves the diagnostic sample a reboot would destroy; **it does not cure the userspace bug**. And this is **single-vessel** (intra-VM) supervision. Everything *above* it remains the long arc (1.2+): service-as-kernel-object with a reconcile loop, cross-node membership beyond the 2-node gossip demo, replica failover, cell migration / checkpoint-resume, Raft/consensus, per-cgroup resource accounting.

There is still **no stable public "Xylem API"** to code against — you get supervision by running your workload and letting the kernel watch it. Build against the single-node native + Linux-compat surfaces documented in §§5–8. When the human talks about "hotswappable / self-healing / clustered JefeOS," 1.1.0's in-place reap-and-respawn is the first concrete piece of that vision; the cross-node control plane is still ahead.

---

## What to expect (and what's not done yet)

JefeOS is a hobby OS at its first stable release. None of this is a dealbreaker for kicking the tires — but know it going in.

**Booting & using it**

- **Run it in a VM.** There's no installer and it has not been run on real hardware. Don't put data you care about on a disk it writes to — back up first.
- **Hyper-V Gen 1 needs a Legacy Network Adapter.** The synthetic NIC has no driver, so without the legacy adapter you'll have no network and no DHCP.
- **Networking is DHCP by default.** On the Hyper-V Default Switch the assigned subnet can change across host reboots.
- **The SSH host key is regenerated on every boot** (not yet persisted) — expect host-key-changed warnings when you reconnect.
- **Mouse is disabled by default on Hyper-V Gen 1** for stability; the GUI is keyboard-driven.
- **The shell is deliberately minimal.** One command per line — no `&&`/`||` chaining and no Ctrl+C job control yet. Pipes (`|`) and redirects (`>`, `>>`) do work, and there are 80+ commands.

**Engineering maturity (as of v1.1.2)**

- **Single-core.** Multi-core (SMP) support is in progress but not the default — expect no parallel speedup.
- **Two kernels at different maturity.** The C++ kernel is the reference; the Rust kernel (JefeRust) is catching up — networking parity is close, but the Rust GUI is simpler and its NTFS is read-only (the C++ kernel does NTFS read+write).
- **Linux compatibility is WSL1-style and partial.** Static musl/glibc binaries, dynamic-linked binaries, and a busybox shell under `chroot` (which now forks and execs) run, and a growing set of Alpine `apk` packages install, but a full Alpine init is not there yet; unimplemented syscalls log their number to serial.
- **POSIX coverage is ~83% (strict).** Common utilities and syscalls work; obscure corners may not.
- **TLS across both kernels.** Both kernels do live TLS 1.3 to real HTTPS hosts — the **C++ kernel runs the Discord bot 24/7 over TLS to Discord's modern certificate chain**, and JefeRust is verified against example.com. The C++ client validates leaf expiry + SAN/CN hostname today; full CA-trust-store chain validation is still being hardened.

For the full builder-facing gotcha list — shell metacharacters, `fork()`, exec timeouts, syscall gaps — see §9 above.

---

**Bottom line for an AI builder:** target the native `INT 0x80` ABI first; use `exec_linux` for musl/glibc static, dynamic-linked, and fork/exec Linux binaries (`fork()` now works — eager full-copy, UP-only; only the deepest Alpine-init depth is still the wall); write persistent state to `/tmp` (NTFS) and volatile to `/run`; drive and observe everything as one-command-at-a-time text over `plink` (re-scraping the host key each session); lean on the strong TLS/SSH/WS network stack; and never chain shell commands with `&&`.