agent: dev launcher — own Linux env-var contract, add dev:tauri, doc sweep

The 2026-05-12 engine-slop pass removed runtime std::env::set_var mutation from src-tauri/src/lib.rs and replaced it with warn_if_x11_env_unset_on_wayland. With no launcher owning the contract, Linux Wayland dogfood was about to regress.

run.sh:
- now owns Linux launcher env defaults via case "$(uname -s)"
  LIBCLANG_PATH=/usr/lib64/llvm21/lib64 (user-set wins)
  WEBKIT_DISABLE_DMABUF_RENDERER=1 (always on Linux; user-set wins)
  GDK_BACKEND=x11, WINIT_UNIX_BACKEND=x11 (Wayland only; user-set wins)
- 60s Vite readiness timeout
- detects early Vite exit (kill -0 + wait) instead of hanging forever
- trap installed before wait so Ctrl-C cleans up
- args forwarded: ./run.sh --release etc.
- non-exec final Tauri launch preserved so cleanup trap fires

package.json:
- "dev:tauri": "./run.sh" — canonical discoverable dev command

Docs:
- README, dev-setup, architecture-map runtime + launcher pages updated with the new contract; canonical command is npm run dev:tauri (./run.sh as direct equivalent)
- dev-launcher-and-scripts.md replaces the incorrect "kills process group" claim with honest "kills the spawned npm process"
- dev-setup.md path /CORBEL-Projects/magnotia → /CORBEL-Projects/transcription-app
- gpu-tuning/plan.md gets a superseded note rather than rewriting the original rationale
- engine-slop-residuals.md gains Area F (packaged-binary launcher contract) with honest wrapper-vs-.desktop trade-off documented

Verification: bash -n run.sh; shellcheck clean; cargo check -p magnotia green; npm pkg get 'scripts.dev:tauri' returns "./run.sh"; stale-ref sweep clean across living docs.

docs/dev-setup.md

@@ -7,7 +7,7 @@ description: Authoritative build dependencies and launch instructions for Magnot
 
 # Magnotia — Developer Setup
 
-Last updated: 2026/04/18. Primary dev target: Fedora 43, x86_64, KDE Wayland, NVIDIA RTX 4070.
+Last updated: 2026/05/12. Primary dev target: Fedora Linux, x86_64, KDE Wayland, NVIDIA RTX 4070.
 
 ---
 
@@ -24,16 +24,18 @@ sudo dnf install cmake clang-devel
 | `cmake` | whisper-rs-sys build system |
 | `clang-devel` | bindgen header generation for whisper-rs-sys |
 
-**Fedora-specific:** `libclang.so` lives in `/usr/lib64/llvm21/lib64/`, not on the standard search path. Set permanently:
+**Fedora-specific:** `libclang.so` lives in `/usr/lib64/llvm21/lib64/`, not on the standard search path. The dev launcher defaults `LIBCLANG_PATH` to that path on Linux, but a value you set in your shell wins.
+
+To set it permanently in fish:
 
 ```bash
 set -Ux LIBCLANG_PATH /usr/lib64/llvm21/lib64
 ```
 
-Or prefix every build command:
+Or prefix one command if you are bypassing the launcher:
 
 ```bash
-LIBCLANG_PATH=/usr/lib64/llvm21/lib64 npm run tauri dev
+LIBCLANG_PATH=/usr/lib64/llvm21/lib64 cargo check -p magnotia
 ```
 
 ### Required (Vulkan GPU build)
@@ -66,15 +68,34 @@ Rust toolchain managed by `rustup`. No extra steps needed beyond what Tauri requ
 
 ### CPU build (default)
 
+Canonical dev launch:
+
 ```bash
-cd /home/jake/Documents/CORBEL-Projects/magnotia
-LIBCLANG_PATH=/usr/lib64/llvm21/lib64 npm run tauri dev
+cd /home/jake/Documents/CORBEL-Projects/transcription-app
+npm run dev:tauri
 ```
 
-Once `set -Ux LIBCLANG_PATH` is in fish config, this becomes:
+Direct shell equivalent:
 
 ```bash
-npm run tauri dev
+./run.sh
+```
+
+`run.sh` starts Vite, waits for port 1420, then launches Tauri with its `beforeDevCommand` disabled so a second Vite instance does not race the first one.
+
+On Linux, `run.sh` also owns the rendering environment contract expected by `src-tauri/src/lib.rs::warn_if_x11_env_unset_on_wayland`:
+
+- `WEBKIT_DISABLE_DMABUF_RENDERER=1` by default on Linux. Set `WEBKIT_DISABLE_DMABUF_RENDERER=0` explicitly to opt out.
+- `GDK_BACKEND=x11` and `WINIT_UNIX_BACKEND=x11` by default only when `XDG_SESSION_TYPE=wayland`.
+- Any value already set in your shell wins because the launcher uses shell defaults (`${VAR:-default}`).
+
+If you prefer shell-rc setup, these manual exports are equivalent on a Wayland session:
+
+```bash
+export WEBKIT_DISABLE_DMABUF_RENDERER="${WEBKIT_DISABLE_DMABUF_RENDERER:-1}"
+export GDK_BACKEND="${GDK_BACKEND:-x11}"
+export WINIT_UNIX_BACKEND="${WINIT_UNIX_BACKEND:-x11}"
+npm run dev:tauri
 ```
 
 ### Vulkan GPU build
@@ -97,16 +118,21 @@ whisper_backend_init_gpu: device 0: CPU (type: 0)             ← no GPU
 
 ## Startup log reference
 
-Normal startup sequence:
+Normal Rust startup logs now come through `tracing` rather than raw `eprintln!`, so the exact timestamp/format depends on `RUST_LOG` and the subscriber formatter. Typical messages include:
 
 ```
-[startup] Wayland workaround: GDK_BACKEND=x11
-[startup] DB init: ~4ms
-[startup] Preferences load: ~200µs
-[startup] Whisper model pre-warmed successfully
+INFO magnotia_startup: DB init complete elapsed_ms=4
+INFO magnotia_startup: preferences load complete elapsed_ms=0
+WARN magnotia_startup: Linux WebKitGTK microphone permission requests are auto-granted for audio-only capture; other permission classes remain denied
 ```
 
-The Wayland workarounds are injected automatically by `ensure_x11_on_wayland()` in `src-tauri/src/lib.rs` — no manual env-var prefix needed.
+When launched through `npm run dev:tauri` / `./run.sh`, you should not see `magnotia_startup` warnings containing:
+
+```
+Linux rendering workaround env var is not set
+```
+
+Those warnings mean the launcher contract was bypassed or broken.
 
 ---
 
@@ -114,7 +140,7 @@ The Wayland workarounds are injected automatically by `ensure_x11_on_wayland()`
 
 | Issue | Cause | Fix |
 |---|---|---|
-| `Unable to find libclang` | Fedora puts clang libs in versioned path | `set -Ux LIBCLANG_PATH /usr/lib64/llvm21/lib64` |
+| `Unable to find libclang` | Fedora puts clang libs in versioned path | Use `npm run dev:tauri` / `./run.sh`, or set `LIBCLANG_PATH=/usr/lib64/llvm21/lib64` |
 | `Could NOT find Vulkan (missing: glslc)` | Shader compiler not installed | `sudo dnf install vulkan-headers vulkan-loader-devel glslc` |
 | `there is no reactor running` | `tokio::spawn` called before runtime starts in `setup()` | Use `tauri::async_runtime::spawn` instead |
 | `effect_update_depth_exceeded` | Svelte 5 `$state` object reassigned instead of mutated | Use `Object.assign(state, updates)` — never spread-replace module-level state |