MoonModules · MoonModules · Sep 28, 2026 · Sep 26, 2026 · Sep 26, 2026 · Sep 28, 2026
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -85,7 +85,7 @@ jobs:
         # Pass the tag via --tag arg, not via an env var named GITHUB_REF_NAME.
         # The built-in GITHUB_REF_NAME is "main" on a push-to-main and would
         # shadow a step-level env override. Explicit CLI arg sidesteps the
-        # collision. Plumbed via env to avoid static-analyser template-injection
+        # collision. Plumbed via env to avoid static-analyzer template-injection
         # warning on the direct ${{ }} expansion inside a shell string.
         env:
           TAG: ${{ inputs.tag || github.ref_name }}
@@ -906,10 +906,10 @@ jobs:
           mkdir -p pages/install
           cp -r mooninstaller/. pages/install/
           cp src/ui/install-picker.js pages/install/
-          # The board-catalog / chip-detection half of the picker — mooninstaller
+          # The device-catalog / chip-detection half of the picker, mooninstaller
           # only (not embedded in firmware), imported by index.html. Must ship to
           # Pages alongside install-picker.js or the ES-module import 404s.
-          cp src/ui/install-picker-boards.js pages/install/
+          cp src/ui/install-picker-devices.js pages/install/
           # library.json — install page reads the project version from it.
           cp library.json pages/install/
           # Board picker images live in docs/assets/deviceModels/ (the project's asset
@@ -931,7 +931,7 @@ jobs:
       # (moonmodules/{core,light}/moxygen/*.md) from each `.h`'s /// comments at
       # MkDocs-build time. moxygen runs via `npx moxygen@2.1.10`, so Node must be
       # present; pin it explicitly (rather than lean on the runner image's default) so
-      # a future image change can't silently drop npx or shift its behaviour. Doxygen
+      # a future image change can't silently drop npx or shift its behavior. Doxygen
       # is the one apt binary we add — the justified non-uv dependency (like ESP-IDF's
       # Python). With the tools present, a moxygen/doxygen failure now RAISES (gen_api
       # GenApiError) and fails this build, rather than shipping a site with no API pages.

diff --git a/.vale.ini b/.vale.ini
@@ -21,6 +21,20 @@ BasedOnStyles = MoonLight
 BasedOnStyles = MoonLight
 View = CComments
 
+# The same, for the languages the scripts and the web interface are written in: a `//` or a `#`
+# carries prose as much as a `///` does, and these files were invisible to the gate until now.
+#
+# NO View here, unlike the C family above, because Vale needs none: its markdown parser already
+# treats a code-shaped line as a block and reads only the prose, so an identifier and a string
+# literal are both left alone. Measured rather than assumed, by linting the same fixture with the
+# view and without it: identical findings either way, which makes a view here dead config that
+# looks like it is doing something.
+[*.{js,mjs}]
+BasedOnStyles = MoonLight
+
+[*.py]
+BasedOnStyles = MoonLight
+
 # Upstream code, vendored rather than written here: not our prose to rule on.
 [src/platform/desktop/vendor/**]
 BasedOnStyles =

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -184,8 +184,8 @@ flowchart LR
     pc{"<b>🧑 run pre-commit</b><br/><i>PO says the words,<br/>once per request</i>"}
     diff{"the diff<br/>touches"}
     pc --> diff
-    always["<b>always</b><br/>💀 check_specs"]
-    md["<b>.md</b><br/>💀 check_prose · build_docs --strict 🐢<br/>💀 check_docgen · 🛸 test_host --python <i>(catalog pages)</i><br/>check_taglines <i>(front pages only)</i>"]
+    always["<b>always</b><br/>💀 check_specs · 💀 check_prose <i>· records, writes to the tree</i>"]
+    md["<b>.md</b><br/>build_docs --strict 🐢<br/>💀 check_docgen · 🛸 test_host --python <i>(catalog pages)</i><br/>check_taglines <i>(front pages only)</i>"]
     code["<b>src/ or test/</b><br/>💀 check_nonblocking · build_desktop 🐢<br/>🛸 test_desktop 🐢 · run_scenario 🐢<br/>💀 check_docgen <i>(the headers it covers)</i><br/>💀 check_platform_boundary <i>(not src/platform)</i><br/>💀 check_esp32_built <i>(not src/platform/desktop)</i><br/>💀 build_desktop --no-jit 🐢 <i>(MoonLive only)</i><br/>💀 collect_kpi 🐢 <i>· records, writes to the tree</i>"]
     web["<b>src/ui or mooninstaller/</b><br/>🛸 test_host --js · 💀 check_devices"]
     py["<b>moondeck/ or moonlive/</b><br/>🛸 test_host --python · 💀 check_firmwares"]
@@ -242,6 +242,8 @@ Commit message: title ≤ 72 characters, imperative. Then a 1 to 3 sentence end-
 
 The product owner pushes; external review runs on the PR; findings are processed on the branch. The same once-per-request rule applies.
 
+**Write the gate list out before running any of it, judgment gates included, and report every line.** A scripted check announces itself by producing output; a judgment gate produces nothing until someone asks, which is why the ones below get skipped. The PR title and description are judged against `git log main..HEAD` rather than the first commit, since a PR opened early keeps a title that then misdescribes every later commit.
+
 ```mermaid
 flowchart LR
     pm{"<b>🧑 run pre-merge</b><br/><i>PO says the words</i>"}

diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -20,7 +20,7 @@ if(MSVC)
     # MSVC-only warnings have no GCC equivalent at -Wall -Wextra and are
     # suppressed below rather than fought at every call site:
     #   C4702 — "unreachable code" inside `if constexpr` early-return branches
-    #           (a well-known MSVC quirk: it analyses the discarded branch as
+    #           (a well-known MSVC quirk: it analyzes the discarded branch as
     #           live and flags everything after `return;`). GCC understands the
     #           constexpr discard and doesn't warn.
     #   C4244 / C4267 — implicit narrowing (int→smaller, size_t→smaller). GCC
@@ -81,7 +81,7 @@ else()
     # (platform.h); -Wfunction-effects then checks TRANSITIVELY that nothing they reach
     # allocates or blocks, through the whole call graph. Clang 20+ only; the flag does not
     # exist on GCC, so the ESP32 build gets no hot-path check — src/platform/esp32/ is
-    # analysed only where the desktop build reaches it (docs/reference/testing.md § Static analysis).
+    # analyzed only where the desktop build reaches it (docs/reference/testing.md § Static analysis).
     # Probe for the flag instead of inferring it from a version: AppleClang reports its own
     # version line (the CI macos-14 runner reads >= 20 while predating the warning), so a version
     # comparison enables -Wfunction-effects on toolchains that reject it — and it is -Werror.
@@ -239,7 +239,7 @@ add_custom_target(build_info_gen ALL
 add_custom_command(
     OUTPUT ${CMAKE_SOURCE_DIR}/src/ui/ui_embedded.h
     COMMAND ${CMAKE_COMMAND} -DUI_DIR=${CMAKE_SOURCE_DIR}/src/ui -DOUT=${CMAKE_SOURCE_DIR}/src/ui/ui_embedded.h -DUV_EXECUTABLE=${UV_EXECUTABLE} -P ${CMAKE_SOURCE_DIR}/src/ui/embed_ui.cmake
-    DEPENDS ${CMAKE_SOURCE_DIR}/src/ui/index.html ${CMAKE_SOURCE_DIR}/src/ui/app.js ${CMAKE_SOURCE_DIR}/src/ui/style.css ${CMAKE_SOURCE_DIR}/src/ui/install-picker.js ${CMAKE_SOURCE_DIR}/src/ui/vendor/prism.js ${CMAKE_SOURCE_DIR}/src/ui/preview3d.js ${CMAKE_SOURCE_DIR}/src/ui/moonlight-logo.png ${CMAKE_SOURCE_DIR}/src/ui/embed_ui.cmake
+    DEPENDS ${CMAKE_SOURCE_DIR}/src/ui/index.html ${CMAKE_SOURCE_DIR}/src/ui/app.js ${CMAKE_SOURCE_DIR}/src/ui/style.css ${CMAKE_SOURCE_DIR}/src/ui/install-picker.js ${CMAKE_SOURCE_DIR}/src/ui/vendor/prism.js ${CMAKE_SOURCE_DIR}/src/ui/preview3d.js ${CMAKE_SOURCE_DIR}/src/ui/moonmodules-logo.png ${CMAKE_SOURCE_DIR}/src/ui/embed_ui.cmake
     COMMENT "Embedding UI files"
 )
 add_custom_target(ui_embed DEPENDS ${CMAKE_SOURCE_DIR}/src/ui/ui_embedded.h)

diff --git a/README.md b/README.md
@@ -94,7 +94,7 @@ The domain-neutral runtime: the module base class, controls, scheduling, persist
 
 ![The Services card, built from declared controls](docs/assets/core/Services.png)
 
-Architecture: [MoonCore](docs/explanation/architecture/mooncore.md) · [MoonModule](docs/explanation/architecture/moonmodule.md) · Use it: [System](docs/moonmodules/core/system.md) · [Control](docs/moonmodules/core/control.md) · [Services](docs/moonmodules/core/services.md)
+Architecture: [MoonCore](docs/explanation/architecture/mooncore.md) · [MoonModule](docs/explanation/architecture/moonmodule.md) · Use it: [System](docs/moonmodules/core/system.md) · [Control](docs/moonmodules/core/system.md#control) · [Services](docs/moonmodules/core/services.md)
 
 ### MoonLight
 
@@ -110,7 +110,7 @@ Scripts compiled to native machine code on the device. Write an effect in the br
 
 ![A MoonLive effect running](docs/assets/light/effects/MoonLiveEffect.gif)
 
-Architecture: [MoonLive](docs/explanation/architecture/moonlive.md) · Use it: [MoonLiveEffect](docs/moonmodules/light/MoonLiveEffect.md) · [the script language](moonlive/README.md)
+Architecture: [MoonLive](docs/explanation/architecture/moonlive.md) · Use it: [MoonLiveEffect](docs/moonmodules/light/moonlive.md) · [the script language](moonlive/README.md)
 
 ### MoonI80
 

diff --git a/docs/assets/luna.png b/docs/assets/luna.png
diff --git a/docs/assets/moonlight-logo.png → docs/assets/moonmodules-logo.png b/docs/assets/moonlight-logo.png → docs/assets/moonmodules-logo.png
diff --git a/docs/assets/uiscenarios/00-intro.webm b/docs/assets/uiscenarios/00-intro.webm
diff --git a/docs/assets/uiscenarios/01-install-desktop.webm b/docs/assets/uiscenarios/01-install-desktop.webm
diff --git a/docs/assets/uiscenarios/01-install-esp32.webm b/docs/assets/uiscenarios/01-install-esp32.webm
diff --git a/docs/assets/uiscenarios/02-first-look-desktop.webm b/docs/assets/uiscenarios/02-first-look-desktop.webm
diff --git a/docs/assets/uiscenarios/02-first-look-esp32.webm b/docs/assets/uiscenarios/02-first-look-esp32.webm
diff --git a/docs/assets/uiscenarios/03-second-look.webm b/docs/assets/uiscenarios/03-second-look.webm
diff --git a/docs/assets/uiscenarios/04-scenario-testing.webm b/docs/assets/uiscenarios/04-scenario-testing.webm
diff --git a/docs/assets/uiscenarios/05-layouts.webm b/docs/assets/uiscenarios/05-layouts.webm
diff --git a/docs/assets/uiscenarios/06-layers.webm b/docs/assets/uiscenarios/06-layers.webm
diff --git a/docs/assets/uiscenarios/07-drivers-desktop.webm b/docs/assets/uiscenarios/07-drivers-desktop.webm
diff --git a/docs/assets/uiscenarios/07-drivers-esp32.webm b/docs/assets/uiscenarios/07-drivers-esp32.webm
diff --git a/docs/assets/uiscenarios/08-moonlive-effects.webm b/docs/assets/uiscenarios/08-moonlive-effects.webm
diff --git a/docs/assets/uiscenarios/09-services.webm b/docs/assets/uiscenarios/09-services.webm
diff --git a/docs/assets/uiscenarios/10-control.webm b/docs/assets/uiscenarios/10-control.webm
diff --git a/docs/assets/uiscenarios/11-moondeck.webm b/docs/assets/uiscenarios/11-moondeck.webm
diff --git a/docs/assets/uiscenarios/12-getting-involved.webm b/docs/assets/uiscenarios/12-getting-involved.webm
diff --git a/docs/assets/uiscenarios/13-attribution.webm b/docs/assets/uiscenarios/13-attribution.webm
diff --git a/docs/assets/uiscenarios/91-show-the-preview.webm b/docs/assets/uiscenarios/91-show-the-preview.webm
diff --git a/docs/assets/uiscenarios/92-change-layout.webm b/docs/assets/uiscenarios/92-change-layout.webm
diff --git a/docs/assets/uiscenarios/93-add-an-effect.webm b/docs/assets/uiscenarios/93-add-an-effect.webm
diff --git a/docs/assets/uiscenarios/94-add-a-modifier.webm b/docs/assets/uiscenarios/94-add-a-modifier.webm
diff --git a/docs/assets/uiscenarios/95-add-a-layer.webm b/docs/assets/uiscenarios/95-add-a-layer.webm
diff --git a/docs/assets/uiscenarios/96-swap-an-effect.webm b/docs/assets/uiscenarios/96-swap-an-effect.webm
diff --git a/docs/assets/uiscenarios/97-write-an-effect.webm b/docs/assets/uiscenarios/97-write-an-effect.webm
diff --git a/docs/assets/uiscenarios/98-react-to-sound.webm b/docs/assets/uiscenarios/98-react-to-sound.webm
diff --git a/docs/contributing/documentation-standards.md b/docs/contributing/documentation-standards.md
@@ -208,6 +208,8 @@ A header reaches Vale through a **View**, `.vale/styles/config/views/CComments.y
 
 ## Comments
 
+These rules cover every comment the project writes, in whatever language: a `///` in a header, a `//` beside a line of the web interface, a `#` in a MoonDeck script. The prose gate reads all three, by two different routes. A C-family file needs the `CComments` View, since Vale has no parser for C and skips the file without one. That View hands back the comment nodes alone, so an identifier is never read as prose. JavaScript and Python need no View: Vale reads those as plain text. Both routes report the same findings, measured by breaking a View on purpose and watching the count hold.
+
 - **Comments say WHY.** Restating what the line does is noise, and usually a naming failure: see [prefer naming over commenting](coding-standards.md#writing-a-line-of-code).
 - **One line, above the code it explains.** A second line is the author still talking. A class `///` gets about ten lines, and each `## ` section of an `@moreinfo` appendix about ten; over that, cut. A file whose comments outnumber its code has stopped being a header.
 - **Settle the `///` first, then the `//`.** The doc comment is what a reader sees on the generated page, so it is where the explanation belongs. A `//` block below one that repeats it is deleted rather than shortened, and most of them turn out to be exactly that. Working the other way round collapses a `//` into one careful line, then deletes it an hour later once the `///` above says the same thing.

diff --git a/docs/how-to/building.md b/docs/how-to/building.md
@@ -6,6 +6,8 @@ How to get the system running on a desktop, an ESP32, a Teensy, or a Raspberry P
 
 Everything that builds, flashes, runs, tests, monitors, or checks the project — for every target — lives as a script under `moondeck/`. The full per-script reference is [moondeck/MoonDeck.md](../moondeck/MoonDeck.md).
 
+<video src="../assets/uiscenarios/11-moondeck.webm" controls playsinline width="720" title="A tour of MoonDeck: why it exists, and what the three tabs hold."></video>
+
 The scripts have two front ends with the same code and arguments:
 
 - **CLI** — `uv run moondeck/<group>/<name>.py`. What agents use; what CI uses. Composes with shell, captures exit codes, parses output.
@@ -253,7 +255,7 @@ Moving to a different release is never automatic: bump `PINNED_IDF_COMMIT` / `PI
 
 #### Adopting the v6.x ecosystem changes
 
-v6.0 introduced ecosystem-level changes beyond the API surface. The stance, under [§ Principles → Industry standards](../CLAUDE.md#principles), is to **embrace these as the ESP32 standard** — if the IDF makes something the recognised way to build, install, provision, or ship, that's the path we want, not a bespoke one we maintain alone. We adopt them **step by step** (each its own commit + hardware re-test) rather than all at once, and only after they clear the **v6.0-floor rule** above, but the default is *yes, adopt*, with the burden on *why not* — not the reverse.
+v6.0 introduced ecosystem-level changes beyond the API surface. The stance, under [§ Principles → Industry standards](../CLAUDE.md#principles), is to **embrace these as the ESP32 standard**. If the IDF makes something the recognized way to build, install, provision, or ship, that is the path we want rather than a bespoke one we maintain alone. We adopt them **step by step**, each its own commit and hardware re-test, rather than all at once, and only after they clear the **v6.0-floor rule** above. The default is *yes, adopt*, with the burden of argument on *why not*.
 
 Two guardrails bound the "embrace everything" stance:
 

diff --git a/docs/index.md b/docs/index.md
@@ -2,11 +2,18 @@
 
 High-performance LED &amp; DMX lighting control for ESP32 and beyond.
 
-[:material-flash: Flash an ESP32 from your browser](/MoonLight/install/){ .md-button .md-button--primary } &nbsp; [:material-github: GitHub](https://github.com/MoonModules/projectMM){ .md-button }
+[:material-flash: Flash an ESP32 from your browser](/projectMM/install/){ .md-button .md-button--primary } &nbsp; [:material-github: GitHub](https://github.com/MoonModules/projectMM){ .md-button }
 
 !!! tip "New here?"
     The [Getting started](gettingstarted.md) guide walks you from a blank ESP32 to your first running light show, step by step, with no build tools required.
 
+## The introduction
+
+Why MoonLight was rebuilt, who wrote it, and the principles it kept.
+The clips that follow it are the proof of what it claims.
+
+<video src="assets/uiscenarios/00-intro.webm" controls playsinline width="720" title="The spoken introduction: why MoonLight was rebuilt, who wrote it, and what it kept."></video>
+
 ## What it is
 
 MoonLight drives large LED installations and DMX fixtures. You build a light show by stacking simple blocks: a **layout** (how the LEDs are arranged), one or more **effects** (what they animate), **modifiers** (mirror, rotate, mask…), and a **driver** (how the pixels reach the hardware). Every setting takes effect live; there is no reboot to apply a change.
@@ -21,7 +28,7 @@ One source tree drives ESP32, Teensy, Raspberry Pi, macOS, Windows and Linux.
 
     Flash a board from your browser and light your first pixels.
 
-    [Getting started](gettingstarted.md) · [Web installer](/MoonLight/install/)
+    [Getting started](gettingstarted.md) · [Web installer](/projectMM/install/)
 
 -   :material-palette: **Build a show**
 
@@ -50,3 +57,15 @@ One source tree drives ESP32, Teensy, Raspberry Pi, macOS, Windows and Linux.
 </div>
 
 The web installer works in Chrome &amp; Edge (Web Serial), with no download required.
+
+## Getting involved
+
+How to start with no hardware at all, how to contribute, and what comes next.
+
+<video src="assets/uiscenarios/12-getting-involved.webm" controls playsinline width="720" title="How to start, how to contribute, and what is next."></video>
+
+## Standing on shoulders
+
+Almost none of this was invented here, and every borrowed idea is credited in the source file that carries it.
+
+<video src="assets/uiscenarios/13-attribution.webm" controls playsinline width="720" title="The people we learned from, and the algorithms we build on."></video>
diff --git a/docs/moonmodules/core/services.md b/docs/moonmodules/core/services.md
@@ -2,6 +2,8 @@
 
 The user-added **Service** modules — capability bridges the device provides or consumes, added and removed at runtime in the `Services` container (the core-domain twin of the light domain's `Effects`/`Drivers`). Fixed device infrastructure (identity, network, inspection tools) lives under **System** — see [core/system.md](system.md). Every row links to its generated technical page (the full API, from the `.h`) and its tests.
 
+<video src="../../assets/uiscenarios/09-services.webm" controls playsinline width="720" title="Every service in turn: audio, button, analog, infrared, and a scripted one."></video>
+
 <a id="services"></a>
 
 ## Services
@@ -18,8 +20,6 @@ A user-added Service: the audio source the audio-reactive effects consume. `mode
 
 <img src="../../assets/core/AudioService.png" width="300" alt="Audio module controls">
 
-<video src="../../assets/uiscenarios/98-react-to-sound.webm" autoplay loop muted playsinline width="720" title="An audio-reactive effect following the room through the board's own microphone"></video>
-
 - `mode` — Local audio, Receive network or Simulate, each showing only its own controls below.
 - `micMode`: (Local, I²S targets) `I2S` for a three-wire part, `PDM` for a two-wire one.
 - `sckPin` / `wsPin` / `sdPin`: (Local, I²S targets) the bus GPIOs, unset until entered.