docs: add CraftOS-PC glossary

2026-06-08 01:46:17 +02:00 · 2026-06-08 01:46:17 +02:00 · e2e6b0f6ee
commit e2e6b0f6ee
parent 7513742a19
6 changed files with 90 additions and 10 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@ -6,11 +6,11 @@ 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/adrs/README.md` for repository architecture decisions.
+Use `docs/README.md` as the entrypoint for CC:Tweaked, CraftOS-PC, Advanced Peripherals, and Create integration documentation links. Use `docs/adrs/README.md` for repository architecture decisions.

 ## Constraints

- Do not add a standalone Lua test harness unless asked. Local execution happens through the CraftOS-PC harness (see `docs/install-craftos-pc.md` and ADR-0005); code otherwise executes in-game.
+- Do not add a standalone Lua test harness unless asked. Local execution happens through the CraftOS-PC harness (see `docs/install-craftos-pc.md`, `docs/craftos_pc_glossary.md`, and ADR-0005); code otherwise executes in-game.
 - 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')()`.
@ -27,7 +27,7 @@ Use `docs/README.md` as the entrypoint for CC:Tweaked, Advanced Peripherals, and
 ## Boot And Install

 - `startup/servers.lua` starts `/programs`, the shell, and configured servers via `parallel.waitForAll`.
- Preserve `periphemu` guards used for CraftOS-PC emulation.
+- Preserve `periphemu` guards used for CraftOS-PC emulation; see `docs/craftos_pc_glossary.md` for upstream emulator references.
 - `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.

--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@ -3,7 +3,7 @@
 Requirements:
 - `just`
 - `luacheck`
- [CraftOS-PC](docs/install-craftos-pc.md) ≥ v2.8.3 — local harness for the CC:Tweaked sandbox.
+- [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:

@ -13,4 +13,4 @@ just install

 This installs the local Git hooks, including a pre-commit hook that runs `just ci`.

-`just ci` is the local verification entry point. Today it verifies that `craftos --version` reports v2.8.3 or newer and runs `just check` for `luacheck`. `just test` is a placeholder for future CraftOS-PC headless integration tests.
+`just ci` is the local verification entry point. Today it verifies that `craftos --version` reports v2.8.3 or newer, runs `just check` for `luacheck`, and runs `just test` for CraftOS-PC headless smoke tests. Use the CraftOS-PC glossary when adjusting `--headless`, `--exec`, `--script`, `--rom`, or `--mount-*` usage.
--- a/docs/README.md
+++ b/docs/README.md
@ -1,10 +1,11 @@
 # Documentation

-Start here when looking up ComputerCraft-related APIs, peripherals, or mod integrations used by this repository.
+Start here when looking up ComputerCraft-related APIs, CraftOS-PC behavior, peripherals, or mod integrations used by this repository.

 ## Indexes

 - [`cc_glossary.md`](cc_glossary.md) - CC:Tweaked globals, modules, peripherals, events, and guides.
+- [`craftos_pc_glossary.md`](craftos_pc_glossary.md) - CraftOS-PC emulator setup, CLI flags, mounting, peripheral emulation, troubleshooting, and related references.
 - [`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.
--- a/docs/adrs/adr-0005-craftos-pc-harness.md
+++ b/docs/adrs/adr-0005-craftos-pc-harness.md
@ -25,14 +25,16 @@ 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 a `check-craftos` recipe that 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.
- **`just ci` is the local verification entry point.** Today it runs `check-craftos` and `check`. The installed pre-commit hook invokes `just ci` directly. `just test` exists as the future home for CraftOS-PC-driven smoke tests.
+- **`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 smoke tests.

 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.

 ## Consequences

 - Contributors must install CraftOS-PC before `just install` succeeds. The install guide makes this a 4-step copy/paste on macOS.
+- Contributors should use the local CraftOS-PC glossary first when researching emulator behavior, then follow the linked upstream pages for details.
 - Headless smoke tests live under `tests/` and are driven by `just test`. Today there are two: `tests/boot.lua` (prints a marker and shuts down — proves the BIOS started) and `tests/ready.lua` (round-trips a `craftos-ready` event through `os.queueEvent` / `os.pullEventRaw` — proves the CC event queue works). Each is invoked as `craftos --headless --script <file>` and its stdout is grepped for `__READY__`. Adding a third test means dropping a Lua file in `tests/` and adding it to the loop in the `test:` recipe.
 - The macOS install symlinks the binary into `/usr/local/bin`, which makes CraftOS-PC unable to auto-discover the ROM that ships inside the `.app` bundle (`Could not mount ROM`). The `test:` recipe works around this by passing `--rom /Applications/CraftOS-PC.app/Contents/Resources` on Darwin. Linux (AppImage) and Windows (installer) auto-discover correctly, so no flag is passed there.
 - The harness version becomes a project-level concern. When CC:Tweaked ships breaking changes that require a newer CraftOS-PC build, we bump the minimum version in `docs/install-craftos-pc.md` and `check-craftos` keeps contributors honest.
--- a/docs/craftos_pc_glossary.md
+++ b/docs/craftos_pc_glossary.md
@ -0,0 +1,59 @@
+# CraftOS-PC Documentation Glossary
+
+Compact index of CraftOS-PC documentation pages from <https://www.craftos-pc.cc/docs/>. CraftOS-PC is the emulator used by this repository; `craftos` is the command-line executable it installs.
+
+Last checked: 2026-06-08.
+
+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 [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
+
+- [What is CraftOS-PC?](https://www.craftos-pc.cc/docs/about)
+- [Downloading & Installing](https://www.craftos-pc.cc/docs/installation)
+- [Getting Started](https://www.craftos-pc.cc/docs/getting-started)
+- [Save Data Location](https://www.craftos-pc.cc/docs/saves)
+- [Standards Mode](https://www.craftos-pc.cc/docs/standards)
+- [Migrating from CCEmuX](https://www.craftos-pc.cc/docs/ccemux)
+- [CraftOS-PC Mobile](https://www.craftos-pc.cc/docs/mobile)
+
+## New Features
+
+- [Peripheral Emulation](https://www.craftos-pc.cc/docs/periphemu)
+- [File System Mounting](https://www.craftos-pc.cc/docs/mounter)
+- [Screenshots & Recording](https://www.craftos-pc.cc/docs/screenshot)
+- [Multiple Computers](https://www.craftos-pc.cc/docs/multicomp)
+- [ComputerCraft Configuration](https://www.craftos-pc.cc/docs/config)
+- [Graphics Mode](https://www.craftos-pc.cc/docs/gfxmode)
+- [HTTP & WebSocket Server](https://www.craftos-pc.cc/docs/http-server)
+- [CC: Tweaked Features](https://www.craftos-pc.cc/docs/cctweaked)
+- [Auto-Updater](https://www.craftos-pc.cc/docs/autoupdate)
+- [Debugger](https://www.craftos-pc.cc/docs/debugger)
+- [Command-Line Flags](https://www.craftos-pc.cc/docs/cli)
+- [Rendering Options](https://www.craftos-pc.cc/docs/renderers)
+- [Raw Mode](https://www.craftos-pc.cc/docs/rawmode)
+- [VS Code Extension](https://www.craftos-pc.cc/docs/extension)
+- [Plugin System](https://www.craftos-pc.cc/docs/plugins)
+- [CraftOS-PC Accelerated](https://www.craftos-pc.cc/docs/accelerated)
+
+## Other Information
+
+- [CraftOS-PC Online](https://www.craftos-pc.cc/docs/online)
+- [CraftOS-PC Remote](https://www.craftos-pc.cc/docs/remote)
+- [Latest Development Build](https://www.craftos-pc.cc/artifact)
+- [Error Messages](https://www.craftos-pc.cc/docs/error-messages)
+- [Report a Bug](https://www.craftos-pc.cc/bugreport)
+- [Privacy Policy](https://www.craftos-pc.cc/docs/privacy)
+- [Contact](https://www.craftos-pc.cc/docs/contact)
+- [Changelog](https://www.craftos-pc.cc/docs/changelog)
+
+## API Reference
+
+- [CC: Tweaked Documentation](https://tweaked.cc/)
+- [Lua 5.2 Reference Manual](https://lua.org/manual/5.2/manual.html)
+- [CraftOS APIs (Old Wiki)](http://www.computercraft.info/wiki/Category:APIs)
--- a/docs/install-craftos-pc.md
+++ b/docs/install-craftos-pc.md
@ -2,9 +2,11 @@

 CraftOS-PC is the local harness used to run this repo's Lua outside of Minecraft. See [ADR-0005](adrs/adr-0005-craftos-pc-harness.md) for why.

+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.

-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.
+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.

 ## macOS

@ -37,11 +39,17 @@ The binary is not on `$PATH` by default. Add a symlink so `just check-craftos` c
 ln -sf /Applications/CraftOS-PC.app/Contents/MacOS/craftos /usr/local/bin/craftos
 ```

-User data (computer state, settings) lives in `~/Library/Application Support/CraftOS-PC` and survives a reinstall — the steps above only touch the `.app` bundle.
+User data (computer state, settings) lives in `~/Library/Application Support/CraftOS-PC` and survives a reinstall. The steps above only touch the `.app` bundle.
+
+When running headless tests on macOS, prefer passing the app bundle's resource directory explicitly if `craftos` is reached through the `/usr/local/bin/craftos` symlink:
+
+```sh
+craftos --headless --rom /Applications/CraftOS-PC.app/Contents/Resources --exec 'print("__READY__"); os.shutdown()'
+```

 ## Windows

-Download `CraftOS-PC-Setup.exe` from the [latest release](https://github.com/MCJack123/craftos2/releases/latest) and run it. The installer puts `craftos.exe` on `$PATH`.
+Download `CraftOS-PC-Setup.exe` from the [latest release](https://github.com/MCJack123/craftos2/releases/latest) and run it. The installer puts `craftos.exe` on `%PATH%`.

 User data: `%appdata%\CraftOS-PC`.

@ -64,10 +72,20 @@ craftos --version

 Must report `CraftOS-PC v2.8.3` or newer. Once this works, `just install` will succeed.

+To verify that CraftOS-PC can boot a computer, not only print its executable version, run:
+
+```sh
+craftos --headless --exec 'print("__READY__"); os.shutdown()'
+```
+
+On macOS, use the `--rom` form shown above if the command fails with `Could not mount ROM`.
+
 ## Running tests

 `just test` runs the headless smoke tests in `tests/` through CraftOS-PC. On macOS the recipe passes `--rom /Applications/CraftOS-PC.app/Contents/Resources` because the `/usr/local/bin/craftos` symlink loses ROM auto-discovery; on Linux and Windows no flag is needed. `just ci` runs the same tests after `luacheck`.

+See [Command-Line Flags](https://www.craftos-pc.cc/docs/cli) for `--headless`, `--exec`, `--script`, `--rom`, and `--mount-*`. See [Error Messages](https://www.craftos-pc.cc/docs/error-messages) for `Could not mount ROM` and other boot-time failures.
+
 ## Updating

 Repeat the steps above against the newer release. The bundle replacement is in-place; the user data directory is preserved.