Audio System + Drivers (#562)

Documentation/README.md

@@ -8,7 +8,10 @@ Tactility is an operating system for the ESP32 microcontroller family. It runs o
 
 ### Simulator (Linux/macOS, no ESP-IDF needed)
 
-Simulator is not supported on Windows
+> [!IMPORTANT]
+> The simulator does **NOT** build or run on native Windows (Win32/PowerShell/cmd). This is
+> a hard platform limitation, not a missing tool or PATH issue — do not attempt `cmake -B
+> buildsim` on Windows, it will not work. WSL is a separate, Linux environment and is fine.
 
 ```bash
 cmake -B buildsim -G Ninja
@@ -27,6 +30,23 @@ idf.py flash monitor            # flash and monitor
 
 Device IDs are the folder names under `Devices/` (e.g. `lilygo-tdeck`, `m5stack-cores3`, `cyd-2432s028r`).
 
+#### Windows: activating the ESP-IDF environment
+
+On native Windows, `idf.py` is not on PATH by default — it must be activated per-shell first.
+The install script places a PowerShell profile activator per IDF version at
+`%IDF_TOOL_PATH%\Microsoft.v<version>.PowerShell_profile.ps1` (path controlled by the
+`IDF_TOOL_PATH` environment variable, set to wherever ESP-IDF's tools were installed, e.g.
+`C:\Espressif\tools`). Source it before running any `idf.py` command:
+
+```powershell
+. "$env:IDF_TOOL_PATH\Microsoft.v5.5.2.PowerShell_profile.ps1"   # match the installed IDF version
+Set-Location "<repo-root>"
+idf.py build 2>&1 | Select-Object -Last 250
+```
+
+This is Windows-specific setup (the main dev works on Linux, where `idf.py` is normally
+already on PATH via `export.sh`/`. ./export.sh` or a shell profile).
+
 ### Devicetree
 
 A device implementation has a `.dts` file.