docs: Update README.md for improved clarity and structure, enhancing overview, prerequisites, quick start, and runtime configuration sections

README.md

@@ -1,22 +1,54 @@
 # SDL3CPlusPlus
-Minimal SDL3 + Vulkan spinning cube demo.
+SDL3 + Vulkan demo app with Lua-driven runtime configuration, audio playback, and a small GUI sample.
 
-## Cheat sheet
+## Overview
+- Renders a spinning cube with Vulkan via SDL3.
+- Lua scripts control behavior under `scripts/`.
+- JSON runtime configs live in `config/`.
+- Optional helpers for audio asset generation and workflow diagnostics.
 
-### Dependencies
-- `python scripts/dev_commands.py dependencies` installs the Conan graph in `build`.
+## Prerequisites
+- Python 3 for helper scripts.
+- Conan for dependency resolution.
+- CMake and a C++ compiler.
+- Ninja (default generator) or Visual Studio 2022 on Windows.
+- Vulkan runtime/driver to run the demo.
 
-### Configure & build
-- `python scripts/dev_commands.py configure` defaults to Ninja+MSVC on Windows or plain Ninja on Linux/macOS, writing into the matching `build-ninja-msvc`/`build-ninja` folder with the `Release` build type; override the generator or build directory with `--generator` / `--build-dir` if you need something else.
-- `python scripts/dev_commands.py build` runs `cmake --build` in the same folder (change `--build-dir` to match a different configure directory).
-- `python scripts/dev_commands.py msvc-quick` (Windows only) runs the VC vars + Ninja build alias; pass `--bat-path` to target a different Visual Studio installation.
-- `python scripts/dev_commands.py run` launches `sdl3_app` (use `--target` to run another executable and `--args` to forward CLI arguments).
-- Prefix any subcommand with `--dry-run` to print the alias-driven shell command without executing it.
+## Quick start
+1. `python scripts/dev_commands.py dependencies`
+2. `python scripts/dev_commands.py configure`
+3. `python scripts/dev_commands.py build`
+4. If you used Conan, load the runtime env vars:
+   - Linux/macOS: `source build/conanrun.sh`
+   - Windows (cmd.exe): `build\conanrun.bat`
+5. `python scripts/dev_commands.py run`
 
-### Run
-- `python scripts/dev_commands.py run [--build-dir ...]` (source `build/conanrun.sh` / `build\conanrun.bat` first if the Conan runtime exports env vars).
+## Build helper commands
+- `python scripts/dev_commands.py configure` uses Ninja by default (Ninja+MSVC on Windows) and writes to `build-ninja`/`build-ninja-msvc`; override with `--generator` and `--build-dir`.
+- `python scripts/dev_commands.py build` runs `cmake --build` for that folder (use `--build-dir` and `--target` as needed).
+- `python scripts/dev_commands.py msvc-quick` runs `vcvarsall.bat` plus a build command (Windows only).
+- Prefix any subcommand with `--dry-run` to print the shell command without executing it.
 
-### Audio assets
+## Running
+- Default build dir: `build-ninja` on Linux/macOS, `build-ninja-msvc` on Windows.
+- `python scripts/dev_commands.py run --build-dir <path>` to run from a custom build directory.
+- `python scripts/dev_commands.py run --target spinning_cube` to launch another executable.
+- `python scripts/dev_commands.py run -- --json-file-in config/gui_runtime.json` to pass app flags (use `--` before app args).
+
+### JSON config examples
+- `python scripts/dev_commands.py run -- --json-file-in config/seed_runtime.json`
+- `python scripts/dev_commands.py run -- --json-file-in config/soundboard_runtime.json`
+- `python scripts/dev_commands.py run -- --json-file-in config/gui_runtime.json`
+
+## Runtime configuration
+- `sdl3_app --json-file-in <path>` loads JSON configs (script path, window size, `lua_debug`, etc.).
+- `sdl3_app --create-seed-json config/seed_runtime.json` writes a starter file assuming `scripts/cube_logic.lua` sits beside the binary.
+- `sdl3_app --set-default-json [path]` stores or overrides the runtime JSON; Windows writes `%APPDATA%/sdl3cpp`, other OSes use `$XDG_CONFIG_HOME/sdl3cpp/default_runtime.json` (fallback `~/.config/sdl3cpp`).
+
+## GUI demo
+`scripts/gui_demo.lua` paints the Lua GUI framework on top of the Vulkan scene. Launch it as `python scripts/dev_commands.py run -- --json-file-in config/gui_runtime.json` or register that config via `sdl3_app --set-default-json`.
+
+## Audio assets
 Install the dependencies that power `scripts/generate_audio_assets.py`:
 - `python -m pip install --user numpy soundfile pedalboard piper-tts`
 
@@ -28,14 +60,6 @@ python -m piper.download_voices en_US-lessac-medium --download-dir scripts/asset
 
 Running the generator recreates procedural effects under `scripts/assets/audio/sfx/` and voice clips under `scripts/assets/audio/tts/`. Use `--force` to rebuild every file and `--skip-sfx` / `--skip-tts` if you only need one subset; add `--verbose` to see the internal logging as the files are created. Override the voice files with `--piper-voice-model <path>` and (optionally) `--piper-voice-config <path>` if you downloaded a different voice or location. Pass `--download-voice` to have the script invoke `piper.download_voices` automatically before rendering (requires `piper-tts` and network access).
 
-### GitHub Actions workflow diagnostics
+## GitHub Actions workflow diagnostics
 - `python -m pip install pyyaml` installs the YAML dependency for the workflow analyzer.
 - `python scripts/workflow_doctor.py [--workflows-dir .github/workflows]` inspects workflows for missing permissions, floating action references, and other reproducibility/security hints.
-
-## Runtime configuration
-1. `sdl3_app --json-file-in <path>` loads JSON configs (script path, window size, `lua_debug`, etc.).
-2. `sdl3_app --create-seed-json config/seed_runtime.json` writes a starter file assuming `scripts/cube_logic.lua` sits beside the binary.
-3. `sdl3_app --set-default-json [path]` stores or overrides the runtime JSON; Windows writes `%APPDATA%/sdl3cpp`, other OSes use `$XDG_CONFIG_HOME/sdl3cpp/default_runtime.json` (fallback `~/.config/sdl3cpp`).
-
-### GUI Demo
-`scripts/gui_demo.lua` paints the Lua GUI framework on top of the Vulkan scene. Launch it as `./build/sdl3_app --json-file-in config/gui_runtime.json` or register that config via `sdl3_app --set-default-json`.