docs(dev): update local installation guidance

CLAUDE.md

@@ -15,7 +15,7 @@ Use `docs/README.md` as the entrypoint for CC:Tweaked, CraftOS-PC, Advanced Peri
 - When changing behavior, add as many useful CraftOS-PC tests as practical. It is acceptable to skip tests that require human-only validation, such as complex turtle motion, in-game UX feel, or visual approval, but still add unit-style non-regression tests for deterministic parts when possible.
 - Use `/apis/libtest.lua` for test scripts under `tests/`; `/programs/runtest.lua` prints `__TRAPOS_TEST_OK__` only after the suite passes.
 - `libtest` cancels each case after `3`s (`--timeout <s>` / `--no-timeout` to override); never commit a hanging test to `tests/`. Slow harness fixtures go in `tests/harness/` behind dedicated recipes. See `docs/adrs/adr-0009-layered-test-timeouts.md`.
-- Git hooks own commit/push verification: pre-commit runs `just test`, and pre-push runs `just ci`. When explicitly asked to commit and/or push, do not run `just test` manually first; rely on the hooks. See `docs/adrs/adr-0011-git-hooks-own-commit-push-verification.md`.
+- Git hooks own commit/push verification: pre-commit runs `just check test`, and pre-push runs `just ci`. When explicitly asked to commit and/or push, do not run `just test` manually first; rely on the hooks. See `docs/adrs/adr-0011-git-hooks-own-commit-push-verification.md`.
 - After editing Lua, run `just check` and fix all `luacheck` warnings.
 - Use 2-space indent, semicolons, and `local function`.
 - `require` paths are absolute ComputerCraft paths, for example `require('/apis/net')()`.

DEVELOPMENT.md

@@ -1,28 +1,13 @@
 # Development
 
-Requirements:
+## Installation
-- `just`
-- `jq`
-- `luacheck`
-- [CraftOS-PC](docs/install-craftos-pc.md) ≥ v2.8.3 — local harness for the CC:Tweaked sandbox; see [`docs/craftos_pc_glossary.md`](docs/craftos_pc_glossary.md) for CLI flags, mounting, `periphemu`, save data, and troubleshooting references.
 
-After cloning the repository, run:
+Install `just`, `jq`, `luacheck`, `openssl`, and [CraftOS-PC v2.8.3+](docs/install-craftos-pc.md), then run:
 
 ```sh
-just install
+just install trapos-install && echo ok
 ```
 
-This installs the local Git hooks: pre-commit runs `just test`, and pre-push runs `just ci`.
+This installs local Git hooks, checks required tools, generates `.env`, and verifies a full TrapOS install on a fresh CraftOS-PC state.
 
-`just ci` is the full local verification entry point. Today it verifies that `craftos --version` reports v2.8.3 or newer, runs `just check` for `luacheck`, runs `just test` for CraftOS-PC headless tests, and runs the harness timeout regression guard. Three launch recipes wrap CraftOS-PC: `just trapos` launches the TrapOS dev environment with repo-local save data under `.craftos` and read-only mounts for `/trapos`, `/apis`, `/programs`, `/servers`, and `/startup`; `just craftos` launches a vanilla CraftOS-PC under `.craftos-vanilla` with no mounts (useful when a probe should not see TrapOS files, or to confirm a behavior is upstream); and `just trapos-install` exercises the real ccpm bootstrap (`install-ccpm.lua` → `ccpm update` → `ccpm install trapos`) end-to-end on a fresh ephemeral state. `just repl` opens the TrapOS dev environment with `--cli` for human interactive use only; LLM agents must not run it. `--headless --exec '<lua>; os.shutdown()'` against either `just trapos` or `just craftos` is the canonical way to verify a hypothesis about CC:Tweaked behavior before writing code or tests — see [`docs/adrs/adr-0012-headless-craftos-pc-as-hypothesis-probe.md`](docs/adrs/adr-0012-headless-craftos-pc-as-hypothesis-probe.md). Use the CraftOS-PC glossary when adjusting `--headless`, `--exec`, `--script`, `--rom`, or `--mount-*` usage.
+See [`docs/README.md`](docs/README.md) for repository docs and [`docs/adrs/README.md`](docs/adrs/README.md) for architecture decisions.
-
-When asking an agent to commit and/or push, rely on these hooks instead of duplicating `just test` manually before Git operations: pre-commit owns `just test`, and pre-push owns `just ci`. Manual `just test` and `just ci` remain appropriate when validating changes outside a commit/push workflow.
-
-Tests live under `tests/` and run inside CraftOS-PC through `just test`, which launches `/programs/runtest.lua`. API-level tests should use `require('/apis/libtest')({ ... })`, register cases with `testlib.test(name, fn)`, and call `testlib.run()` at the end. `libtest` tests remain normal ComputerCraft programs; the runner handles suite discovery, grouped output, and the `__TRAPOS_TEST_OK__` shell success contract. Pass `--pretty` to `just test` for grouped colored `[OK]`/`[KO]` statuses, or `--verbose` for additional runner/debug detail.
-
-Test timeouts run in two independent layers (see [`docs/adrs/adr-0009-layered-test-timeouts.md`](docs/adrs/adr-0009-layered-test-timeouts.md)):
-
-- **libtest per-case timeout (primary).** Each `libtest` case is cancelled after `3` seconds by default, failing with a distinct `libtest timeout` message. Override with `--timeout <seconds>`, or disable with `--no-timeout` (both forwarded by `runtest` to each case). This catches a single hung case quickly without taking down the whole run.
-- **Shell watchdog (backstop).** The whole CraftOS-PC process is killed if it does not finish within `TRAP_CCLIBS_TEST_TIMEOUT_SECONDS` (`.env.test` ships `3`; the recipe falls back to `3`). Keep it at or above the `3`s libtest default so libtest fires first; the watchdog only catches what Lua cannot interrupt. Override in your shell for slower local probes.
-
-`just test-timeout` is a self-asserting regression guard for these layers and runs automatically as part of `just ci`. It chains `just test-timeout-lua` (proves libtest cancels a slow case immediately with `--timeout 0`, before the shell backstop) and `just test-timeout-shell` (proves the `TRAP_CCLIBS_TEST_TIMEOUT_WATCHDOG_SECONDS` watchdog, default `1`, kills a slow case run with `--no-timeout`). Both drive the `tests/harness/slow-case.lua` fixture, which is never picked up by the normal `just test` suite (`runtest` skips `tests/` subdirectories).

README.md

@@ -84,4 +84,4 @@ Servers listed in `manifest.autostart` are launched at boot by `startup/servers.
 - `upgrade`: alias for `ccpm upgrade`.
 
 ## Development
-See [DEVELOPMENT.md](./DEVELOPMENT.md) for development setup and workflow.
+See [DEVELOPMENT.md](./DEVELOPMENT.md) for local development installation.

docs/adrs/adr-0005-craftos-pc-harness.md

@@ -26,10 +26,10 @@ Treat CraftOS-PC as a first-class local development dependency.
 - **Minimum version `v2.8.3`** — recent enough to have the current CC:Tweaked ROM, old enough that contributors already on a 2.8.x build will not be forced to upgrade again immediately.
 - **Documented install** in [`docs/install-craftos-pc.md`](../install-craftos-pc.md), with a SHA-256-verified macOS flow and pointers to the official Windows/Linux artifacts.
 - **Documented upstream navigation** in [`docs/craftos_pc_glossary.md`](../craftos_pc_glossary.md), covering CLI flags, mounts, `periphemu`, save data, and troubleshooting pages.
-- **Verified by `just install`** via `check-install`, which checks `craftos`, `jq`, and `luacheck`. `check-craftos` runs `craftos --version` and requires v2.8.3 or newer. Failure prints a one-line pointer to the install guide instead of a long stack trace.
+- **Verified by `just install`** via `check-install`, which checks `craftos`, `jq`, `luacheck`, and `openssl`. `check-craftos` runs `craftos --version` and requires v2.8.3 or newer. Failure prints a one-line pointer to the install guide instead of a long stack trace.
 - **Repository-local launch recipe.** `just trapos` runs CraftOS-PC with `--directory .craftos`, keeps the macOS `--rom /Applications/CraftOS-PC.app/Contents/Resources` workaround, mounts the repository root read-only at `/trapos`, and mounts each manifest top-level directory read-only at its ComputerCraft root path. (Originally `just craftos`; renamed when a separate vanilla-emulator recipe was added — see ADR-0012.)
 - **Vanilla launch recipe.** `just craftos` launches CraftOS-PC under `.craftos-vanilla/` with no mounts, for probes that should not see TrapOS files and for the `just trapos-install` end-to-end install verification. See ADR-0012.
-- **`just ci` is the local verification entry point.** Today it runs `check-craftos`, `check`, and `test`. The installed pre-commit hook invokes `just ci` directly, and `just test` owns CraftOS-PC-driven integration tests.
+- **`just ci` is the local verification entry point.** Today it runs `check-craftos`, `check`, and `test`. Local Git hooks are installed by `just install`; see [ADR-0011](adr-0011-git-hooks-own-commit-push-verification.md) for the current commit/push split.
 
 The existing `CLAUDE.md` constraint ("Do not run Lua locally or add a test harness unless asked") is reframed rather than removed: there is still no standalone Lua harness, and we are not adding a Busted-style test runner. The harness *is* CraftOS-PC, invoked deliberately.
 

docs/adrs/adr-0012-headless-craftos-pc-as-hypothesis-probe.md

@@ -74,7 +74,7 @@ Conventions:
 - Faster convergence on correct fixes: agents stop committing speculative changes that pass
   `luacheck` but fail in-game.
 - A named pattern (`--headless --exec '<lua>; os.shutdown()'`) shows up in `CLAUDE.md` and
-  `DEVELOPMENT.md`, so contributors and agents reach for it without rediscovery.
+  `docs/install-craftos-pc.md`, so contributors and agents reach for it without rediscovery.
 - `.craftos-vanilla/` is added to `.gitignore` alongside `.craftos/`.
 - `just trapos-install` is *not* part of `just ci`: it is network-dependent and slower
   than `just test`. Run it manually when touching `install-ccpm.lua` or ccpm package

docs/install-craftos-pc.md

@@ -4,7 +4,7 @@ CraftOS-PC is the local harness used to run this repo's Lua outside of Minecraft
 
 CraftOS-PC is the emulator; `craftos` is the command-line executable it installs. For the broader upstream documentation index, see [`craftos_pc_glossary.md`](craftos_pc_glossary.md).
 
-Minimum version: **v2.8.3**. `just install` runs `craftos --version` to verify it is on `$PATH` and recent enough; it also checks that `jq` and `luacheck` are installed.
+Minimum version: **v2.8.3**. `just install` runs `craftos --version` to verify it is on `$PATH` and recent enough; it also checks that `jq`, `luacheck`, and `openssl` are installed.
 
 The upstream installation page is <https://www.craftos-pc.cc/docs/installation>. The notes below pin the version we test against and add a SHA-256 verification step.