diff --git a/AGENTS.md b/AGENTS.md
index 79d0c32..72f620d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -21,6 +21,15 @@ Use [`docs/README.md`](docs/README.md) as the entrypoint for CC:Tweaked, CraftOS
 - `require` paths are absolute ComputerCraft paths, for example `require('/apis/net')()`.
 - Most API modules return factories; call the required module once before use.
 
+## Running CraftOS-PC
+
+Always go through the `just` recipes — they set repo-local state and the macOS `--rom` path; never call `craftos` directly.
+
+- `just craftos [args]` — interactive vanilla CraftOS-PC, no TrapOS mounts, state in `.craftos-vanilla/`. `just trapos [args]` is the same but with the repo mounted and TrapOS state in `.craftos/`.
+- `just craftos --headless` — pass-through flags to CraftOS-PC; `--headless` boots without a GUI and `--exec '<lua>'` runs Lua before the shell. Handy for quick non-interactive boots; combine with `just trapos --headless` for a booted TrapOS env.
+- For one-shot automated probes prefer `just trapos-exec '<lua>'` / `just craftos-exec '<lua>'`: they always shut down and have a host watchdog, so they cannot hang the terminal.
+- `just test [--pretty]` runs the full CraftOS-PC test suite (`__TRAPOS_TEST_OK__` on success).
+
 ## Architecture
 
 - `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.