MoonModules · ewowi · Aug 23, 2026 · Aug 23, 2026 · Aug 23, 2026 · Aug 23, 2026
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -529,6 +529,7 @@ jobs:
             dist/projectMM-*.tar.gz
             dist/projectMM-*.zip
             dist/projectMM-*.dmg
+            dist/projectMM-*-setup.exe
             dist/projectmm_*.deb
 
   # Deploy the web installer to GitHub Pages. Separate from `release` because

diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -207,8 +207,37 @@ add_custom_target(ui_embed DEPENDS ${CMAKE_SOURCE_DIR}/src/ui/ui_embedded.h)
 # running); wiring the dep here makes the ordering explicit on every consumer.
 add_dependencies(mm_core ui_embed build_info_gen)
 
+# Windows: give the exe its own icon, so it is recognizable in Explorer, the taskbar and the Start
+# menu whether it was installed or just unzipped. Generated from the same web-installer/favicon.png
+# the macOS .icns comes from, so the mark has one source rather than a checked-in binary per
+# platform. Nothing here runs on macOS or Linux, which carry their icon in the .app and the .deb.
+set(MM_WIN_RESOURCES "")
+if(WIN32)
+    set(MM_ICON "${CMAKE_BINARY_DIR}/projectMM.ico")
+    set(MM_RC   "${CMAKE_BINARY_DIR}/projectMM.rc")
+    add_custom_command(
+        OUTPUT "${MM_ICON}"
+        # `uv run <script>` rather than the usual `uv run python <script>`: make_ico.py declares
+        # Pillow inline (PEP 723), and only the script form makes uv honour that declaration.
+        COMMAND ${UV_EXECUTABLE} run "${CMAKE_SOURCE_DIR}/moondeck/ci/make_ico.py"
+                "${CMAKE_SOURCE_DIR}/web-installer/favicon.png" "${MM_ICON}"
+        DEPENDS "${CMAKE_SOURCE_DIR}/web-installer/favicon.png"
+                "${CMAKE_SOURCE_DIR}/moondeck/ci/make_ico.py"
+        COMMENT "Generating projectMM.ico from favicon.png"
+        VERBATIM)
+    # Forward slashes: rc.exe accepts them, and a backslash here would be an escape.
+    file(WRITE "${MM_RC}"
+         "// Generated by CMake from web-installer/favicon.png. Do not edit.\n"
+         "IDI_ICON1 ICON \"${MM_ICON}\"\n")
+    # The .ico rides along as a source so the custom command runs, but it is data, not something to
+    # compile; the .rc recompiles whenever the icon is regenerated.
+    set_source_files_properties("${MM_ICON}" PROPERTIES HEADER_FILE_ONLY TRUE)
+    set_source_files_properties("${MM_RC}" PROPERTIES OBJECT_DEPENDS "${MM_ICON}")
+    set(MM_WIN_RESOURCES "${MM_RC}" "${MM_ICON}")
+endif()
+
 # Application
-add_executable(projectMM src/main.cpp src/platform/desktop/main_desktop.cpp)
+add_executable(projectMM src/main.cpp src/platform/desktop/main_desktop.cpp ${MM_WIN_RESOURCES})
 target_link_libraries(projectMM PRIVATE mm_core mm_platform)
 add_dependencies(projectMM ui_embed build_info_gen)
 

diff --git a/README.md b/README.md
@@ -96,15 +96,17 @@ The numbers above are observations. The **contracts** projectMM commits to, what
 
 ![Installer](docs/assets/ui/installer.png)
 
-**Desktop: download and run.** Grab the build for your OS from the [releases page](https://github.com/MoonModules/projectMM/releases):
+**Desktop: download and run.** Grab the build for your OS from the [releases page](https://github.com/MoonModules/projectMM/releases). Step-by-step with screenshots for Windows: [Installing projectMM on a desktop](docs/tutorials/installing-to-desktop.md).
 
-- **macOS arm64:** `projectMM-macos-arm64-vX.Y.Z.dmg`: open it and drag projectMM to Applications, then launch it like any app. A Terminal window opens showing what it is doing, your browser opens the UI, and closing that window stops it. (`projectMM-macos-arm64-vX.Y.Z.tar.gz` is the same binary without the wrapper, for scripting.) x86-64 macOS is supported and tested, but only the arm64 build is packaged: build from source for an Intel Mac. The app is ad-hoc signed rather than notarized, so the first launch is refused with "Apple could not verify projectMM is free of malware". On macOS 15 and later that dialog offers no way through, so clear the download flag once in Terminal and open it again: `xattr -dr com.apple.quarantine /Applications/projectMM.app` (or `./projectMM` for the tarball).
-- **Windows x64:** `projectMM-windows-x64-vX.Y.Z.zip`: unzip, double-click `projectMM.exe`. SmartScreen may warn on first run because the binary is unsigned (More info → Run anyway).
+- **macOS arm64:** `projectMM-macos-arm64-vX.Y.Z.dmg`: open it and drag projectMM to Applications, then launch it like any app. A Terminal window opens showing what it is doing, your browser opens the UI, and closing that window stops it. (`projectMM-macos-arm64-vX.Y.Z.tar.gz` is the same binary without the wrapper, for scripting.) x86-64 macOS is supported and tested, but only the arm64 build is packaged: build from source for an Intel Mac. The binary is ad-hoc signed rather than notarized, so Gatekeeper says it cannot verify the developer; right-click → Open and confirm, or clear the flag with `xattr -dr com.apple.quarantine ./projectMM`.
+- **Windows x64:** `projectMM-windows-x64-vX.Y.Z-setup.exe`: run it and projectMM installs for your user (no admin prompt) with a Start-menu entry and an uninstaller. `projectMM-windows-x64-vX.Y.Z.zip` is the same binary without the installer, to unzip and run from anywhere. SmartScreen may warn on first run because neither is signed (More info → Run anyway).
 - **Linux x64:** `projectMM-linux-x64-vX.Y.Z.tar.gz`, or `projectmm_X.Y.Z_amd64.deb` on Debian, Ubuntu and Raspberry Pi OS (`sudo apt install ./projectmm_X.Y.Z_amd64.deb` puts it on your PATH).
 
 Then open `http://localhost:8080/`. It opens by itself on start; pass `--no-browser` to suppress
 that (a headless server, or a service manager), and `--port <n>` to serve somewhere else.
 
+**Your settings live with your user, not beside the executable**, so they survive moving the app, reinstalling, and upgrading: `%LOCALAPPDATA%\projectMM` on Windows, `~/Library/Application Support/projectMM` on macOS, and `$XDG_DATA_HOME/projectMM` on Linux, falling back to `~/.local/share/projectMM` when that is unset. An uninstall leaves them in place; delete that folder to start clean. Set `MM_DATA_DIR` to put them somewhere else. Running from a source checkout keeps using `build/` instead, so a development tree stays self-contained.
+
 Once running, the UI lets you build a render pipeline visually (layouts → layers with effects + modifiers → drivers), preview the result in 3D, send it to Art-Net, and save it. The source tree also builds for Teensy, Raspberry Pi, and Linux from source (see [building.md](docs/building.md)), though currently only the macOS, Windows, Linux and ESP32 binaries ship as releases.
 
 ### From source

diff --git a/docs/MIGRATING.md b/docs/MIGRATING.md
@@ -22,6 +22,19 @@ projectMM ships **no migration code**: the persistence layer is robust by defaul
 
 ## Unreleased (`next-iteration`)
 
+### Desktop settings move to a per-user directory (2026-08-23)
+
+The desktop build wrote its configuration to `build/.config`, resolved against whatever directory the process happened to start in. That is a source-checkout layout, and it shipped: a downloaded binary either could not write there at all, failing every save and logging one line per save, or it wrote settings that belonged to that *folder* rather than to the user, so moving the executable lost them.
+
+Settings now live with the user: `%LOCALAPPDATA%\projectMM` on Windows, `~/Library/Application Support/projectMM` on macOS, and `$XDG_DATA_HOME/projectMM` on Linux, falling back to `~/.local/share/projectMM` when that is unset. `MM_DATA_DIR` overrides it. **A source checkout is unchanged** and still uses `build/.config`, so a development tree and every gate script behave exactly as before.
+
+**Action: *nothing*, unless your settings actually persisted before.** The old behavior had two modes, and only one of them leaves anything to move:
+
+- **Saves were failing.** The log showed `write failed for /.config/...` on every change and nothing survived a restart. Nothing to carry across.
+- **Saves were succeeding, per folder.** They are in a `build/.config` folder beside wherever you launched from: the folder you unzipped into on Windows and Linux, and `~/build/.config` on macOS, because the `.app` launcher starts in your home directory. **Action: *move a folder*.** Move the `.config` directory itself into the new per-user directory, so it lands as `<data directory>/.config` rather than spilling its files into the root. Or leave it and reconfigure from scratch.
+
+ESP32 is unaffected: LittleFS mounts at a fixed partition and never used this path.
+
 ### The `Layers` container is renamed to `Effects` (2026-08-08)
 
 The three top-level light containers are now **Layouts, Effects, Drivers** — L.E.D. The old name sat one character from its own child (`Layers` holding `Layer`s) and read as a near-twin of `Layouts`, which is the pair a newcomer actually has to tell apart. The tree is unchanged in shape: `Effects` → `Layer`s → effects and modifiers.

diff --git a/docs/assets/tutorials/windows-01-download.png b/docs/assets/tutorials/windows-01-download.png
diff --git a/docs/assets/tutorials/windows-02-extract.png b/docs/assets/tutorials/windows-02-extract.png
diff --git a/docs/assets/tutorials/windows-03-smartscreen.png b/docs/assets/tutorials/windows-03-smartscreen.png
diff --git a/docs/assets/tutorials/windows-04-running.png b/docs/assets/tutorials/windows-04-running.png
diff --git a/docs/backlog/backlog-core.md b/docs/backlog/backlog-core.md
@@ -940,6 +940,14 @@ The tool shells out to `c++` and `objdump` to build the per-ISA emitter and disa
 
 Closing it is a compiler/disassembler pair behind the two `subprocess.run` calls: `cl.exe` for the build, and for the disassembly either LLVM's `llvm-objdump` (which understands `-b binary` the way the tool already expects, and ships with the VS "C++ Clang tools" component) or a `.obj` wrapper around `dumpbin /disasm`, which does not. Prefer the former — the flags are already right, so it is a lookup rather than a second code path.
 
+## A non-ASCII Windows profile path defeats the desktop settings directory (2026-08-23)
+
+`std::getenv("LOCALAPPDATA")` returns the ANSI form of the path, so a Windows user whose profile name carries characters outside the system codepage (CJK and Cyrillic on a Western machine; most accented Latin survives cp1252) gets `?` where those characters were. `?` is not legal in a Windows filename, so `create_directories` fails, `fsMount` returns false, and the driver reports `cannot use ..., persistence disabled` naming the mangled path. It degrades visibly rather than corrupting anything, which is the standard Principle 5 asks for, but that user has no working persistence.
+
+Reading the variable wide is only half of it. `toFsPath` composes a `std::filesystem::path`, which stores wide on Windows, but every open in the layer goes back through `.string()` to reach `std::fopen` (fsRead, fsReadAt, fsWriteAtomic, fsWriteStream, and the mount probe), a narrowing the code comments on deliberately at `fsRead`. So a wide `LOCALAPPDATA` alone would produce a correct path that still cannot be opened: the fix is one `_wfopen`-on-Windows helper shared by all five sites, plus a test with a non-ASCII root.
+
+Not done with the per-user data directory because it reverses a documented decision across the whole desktop filesystem layer, four of whose five call sites predate that change. What the change did do is make the root capable of containing a username, where it was previously the literal `build`. Worth closing the next time this file is opened for other reasons.
+
 ## A driven GPIO the Pins map never sees: bus padding, and a hidden clockPin
 
 **Found:** 2026-08-21, on MM-S31, after a bench session that started as "the LED panel stopped working" and cost hours chasing a firmware regression that did not exist.

diff --git a/docs/building.md b/docs/building.md
@@ -65,6 +65,28 @@ Or use MoonDeck's Desktop tab for the same operations with a status dot per card
 
 Each host writes into its own build dir: `build/macos/`, `build/linux/`, `build/windows/`. The per-host layout mirrors the ESP32 side's `build/esp32-<board>/` shape — one directory per target, no cross-target clobbering on a multi-host dev machine.
 
+### Where the desktop keeps its settings
+
+A **source checkout writes to `build/.config/`**, recognized by `CMakeLists.txt` and `moondeck/` both being in the working directory, so a development tree stays self-contained and gitignored. Anywhere else, an installed or unzipped binary writes to the OS per-user data directory:
+
+| Platform | Directory |
+|---|---|
+| Windows | `%LOCALAPPDATA%\projectMM` |
+| macOS | `~/Library/Application Support/projectMM` |
+| Linux | `$XDG_DATA_HOME/projectMM`, else `~/.local/share/projectMM` |
+
+`MM_DATA_DIR` overrides both, which is how the test suite pins its root into the build tree rather than touching a developer's real settings.
+
+The distinction matters because a shipped binary is launched from a download folder or a Start-menu shortcut, where a path relative to the working directory is either unwritable or belongs to that folder rather than to the user. The root is created when the filesystem mounts, and a location that cannot be written to fails the mount and is reported once, rather than surfacing as a failed save on every change.
+
+### Packaging
+
+`uv run moondeck/ci/package_desktop.py` builds and packages for the host it runs on: a `.dmg` with a `.app` on macOS, a `.tar.gz` plus a `.deb` on Linux, and a `.zip` plus an NSIS `-setup.exe` on Windows. The Windows installer puts the program in `%LOCALAPPDATA%\Programs\projectMM` with a Start-menu shortcut and an uninstaller; it needs no elevation, and it never touches the settings directory, so an upgrade keeps the user's configuration.
+
+Both the Windows icon and the macOS `.icns` derive from `web-installer/favicon.png`, so the mark has one source. The `.ico` is generated during the CMake build (`moondeck/ci/make_ico.py`, which pulls Pillow on demand through uv) and embedded in the executable, so the binary carries its icon whether it was installed or just unzipped.
+
+Each packager skips its platform-specific format when the tool is missing (`dpkg-deb`, `makensis`) on a dev machine, and fails outright under CI, where a missing artifact would otherwise fail the release with an error naming a glob rather than the absent tool.
+
 ### Prerequisites
 
 Every host needs [uv](https://docs.astral.sh/uv/), CMake 3.20+, and a C++20 compiler.

diff --git a/docs/history/lessons.md b/docs/history/lessons.md
@@ -574,3 +574,19 @@ evidence which *looks* most authoritative here is the evidence that lies.
   and one was rewritten. The habit that catches it is cheap: **sabotage the fix and confirm the test
   goes red before believing it.** Two of those three had also been failing for a reason unrelated to
   what they claimed to assert, which the control check surfaced immediately.
+
+- **A build script that does not build what the next command tests produces a confident false
+  green.** `build_desktop.py` builds `projectMM` but not `mm_tests`/`mm_scenarios` unless given
+  `--tests`, so `ctest` straight after it runs whatever binary was there before. It reported "1377
+  passed" against a test binary two hours old, on a change whose new option string was not even
+  present in it. The tell is cheap and worth the habit: **after changing code, confirm the test
+  binary actually contains the change** (a `grep` for a new string, or a run of just the new case)
+  before believing a green suite. The staleness guards in `run_scenario.py` exist for exactly this
+  and are why the scenario half never went unnoticed; the unit half has no such guard.
+
+- **A freshness guard keyed on mtime must exclude files the build itself rewrites.** The same guard
+  then cried wolf: `build_info.h` embeds a `+` when `git status` reports a dirty tree, and a gate run
+  dirties the tree by writing its own scenario baselines and metrics. So every gate run left the
+  next one reporting a stale runner, a self-inflicted loop that reads exactly like a real staleness
+  failure. **Generated build metadata is not source**, and a guard that cannot tell them apart
+  teaches people to ignore it.