feat: create firmware skeleton and reproducible build

README.md

@@ -0,0 +1,66 @@
+# maze32
+
+maze32 is an ESP32-C6-hosted browser maze game. The current firmware skeleton
+mounts a LittleFS image, serves a compressed static page, and exposes a bounded
+`/health` response containing the firmware version and startup state.
+
+## Prerequisites
+
+- PlatformIO Core installed at `/home/sasa/.platformio/penv/bin/pio`;
+- a C11 host compiler available as `cc`;
+- Python 3.
+
+## Build and verify
+
+Parse the locked PlatformIO configuration:
+
+```sh
+/home/sasa/.platformio/penv/bin/pio project config
+```
+
+Run the portable host tests and deterministic asset check:
+
+```sh
+./scripts/run_host_tests.sh
+```
+
+Build the firmware. The PlatformIO hook checks the application image against
+the 2 MiB `factory` partition:
+
+```sh
+/home/sasa/.platformio/penv/bin/pio run
+```
+
+Generate compressed assets explicitly when needed:
+
+```sh
+/home/sasa/.platformio/penv/bin/python scripts/generate_web_assets.py
+```
+
+Build the LittleFS image. Asset generation runs automatically before packaging,
+and the PlatformIO hook checks the image against the 1,984 KiB `littlefs`
+partition:
+
+```sh
+/home/sasa/.platformio/penv/bin/pio run --target buildfs
+```
+
+## Device commands
+
+Upload the application and LittleFS image:
+
+```sh
+/home/sasa/.platformio/penv/bin/pio run --target upload
+/home/sasa/.platformio/penv/bin/pio run --target uploadfs
+```
+
+Monitor startup at 115200 baud:
+
+```sh
+/home/sasa/.platformio/penv/bin/pio device monitor
+```
+
+A successful boot reports the firmware version, LittleFS capacity and use, the
+HTTP service startup, and health state `serving`. Network provisioning is part
+of a later milestone; this milestone only establishes the HTTP/static service
+that will be attached to that network lifecycle.