1 files changed, 56 insertions, 0 deletions
diff --git a/doc/HOWTO.md b/doc/HOWTO.md
index 5af3f05..36216fa 100644
--- a/doc/HOWTO.md
+++ b/doc/HOWTO.md
@@ -55,6 +55,19 @@ cmake -S . -B build -DDEMO_ALL_OPTIONS=ON
 cmake --build build
 ```
 
+### Build System Notes
+
+**Incremental Builds**: The build system tracks all source files (.cc, .h) and asset files (.wgsl shaders, .spec audio, .obj meshes) as dependencies. Editing any file will trigger the necessary rebuilds automatically.
+
+**Asset Dependency Tracking**: CMake tracks 42 demo assets and 17 test assets individually. Changing a shader file (e.g., `assets/final/shaders/renderer_3d.wgsl`) automatically regenerates the asset bundle and recompiles dependent files. No manual workarounds needed.
+
+**Header Organization**: The `asset_manager` system is split into three headers for faster incremental builds:
+- `asset_manager_dcl.h`: Forward declarations (use in headers)
+- `asset_manager.h`: Core API (GetAsset/DropAsset)
+- `asset_manager_utils.h`: Typed helpers (TextureAsset/MeshAsset)
+
+Include only what you need to minimize rebuild times.
+
 ## git cloning
 
 if you have the public ssh key authorized on the VPS, you can use
@@ -293,6 +306,49 @@ The executable will be located at `build/specview`.
 ./build/specview path/to/input.spec
 ```
 
+### Audio Analysis & Playback Tool (`specplay`)
+
+A diagnostic tool for analyzing and playing .spec spectrogram files and .wav audio files. Useful for debugging audio issues, detecting clipping, and comparing spectrograms to source audio.
+
+#### Building the Tool
+
+`specplay` is built along with other tools when enabling `DEMO_BUILD_TOOLS`.
+
+```bash
+cmake -S . -B build -DDEMO_BUILD_TOOLS=ON
+cmake --build build
+```
+The executable will be located at `build/specplay`.
+
+#### Usage
+
+**Play and analyze a .spec file:**
+```bash
+./build/specplay path/to/input.spec
+```
+
+**Play and analyze a .wav file:**
+```bash
+./build/specplay path/to/input.wav
+```
+
+#### Output Example
+```
+Loading .spec: version=1, dct_size=512, frames=68
+PCM stats: Peak=0.403, RMS=0.058
+Playing 1.09 seconds... Press Ctrl+C to stop.
+[CLIP at sample 1234: 1.523]  # Only shown if clipping detected
+Playback complete.
+```
+
+#### Use Cases
+- **Detect clipping**: Peak > 1.0 indicates samples will clip
+- **Compare loudness**: RMS shows average energy (loudness)
+- **Verify spectrograms**: Ensure .spec matches source .wav
+- **Debug distortion**: Quickly test individual samples
+
+See `tools/specplay_README.md` for detailed documentation and future enhancement ideas.
+
 ### Asset Management System
 
 This system allows embedding binary assets directly into the demo executable.