# ADR 0006: Simplify `periphemu` Bootstrap

## Status

Accepted

## Date

2026-06-08

## Context

`startup/servers.lua` historically called `periphemu.create` four times on computer 0: a top modem, two `computer` peers at ids 1 and 2 (both labelled `Trap` in saved per-computer config), and a router peer at id 10. In CraftOS-PC GUI mode this opened **four windows** on every launch (`Computer 0`, two duplicate `Trap`s, and `Router`).

That setup predates the current workflow:

- The install path is now manifest-driven (`install.lua` v3.0.0 fetches files listed in `manifest.json` and writes a marker at `/trapos/manifest.json`). The legacy `apis/`, `programs/`, `servers/`, `install.lua` files hand-copied into each per-computer dir are obsolete.
- Local verification runs **headless** through `just test` against scripts in `tests/`; the smokes don't need persistent emulated peers.
- The duplicate `Trap` label and persistent stale computer state across versions caused recurring confusion.

The CraftOS-PC data directory (`~/Library/Application Support/CraftOS-PC/`) had also accumulated years of stale state in `computer/`, `old_computer/`, and per-id `config/*.json` files (labels like `test`, two `Trap`s, etc.).

## Decision

- `startup/servers.lua` attaches **only a top modem** under `periphemu`:

  ```lua
  if periphemu then
    periphemu.create('top', 'modem');
  end
  ```

- Extra emulated computers are spawned manually from the CraftOS-PC shell when actually needed (e.g. `periphemu create 10 computer` to bring up a router peer for cross-VM testing). The pattern is documented in [`docs/periphemu.md`](../periphemu.md).
- Wiped the live CraftOS-PC data dir back to a clean slate (one-time, manually). Removed `computer/`, `old_computer/`, and all per-id `config/*.json`. Preserved `config/global.json` (user-level CraftOS-PC settings). A full pre-wipe backup lives at `~/Backups/craftos-pc-2026-06-08/CraftOS-PC/` outside any repo.

## Consequences

- `craftos` (GUI) now opens a single unlabelled `Computer 0` window with a top modem attached. No more duplicate `Trap` windows.
- `just test` is unchanged: the headless smokes set up whatever they need per script.
- New contributors and fresh machines get a clean state by default — no inherited per-computer config to chase.
- Cross-machine testing now requires an explicit `periphemu create` call from the shell rather than being implicit on boot. That is a deliberate trade-off: the cost is one extra command when you genuinely need a peer; the benefit is no surprise windows and no persisted ghost VMs.
- The `if periphemu then` guard (called out in CLAUDE.md) is preserved, so in-game behavior is unchanged.

## Future Work

- If `tests/` grows a multi-VM scenario, drive peer creation from the test script itself (each `tests/*.lua` already owns its setup) rather than re-adding peers to `startup/servers.lua`.
- Consider a small `programs/spawn-peer.lua` wrapper to make ad-hoc shell incantations friendlier (`spawn-peer 10` instead of `periphemu create 10 computer`). Not done now — premature for current usage.