docs: translate CLAUDE.md to English

Per the committed=English rule. Also documents the windowed-video idle-inhibit added in the same series.

CLAUDE.md

@@ -1,86 +1,94 @@
 # Moonarch
 
-Reproduzierbares Arch-Linux-Setup basierend auf archinstall + Post-Install-Automatisierung.
+Reproducible Arch Linux setup based on archinstall + post-install automation.
 
-## Projektstruktur
+## Project Structure
 
-- `config/` — archinstall-Konfiguration (inkl. custom-commands die das Repo nach /opt/moonarch klonen, root-owned)
+- `config/` — archinstall configuration (incl. custom-commands that clone the repo to /opt/moonarch, root-owned)
-- `scripts/` — Post-Install- und Helper-Scripts
+- `scripts/` — post-install and helper scripts
-- `packages/` — Paketlisten (offiziell + AUR), getrennt gepflegt
+- `packages/` — package lists (official + AUR), maintained separately
-- `defaults/` — XDG-Configs, Shell-Config, Helper-Binaries, systemd Services, udev-Regeln, greetd/moongreet-Config, Wallpaper
+- `defaults/` — XDG configs, shell config, helper binaries, systemd services, udev rules, greetd/moongreet config, wallpaper
 
 ## Battery Conservation Mode
 
-Laptops mit `charge_control_end_threshold`-Support (ThinkPad, Framework, etc.) erhalten einen Waybar-Toggle:
+Laptops with `charge_control_end_threshold` support (ThinkPad, Framework, etc.) get a Waybar toggle:
-- Klick auf das Battery-Modul schaltet zwischen 80% und 100% Ladegrenze um
+- Clicking the battery module toggles the charge limit between 80% and 100%
-- Bei aktiver Conservation erscheint ein ♥-Icon neben der Battery-Anzeige
+- When conservation is active, a ♥ icon appears next to the battery indicator
-- Zustand wird in `/var/lib/moonarch/batsaver-threshold` persistiert und beim Boot via systemd-Service (`moonarch-batsaver-restore`) wiederhergestellt
+- State is persisted in `/var/lib/moonarch/batsaver-threshold` and restored on boot via a systemd service (`moonarch-batsaver-restore`)
-- Toggle-Flow: `moonarch-batsaver-toggle` (User-Script) liest sysfs, entscheidet 80↔100, ruft `pkexec /usr/bin/moonarch-batsaver-apply $NEW` für den privilegierten sysfs+state-Schreibschritt. Standard-pkexec-Prompt (Passwort einmal pro Session-Cache)
+- Toggle flow: `moonarch-batsaver-toggle` (user script) reads sysfs, decides 80↔100, calls `pkexec /usr/bin/moonarch-batsaver-apply $NEW` for the privileged sysfs+state write step. Standard pkexec prompt (password once per session cache)
-- Auf Desktops ohne Battery-Support versteckt sich das Feature komplett
+- On desktops without battery support the feature is hidden entirely
 
-## Nightlight (Blaufilter)
+## Nightlight (Blue Light Filter)
 
-Waybar-Toggle für wlsunset (Wayland-nativer Blaufilter), persistenter Zustand via systemd:
+Waybar toggle for wlsunset (Wayland-native blue light filter), persistent state via systemd:
-- `wlsunset.service` (systemd User-Service) mit `After=kanshi.service` — startet erst wenn alle Outputs konfiguriert sind
+- `wlsunset.service` (systemd user service) with `After=kanshi.service` — starts only once all outputs are configured
-- **Default OFF** — frische Installs starten ohne Filter. PKGBUILD legt für `wlsunset` bewusst KEINEN Symlink in `/etc/systemd/user/graphical-session.target.wants/` an, post-install.sh enabled den Service nicht.
+- **Default OFF** — fresh installs start without the filter. The PKGBUILD deliberately creates NO symlink for `wlsunset` in `/etc/systemd/user/graphical-session.target.wants/`, and post-install.sh does not enable the service.
-- Klick auf das Nightlight-Modul in `group/brightness` toggled wlsunset an/aus (`enable --now` / `disable --now`)
+- Clicking the nightlight module in `group/brightness` toggles wlsunset on/off (`enable --now` / `disable --now`)
-- Zustand überlebt Reboots (User-Scope-Symlink in `~/.config/systemd/user/...wants/`)
+- State survives reboots (user-scope symlink in `~/.config/systemd/user/...wants/`)
-- Aktiver Zustand zeigt 󰌵 in Catppuccin Yellow, inaktiv 󰌶 in Standard-Textfarbe
+- Active state shows 󰌵 in Catppuccin Yellow, inactive 󰌶 in the default text color
-- Signal SIGRTMIN+11 für sofortiges Waybar-Refresh
+- Signal SIGRTMIN+11 for immediate Waybar refresh
-- Scripts: `moonarch-nightlight` (Toggle), `moonarch-waybar-nightlight` (Status-JSON)
+- Scripts: `moonarch-nightlight` (toggle), `moonarch-waybar-nightlight` (status JSON)
-- **Wichtig**: Auf gar keinen Fall einen Global-Scope-Symlink in `/etc/systemd/user/...wants/wlsunset.service` anlegen — der überstimmt jedes User-`disable` und macht den Filter de-facto unausschaltbar.
+- **Important**: Never create a global-scope symlink at `/etc/systemd/user/...wants/wlsunset.service` — it overrides any user `disable` and makes the filter effectively impossible to turn off.
 
 ## Waybar Config Merger (moonarch-waybar)
 
-Waybar wird über `moonarch-waybar` gestartet (nicht direkt). Der Wrapper merged eine optionale User-Config (`~/.config/waybar/userconfig`) mit der System-Config (`/etc/xdg/waybar/config`):
+Waybar is started via `moonarch-waybar` (not directly). The wrapper merges an optional user config (`~/.config/waybar/userconfig`) with the system config (`/etc/xdg/waybar/config`):
-- `prepend`/`append`-Keys in der userconfig erweitern `modules-left`/`modules-center`/`modules-right` Arrays
+- `prepend`/`append` keys in the userconfig extend the `modules-left`/`modules-center`/`modules-right` arrays
-- Alle anderen Top-Level-Keys werden als Modul-Definitionen per Object-Merge eingefügt
+- All other top-level keys are inserted as module definitions via object merge
-- Merge wird nur bei Änderungen ausgeführt (Timestamp-Vergleich)
+- The merge runs only on changes (timestamp comparison)
-- Bei Fehler: `notify-send` + `logger`, Waybar startet mit System-Config
+- On error: `notify-send` + `logger`, Waybar starts with the system config
-- Generiert `~/.config/waybar/style.css` mit `@import` der System-Styles falls nicht vorhanden
+- Generates `~/.config/waybar/style.css` with an `@import` of the system styles if not present
-- Benötigt `jq` (in PKGBUILD als Dependency)
+- Requires `jq` (declared as a dependency in the PKGBUILD)
-- System-Config muss valides JSON sein (kein JSONC)
+- The system config must be valid JSON (no JSONC)
 
 ## mpv + ModernZ OSC
 
-Videoplayer ist `mpv` mit [ModernZ](https://github.com/Samillion/ModernZ) als OSC, Thumbnails via thumbfast:
+The video player is `mpv` with [ModernZ](https://github.com/Samillion/ModernZ) as the OSC, thumbnails via thumbfast:
-- `mpv-modernz-git` liefert `modernz.lua` + Font + Default-Config nach `/etc/mpv/`
+- `mpv-modernz-git` provides `modernz.lua` + font + default config to `/etc/mpv/`
-- `mpv-thumbfast-git` liefert `thumbfast.lua` nach `/etc/mpv/scripts/` (wird von ModernZ automatisch erkannt)
+- `mpv-thumbfast-git` provides `thumbfast.lua` to `/etc/mpv/scripts/` (auto-detected by ModernZ)
-- `defaults/etc/mpv/mpv.conf` wird von moonarch-git direkt nach `/etc/mpv/mpv.conf` installiert (owned)
+- `defaults/etc/mpv/mpv.conf` is installed directly to `/etc/mpv/mpv.conf` by moonarch-git (owned)
-- Stock-OSC + Titelleiste deaktiviert, `autofit-larger=80%x80%` cappt übergroße Fenster
+- Stock OSC + title bar disabled, `autofit-larger=80%x80%` caps oversized windows
-- ModernZ-Overrides per `script-opts-append` in mpv.conf: Orange-Akzent → Catppuccin Lavender (`#b4befe`), OSC-Scale 0.75, `window_title_font_size=18`, `ontop_button=no`
+- ModernZ overrides via `script-opts-append` in mpv.conf: orange accent → Catppuccin Lavender (`#b4befe`), OSC scale 0.75, `window_title_font_size=18`, `ontop_button=no`
-- **Wichtig**: mpv behandelt `#` als Mid-Line-Kommentar; Hex-Farben müssen gequotet werden: `script-opts-append="modernz-seekbarfg_color=#b4befe"` (nicht `\#`, das escaped nur und verschluckt den Rest)
+- **Important**: mpv treats `#` as a mid-line comment; hex colors must be quoted: `script-opts-append="modernz-seekbarfg_color=#b4befe"` (not `\#`, which only escapes and swallows the rest)
-- Niri öffnet mpv floating (`window-rule` in `defaults/xdg/niri/config.kdl`)
+- Niri opens mpv floating (`window-rule` in `defaults/xdg/niri/config.kdl`)
 
 ## System Health Check (moonarch-doctor / moondoc)
 
-Diagnose-Script das den Systemzustand gegen moonarch-Defaults prüft:
+Diagnostic script that checks the system state against moonarch defaults:
-- Pakete (official.txt + aur.txt installiert? Orphans?)
+- Packages (official.txt + aur.txt installed? Orphans?)
-- System-Services (NetworkManager, bluetooth, greetd, ufw, auto-cpufreq, etc.)
+- System services (NetworkManager, bluetooth, greetd, ufw, auto-cpufreq, etc.)
-- User-Services (kanshi, wlsunset, stasis, walker, nautilus, cliphist-text, cliphist-image)
+- User services (kanshi, wlsunset, stasis, walker, nautilus, cliphist-text, cliphist-image)
-- Config-Dateien (SHA256-Vergleich deployed vs. moonarch-Default)
+- Config files (SHA256 comparison deployed vs. moonarch default)
-- Helper-Scripts + Symlinks (moonup, moondoc)
+- Helper scripts + symlinks (moonup, moondoc)
-- System-Config (UFW, Pacman/Paru Repos, Default Shell)
+- System config (UFW, pacman/paru repos, default shell)
-- Verzeichnisse + Permissions
+- Directories + permissions
 
 ## Fontconfig Defaults
 
-Systemweite generic-family Defaults via `defaults/etc/fonts/conf.d/65-moonarch-fonts.conf` (owned by moonarch-git):
+System-wide generic-family defaults via `defaults/etc/fonts/conf.d/65-moonarch-fonts.conf` (owned by moonarch-git):
 - `sans-serif` → UbuntuSans Nerd Font, `monospace` → UbuntuSansMono Nerd Font
-- Nummer **65**: lädt nach `60-latin.conf`, sodass die moonarch-Prefs den Stock-Default (Noto/DejaVu) schlagen. `local.conf` (bei 51 via `51-local.conf`) lädt zu früh und wird von 60-latin überstimmt — daher **nicht** verwenden (außerdem für lokale User-Overrides reserviert).
+- Number **65**: loads after `60-latin.conf`, so the moonarch prefs beat the stock default (Noto/DejaVu). `local.conf` (at 51 via `51-local.conf`) loads too early and is overridden by 60-latin — therefore **do not** use it (it is also reserved for local user overrides).
-- Aliases brauchen `binding="strong"` — ein weak `<prefer>` (fontconfig-Default) rankt hinter dem effektiven generischen Fallback und greift nicht.
+- Aliases need `binding="strong"` — a weak `<prefer>` (fontconfig default) ranks behind the effective generic fallback and does not take effect.
-- Greift nur für Apps die generische Familien nutzen (z.B. Firefox-Web-Fallback). moonarch-Apps (Waybar, foot, GTK, walker, swaync) setzen den Font explizit.
+- Only applies to apps that use generic families (e.g. Firefox web fallback). moonarch apps (Waybar, foot, GTK, walker, swaync) set the font explicitly.
 
 ## Browser Idle-Inhibit (xdg-desktop-portal)
 
-Damit Fenster-Browservideo (Firefox/Waterfox) den Screen wachhält, via `defaults/etc/xdg-desktop-portal/niri-portals.conf` (owned by moonarch-git, höhere Priorität als niris `/usr/share/xdg-desktop-portal/niri-portals.conf`):
+So that windowed browser video (Firefox/Waterfox) keeps the screen awake, via `defaults/etc/xdg-desktop-portal/niri-portals.conf` (owned by moonarch-git, higher priority than niri's `/usr/share/xdg-desktop-portal/niri-portals.conf`):
-- `xdg-desktop-portal-gtk` meldet das `Inhibit`-Interface als success, obwohl es unter Niri niemand implementiert → Firefox glaubt, der Idle-Inhibit lief über den Portal, und nutzt den nativen Wayland-`idle-inhibit` nicht. Ergebnis: kein Inhibitor, Screen schläft.
+- `xdg-desktop-portal-gtk` reports the `Inhibit` interface as success even though nobody implements it under Niri → Firefox believes the idle-inhibit went through the portal and does not use the native Wayland `idle-inhibit`. Result: no inhibitor, screen sleeps.
-- Fix: `org.freedesktop.impl.portal.Inhibit=none` → Firefox fällt auf `zwp_idle_inhibit` zurück, den Niri honoriert. Die übrigen `[preferred]`-Zeilen sind 1:1 von niris Default übernommen (portals.conf wird nicht gemerged — die höchstpriore Datei gilt komplett).
+- Fix: `org.freedesktop.impl.portal.Inhibit=none` → Firefox falls back to `zwp_idle_inhibit`, which Niri honors. The remaining `[preferred]` lines are taken 1:1 from niri's default (portals.conf is not merged — the highest-priority file applies in full).
-- stasis ist hier unbeteiligt: `monitor_media` (pactl) erfasst Browser-Audio per Design nicht (nur Non-Browser-Player); Browser laufen über den Inhibit-Pfad.
+- stasis is uninvolved here: `monitor_media` (pactl) does not capture browser audio by design (non-browser players only); browsers go through the inhibit path.
-- **Aktivierung:** xdg-desktop-portal + Browser neu starten — Firefox fragt den Portal-Support beim Start ab.
+- **Activation:** restart xdg-desktop-portal + the browser — Firefox queries portal support at startup.
 
-## Konventionen
+### Windowed / Muted Video: wayland-pipewire-idle-inhibit
 
-- Paketlisten sind einfache Textdateien, ein Paket pro Zeile, Kommentare mit `#`
+The portal fix only applies to **fullscreen** video — Firefox/Waterfox send the idle-inhibit only in fullscreen. Windowed video remains unprotected: stasis ignores browser audio (pactl, browser-excluded, no MPRIS backend), Niri gets no inhibitor, the screen sleeps mid-video.
-- Shell-Scripts müssen POSIX-kompatibel oder explizit bash/zsh sein
+
-- Alle Pfade im archinstall-Config relativ zum Installationsziel
+Solution: `wayland-pipewire-idle-inhibit` (AUR, systemd user service; in `packages/aur.txt` + `post-install.sh` USER_SERVICES + moonarch-doctor). Holds a Wayland `zwp_idle_inhibit` inhibitor while PipeWire outputs audio (default threshold 5s). Niri then suppresses idle → stasis stays awake, daemon-independent. Releases automatically when audio stops.
+- Catches windowed video **with sound**. Misses muted video (no audio signal) — edge case, accepted.
+- **Never** put `waterfox`/a browser in stasis `inhibit_apps`: that inhibits unconditionally as long as the browser process runs → the system never idles. This exact wrong fix caused the "no idle" bug.
+
+## Conventions
+
+- Package lists are plain text files, one package per line, comments with `#`
+- Shell scripts must be POSIX-compatible or explicitly bash/zsh
+- All paths in the archinstall config are relative to the install target