docs: add architecture decision records

CLAUDE.md

@@ -6,7 +6,7 @@ Concise guidance for agents working in this repository.
 
 ComputerCraft / CC:Tweaked Lua APIs, servers, and programs for Minecraft 1.21. Code runs in the ComputerCraft sandbox, not standard Lua.
 
-Use `docs/README.md` as the entrypoint for CC:Tweaked, Advanced Peripherals, and Create integration documentation links.
+Use `docs/README.md` as the entrypoint for CC:Tweaked, Advanced Peripherals, and Create integration documentation links. Use `docs/adrs/README.md` for repository architecture decisions.
 
 ## Constraints
 
@@ -18,8 +18,9 @@ Use `docs/README.md` as the entrypoint for CC:Tweaked, Advanced Peripherals, and
 
 ## Architecture
 
-- `apis/eventloop.lua` is the single-threaded event loop around `os.pullEventRaw`.
-- `apis/net.lua` builds modem packet messaging, routing, and request/response RPC on the event loop.
+- `apis/eventloop.lua` is the single-threaded event loop around `os.pullEventRaw`; consider using it everywhere async behavior is needed. A handler that returns `api.STOP` auto-unregisters.
+- `apis/net.lua` builds modem packet messaging, routing, and request/response RPC on the event loop. `sendRequest` returns `ok, result, packet` and defaults to a 0.5s timeout.
+- A router (`/programs/router.lua`) must be running somewhere on the network; without it, packets lack `routerId`, `isPacketOk` rejects them, and cross-machine messaging silently fails.
 - `servers/` listen for requests and start loops; `programs/` are clients that send requests and exit.
 - Well-known channels: `9` ping, `10` router/default routing. Keep duplicated constants in sync.
 
@@ -27,7 +28,7 @@ Use `docs/README.md` as the entrypoint for CC:Tweaked, Advanced Peripherals, and
 
 - `startup/servers.lua` starts `/programs`, the shell, and configured servers via `parallel.waitForAll`.
 - Preserve `periphemu` guards used for CraftOS-PC emulation.
-- `install.lua` downloads files listed in `LIST_FILES`; add shipped files there.
+- `install.lua` downloads files listed in `LIST_FILES` from `master` by default, or from `next` with `--beta`; add shipped files there.
 - Add new servers to `startup/servers.lua` as needed.
 
 ## Conventions

docs/README.md

@@ -7,6 +7,7 @@ Start here when looking up ComputerCraft-related APIs, peripherals, or mod integ
 - [`cc_glossary.md`](cc_glossary.md) - CC:Tweaked globals, modules, peripherals, events, and guides.
 - [`advanced_peripherals_glossary.md`](advanced_peripherals_glossary.md) - Advanced Peripherals 0.7 guides, peripherals, turtles, integrations, and changelog pages.
 - [`create_cc_tweaked_glossary.md`](create_cc_tweaked_glossary.md) - Create CC:Tweaked integration pages.
+- [`adrs/`](adrs/) - Lightweight Architecture Decision Records for this repository.
 
 ## Notes
 

docs/adrs/README.md

@@ -0,0 +1,13 @@
+# Architecture Decision Records
+
+This directory contains lightweight Architecture Decision Records for this repository.
+
+The goal is simple: keep a short memory of why we made repo-level choices while building ComputerCraft / CC:Tweaked code for Minecraft. This is not meant to be a heavy process.
+
+Future ADRs can reuse the shape of the existing files when it is useful.
+
+## Records
+
+- [`adr-0001-target-computercraft.md`](adr-0001-target-computercraft.md) - Target ComputerCraft.
+- [`adr-0002-use-eventloop-for-async-code.md`](adr-0002-use-eventloop-for-async-code.md) - Use eventloop for async code.
+- [`adr-0003-current-net-api-state.md`](adr-0003-current-net-api-state.md) - Current net API state.

docs/adrs/adr-0001-target-computercraft.md

@@ -0,0 +1,28 @@
+# ADR 0001: Target ComputerCraft
+
+## Status
+
+Accepted
+
+## Date
+
+2026-06-07
+
+## Context
+
+This repository exists to build APIs, servers, and programs for ComputerCraft / CC:Tweaked inside Minecraft.
+
+The code is Lua, but the runtime is not generic local Lua. The real environment provides ComputerCraft APIs such as `os.pullEvent`, `peripheral`, modems, timers, labels, computer IDs, and the CraftOS filesystem.
+
+## Decision
+
+This repo targets ComputerCraft / CC:Tweaked first.
+
+Local Lua compatibility is not a goal by itself. Code can assume the ComputerCraft runtime and use ComputerCraft conventions when they make the in-game code clearer.
+
+## Consequences
+
+- Prefer ComputerCraft-style absolute `require` paths, such as `require('/apis/net')()` (most API modules return factories — call the result once to get the API).
+- Local checks are useful, but runtime behavior should be validated in-game or with CraftOS-PC when needed.
+- Avoid adding a local Lua harness unless there is a clear reason.
+- Keep the repository practical: this is for playing Minecraft, not designing a general Lua framework.

docs/adrs/adr-0002-use-eventloop-for-async-code.md

@@ -0,0 +1,28 @@
+# ADR 0002: Use Eventloop For Async Code
+
+## Status
+
+Accepted
+
+## Date
+
+2026-06-07
+
+## Context
+
+ComputerCraft is event-driven. Direct `os.pullEvent` loops are easy to write, but they are hard to compose when multiple things need to happen at the same time.
+
+This matters for servers, network listeners, timers, peripheral events, and future UI code. UI code especially will need to handle input, redraws, network replies, and timers together.
+
+## Decision
+
+New async code should use `/apis/eventloop`.
+
+Event handlers, timers, server listeners, and future UI behavior should compose through the event loop instead of each feature owning its own blocking event loop.
+
+## Consequences
+
+- Prefer `eventloop.register`, `setTimeout`, `onStart`, `onStop`, and `startLoop` for async behavior.
+- APIs that listen for events should accept an existing event loop as a constructor argument, the way `/apis/net` already takes one. Do not create a private loop inside a module.
+- Direct `os.pullEvent` loops should be rare and justified.
+- Existing code can stay as-is for now, but future async, server, and UI code should move toward eventloop composition.

docs/adrs/adr-0003-current-net-api-state.md

@@ -0,0 +1,36 @@
+# ADR 0003: Current Net API State
+
+## Status
+
+Accepted
+
+## Date
+
+2026-06-07
+
+## Context
+
+`/apis/net` is the current networking abstraction in this repository.
+
+It wraps modem messages with packet metadata and uses `/apis/eventloop` for listeners and request/response flows. It is useful for today's basic routed messages and RPC-like requests, but it is not a final protocol design.
+
+## Decision
+
+Keep using `/apis/net` for simple program and server messaging.
+
+Document the current behavior as the baseline, without over-designing the future protocol before real needs appear.
+
+## Current State
+
+- Default routing channel is `10`.
+- Ping channel is `9`.
+- Packets include `sourceId`, `sourceLabel`, `routerId`, `destId`, and `message`.
+- Main convenience APIs include `send`, `listen`, `sendRequest`, `sendMultipleRequests`, `listenRequest`, `createEvent`, `createRequest`, and `openChannel` (alias `open`). Listening on a non-default channel requires `openChannel` first.
+- `sendRequest` and `sendMultipleRequests` run a private event loop, default to a `0.5s` timeout, and return `ok, result, packet` (or `ok, results, packets` for the multi variant).
+- Router behavior currently lives separately in `/programs/router.lua`. A router must be running on the network — otherwise non-router senders produce packets with `routerId = nil` and `isPacketOk` drops them on receive, so cross-machine messages silently fail.
+
+## Consequences
+
+- Use `/apis/net` for current basic messaging needs.
+- Keep duplicated well-known channel constants in sync while they remain duplicated.
+- Future ADRs can replace or refine this one if the network protocol gains discovery, retries, schemas, versioning, auth, or a different routing model.