docs(periphemu): simplify bootstrap

docs/adrs/README.md

@@ -13,3 +13,4 @@ Future ADRs can reuse the shape of the existing files when it is useful.
 - [`adr-0003-current-net-api-state.md`](adr-0003-current-net-api-state.md) - Current net API state.
 - [`adr-0004-trapos-branding-and-manifest.md`](adr-0004-trapos-branding-and-manifest.md) - TrapOS branding and manifest-driven installs.
 - [`adr-0005-craftos-pc-harness.md`](adr-0005-craftos-pc-harness.md) - CraftOS-PC as the local harness.
+- [`adr-0006-simplify-periphemu-bootstrap.md`](adr-0006-simplify-periphemu-bootstrap.md) - Simplify periphemu bootstrap.

docs/adrs/adr-0006-simplify-periphemu-bootstrap.md

@@ -0,0 +1,47 @@
+# 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.

docs/craftos_pc_glossary.md

@@ -9,7 +9,7 @@ Repo notes:
 - Use [Install CraftOS-PC](install-craftos-pc.md) for the pinned local setup used by this repository.
 - Use [Command-Line Flags](https://www.craftos-pc.cc/docs/cli) for `--headless`, `--script`, `--exec`, `--rom`, `--directory`, `--id`, and `--mount-*`.
 - Use [File System Mounting](https://www.craftos-pc.cc/docs/mounter) for exposing repository files inside CraftOS-PC.
-- Use [Peripheral Emulation](https://www.craftos-pc.cc/docs/periphemu) for `periphemu` and local modem/peripheral tests.
+- Use [Peripheral Emulation](https://www.craftos-pc.cc/docs/periphemu) for `periphemu` and local modem/peripheral tests. See [`docs/periphemu.md`](periphemu.md) for the in-repo reference and how this repo uses it.
 - Use [Error Messages](https://www.craftos-pc.cc/docs/error-messages) when `craftos --help` works but booting a computer fails, including `Could not mount ROM`.
 
 ## Introduction

docs/periphemu.md

@@ -0,0 +1,69 @@
+# `periphemu` — CraftOS-PC Peripheral Emulation
+
+In-repo reference for the `periphemu` global exposed by [CraftOS-PC](https://www.craftos-pc.cc/). It does **not** exist in CC:Tweaked in-game — always guard usage with `if periphemu then`.
+
+Upstream: <https://www.craftos-pc.cc/docs/periphemu>. See also the [CraftOS-PC glossary](craftos_pc_glossary.md) and [ADR-0005](adrs/adr-0005-craftos-pc-harness.md) (why CraftOS-PC is our local harness) and [ADR-0006](adrs/adr-0006-simplify-periphemu-bootstrap.md) (why our startup attaches only a modem).
+
+## Usage in this repo
+
+`startup/servers.lua` attaches a single top modem when running under CraftOS-PC:
+
+```lua
+if periphemu then
+  periphemu.create('top', 'modem');
+end
+```
+
+That is the only `periphemu` call in the codebase. In-game (`periphemu == nil`) the block is a no-op. Locally a top modem is enough to boot the router, `ping-server`, and clients on the same VM.
+
+To exercise cross-computer behavior locally, spawn extra peers ad-hoc from the shell:
+
+```
+periphemu create 10 computer    # spawn router VM (id 10)
+periphemu create 1 computer     # spawn a client VM
+```
+
+Each call opens a new CraftOS-PC window (GUI mode). Keep this out of `startup/servers.lua` — persistent emulated peers clutter the desktop and leave stale state under `~/Library/Application Support/CraftOS-PC/computer/<id>/`.
+
+## API
+
+### `periphemu.create(side, type[, arg])` → `boolean`
+
+Attaches a peripheral. Returns `true` on success, `false` if `side` is already occupied.
+
+- `side` (string | number) — string for directional sides (`"top"`, `"left"`, …) or arbitrary names (`"modem_4"`); a number to attach a `computer` peripheral by id.
+- `type` (string) — see types below.
+- `arg` (optional) — type-specific, see table below.
+
+### `periphemu.remove(side)` → `boolean`
+
+Detaches the peripheral on `side`. Returns `false` if nothing is attached.
+
+### `periphemu.names()` → `string[]`
+
+Returns the list of peripheral type identifiers this CraftOS-PC build accepts as the `type` argument to `create`.
+
+## Peripheral types
+
+| Type           | Third arg            | Notes                                                                |
+| -------------- | -------------------- | -------------------------------------------------------------------- |
+| `modem`        | network id (number)  | Default network if omitted. Used to isolate modem networks.          |
+| `computer`     | —                    | `side` is the computer id (number). Spawns a new VM window.          |
+| `drive`        | mount path / `record:` / `treasure:` / `computer:<id>` | Initial mounted disk.            |
+| `monitor`      | —                    | Size is set via `monitor.setTextScale` after attach.                 |
+| `printer`      | output PDF path      | Required. Receives printed pages as PDF.                             |
+| `speaker`      | —                    | See caveat below about `playAudio` vs CC:T.                          |
+| `debugger`     | —                    | Attaches the CraftOS-PC debugger; see upstream debugger docs.        |
+| `debug_adapter`| —                    | DAP front-end peripheral.                                            |
+| `chest`        | `true`/`false`       | `true` = double chest. Also accepts `minecraft:chest`.               |
+| `energy`       | max energy (number)  | Optional further args declare supported energy type strings.         |
+| `tank`         | tank count (number)  | Optional further args set tank size and accepted fluid type strings. |
+
+Call `periphemu.names()` from a CraftOS-PC shell to confirm what the current build supports — the upstream list grows occasionally.
+
+## Caveats
+
+- **CC:T has no `periphemu`.** Always guard with `if periphemu then`. CLAUDE.md and [ADR-0005](adrs/adr-0005-craftos-pc-harness.md) treat that guard as mandatory.
+- **Speaker `playAudio` differs from CC:T** unless [standards mode](https://www.craftos-pc.cc/docs/standards) is on — CraftOS-PC queues audio without ever returning `false`.
+- **Modem network id** segregates emulated networks. Two modems with different ids will not see each other; useful for testing the [router](../programs/router.lua) against a sealed network.
+- **Persisted per-computer state** lives at `~/Library/Application Support/CraftOS-PC/computer/<id>/` and `config/<id>.json` (labels stored base64-encoded). Spawning a new id leaves that state behind across sessions.

startup/servers.lua

@@ -1,4 +1,4 @@
-local _VERSION = '1.2.0'
+local _VERSION = '1.3.0'
 
 local LOCAL_MANIFEST_PATH = '/trapos/manifest.json';
 
@@ -18,27 +18,8 @@ end
 
 init();
 
-local periphEmulation = function()
-  -- attach modem
-  periphemu.create('top', 'modem');
-
-  if os.getComputerID() == 0 then
-    -- attach computers
-
-    os.sleep(0.1)
-    periphemu.create(1, 'computer');
-
-    os.sleep(0.1)
-    periphemu.create(2, 'computer');
-
-    -- attach router
-    os.sleep(0.1)
-    periphemu.create(10, 'computer');
-  end
-end
-
 if periphemu then
-  periphEmulation();
+  periphemu.create('top', 'modem');
 end
 
 local function shellFn()