TOPLLab · tolauwae · Aug 11, 2026 · Jul 9, 2026 · Jul 9, 2026 · Jul 9, 2026
diff --git a/README.md b/README.md
@@ -41,61 +41,46 @@ This project is released under the Mozilla Public License 2.0, and is being deve
 If you use just, the most common project commands are collected in the justfile.
 To run the virtual machine locally (emulator) for the first time, use:
 
+```bash
+just setup emulator ; just run emulator tutorials/wat/main/fac.wat
 ```
-just setup ; just run emulator tutorials/wat/main/fac.wat
+
+You can use the debugger by running:
+
+```bash
+just monitor emulator 8119
 ```
 
 ## Build and Development Instructions
 
 > [!NOTE]
-> **Supported platforms:** Linux (Ubuntu), macOS, ESP-IDF, Arduino
+> **Supported platforms:** Linux (Ubuntu), macOS, Zephyr, ESP-IDF, Arduino
 
 The project uses CMake. Quick install looks like this:
 
 ```bash
 git clone --recursive git@github.com:TOPLLab/WARDuino.git
 cd WARDuino
-mkdir build-emu
-cd build-emu
-cmake .. -D BUILD_EMULATOR=ON
-make
+just build emulator
 ```
 
 This will build the command-line tool (`emulator`), which has been tested on both linux and macOS.
 
-The WARDuino VM can be compiled with both the Arduino and ESP-IDF toolchains, and has been extensively tested on different ESP8266 and ESP32 microcontrollers.
-
-### Build for ESP-IDF
-
-> [!WARNING]
-> Primitive support for IDF is under construction.
-
-Before you can compile and flash with ESP-IDF, you must install and enable [the toolchain](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/linux-macos-setup.html).
-You also need to disable the watchdog timer:
+```bash
+./build-emu/wdcli --help
+```
 
-1. Go to the root folder of the WARDuino repo
-2. run `idf.py menuconfig`
-3. Under **Component config → ESP System Settings** disable the following options:
-   - Interrupt watchdog
-   - Initialize Task Watchdog Timer on startup
-4. Save and quit the menu
+The WARDuino VM can be compiled with both the Arduino and ESP-IDF toolchains, and has been extensively tested on different ESP8266 and ESP32 microcontrollers.
 
-Make sure the ESP-IDF tools are enabled, otherwise these steps will not work.
+### Build for Zephyr
 
-To install the WARDuino with the ESP-IDF toolchain perform the following steps starting from the project root folder:
+First, install the [Zephyr SDK](https://docs.zephyrproject.org/latest/develop/getting_started/index.html#getting-started-guide), then run:
 
 ```bash
-mkdir build
-cd build
-cmake .. -D BUILD_ESP=ON
-make flash
+just build zephyr tutorials/wat/main/blink.wat ; just flash zephyr ; just monitor zephyr
 ```
 
-Or simply run `idf.py flash`.
-
-### Build for Zephyr
-
-First, install the [Zephyr SDK](https://docs.zephyrproject.org/latest/develop/getting_started/index.html#getting-started-guide), then follow these steps:
+Alternative, when you do not have just, you can follow the following steps:
 
 1. Activate your Zephyr environment:
 ```bash
@@ -165,7 +150,6 @@ arduino-cli lib install --git-url https://github.com/me-no-dev/AsyncTCP.git
 
 If you haven't done so already, clone (or symlink) this repository to `~/Arduino/libraries` to make WARDuino available to Arduino.
 
-
 After this initial installation steps you can start using WARDuino with the Arduino toolchain.
 You can upload the example file as follows, starting from the project root:
 
@@ -185,18 +169,52 @@ The CLI is also used to run the various unit and specification tests for WARDuin
 
 To install the CLI perform the following steps starting from the project root folder:
 
+```bash
+just build emulator ; echo ; ./build-emu/wdcli --help
+```
+
+Alternative, when you do not have just, use:
+
 ```bash
 mkdir build-emu
 cd build-emu
 cmake .. -D BUILD_EMULATOR=ON
 make
 ```
 
-## WebAssembly Specification tests
+### Build for ESP-IDF
+
+> [!WARNING]
+> Primitive support for IDF is under construction.
+
+Before you can compile and flash with ESP-IDF, you must install and enable [the toolchain](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/linux-macos-setup.html).
+You also need to disable the watchdog timer:
 
-```shell
-cd tests/latch
-npm run spectest
+1. Go to the root folder of the WARDuino repo
+2. run `idf.py menuconfig`
+3. Under **Component config → ESP System Settings** disable the following options:
+   - Interrupt watchdog
+   - Initialize Task Watchdog Timer on startup
+4. Save and quit the menu
+
+Make sure the ESP-IDF tools are enabled, otherwise these steps will not work.
+
+To install the WARDuino with the ESP-IDF toolchain perform the following steps starting from the project root folder:
+
+```bash
+mkdir build
+cd build
+cmake .. -D BUILD_ESP=ON
+make flash
+```
+
+Or simply run `idf.py flash`.
+
+## Run test suites
+
+```bash
+just build emulator
+just test all
 ```
 
 ## Technical support and feedback
@@ -205,7 +223,7 @@ For a feature request or bug report, create a [GitHub issue](https://github.com/
 
 ## Acknowledgments
 
-WARDuino by Robbert Gurdeep Singh, Tom Lauwaerts, Carlos Rojas Castillo, Maarten Steevens and Christophe Scholliers is licensed under a [MPL-2.0 License](./LICENSE).
+WARDuino by Tom Lauwaerts, Maarten Steevens, Carlos Rojas Castillo, and Christophe Scholliers is licensed under a [MPL-2.0 License](./LICENSE).
 An early version of this work was derived from [kanaka/wac](https://github.com/kanaka/wac) by Joel Martin.
 
 If you need to cite WARDuino in your research, use:

diff --git a/justfile b/justfile
@@ -1,7 +1,5 @@
 set unstable
-
-default:
-    just --list
+set default-list := true
 
 
 ## Run
@@ -12,6 +10,7 @@ run platform program:
     just stage {{program}}
     just build {{platform}}
     just flash {{platform}} upload.wasm
+    just monitor {{platform}}
 
 
 ## Stage
@@ -34,6 +33,17 @@ wat program:
 clean:
     rm -rf build-emu build-doctest build
 
+[group('clean')]
+[doc('Clean tests folders')]
+clean-tests:
+    rm -rf tests/latch/node-modules
+
+[group('clean')]
+[doc("Hard reset repository")]
+[confirm("Clean all generated files and Git data?")]
+reset: clean clean-tests _prune
+
+
 ## Build
 
 has(flags, flag) := if flags =~ ('(^| )' + flag + '($| )') { "true" } else { "false" }
@@ -59,9 +69,9 @@ build platform *flags:
 [group('build')]
 [working-directory: 'build-emu']
 [doc('Platform: emulator')]
-emulator *flags: _mkdir-emu
-    cmake .. -D BUILD_EMULATOR=ON {{cmake(flags)}} -G Ninja
-    ninja
+emulator *flags:
+    cmake -S . -B build-emu -D BUILD_EMULATOR=ON {{cmake(flags)}} -G Ninja
+    cmake --build build-emu
 
 [group('build')]
 [doc('Platform: zephyr')]
@@ -73,71 +83,106 @@ zephyr *flags='-b esp32_devkitc_wroom/esp32/procpu':
 
 [group('exec')]
 [doc('Flash/execute platform')]
-flash platform program *flags:
+flash platform program="upload.wasm" *flags:
     just _flash_{{platform}} {{program}} {{flags}}
 
 _flash_zephyr program *flags:
     just _zephyr "west flash {{flags}}"
 
-_flash_emulator program *flags: (cli program flags)
+_flash_emulator program *flags='--socket 8119': (cli program flags)
 
 [group('exec')]
 [doc('Run command-line interface')]
 cli program *flags:
     ./build-emu/wdcli {{program}} {{flags}}
 
 
+## Monitor
+
+[group('monitor')]
+monitor platform port='8119':
+    just _monitor_{{platform}} {{port}}
+
+[no-exit-message]
+_monitor_emulator port='8119':
+    telnet localhost {{port}}
+
+
+_monitor_zephyr port:
+    west espressif monitor
+
+
 ## Setup
 
 [group('setup')]
-[doc('Setup toolchains & platforms')]
-setup platform: _setup-emulator
+[doc('Setup toolchains & platforms (target: emulator, tests)')]
+setup target:
+    just _setup-{{target}}
+
+[confirm('You are about to install nanopb using Homebrew. Proceed? [y/n]')]
+_nanopb:
+    brew install nanopb
 
 [group('setup')]
 [doc('Setup: emulator')]
-_setup-emulator:
+_setup-emulator: _nanopb
     git submodule update --init --recursive
 
+[working-directory: 'tests/latch/']
+_setup-tests:
+    npm i
+
 [group('lint')]
 [doc('Lint src folder')]
+[no-exit-message]
 lint:
     clang-format -i src/**/*
 
 ## Tests
 
 [group('test')]
-[doc('Run tests')]
+[doc('Run tests at level (unit, integration, spec, all)')]
 test level='all':
     just {{level}}
 
 [group('test')]
-[doc('Run unit tests')]
 unit: _mkdir-doctest _build-doctest
     ctest --test-dir ./build-doctest --output-on-failure
 
 [group('test')]
-[doc('Run spec tests')]
 [working-directory: 'tests/latch/']
 spec: 
     WABT="../../lib/wabt/build/" npm run tests:spec
 
 [group('test')]
-[doc('Run integration tests')]
 [working-directory: 'tests/latch/']
 integration: 
     WABT="../../lib/wabt/build/" npm run tests:integration
 
 [group('test')]
-[doc('Run integration tests')]
 [working-directory: 'tests/latch/']
 all: 
     WABT="../../lib/wabt/build/" npm run tests:all
 
-## Private recipes
 
-# make build folder
-_mkdir-emu:
-    mkdir -p build-emu
+## QoL / Maintenance
+
+[group('maintenance')]
+[doc('Run routine Git maintenance')]
+maintain:
+    git maintenance run
+
+[group('maintenance')]
+[doc('Aggressively prune Git objects and stale remote refs')]
+[confirm("GC git and delete stale files?")]
+prune: _prune
+
+_prune:
+    git maintenance run --task=gc
+    git remote prune origin
+
+
+## Private recipes
 
 # make build folder
 _mkdir-doctest: