---
name: obsidos-verify
description: Run and verify ObsidOS changes in the Minecraft client. Use when a change needs in-game confirmation, when checking a substep's Done-when, or before marking plan work complete.
---

# Verifying ObsidOS in-game

## Run
```
./gradlew runClient
```
Dev mode: kernel reads distro Lua live from `distro/` checkout — Lua edits need no rebuild, Java edits do. First boot creates `run/obsidos/` sandbox root.

## Standard verification flow
1. Build/launch, watch log for kernel init line + any mixin failures.
2. Open OS: in-game keybind, or title-screen keybind (no-world paths must also work — `/sys/mc/*` absent there).
3. Exercise the specific Done-when from the substep md, literally.
4. Lua errors must show as tracebacks in-OS (terminal/panic screen), never as client crash. A client crash from Lua input = kernel bug, fix before proceeding.
5. Panic combo (triple-ESC) must always close the screen — spot-check after input changes.

## Useful checks
- Fresh-boot test: delete `run/obsidos/` → seeding + first boot path.
- Brick test: delete `run/obsidos/boot/init.lua` → Java panic screen → factory reset → boots.
- Perf: F3 FPS with a `while true do end` test program running — budget must hold framerate.
- Leak: spawn/kill loops for any new resource (surfaces, handles, watchers); watch memory.
- Persistence: write file → quit client fully → relaunch → read back.

## Test programs
Keep throwaway checks as `ktest-*` programs in a dev package (`distro/packages/ktest/`), runnable from osh. Prefer adding a ktest over one-off manual poking — they accumulate into a regression suite.

## When verification fails
Report the actual failure (log excerpt, traceback) — don't mark substep done. If the plan's Done-when turned out to be wrong/untestable, fix the substep md to a testable criterion and say so.