Drive HUB75 panels natively, drive the UI from run files, and restructure the docs

.gitignore

@@ -145,3 +145,15 @@ __pycache__/
 # Root-anchored + dir-scoped, like /build/ above: a bare `.snapshots` would also swallow any
 # nested path of that name anywhere in the tree.
 /.snapshots/
+
+# Video-production OUTPUT: the music a cut is scored against, the raw takes, the
+# finished videos, and the intermediates between them. Nothing here is redistributable
+# (licensed music, large binaries), and a repository is not a media library: what ships
+# to a viewer lives on the video platform.
+#
+# The whole folder, because /media/ is output ONLY. The sources live elsewhere by
+# design: the run files under test/uiscenarios/, the published doc clips under
+# docs/assets/uiscenarios/, the tooling under moondeck/uiscenario/. An earlier version
+# listed media types one by one, to protect run files that used to live here; they no
+# longer do, so the rule can say what it means.
+/media/

CLAUDE.md

@@ -205,6 +205,8 @@ flowchart LR
 
 Each name is a script under `moondeck/`, run through `uv run`; the command and what it does are in [MoonDeck.md](moondeck/MoonDeck.md), one section per script. 🐢 marks a check costing tens of seconds or more.
 
+**`test_host --ui` is never a gate.** The UI scenario runs drive a real browser against a running device and are what the documentation clips are recorded from, so they cost minutes and skip wholesale without a desktop and a Playwright browser. They run on request only, never as part of pre-commit, pre-merge or pre-release, and the `src/ui` trigger above means `--js` alone.
+
 
 Three checks earn their place for a reason worth knowing. **Repo health** is the only place the creeping numbers are visible: flash and DRAM per target, binary size, the tick matrix, line counts, complexity warnings. Its diff belongs in the commit and its deltas in the commit message. It runs when the code changes rather than on every commit, because its timings drift with the host: on a docs-only diff it records a regression that nothing in the diff caused. **The no-backend build** catches a helper left unused outside its guard, fatal under GCC while clang stays silent. **ESP32 firmware fresh** compares the binary against every source in a tenth of a second and catches the edit that was never compiled; compile for real after an sdkconfig or toolchain change. The [provisioning path](moondeck/MoonDeck.md#improv_smoke_test) is the five files MoonDeck names.
 

README.md

@@ -164,7 +164,7 @@ Per-grid and per-device tables, free-heap figures, and why WiFi costs what it do
 
 **ESP32**: open the [web installer](https://moonmodules.org/projectMM/install/) in Chrome or Edge ([MoonInstaller](#mooninstaller)). It walks you through device, firmware, flashing and network setup.
 
-**Desktop**: download your build from the [releases page](https://github.com/MoonModules/projectMM/releases), then open `http://localhost:8080/`. Step by step with screenshots: [Installing projectMM on a desktop](docs/tutorials/installing-to-desktop.md).
+**Desktop**: download your build from the [releases page](https://github.com/MoonModules/projectMM/releases), then open `http://localhost:8080/`. Step by step with screenshots: [Installing projectMM on a desktop](docs/how-to/installing-to-desktop.md).
 
 - **macOS arm64**: `.dmg`, drag to Applications. Ad-hoc signed, so right-click and Open the first time.
 - **Windows x64**: `-setup.exe` installs for your user without an admin prompt. Unsigned, so SmartScreen asks once.

docs/explanation/architecture/moonbase.md

@@ -4,6 +4,28 @@ A small maintenance image in the factory slot that installs updates into one lar
 
 What it replaces comes first, then the update cycle, then how MoonBase itself is updated and how the two images are told apart.
 
+```mermaid
+flowchart LR
+    subgraph flash["one flash, two images"]
+        direction TB
+        base["factory slot<br/>MoonBase, ~750 KB<br/>small and rarely changing"]
+        app["app slot<br/>projectMM<br/>one copy, not two"]
+        fs["filesystem<br/>the space the second<br/>app slot used to hold"]
+    end
+
+    base -->|"installs the app<br/>while running from factory"| app
+    app -->|"installs MoonBase<br/>while running from ota_0"| base
+
+    classDef recovery fill:#4d3d1f,stroke:#c9a95f,color:#fff
+    classDef running fill:#1f4d3d,stroke:#5fb89a,color:#fff
+    classDef gained fill:#2d3561,stroke:#7b88c9,color:#fff
+    class base recovery
+    class app running
+    class fs gained
+```
+
+Neither image can rewrite the partition it is executing from, so each installs the other. That is the whole scheme: the arrows are the only two write paths, and the app is the only thing that can repair a broken recovery image. The two directions fail differently, and both fail safe. An app update points the bootloader at MoonBase first, so a power cut anywhere in it lands in MoonBase, which a user retries from over the network. A MoonBase update writes and verifies the factory slot without touching otadata, so a cut there leaves the still-valid app in `ota_0` to boot and try again.
+
 ## What it replaces
 
 Dual-OTA spends half the app area on a second copy of the firmware that is idle except during an

docs/explanation/architecture/mooncloud.md

@@ -25,7 +25,7 @@ flowchart LR
     class db check
 ```
 
-The device talks to one origin and nothing else. A report is one POST; the aggregates come back from the same Worker that stored them.
+The device talks to one origin and nothing else.
 
 ## The decisions that shape it
 

docs/explanation/architecture/mooncore.md

@@ -4,6 +4,44 @@ The domain-neutral runtime: the platform abstraction, the services that bridge t
 
 The runtime is described from the outside in: what a service is, how several devices behave as one, how a device is named, and last the platform layer every one of them calls through.
 
+```mermaid
+flowchart TB
+    q{"does the module consume<br/>the light output buffer?"}
+    drv["driver<br/>lives in the light domain"]
+    svc["service<br/>lives here, in core"]
+
+    q -->|"yes"| drv
+    q -->|"no"| svc
+
+    subgraph core["MoonCore · knows nothing about lights"]
+        direction TB
+        services["Services<br/>user-added: gyro, mic, relay"]
+        system["System<br/>wired by code: identity, network"]
+        multi["multi-device<br/>discovery, and a shared clock"]
+    end
+
+    plat["platform abstraction<br/>time · memory · allocExec<br/>sockets · scheduling"]
+    hw["ESP32 · Teensy · desktop"]
+
+    svc --> services
+    services --> plat
+    system --> plat
+    multi --> plat
+    drv -.->|"reaches hardware<br/>the same way"| plat
+    plat --> hw
+
+    classDef ask fill:#2d3561,stroke:#7b88c9,color:#fff
+    classDef light fill:#4d3d1f,stroke:#c9a95f,color:#fff
+    classDef neutral fill:#1f4d3d,stroke:#5fb89a,color:#fff
+    classDef seam fill:#3d2d61,stroke:#a07bc9,color:#fff
+    class q ask
+    class drv light
+    class svc,services,system,multi neutral
+    class plat,hw seam
+```
+
+One question sorts every module, and it is about the data relationship rather than the connector: a DMX sender speaks over a UART and is still a driver, because it sends the rendered buffer. Everything below the seam is reached only through the platform layer, which is why the same tree runs on a board and on a laptop.
+
 ## Services
 
 A **service** is a MoonModule (role `ModuleRole::Service`) that bridges to the outside world (hardware or network) *independently of the light pipeline*. Examples: a gyro/IMU over I²C, a microphone over I²S, a relay or GPIO toggled out, a status push to Home Assistant. Services are **domain-neutral and live in core**; the platform transport they use (I²C, UART, GPIO) is itself a domain-neutral platform primitive.

docs/explanation/architecture/moondeck.md

@@ -6,8 +6,6 @@ The shape comes first, then why the scripts are ours, then where the state lives
 
 ## One script per task, two front ends
 
-![MoonDeck, one page per task](../../assets/ui/moondeck_desktop.png)
-
 ```mermaid
 flowchart LR
     task["<b>a task</b><br/><i>build · flash · test · check</i>"]
@@ -29,6 +27,8 @@ flowchart LR
 
 Every action the console offers is a thin wrapper around a script, so `uv run moondeck/build/build_desktop.py` and the button run the same code. That is the whole design: one implementation, two ways in, and no path where a human and an agent measure something differently.
 
+![MoonDeck, one page per task](../../assets/ui/moondeck_desktop.png)
+
 **The script is the contract.** It picks the right per-host build directory, applies the flags the gate expects, and tees its output where the report reads it. Reaching past it to `cmake` or `idf.py` produces a number measured differently, or a stale binary the script would have rebuilt.
 
 ## Why our own scripts

docs/explanation/architecture/mooninstaller.md

@@ -2,10 +2,41 @@
 
 Three words name three different things, and a device is configured by all of them: the firmware it runs, the deviceModel it is, and the board it sits on. Getting a device onto the network is the installer's job; knowing what it is afterwards is this vocabulary.
 
-![The installer picking a device model by picture](../../assets/ui/installer.png)
-
 The three words come first, then where a default legitimately comes from.
 
+```mermaid
+flowchart TB
+    mcu["MCU<br/>classic · S3 · P4"]
+    fw["firmware<br/>the compiled binary"]
+    model["deviceModel<br/>the assembled product<br/>Olimex ESP32-Gateway Rev G"]
+    board["board<br/>the bare PCB, literally"]
+    name["deviceName<br/>which individual unit this is"]
+
+    mcu --> fw
+    fw -->|"seeds a per-chip default"| model
+    board --> model
+    model --> name
+
+    fixes["fixes: which radios, which<br/>ethernet driver, PSRAM"]
+    owns["fixes: the real pin map,<br/>buttons, mic, TX power"]
+
+    fw -.-> fixes
+    model -.-> owns
+
+    classDef silicon fill:#4d3d1f,stroke:#c9a95f,color:#fff
+    classDef product fill:#1f4d3d,stroke:#5fb89a,color:#fff
+    classDef unit fill:#2d3561,stroke:#7b88c9,color:#fff
+    classDef note fill:#3d2d61,stroke:#a07bc9,color:#fff
+    class mcu,fw silicon
+    class model,board product
+    class name unit
+    class fixes,owns note
+```
+
+A default belongs at the level that fixes it, which is the whole rule. The firmware seeds what the silicon decides; the deviceModel overrides it with what the product wired. So the ethernet pins appear at both levels without contradiction: the firmware offers a fallback, the catalog entry states the truth. A control nobody fixed is omitted, and stays unset for the user to wire.
+
+![The installer picking a device model by picture](../../assets/ui/installer.png)
+
 ## The three words
 
 Three distinct things, kept distinct in the vocabulary:

docs/explanation/architecture/moonlight.md

@@ -6,8 +6,6 @@ The pipeline comes first, then each stage in the order light flows through it, a
 
 ## The pipeline
 
-![A layout, a layer of effects, and the drivers that output it](../../assets/light/Effects.png)
-
 Modules in the light pipeline can be added, replaced, or removed dynamically at runtime.
 
 ```mermaid
@@ -54,6 +52,8 @@ flowchart TB
     class dma,udp,sock gate
 ```
 
+![A layout, a layer of effects, and the drivers that output it](../../assets/light/Effects.png)
+
 **Data flow.** The pipeline instantiates both core data-exchange shapes (see [data exchange between modules](moonmodule.md#data-exchange-between-modules)):
 
 - *Shared-struct (pull):* `Drivers` hands every child driver a `Buffer*` (source) plus a `Correction*` (shared brightness/reorder/white), and `Layer` exposes its pixel buffer to `Drivers` directly on the identity-mapping fast path: each consumer holds a `const`-pointer and reads it per frame. The pointers are **(re)bound on every rebuild**, more than at boot: `Drivers::prepare()` re-resolves the active `Layer` (`Effects::activeLayer()`) and calls `passBufferToDrivers()`, which re-runs `setSourceBuffer()`/`setLayer()` on each child (clearing them to `nullptr` when there is no active Layer). So a held pointer is valid only until the next rebuild. That is why consumers re-read it each frame and tolerate a null, per the [robustness rule](moonmodule.md#robustness): a Layer add, delete or replace re-binds or clears it live, with no dangling reference.

docs/explanation/architecture/moonlive.md

@@ -4,6 +4,43 @@ Scripts compiled to native machine code on the device. An effect written as text
 
 The engine comes first, then how a script reaches the device, and last the one place the lifecycle does not yet fit.
 
+```mermaid
+flowchart TB
+    src["a script, as text<br/>written in the browser"]
+
+    subgraph front["front-end · core, platform-independent"]
+        direction TB
+        lex["lex and parse<br/>every argument is an expression"]
+        ir["typed IR<br/>three-address ops over virtual registers"]
+        lex --> ir
+    end
+
+    subgraph seam["the two seams"]
+        direction TB
+        host["host builtin table<br/>name to Call or Inline<br/>the LED words live only here"]
+        back["per-ISA backend<br/>Xtensa · RISC-V · host<br/>a new CPU is a new file"]
+    end
+
+    native["native machine code<br/>in an allocExec block"]
+    tick["the render loop<br/>calls it through a function pointer"]
+
+    src --> lex
+    ir --> back
+    host -.->|"names and opcodes"| back
+    back --> native --> tick
+
+    classDef text fill:#2d3561,stroke:#7b88c9,color:#fff
+    classDef core fill:#1f4d3d,stroke:#5fb89a,color:#fff
+    classDef edge fill:#4d3d1f,stroke:#c9a95f,color:#fff
+    classDef out fill:#3d2d61,stroke:#a07bc9,color:#fff
+    class src text
+    class lex,ir core
+    class host,back edge
+    class native,tick out
+```
+
+The IR is the seam, and it is what keeps the three tiers from knowing about each other: it names operations, never an instruction set and never a domain. The front-end never branches on CPU, the core never learns an LED word, and the compiled result is called like any other function. Adding a CPU is a backend file; adding a domain function is a table entry.
+
 ## A native-codegen compiler
 
 MoonLive lets you author an effect (later: a layout, modifier, driver, or core rule) as **text** and run it on a running device, with no recompile-and-flash cycle. Its standout property is *how* it runs the script. It is a **native-codegen compiler** rather than a bytecode interpreter: source text is lexed, parsed, lowered to a typed IR, and assembled to real machine code. The render loop calls that through a plain function pointer, so a scripted effect runs at near-hand-written speed in the hot path. This is the core construct; a scripted effect (`MoonLiveEffect`) is the thin binding that gives it the MoonModule lifecycle.