docs: add "Working on Nomarchy" orientation guide

A short, task-indexed guide for navigating the repo: the core/features/themes
mental model, the two app-config namespaces, the four script locations (incl.
themes/engine/scripts/), the build/test loop, how theming works, and a
Walker+elephant deep-dive covering the dmenu vs custom-provider menu paths.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.gitea/workflows/check.yml

@@ -0,0 +1,190 @@
+# Nomarchy CI — eval + lint.
+#
+# Catches the regressions that hurt today:
+#   1. Flake stops evaluating (broken option ref, missing import, etc.).
+#      Checked per-output rather than via `nix flake check` so we can skip
+#      packages.allThemeVariants — the 22-generation linkFarm that OOMs the
+#      runner; every palette is validated one-at-a-time by the matrix (4).
+#   2. A `nomarchy-*` shell script has a syntax error or a shellcheck
+#      error-severity issue.
+#   3. `docs/SCRIPTS.md` drifts from the repo state because somebody
+#      added / removed / renamed a script and didn't run the generator
+#      (the pre-commit hook handles this, but only when enabled per-clone).
+#   4. An opt-in nomarchy.* toggle stops evaluating. `nix flake check`
+#      only evaluates the four default configs, so a bug that only fires
+#      when a toggle is flipped sails through (e.g. the impermanence
+#      systemd-stage-1 assertion). nomarchy-eval-matrix layers each toggle
+#      onto the default config and forces system.build.toplevel.
+#
+# Doesn't build ISOs — that needs a binary cache. Add a separate job
+# once Cachix/Attic is in place.
+
+name: Check
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  eval-and-lint:
+    runs-on: ubuntu-latest
+    # Flakes for every `nix` invocation in the job (the bare `nix flake
+    # check` below relies on this; the scripts pass the flag themselves).
+    # sandbox=false because Stylix/base16.nix do import-from-derivation —
+    # eval realizes fetched `-source` paths mid-check, and the single-user
+    # Nix in this container can't set up the build sandbox (no user
+    # namespaces), which otherwise surfaces as "path '…-source' is not
+    # valid". NIX_SSL_CERT_FILE because we add nix to PATH without sourcing
+    # the installer's profile (which is what normally exports it).
+    env:
+      NIX_CONFIG: |
+        experimental-features = nix-command flakes
+        sandbox = false
+      NIX_SSL_CERT_FILE: /etc/ssl/certs/ca-certificates.crt
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install Nix
+        # Plain shell install rather than a JS action: act_runner's bundled
+        # `act` only supports up to node20, and nix-installer-action@main
+        # moved to node24 ("runs.using ... got node24"). A run step has no
+        # node-runtime coupling. Single-user (--no-daemon) needs no systemd,
+        # which the catthehacker container doesn't run as PID 1.
+        #
+        # The installer runs as root here and honours build-users-group=
+        # nixbld from its bundled nix.conf, aborting unless that group exists
+        # AND has members. Create the nixbld group + build users (what a
+        # multi-user install does) before running it.
+        #
+        # Pin the Nix version: the latest (2.34) uses lazy-trees / a git
+        # cache that doesn't materialise flake-input `-source` paths into
+        # the store, so Stylix's import-from-derivation reads fail with
+        # "path '…-source' is not valid". 2.31.5 matches the Nix that wrote
+        # flake.lock locally and evaluates the flake cleanly.
+        run: |
+          NIX_VERSION=2.31.5
+          groupadd -r nixbld 2>/dev/null || true
+          for i in $(seq 1 10); do
+            useradd -r -g nixbld -G nixbld -d /var/empty \
+              -s /usr/sbin/nologin -c "Nix build user $i" "nixbld$i" 2>/dev/null || true
+          done
+          curl -L "https://releases.nixos.org/nix/nix-${NIX_VERSION}/install" | sh -s -- --no-daemon
+          echo "$HOME/.nix-profile/bin" >> "$GITHUB_PATH"
+
+      - name: Materialize flake-input sources for eval
+        # Walker's flake reads its own source tree during evaluation:
+        # importTOML resources/config.toml in its home-manager module and
+        # lib.fileset.toSource for the package src (cargoLock.lockFile =
+        # "${src}/Cargo.lock"). On a cold store the input source isn't
+        # materialised, so flake check / eval die with "path '…-source' is
+        # not valid" (works locally only because prior builds materialised
+        # it; `nix flake archive` reports the input but doesn't make the
+        # fileset-derived src readable). `nix build` of walker's src
+        # eagerly realises it — and the input it reads from — priming the
+        # store so the later eval steps find every path valid.
+        run: |
+          nix build --no-link --impure --expr 'let f = builtins.getFlake (toString ./.); in f.inputs.walker.packages.${builtins.currentSystem}.default.src'
+
+      - name: Check flake outputs (except the 22-variant pre-cache package)
+        # Stand-in for `nix flake check --no-build`. That also evaluates
+        # packages.allThemeVariants — a linkFarm whose drvPath forces all 22
+        # home generations into memory at once, OOM-killing the runner. The
+        # eval matrix below already validates every palette one-at-a-time, so
+        # that package's CI value is near-zero. Here we force every other
+        # output (all 4 system closures incl. assertions, both standalone
+        # home generations, the installer VM package, the overlay, the app)
+        # and skip only allThemeVariants/default. Each tryEval is GC'd before
+        # the next, so peak memory is one config, not twenty-two.
+        run: |
+          nix eval --impure --raw --expr 'let
+            f = builtins.getFlake (toString ./.);
+            lib = f.inputs.nixpkgs.lib;
+            sys = "x86_64-linux";
+            ok = x: (builtins.tryEval (builtins.seq x true)).success;
+            checks = {
+              "nixos.default"            = ok f.nixosConfigurations.default.config.system.build.toplevel.drvPath;
+              "nixos.nomarchy-installer" = ok f.nixosConfigurations.nomarchy-installer.config.system.build.toplevel.drvPath;
+              "nixos.installerVm"        = ok f.nixosConfigurations.installerVm.config.system.build.toplevel.drvPath;
+              "nixos.nomarchy-live"      = ok f.nixosConfigurations.nomarchy-live.config.system.build.toplevel.drvPath;
+              "home.nomarchy"            = ok f.homeConfigurations.nomarchy.activationPackage.drvPath;
+              "home.nixos"               = ok f.homeConfigurations.nixos.activationPackage.drvPath;
+              "packages.installerVm"     = ok f.packages.${sys}.installerVm.drvPath;
+              "overlays.default"         = ok (builtins.isFunction f.overlays.default);
+              "apps.installerVm"         = ok f.apps.${sys}.installerVm.program;
+            };
+            failed = builtins.attrNames (lib.filterAttrs (_: v: !v) checks);
+          in if failed == [] then "ALL OK"
+             else throw ("flake-output checks failed: " + builtins.concatStringsSep ", " failed)'
+
+      - name: Evaluate opt-in toggle / palette / home matrix
+        # flake check never flips a nomarchy.* toggle; this does. jq is
+        # provided via nix shell so the step doesn't depend on the runner
+        # image preinstalling it.
+        run: nix shell nixpkgs#jq --command ./bin/utils/nomarchy-eval-matrix
+
+      - name: Lint nomarchy-* scripts (bash -n + shellcheck)
+        run: |
+          # Mirror what .githooks/pre-commit runs locally, but across the
+          # whole tree instead of just changed files. Pre-commit gates
+          # individual commits; CI gates branches (including --no-verify
+          # bypasses).
+          set -e
+          fail=0
+          while IFS= read -r script; do
+            [[ -f "$script" ]] || continue
+            # Python helpers ship under the same nomarchy- prefix
+            # (e.g. nomarchy-haptic-touchpad). Skip non-bash.
+            head -1 "$script" | grep -qE '^#!.*\bbash\b' || continue
+            if ! bash -n "$script"; then
+              echo "::error file=$script::bash syntax error"
+              fail=1
+            fi
+            if ! nix shell nixpkgs#shellcheck --command shellcheck \
+                  --severity=error --shell=bash "$script"; then
+              echo "::error file=$script::shellcheck error-severity issue"
+              fail=1
+            fi
+          done < <(find features/scripts/utils core/system/scripts \
+                        themes/engine/scripts \
+                        -maxdepth 1 -type f -name 'nomarchy-*')
+          exit "$fail"
+
+      - name: docs/SCRIPTS.md is up to date
+        run: |
+          # Regenerate to a temp file and compare. If different, the
+          # contributor forgot to run the generator (or skipped the
+          # pre-commit hook). Fail loudly and tell them the fix.
+          ./bin/utils/nomarchy-docs-scripts --out /tmp/SCRIPTS.regen.md
+          if ! diff -q docs/SCRIPTS.md /tmp/SCRIPTS.regen.md >/dev/null; then
+            echo "::error::docs/SCRIPTS.md is stale."
+            echo "Run: ./bin/utils/nomarchy-docs-scripts --out docs/SCRIPTS.md"
+            echo "Then commit the regenerated file."
+            echo "--- diff ---"
+            diff -u docs/SCRIPTS.md /tmp/SCRIPTS.regen.md || true
+            exit 1
+          fi
+
+      - name: installer/hardware-db.sh references real nixos-hardware modules
+        run: |
+          # Every 4th-pipe-field in HARDWARE_DB is a nixos-hardware module
+          # name. Half the DB used to point at modules that don't exist
+          # (e.g. microsoft-surface-pro-8 — there's only -pro-intel and
+          # -pro-9), which made the install fail at eval time with
+          # cryptic "attribute not found" errors on real laptops. This
+          # step catches that regression class.
+          awk -F'|' '/^  "/ { gsub(/"/,"",$4); gsub(/^[[:space:]]+|[[:space:]]+$/,"",$4); if ($4) print $4 }' \
+            installer/hardware-db.sh | sort -u > /tmp/db-refs.txt
+          nix eval --impure --json --expr '
+            let
+              nh = (builtins.getFlake (toString ./.)).inputs.nixos-hardware.nixosModules;
+            in builtins.attrNames nh' \
+            | nix shell nixpkgs#jq --command jq -r '.[]' | sort -u > /tmp/db-real.txt
+          missing=$(comm -23 /tmp/db-refs.txt /tmp/db-real.txt)
+          if [[ -n "$missing" ]]; then
+            echo "::error::hardware-db.sh references nixos-hardware modules that don't exist:"
+            printf '  - %s\n' $missing
+            echo "Either fix the name (check the actual attr in nixos-hardware) or drop the row."
+            exit 1
+          fi

.githooks/pre-commit

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# Nomarchy pre-commit hook.
+#
+# Enable per-clone with:
+#   git config core.hooksPath .githooks
+#
+# Two responsibilities:
+#  1. Lint changed nomarchy-* scripts (bash -n + shellcheck if available)
+#     so syntax errors and unquoted-var bugs don't ship.
+#  2. Regenerate docs/SCRIPTS.md when any nomarchy-* script under the three
+#     script directories is added, modified, or deleted in this commit, and
+#     stage the refreshed file so it lands with the change.
+
+set -e
+
+repo_root="$(git rev-parse --show-toplevel)"
+cd "$repo_root"
+
+script_dirs_re='^(features/scripts/utils|core/system/scripts|themes/engine/scripts)/nomarchy-'
+
+# 1. Lint changed scripts. bash -n catches syntax errors (always fatal).
+# shellcheck catches unquoted-var, use-before-define, missing-shebang, etc.
+# We only fail on severity=error so the long tail of pre-existing warnings
+# (info / style / warning) doesn't block commits — those can be cleaned up
+# incrementally without a flag day.
+changed_scripts=$(git diff --cached --name-only --diff-filter=ACMR \
+                  | grep -E "$script_dirs_re" || true)
+if [[ -n "$changed_scripts" ]]; then
+  while IFS= read -r script; do
+    [[ -f "$script" ]] || continue
+    # Only lint scripts with a bash shebang. nomarchy-* is a name
+    # convention, not a language guarantee — at least one Python helper
+    # ships under the same prefix (nomarchy-haptic-touchpad).
+    head -1 "$script" | grep -qE '^#!.*\bbash\b' || continue
+    if ! bash -n "$script"; then
+      echo "pre-commit: bash syntax error in $script — aborting commit." >&2
+      exit 1
+    fi
+    if command -v shellcheck >/dev/null 2>&1; then
+      if ! shellcheck --severity=error --shell=bash "$script"; then
+        echo "pre-commit: shellcheck found error-level issues in $script — aborting commit." >&2
+        echo "pre-commit: fix the reported issues, or rerun with --no-verify after a deliberate decision to ship." >&2
+        exit 1
+      fi
+    fi
+  done <<< "$changed_scripts"
+fi
+
+# 2. Regenerate the script audit doc.
+if git diff --cached --name-only --diff-filter=ACMRD | grep -qE "$script_dirs_re"; then
+  echo "pre-commit: regenerating docs/SCRIPTS.md (script change detected)…"
+  ./bin/utils/nomarchy-docs-scripts --out docs/SCRIPTS.md
+  git add docs/SCRIPTS.md
+fi

README.md

@@ -1,6 +1,6 @@
 # 👑 Nomarchy
 
-**Nomarchy** is a professional-grade NixOS distribution that replicates the Omarchy Wayland workflow with a strictly declarative, flake-based architecture. It provides a highly polished, "it just works" experience for power users who want a beautiful Hyprland environment without sacrificing the reliability of NixOS.
+**Nomarchy** is a professional-grade NixOS distribution that ships a highly curated Hyprland desktop on a strictly declarative, flake-based foundation. It provides a highly polished, "it just works" experience for power users who want a beautiful Wayland environment without sacrificing the reliability of NixOS.
 
 ## ✨ Key Features
 
@@ -40,7 +40,8 @@ This builds a full graphical VM of the installer environment. Once inside, click
 ### 2. Build the Installer ISO
 To install on physical hardware, generate your own bootable image:
 ```bash
-nix build .#nixosConfigurations.installerIso.config.system.build.isoImage
+./features/scripts/utils/nomarchy-build-iso       # Minimal TTY installer
+./features/scripts/utils/nomarchy-build-live-iso  # Graphical try-before-install
 ```
 The ISO will be located at `./result/iso/nixos-*.iso`. Flash it to a USB drive and boot.
 
@@ -83,7 +84,7 @@ Add user-level packages, aliases, and dotfiles here.
 nomarchy.home.terminal = "kitty";
 ```
 
-For the full list of `nomarchy.*` options you can set in `system.nix` and `home.nix`, see the [Options Reference](docs/OPTIONS.md). For where the project is heading next, see the [Roadmap](docs/ROADMAP.md).
+For the full list of `nomarchy.*` options you can set in `system.nix` and `home.nix`, see the [Options Reference](docs/OPTIONS.md). For custom automation, see [Runtime Hooks](docs/HOOKS.md). Hit a rebuild error? Check [Troubleshooting](docs/TROUBLESHOOTING.md). For where the project is heading next, see the [Roadmap](docs/ROADMAP.md).
 
 ### Applying Changes
 After editing your files, apply them instantly. **IMPORTANT:** Nomarchy requires the `--impure` flag for evaluation. You **MUST** use the following aliases rather than standard NixOS commands:
@@ -114,4 +115,4 @@ Nomarchy includes dozens of productivity scripts available in your PATH. Some hi
 - `nomarchy-menu`: The central hub for all utilities and pickers.
 
 ---
-*Built with ❤️ using NixOS, Hyprland, Stylix, and the spirit of Omarchy.*
+*Built with ❤️ using NixOS, Hyprland, Stylix, and the Nomarchy Community.*

bin/utils/nomarchy-docs-keybindings

@@ -15,8 +15,7 @@ repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
 
 sources=(
   "core/home/config/nomarchy/default/hypr/bindings/utilities.conf|Utilities"
-  "core/home/config/nomarchy/default/hypr/bindings/tiling.conf|Tiling"
-  "core/home/config/nomarchy/default/hypr/bindings/tiling-v2.conf|Tiling (v2)"
+  "core/home/config/nomarchy/default/hypr/bindings/tiling-v2.conf|Tiling"
   "core/home/config/nomarchy/default/hypr/bindings/clipboard.conf|Clipboard"
   "core/home/config/nomarchy/default/hypr/bindings/media.conf|Media keys"
   "features/desktop/hyprland/config/bindings.conf|Apps & web shortcuts"

bin/utils/nomarchy-docs-scripts

@@ -3,6 +3,12 @@
 # pipefail and -e off; -u stays.
 set -u
 
+# Deterministic collation regardless of the caller's locale. Without this
+# `sort` orders rows and caller lists by the ambient LC_COLLATE (UTF-8 on a
+# dev box, C in the CI container), so the committed doc and CI's regenerated
+# copy disagree on ordering and the drift check fails on pure noise.
+export LC_ALL=C
+
 # nomarchy-docs-scripts
 #
 # Regenerates docs/SCRIPTS.md from the repo state. Produces:
@@ -50,10 +56,13 @@ done
 # their own caller.)
 # File types we search for references. *.md catches docs and README;
 # branding/hook/extension files have varied or no extensions.
+# *.lua catches elephant providers; *.ini catches mako on-button-* hooks;
+# *.desktop catches MimeType-registered URL handlers.
 grep_includes=(
   --include='*.nix' --include='*.conf' --include='*.sh' --include='*.md'
-  --include='nomarchy-*' --include='*.jsonc' --include='*.toml'
-  --include='*.txt' --include='*.sample'
+  --include='nomarchy-*' --include='*.jsonc' --include='*.json'
+  --include='*.toml' --include='*.ini' --include='*.lua'
+  --include='*.desktop' --include='*.txt' --include='*.sample'
 )
 search_dirs=(core features themes installer hosts bin lib README.md)
 
@@ -75,9 +84,43 @@ ref_files_per_cmd() {
 }
 
 # All distinct nomarchy-* tokens we see anywhere in the repo.
-all_refs=$(grep -rohE 'nomarchy-[a-z0-9][a-z0-9-]+' \
+# Final char must be alphanumeric — dropping trailing-dash matches like
+# `nomarchy-pkg-` that come from glob references (`for c in nomarchy-pkg-*`).
+# Restrict to grep_includes so binaries / tmpfiles don't pollute the set.
+# The first `grep -vE` drops lines where `nomarchy-*` is a derivation /
+# tmp file / sudoers basename / systemd unit / flake output / docker
+# container identifier rather than a shell invocation.
+# The second `grep -vE` is a token-level safety net for prefix-only
+# tokens left over from wildcards/expansions (e.g. `nomarchy-pkg-*`).
+all_refs=$(grep -rhE 'nomarchy-[a-z0-9]([a-z0-9-]*[a-z0-9])?' \
+            "${grep_includes[@]}" \
             "${search_dirs[@]}" 2>/dev/null \
+          | grep -vE \
+              -e '(pname|name)[[:space:]]*=[[:space:]]*"nomarchy-' \
+              -e '/tmp/nomarchy-' \
+              -e '/etc/sudoers\.d/[^"[:space:]]*nomarchy-' \
+              -e 'nixosConfigurations\.nomarchy-' \
+              -e 'packages\.[^.]+\.nomarchy-' \
+              -e '\./result/bin/run-nomarchy-' \
+              -e 'mktemp[[:space:]]+[^|]*-t[[:space:]]+nomarchy-' \
+              -e '(TIMER_NAME|NOPASSWD_FILE|UNIT_NAME)=.*nomarchy-' \
+              -e '\.services\.nomarchy-' \
+              -e 'docker[[:space:]]+[^|]*nomarchy-' \
+          | grep -oE 'nomarchy-[a-z0-9]([a-z0-9-]*[a-z0-9])?' \
+          | grep -vE '^(nomarchy-launch|nomarchy-brightness|nomarchy-cmd|nomarchy-pkg|nomarchy-restart|nomarchy-toggle|nomarchy-theme|nomarchy-webapp-handler|nomarchy-font-selector|nomarchy-theme-selector|nomarchy-wallpaper-selector|nomarchy-setup|nomarchy-refresh|nomarchy-scripts|nomarchy-system-scripts|nomarchy-theme-engine-scripts)$' \
+          | grep -vE '^(nomarchy-plymouth|nomarchy-sddm-theme|nomarchy-live|nomarchy-rev|nomarchy-windows)$' \
+          | grep -vE '^(nomarchy-eval-matrix|nomarchy-docs-scripts|nomarchy-docs-keybindings)$' \
           | sort -u)
+# The second denylist covers identifiers whose ambiguity survives the line
+# filter: `nomarchy-plymouth` / `nomarchy-sddm-theme` are Nix derivation
+# names referenced as bare idents in `[...]` lists, `nomarchy-live` is an
+# ISO label that shows up in comments, `nomarchy-rev` is `/etc/nomarchy-rev`
+# (written by the ISO), and `nomarchy-windows` is a docker container name
+# in compose heredocs.
+# The third denylist: `nomarchy-eval-matrix`, `nomarchy-docs-scripts` (this
+# generator), and `nomarchy-docs-keybindings` are bin/utils repo tools that
+# name themselves in their own headers / AGENT.md — not user-facing scripts
+# that ship in nomarchy-system-scripts.
 
 # --- Render: header --------------------------------------------------------
 

bin/utils/nomarchy-eval-matrix

@@ -0,0 +1,149 @@
+#!/usr/bin/env bash
+# nomarchy-eval-matrix
+#
+# Evaluates the opt-in nomarchy.* surface that the per-output flake check
+# never touches. flake check only evaluates the default configs, so a bug
+# that only fires when a toggle is flipped — a renamed option, a failed
+# assertion, a stale reference — sails straight through. Two such bugs
+# shipped to main before this existed (the vscode option rename and the
+# impermanence systemd-stage-1 assertion); both would have been caught
+# here.
+#
+# Cost matters: this runs in CI on a small self-hosted runner, and the
+# first cut (one full `extendModules` eval per individual toggle, plus one
+# per palette) did ~39 whole-system evaluations and ran ~3h. So:
+#
+#   * Compatible toggles are COMBINED into a few configs (a failure means
+#     re-run the offending toggle alone to pinpoint it — see the trace hint
+#     at the end). laptop vs desktop formFactor conflict, so they split;
+#     impermanence's multi-disk variant gets its own config for the alt
+#     mainLuksName.
+#   * Palettes are checked DIRECTLY via the lib — the per-palette risk is
+#     the system-side Plymouth base00 → RGB math (fromHexString of 2-char
+#     slices in themes/engine/plymouth.nix), which is pure and needs no
+#     module-system instantiation. Forcing the whole palette attrset also
+#     catches a missing/garbled palette.
+#   * The standalone homeConfigurations aren't re-checked here — the
+#     per-output flake-check step already forces both.
+#
+# Net: a handful of full evals instead of ~39. Results come from
+# builtins.tryEval so one failure doesn't mask the rest.
+#
+#   nomarchy-eval-matrix          # run the matrix, table + exit code
+#
+# Add a new opt-in option's coverage by dropping it into the relevant
+# combined scenario in the `scenarios` attrset below.
+
+set -u
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+cd "$repo_root"
+
+NIX=(nix --extra-experimental-features 'nix-command flakes')
+
+read -r -d '' EXPR <<'NIXEOF' || true
+let
+  f = builtins.getFlake (toString ./.);
+  lib = f.inputs.nixpkgs.lib;
+  nl = import ./lib { inherit lib; };
+  default = f.nixosConfigurations.default;
+
+  forced = x: (builtins.tryEval (builtins.seq x true)).success;
+
+  # Combined opt-in scenarios. Each enables as many compatible toggles as
+  # possible so CI does ~3 full-system evals, not one per toggle. Home-side
+  # options go under home-manager.users.nomarchy.nomarchy.*.
+  scenarios = {
+    # laptop formFactor + every compatible system/home toggle + impermanence.
+    "laptop-stack" = {
+      nomarchy.system = {
+        formFactor = "laptop";
+        laptop.enable = true;
+        accessibility.enable = true;
+        gaming.enable = true;
+        features.hybridGPU = true;
+        hibernation.enable = true;
+        virtualization.docker.enable = true;
+        impermanence.enable = true;
+      };
+      nomarchy.hardware.fwupd = true;
+      home-manager.users.nomarchy.nomarchy = {
+        accessibility.enable = true;
+        gaming.enable = true;
+        overrides.enable = true;
+        panelPosition = "bottom";
+        keymap = { layout = "de"; variant = "nodeadkeys"; };
+        toggles = { waybar = false; idle = false; nightlight = false; };
+      };
+    };
+
+    # desktop preset — conflicts with the laptop formFactor, so its own eval.
+    "desktop-stack" = {
+      nomarchy.system = { formFactor = "desktop"; desktop.enable = true; };
+    };
+
+    # impermanence multi-disk variant (alternate mainLuksName).
+    "impermanence-multi" = {
+      nomarchy.system.impermanence = { enable = true; mainLuksName = "crypted_main"; };
+    };
+  };
+
+  evalToplevel = mod:
+    forced (default.extendModules { modules = [ mod ]; }).config.system.build.toplevel.drvPath;
+
+  # base00 → the three byte values the Plymouth template substitutes; plus
+  # the whole palette attrset, so a missing/garbled palette is caught.
+  paletteOk = name:
+    let
+      p = nl.getPalette name;
+      b = p.base00;
+      bytes = [
+        (lib.fromHexString (lib.substring 0 2 b))
+        (lib.fromHexString (lib.substring 2 2 b))
+        (lib.fromHexString (lib.substring 4 2 b))
+      ];
+    in forced (builtins.deepSeq [ p bytes ] true);
+in {
+  scenarios = builtins.mapAttrs (_: evalToplevel) scenarios;
+  palettes  = builtins.listToAttrs (map (n: { name = n; value = paletteOk n; }) nl.themeNames);
+}
+NIXEOF
+
+echo "Evaluating combined toggle scenarios + per-palette colour math..."
+json="$("${NIX[@]}" eval --impure --json --expr "$EXPR" 2>/tmp/eval-matrix.err)"
+status=$?
+if [[ $status -ne 0 || -z "$json" ]]; then
+  echo "ERROR: the matrix evaluation aborted before producing results." >&2
+  echo "This usually means an uncatchable error (abort/infinite recursion) in one" >&2
+  echo "scenario, or a syntax error in the expression. Full output:" >&2
+  cat /tmp/eval-matrix.err >&2
+  exit 1
+fi
+
+# Render each section and tally failures.
+fails=0
+render() {
+  local section="$1"
+  echo
+  echo "=== $section ==="
+  while IFS=$'\t' read -r name ok; do
+    if [[ "$ok" == "true" ]]; then
+      printf '  ok    %s\n' "$name"
+    else
+      printf '  FAIL  %s\n' "$name"
+      fails=$((fails + 1))
+    fi
+  done < <(echo "$json" | jq -r --arg s "$section" '.[$s] | to_entries[] | "\(.key)\t\(.value)"' | sort)
+}
+
+render scenarios
+render palettes
+
+echo
+if [[ $fails -gt 0 ]]; then
+  echo "$fails scenario(s) failed to evaluate. A combined scenario bundles several"
+  echo "toggles — re-run the suspects individually for the trace, e.g.:"
+  echo "  nix eval --impure --show-trace --expr 'let f = builtins.getFlake (toString ./.); in (f.nixosConfigurations.default.extendModules { modules = [ { <the toggle> } ]; }).config.system.build.toplevel.drvPath'"
+  exit 1
+fi
+echo "All scenarios evaluated cleanly."

core/branding/about.txt

@@ -0,0 +1,16 @@
+# About Nomarchy
+
+Nomarchy is a highly curated, NixOS-based distribution designed for power users.
+It features a customized Hyprland desktop environment with a declarative
+theming engine and a suite of integrated utility scripts.
+
+Built on a foundation of:
+- NixOS (Linux)
+- Hyprland (Window Manager)
+- Waybar (Status Bar)
+- Walker (Application Launcher & Menu)
+- Stylix (Theming Engine)
+
+Version: 2026.05.04
+Docs: https://github.com/nomarchy/nomarchy/docs
+Manual: nomarchy-manual (Command)

core/branding/screensaver.txt

@@ -0,0 +1,11 @@
+# Nomarchy Screensaver Configuration
+
+Nomarchy uses hyprlock for locking and hypridle for idle management.
+To configure the screensaver/lock screen visuals, edit:
+~/.config/hypr/hyprlock.conf
+
+To configure idle timeouts and actions, edit:
+~/.config/hypr/hypridle.conf
+
+You can also toggle the screensaver/idle management via the Nomarchy Menu:
+Trigger > Toggle > Idle Lock

core/home/accessibility.nix

@@ -0,0 +1,28 @@
+{ config, lib, ... }:
+
+let
+  cfg = config.nomarchy.accessibility;
+in
+{
+  config = lib.mkIf cfg.enable {
+    # Hyprland-side accessibility extras. The system preset
+    # (core/system/accessibility.nix) covers AT-SPI2 + Orca on PATH +
+    # XCURSOR_SIZE; this module adds the bits Hyprland reads directly.
+    #
+    # Loaded via extraConfig (mkAfter) so it merges with — and overrides
+    # — the templated input.conf for the repeat-rate / repeat-delay
+    # fields. The Orca keybinding is additive.
+    wayland.windowManager.hyprland.extraConfig = lib.mkAfter ''
+      # Accessibility — slower key-repeat so holding a key isn't a
+      # runaway machine-gun for users with low-mobility hands.
+      input {
+        repeat_rate = 25
+        repeat_delay = 1000
+      }
+
+      # Launch the Orca screen reader. The system preset puts `orca`
+      # on PATH when nomarchy.system.accessibility.enable = true.
+      bindd = SUPER ALT, S, Launch Orca, exec, orca
+    '';
+  };
+}

core/home/behavior.nix

@@ -1,94 +0,0 @@
-{ config, lib, ... }:
-
-# Behavior Configuration Module
-#
-# This module deploys non-visual configuration files (keybindings, input settings,
-# window rules, etc.) with lib.mkDefault, allowing downstream users to override.
-#
-# Visual/theme configs are handled separately by theme-loader.nix and stylix.nix.
-#
-# Behavior configs include:
-# - Keybindings (bindings, media keys, clipboard)
-# - Input settings (keyboard, mouse, touchpad)
-# - Window rules and layouts
-# - Autostart applications
-# - Environment variables
-
-let
-  configDir = ./config;
-  overridesDir = "${config.home.homeDirectory}/.config/nomarchy/overrides";
-
-  # Behavior config categories with their source paths
-  behaviorConfigs = {
-    # Hyprland behavior (non-visual)
-    "nomarchy/default/hypr/bindings.conf" = "hypr/bindings.conf";
-    "nomarchy/default/hypr/bindings/media.conf" = "hypr/bindings/media.conf";
-    "nomarchy/default/hypr/bindings/clipboard.conf" = "hypr/bindings/clipboard.conf";
-    "nomarchy/default/hypr/bindings/tiling-v2.conf" = "hypr/bindings/tiling-v2.conf";
-    "nomarchy/default/hypr/bindings/utilities.conf" = "hypr/bindings/utilities.conf";
-    "nomarchy/default/hypr/input.conf" = "hypr/input.conf";
-    "nomarchy/default/hypr/windows.conf" = "hypr/windows.conf";
-    "nomarchy/default/hypr/autostart.conf" = "hypr/autostart.conf";
-    "nomarchy/default/hypr/envs.conf" = "hypr/envs.conf";
-    "nomarchy/default/hypr/looknfeel.conf" = "hypr/looknfeel.conf";
-
-    # App-specific window rules (behavior, not visual)
-    "nomarchy/default/hypr/apps.conf" = "hypr/apps.conf";
-    "nomarchy/default/hypr/apps/qemu.conf" = "hypr/apps/qemu.conf";
-    "nomarchy/default/hypr/apps/steam.conf" = "hypr/apps/steam.conf";
-    "nomarchy/default/hypr/apps/terminals.conf" = "hypr/apps/terminals.conf";
-    "nomarchy/default/hypr/apps/walker.conf" = "hypr/apps/walker.conf";
-    "nomarchy/default/hypr/apps/browser.conf" = "hypr/apps/browser.conf";
-    "nomarchy/default/hypr/apps/1password.conf" = "hypr/apps/1password.conf";
-    "nomarchy/default/hypr/apps/bitwarden.conf" = "hypr/apps/bitwarden.conf";
-    "nomarchy/default/hypr/apps/pip.conf" = "hypr/apps/pip.conf";
-    "nomarchy/default/hypr/apps/system.conf" = "hypr/apps/system.conf";
-    "nomarchy/default/hypr/apps/localsend.conf" = "hypr/apps/localsend.conf";
-    "nomarchy/default/hypr/apps/telegram.conf" = "hypr/apps/telegram.conf";
-    "nomarchy/default/hypr/apps/geforce.conf" = "hypr/apps/geforce.conf";
-    "nomarchy/default/hypr/apps/moonlight.conf" = "hypr/apps/moonlight.conf";
-    "nomarchy/default/hypr/apps/retroarch.conf" = "hypr/apps/retroarch.conf";
-    "nomarchy/default/hypr/apps/webcam-overlay.conf" = "hypr/apps/webcam-overlay.conf";
-    "nomarchy/default/hypr/apps/davinci-resolve.conf" = "hypr/apps/davinci-resolve.conf";
-    "nomarchy/default/hypr/apps/hyprshot.conf" = "hypr/apps/hyprshot.conf";
-  };
-
-in
-{
-  options.nomarchy.behavior = {
-    hyprland = {
-      bindings = lib.mkOption {
-        type = lib.types.bool;
-        default = true;
-        description = "Whether to deploy default Hyprland keybindings.";
-      };
-      input = lib.mkOption {
-        type = lib.types.bool;
-        default = true;
-        description = "Whether to deploy default input settings.";
-      };
-      windowRules = lib.mkOption {
-        type = lib.types.bool;
-        default = true;
-        description = "Whether to deploy default window rules.";
-      };
-      autostart = lib.mkOption {
-        type = lib.types.bool;
-        default = true;
-        description = "Whether to deploy default autostart configuration.";
-      };
-    };
-  };
-
-  config = {
-    # Note: The actual config deployment is handled by configs.nix
-    # This module provides the options and documentation for behavior configs
-    # The separation allows users to selectively disable behavior categories
-
-    # Ensure behavior config directories exist in overrides
-    home.activation.createBehaviorOverrideDirs = lib.hm.dag.entryAfter [ "writeBoundary" ] ''
-      mkdir -p "${overridesDir}/hypr/bindings"
-      mkdir -p "${overridesDir}/hypr/apps"
-    '';
-  };
-}

core/home/config/nomarchy-skill/SKILL.md

@@ -8,7 +8,7 @@ description: >
   monitors, gaps, borders, blur, opacity, waybar, walker, terminal config, themes,
   wallpaper, night light, idle, lock screen, screenshots, layer rules, workspace
   settings, display config, and user-facing nomarchy commands. Excludes Nomarchy
-  source development in ~/.local/share/nomarchy/ and nomarchy-dev-* workflows.
+  source development in ~/.local/share/nomarchy/ and repo-internal workflows.
 ---
 
 # Nomarchy Skill
@@ -34,7 +34,7 @@ It is not for contributing to Nomarchy source code.
 
 **If you're about to edit a config file in ~/.config/ on this system, STOP and use this skill first.**
 
-**Do NOT use this skill for Nomarchy development tasks** (editing files in `~/.local/share/nomarchy/`, creating migrations, or running `nomarchy-dev-*` workflows).
+**Do NOT use this skill for Nomarchy development tasks** — editing files in `~/.local/share/nomarchy/` or modifying repo internals.
 
 ## Critical Safety Rules
 
@@ -57,7 +57,7 @@ This directory contains Nomarchy's source files managed by git. Any changes will
 
 **Reading `~/.local/share/nomarchy/` is SAFE and useful** - do it freely to:
 - Understand how nomarchy commands work: `cat $(which nomarchy-theme-set)`
-- See default configs before customizing: `cat ~/.local/share/nomarchy/config/waybar/config.jsonc`
+- See default configs before customizing: `cat ~/.local/share/nomarchy/config/fastfetch/config.jsonc`
 - Check stock theme files to copy for customization
 - Reference default hyprland settings: `cat ~/.config/nomarchy/default/hypr/*`
 
@@ -109,7 +109,7 @@ cat $(which nomarchy-theme-set)
 | `nomarchy-install-*` | Install optional software | `nomarchy-install-docker-dbs` |
 | `nomarchy-launch-*` | Launch apps | `nomarchy-launch-browser` |
 | `nomarchy-cmd-*` | System commands | `nomarchy-cmd-screenshot` |
-| `nomarchy-pkg-*` | Package management | `nomarchy-pkg-install <pkg>` |
+| `nomarchy-pkg-*` | Package management | `nomarchy-pkg-add <pkg>` |
 | `nomarchy-setup-*` | Initial setup tasks | `nomarchy-setup-fingerprint` |
 | `nomarchy-update-*` | System updates | `nomarchy-update` |
 
@@ -244,6 +244,9 @@ nomarchy-theme-set <name>        # Apply theme (use "Tokyo Night" not "tokyo-nig
 nomarchy-theme-next              # Cycle to next theme
 nomarchy-theme-bg-next           # Cycle wallpaper
 nomarchy-theme-install <url>     # Install from git repo
+nomarchy-theme-remove <name>     # Remove an installed extra theme
+nomarchy-theme-refresh           # Re-apply current theme from templates
+nomarchy-theme-bg-install        # Open backgrounds dir to drop in custom images
 ```
 
 ### Keybindings
@@ -311,10 +314,38 @@ nomarchy-debug --no-sudo --print # Debug info (ALWAYS use these flags)
 nomarchy-lock-screen             # Lock screen
 nomarchy-system-shutdown         # Shutdown
 nomarchy-system-reboot           # Reboot
+nomarchy-sudo-passwordless-toggle # Toggle 15-min passwordless sudo
+nomarchy-sudo-reset              # Clear sudo lockout / faillock
+nomarchy-restart-trackpad        # Reload intel_quicki2c (fixes dead THC trackpad)
 ```
 
 **IMPORTANT:** Always run `nomarchy-debug` with `--no-sudo --print` flags to avoid interactive sudo prompts that will hang the terminal.
 
+### Custom App Launchers
+
+```bash
+nomarchy-webapp-install                  # Add a web app launcher (interactive)
+nomarchy-webapp-remove [name...]         # Remove web apps (interactive if no name)
+nomarchy-webapp-remove-all               # Bulk-remove every web app
+nomarchy-tui-install                     # Add a TUI launcher for a terminal program
+nomarchy-tui-remove [name...]            # Remove TUI launchers
+nomarchy-tui-remove-all                  # Bulk-remove every TUI launcher
+```
+
+Both families write `.desktop` files into `~/.local/share/applications/` so they appear in the app launcher (walker / rofi).
+
+### Virtualization
+
+```bash
+nomarchy-windows-vm install              # Provision a Windows VM via docker-compose
+nomarchy-windows-vm launch               # Connect to the VM (auto-stop on disconnect)
+nomarchy-windows-vm launch -k            # Connect, keep VM running after disconnect
+nomarchy-windows-vm stop                 # Shut the VM down
+nomarchy-windows-vm status               # Show current state
+```
+
+Requires KVM (`/dev/kvm`) and Docker (enable via `nomarchy.system.virtualization.docker`).
+
 ## Troubleshooting
 
 ```bash
@@ -325,11 +356,13 @@ nomarchy-debug --no-sudo --print
 nomarchy-upload-log
 
 # Reset specific config to defaults
+# Examples: nomarchy-refresh-fastfetch, nomarchy-refresh-hyprland, nomarchy-refresh-waybar
 nomarchy-refresh-<app>
 
 # Refresh specific config file
-# config-file path is relative to ~/.config/
-# eg. nomarchy-refresh-config hypr/hyprlock.conf will refresh ~/.config/hypr/hyprlock.conf
+# config-file path is relative to ~/.config/; the stock copy must exist under
+# ~/.local/share/nomarchy/config/ (i.e. a core/home/config item).
+# eg. nomarchy-refresh-config fastfetch/config.jsonc refreshes ~/.config/fastfetch/config.jsonc
 nomarchy-refresh-config <config-file>
 
 # Full reinstall of configs (nuclear option)
@@ -344,7 +377,7 @@ When user requests system changes:
 2. **Is it a config edit?** Edit in `~/.config/`, never `~/.local/share/nomarchy/`
 3. **Is it a theme customization?** Create a NEW custom theme directory
 4. **Is it automation?** Use hooks in `~/.config/nomarchy/hooks/`
-5. **Is it a package install?** Use `nomarchy-pkg-add` (or `nomarchy-pkg-aur-add` for AUR-only packages)
+5. **Is it a package install?** Use `nomarchy-pkg-add` (adds to `user-packages.json`; rebuild applies it). The AUR does not exist on NixOS — search nixpkgs with `nix search nixpkgs <name>`.
 6. **Unsure if command exists?** Search with `compgen -c | grep nomarchy`
 
 ## Out of Scope
@@ -352,7 +385,7 @@ When user requests system changes:
 This skill intentionally does not cover Nomarchy source development. Do not use this skill for:
 - Editing files in `~/.local/share/nomarchy/` (`bin/`, `config/`, `default/`, `themes/`, `migrations/`, etc.)
 - Creating or editing migrations
-- Running `nomarchy-dev-*` commands
+- Modifying Nomarchy's own source tree
 
 ## Example Requests
 

core/home/config/nomarchy/default/bash/envs

@@ -3,5 +3,4 @@ export SUDO_EDITOR="$EDITOR"
 export BAT_THEME=ansi
 
 # Duplicated from .config/uwsm/env so SSH works too
-export NOMARCHY_PATH=$HOME/.local/share/nomarchy
-export PATH=$NOMARCHY_PATH/bin:$PATH:$HOME/.local/bin
+export PATH=$PATH:$HOME/.local/bin

core/home/config/nomarchy/default/bashrc

@@ -1,11 +0,0 @@
-# If not running interactively, don't do anything (leave this at the top of this file)
-[[ $- != *i* ]] && return
-
-# All the default Nomarchy aliases and functions
-# (don't mess with these directly, just overwrite them here!)
-source ~/.config/nomarchy/default/bash/rc
-
-# Add your own exports, aliases, and functions here.
-#
-# Make an alias for invoking commands you use constantly
-# alias p='python'

core/home/config/nomarchy/default/hypr/apps.conf

@@ -1,8 +1,18 @@
-# App-specific tweaks
+# App-specific tweaks. All rules are class- or title-gated, so sourcing
+# unconditionally is harmless when the app isn't installed or running.
+source = ~/.config/nomarchy/default/hypr/apps/1password.conf
+source = ~/.config/nomarchy/default/hypr/apps/bitwarden.conf
 source = ~/.config/nomarchy/default/hypr/apps/browser.conf
+source = ~/.config/nomarchy/default/hypr/apps/davinci-resolve.conf
+source = ~/.config/nomarchy/default/hypr/apps/geforce.conf
 source = ~/.config/nomarchy/default/hypr/apps/hyprshot.conf
 source = ~/.config/nomarchy/default/hypr/apps/localsend.conf
+source = ~/.config/nomarchy/default/hypr/apps/moonlight.conf
+source = ~/.config/nomarchy/default/hypr/apps/pip.conf
+source = ~/.config/nomarchy/default/hypr/apps/qemu.conf
 source = ~/.config/nomarchy/default/hypr/apps/retroarch.conf
+source = ~/.config/nomarchy/default/hypr/apps/steam.conf
+source = ~/.config/nomarchy/default/hypr/apps/system.conf
 source = ~/.config/nomarchy/default/hypr/apps/telegram.conf
 source = ~/.config/nomarchy/default/hypr/apps/terminals.conf
 source = ~/.config/nomarchy/default/hypr/apps/walker.conf

core/home/config/nomarchy/default/hypr/apps/geforce.conf

@@ -1,5 +1 @@
-windowrule {
-  name = geforce
-  class:= GeForceNOW
-  idle_inhibit = fullscreen
-}
+windowrulev2 = idleinhibit fullscreen, class:^(GeForceNOW)$

core/home/config/nomarchy/default/hypr/apps/moonlight.conf

@@ -1,6 +1,2 @@
-windowrule {
-  name = moonlight
-  class:= com.moonlight_stream.Moonlight
-  fullscreen = 1
-  idle_inhibit = fullscreen
-}
+windowrulev2 = fullscreen, class:^(com.moonlight_stream.Moonlight)$
+windowrulev2 = idleinhibit fullscreen, class:^(com.moonlight_stream.Moonlight)$

core/home/config/nomarchy/default/hypr/apps/pip.conf

@@ -4,7 +4,7 @@ windowrulev2 = tag -default-opacity, tag:pip
 windowrulev2 = float, tag:pip
 windowrulev2 = pin, tag:pip
 windowrulev2 = size 600 338, tag:pip
-windowrulev2 = keep_aspect_ratio on, tag:pip
-windowrulev2 = border_size 0, tag:pip
+windowrulev2 = keepaspectratio, tag:pip
+windowrulev2 = bordersize 0, tag:pip
 windowrulev2 = opacity 1 1, tag:pip
 windowrulev2 = move (monitor_w-window_w-40) (monitor_h*0.04), tag:pip

core/home/config/nomarchy/default/hypr/apps/retroarch.conf

@@ -1,4 +1,4 @@
 windowrulev2 = fullscreen, class:com.libretro.RetroArch
 windowrulev2 = tag -default-opacity, class:com.libretro.RetroArch
 windowrulev2 = opacity 1 1, class:com.libretro.RetroArch
-windowrulev2 = idleinhibit, fullscreen, class:com.libretro.RetroArch
+windowrulev2 = idleinhibit fullscreen, class:com.libretro.RetroArch

core/home/config/nomarchy/default/hypr/apps/steam.conf

@@ -5,4 +5,4 @@ windowrulev2 = tag -default-opacity, class:steam.*
 windowrulev2 = opacity 1 1, class:steam.*
 windowrulev2 = size 1100 700, class:steam, title:Steam
 windowrulev2 = size 460 800, class:steam, title:Friends List
-windowrulev2 = idleinhibit, fullscreen, class:steam
+windowrulev2 = idleinhibit fullscreen, class:steam

core/home/config/nomarchy/default/hypr/apps/system.conf

@@ -20,4 +20,4 @@ windowrulev2 = opacity 1 1, class:^(zoom|vlc|mpv|org.kde.kdenlive|com.obsproject
 windowrulev2 = rounding 8, tag:pop
 
 # Prevent idle while open
-windowrulev2 = idleinhibit, always, tag:noidle
+windowrulev2 = idleinhibit always, tag:noidle

core/home/config/nomarchy/default/hypr/autostart.conf

@@ -1,5 +1,6 @@
 exec-once = uwsm-app -- hypridle
 exec-once = uwsm-app -- mako
+exec-once = nomarchy-welcome
 # exec-once = uwsm-app -- waybar
 # fcitx5 is autostarted by NixOS's i18n.inputMethod when
 # nomarchy.system.inputMethod.enable = true; no manual exec-once needed.

core/home/config/nomarchy/default/hypr/bindings.conf

@@ -1,16 +0,0 @@
-# Deprecated bindings file. New installations include everything directly.
-
-bindd = SUPER, RETURN, Terminal, exec, $terminal
-bindd = SUPER, F, File manager, exec, $fileManager
-bindd = SUPER, B, Web browser, exec, $browser
-bindd = SUPER, M, Music player, exec, $music
-bindd = SUPER, N, Neovim, exec, $terminal -e nvim
-bindd = SUPER, T, Top, exec, $terminal -e btop
-bindd = SUPER, D, Lazy Docker, exec, $terminal -e lazydocker
-bindd = SUPER, G, Messenger, exec, $messenger
-bindd = SUPER, O, Obsidian, exec, obsidian -disable-gpu
-bindd = SUPER, SLASH, Password manager, exec, $passwordManager
-
-source = ~/.config/nomarchy/default/hypr/bindings/media.conf
-source = ~/.config/nomarchy/default/hypr/bindings/tiling.conf
-source = ~/.config/nomarchy/default/hypr/bindings/utilities.conf

core/home/config/nomarchy/default/hypr/bindings/tiling.conf

@@ -1,74 +0,0 @@
-# This is now a deprecated file meant for those who did not wish to learn the latest Nomarchy hotkeys.
-# Do not make changes here, but bring them to tiling-v2.conf instead.
-
-# Close windows
-bindd = SUPER, Q, Close window, killactive,
-bindd = CTRL ALT, DELETE, Close all windows, exec, nomarchy-hyprland-window-close-all
-
-# Control tiling
-bindd = SUPER, J, Toggle window split, togglesplit, # dwindle
-bindd = SUPER, P, Pseudo window, pseudo, # dwindle
-bindd = SUPER SHIFT, V, Toggle window floating/tiling, togglefloating,
-bindd = SHIFT, F11, Force full screen, fullscreen, 0
-bindd = ALT, F11, Full width, fullscreen, 1
-
-# Move focus with SUPER + arrow keys
-bindd = SUPER, LEFT, Move focus left, movefocus, l
-bindd = SUPER, RIGHT, Move focus right, movefocus, r
-bindd = SUPER, UP, Move focus up, movefocus, u
-bindd = SUPER, DOWN, Move focus down, movefocus, d
-
-# Switch workspaces with SUPER + [0-9]
-bindd = SUPER, code:10, Switch to workspace 1, workspace, 1
-bindd = SUPER, code:11, Switch to workspace 2, workspace, 2
-bindd = SUPER, code:12, Switch to workspace 3, workspace, 3
-bindd = SUPER, code:13, Switch to workspace 4, workspace, 4
-bindd = SUPER, code:14, Switch to workspace 5, workspace, 5
-bindd = SUPER, code:15, Switch to workspace 6, workspace, 6
-bindd = SUPER, code:16, Switch to workspace 7, workspace, 7
-bindd = SUPER, code:17, Switch to workspace 8, workspace, 8
-bindd = SUPER, code:18, Switch to workspace 9, workspace, 9
-bindd = SUPER, code:19, Switch to workspace 10, workspace, 10
-
-# Move active window to a workspace with SUPER + SHIFT + [0-9]
-bindd = SUPER SHIFT, code:10, Move window to workspace 1, movetoworkspace, 1
-bindd = SUPER SHIFT, code:11, Move window to workspace 2, movetoworkspace, 2
-bindd = SUPER SHIFT, code:12, Move window to workspace 3, movetoworkspace, 3
-bindd = SUPER SHIFT, code:13, Move window to workspace 4, movetoworkspace, 4
-bindd = SUPER SHIFT, code:14, Move window to workspace 5, movetoworkspace, 5
-bindd = SUPER SHIFT, code:15, Move window to workspace 6, movetoworkspace, 6
-bindd = SUPER SHIFT, code:16, Move window to workspace 7, movetoworkspace, 7
-bindd = SUPER SHIFT, code:17, Move window to workspace 8, movetoworkspace, 8
-bindd = SUPER SHIFT, code:18, Move window to workspace 9, movetoworkspace, 9
-bindd = SUPER SHIFT, code:19, Move window to workspace 10, movetoworkspace, 10
-
-# TAB between workspaces
-bindd = SUPER, TAB, Next workspace, workspace, e+1
-bindd = SUPER SHIFT, TAB, Previous workspace, workspace, e-1
-bindd = SUPER CTRL, TAB, Former workspace, workspace, previous
-
-# Swap active window with the one next to it with SUPER + SHIFT + arrow keys
-bindd = SUPER SHIFT, LEFT, Swap window to the left, swapwindow, l
-bindd = SUPER SHIFT, RIGHT, Swap window to the right, swapwindow, r
-bindd = SUPER SHIFT, UP, Swap window up, swapwindow, u
-bindd = SUPER SHIFT, DOWN, Swap window down, swapwindow, d
-
-# Cycle through applications on active workspace
-bindd = ALT, TAB, Cycle to next window, cyclenext
-bindd = ALT SHIFT, TAB, Cycle to prev window, cyclenext, prev
-bindd = ALT, TAB, Reveal active window on top, bringactivetotop
-bindd = ALT SHIFT, TAB, Reveal active window on top, bringactivetotop
-
-# Resize active window
-bindd = SUPER, code:20, Expand window left, resizeactive, -100 0    # - key
-bindd = SUPER, code:21, Shrink window left, resizeactive, 100 0     # = key
-bindd = SUPER SHIFT, code:20, Shrink window up, resizeactive, 0 -100
-bindd = SUPER SHIFT, code:21, Expand window down, resizeactive, 0 100
-
-# Scroll through existing workspaces with SUPER + scroll
-bindd = SUPER, MOUSE_DOWN, Scroll active workspace forward, workspace, e+1
-bindd = SUPER, MOUSE_UP, Scroll active workspace backward, workspace, e-1
-
-# Move/resize windows with mainMod + LMB/RMB and dragging
-bindmd = SUPER, mouse:272, Move window, movewindow
-bindmd = SUPER, mouse:273, Resize window, resizewindow

core/home/config/nomarchy/default/hypr/bindings/utilities.conf

@@ -51,9 +51,6 @@ bindd = SUPER CTRL, B, Bluetooth controls, exec, nomarchy-launch-bluetooth
 bindd = SUPER CTRL, W, Wifi controls, exec, nomarchy-launch-wifi
 bindd = SUPER CTRL, T, Activity, exec, nomarchy-launch-tui btop
 
-# Dictation
-bindd = SUPER CTRL, X, Toggle dictation, exec, voxtype record toggle
-
 # Zoom
 bindd = SUPER CTRL, Z, Zoom in, exec, hyprctl keyword cursor:zoom_factor $(hyprctl getoption cursor:zoom_factor -j | jq '.float + 1')
 bindd = SUPER CTRL ALT, Z, Reset zoom, exec, hyprctl keyword cursor:zoom_factor 1

core/home/config/nomarchy/default/hypr/input.conf

@@ -1,21 +0,0 @@
-# https://wiki.hyprland.org/Configuring/Variables/#input
-input {
-    kb_layout = us
-    kb_variant =
-    kb_model =
-    kb_options = compose:caps
-    kb_rules =
-
-    follow_mouse = 1
-
-    sensitivity = 0 # -1.0 - 1.0, 0 means no modification.
-
-    touchpad {
-        natural_scroll = false
-    }
-}
-
-misc {
-    key_press_enables_dpms = true  # key press will trigger wake
-    mouse_move_enables_dpms = true # mouse move will trigger wake
-}

core/home/config/nomarchy/default/hypr/plain-bindings.conf

@@ -1,16 +0,0 @@
-# Application bindings
-bindd = SUPER, RETURN, Terminal, exec, uwsm-app -- xdg-terminal-exec --dir="$(nomarchy-cmd-terminal-cwd)"
-bindd = SUPER SHIFT, RETURN, Browser, exec, nomarchy-launch-browser
-bindd = SUPER SHIFT, F, File manager, exec, uwsm-app -- nautilus --new-window
-bindd = SUPER ALT SHIFT, F, File manager (cwd), exec, uwsm-app -- nautilus --new-window "$(nomarchy-cmd-terminal-cwd)"
-bindd = SUPER SHIFT, B, Browser, exec, nomarchy-launch-browser
-bindd = SUPER SHIFT ALT, B, Browser (private), exec, nomarchy-launch-browser --private
-bindd = SUPER SHIFT, N, Editor, exec, nomarchy-launch-editor
-
-# Add extra bindings
-# bindd = SUPER SHIFT, A, ChatGPT, exec, nomarchy-launch-webapp "https://chatgpt.com"
-# bindd = SUPER SHIFT, R, exec, alacritty -e ssh your-server
-
-# Overwrite existing bindings, like putting Nomarchy Menu on Super + Space
-# unbind = SUPER, SPACE
-# bindd = SUPER, SPACE, Nomarchy menu, exec, nomarchy-menu

core/home/config/nomarchy/default/mako/core.ini

@@ -22,12 +22,15 @@ layer=overlay
 
 [summary~="Setup Wi-Fi"]
 on-button-left=exec sh -c 'nomarchy-notification-dismiss "Setup Wi-Fi"; nomarchy-launch-wifi'
+on-click=exec sh -c 'nomarchy-notification-dismiss "Setup Wi-Fi"; nomarchy-launch-wifi'
 
 [summary~="Update System"]
 on-button-left=exec sh -c 'nomarchy-notification-dismiss "Update System"; nomarchy-launch-floating-terminal-with-presentation nomarchy-update'
+on-click=exec sh -c 'nomarchy-notification-dismiss "Update System"; nomarchy-launch-floating-terminal-with-presentation nomarchy-update'
 
 [summary~="Learn Keybindings"]
 on-button-left=exec sh -c 'nomarchy-notification-dismiss "Learn Keybindings"; nomarchy-menu-keybindings'
+on-click=exec sh -c 'nomarchy-notification-dismiss "Learn Keybindings"; nomarchy-menu-keybindings'
 
 [summary~="Screenshot copied & saved"]
 max-icon-size=80

core/home/config/nomarchy/default/voxtype/config.toml

@@ -1,97 +0,0 @@
-# Voxtype Configuration
-#
-# Location: ~/.config/voxtype/config.toml
-# All settings can be overridden via CLI flags
-#
-# State file for external integrations (Waybar, polybar, etc.)
-# Use "auto" for default location ($XDG_RUNTIME_DIR/voxtype/state),
-# a custom path, or "disabled" to turn off. The daemon writes state
-# ("idle", "recording", "transcribing") to this file whenever it changes.
-# Required for `voxtype record toggle` and `voxtype status` commands.
-state_file = "auto"
-
-[hotkey]
-# Hotkey is configured in Hyprland. Default is Super + Ctrl + X
-enabled = false
-
-[audio]
-# Audio input device ("default" uses system default)
-# List devices with: pactl list sources short
-device = "default"
-
-# Sample rate in Hz (whisper expects 16000)
-sample_rate = 16000
-
-# Maximum recording duration in seconds (safety limit)
-max_duration_secs = 60
-
-# [audio.feedback]
-# Enable audio feedback sounds (beeps when recording starts/stops)
-# enabled = true
-#
-# Sound theme: "default", "subtle", "mechanical", or path to custom theme directory
-# theme = "default"
-#
-# Volume level (0.0 to 1.0)
-# volume = 0.7
-
-[whisper]
-# Model to use for transcription
-# Options: tiny, tiny.en, base, base.en, small, small.en, medium, medium.en, large-v3, large-v3-turbo
-# .en models are English-only but faster and more accurate for English
-# large-v3-turbo is faster than large-v3 with minimal accuracy loss (recommended for GPU)
-# Or provide absolute path to a custom .bin model file
-model = "base.en"
-
-# Language for transcription
-# Use "en" for English, "auto" for auto-detection
-# See: https://github.com/openai/whisper#available-models-and-languages
-language = "en"
-
-# Translate non-English speech to English
-translate = false
-
-# Number of CPU threads for inference (omit for auto-detection)
-# threads = 4
-
-[output]
-# Primary output mode: "type" or "clipboard"
-# - type: Simulates keyboard input at cursor position (requires ydotool)
-# - clipboard: Copies text to clipboard (requires wl-copy)
-mode = "type"
-
-# Fall back to clipboard if typing fails
-fallback_to_clipboard = true
-
-# Delay between typed characters in milliseconds
-# 0 = fastest possible, increase if characters are dropped
-type_delay_ms = 1
-
-# Post-processing command (optional)
-# Pipe transcribed text through an external command for cleanup before output.
-# The command receives text on stdin and outputs processed text on stdout.
-# Useful for LLM-based text cleanup, grammar correction, filler word removal.
-# On any failure (timeout, error), falls back to original transcription.
-#
-# [output.post_process]
-# command = "ollama run llama3.2:1b 'Clean up this dictation. Fix grammar, remove filler words. Output only the cleaned text:'"
-# timeout_ms = 30000  # 30 second timeout (generous for LLM)
-
-[output.notification]
-# Show notification when recording starts (hotkey pressed)
-on_recording_start = false
-
-# Show notification when recording stops (transcription beginning)
-on_recording_stop = false
-
-# Show notification with transcribed text after transcription completes
-on_transcription = false
-
-# [text]
-# Text processing options (word replacements, spoken punctuation)
-#
-# Enable spoken punctuation conversion (e.g., say "period" to get ".")
-# spoken_punctuation = false
-#
-# Custom word replacements (case-insensitive)
-# replacements = { "hyperwhisper" = "hyprwhspr" }

core/home/config/nomarchy/hooks/post-install.sample

@@ -0,0 +1,9 @@
+#!/bin/bash
+
+# This hook is called after the nomarchy-welcome wizard finishes successfully.
+# Use it to run any custom first-boot logic (e.g. cloning your dotfiles repo,
+# setting up SSH keys, or launching specific initial apps).
+
+# Example: Open the manual and show a notification
+# nomarchy-manual
+# notify-send "Welcome home" "Your Nomarchy system is ready to use."

core/home/configs.nix

@@ -51,5 +51,56 @@ let
 
 in
 {
-  xdg.configFile = configMappings;
+  xdg.configFile = configMappings // {
+    # mako reads ~/.config/mako/config by default. The themed Nomarchy
+    # config (urgency rules, app filters, button handlers) lives under
+    # nomarchy/default/mako/core.ini for organizational reasons, so wire
+    # it explicitly here. Without this, mako silently falls back to its
+    # built-in defaults and every Nomarchy notification customization is
+    # inert.
+    "mako/config".source = lib.mkDefault ./config/nomarchy/default/mako/core.ini;
+
+    # Hyprland's native-Wayland input config — templated from
+    # nomarchy.keymap.{layout,variant} so non-US users get the right
+    # layout in Wayland apps. The previous static input.conf hardcoded
+    # `kb_layout = us`, so the installer's xkb.layout / console.keyMap
+    # writes only reached XWayland and the TTY. Generated here rather
+    # than shipped under config/nomarchy/default/hypr/ so the keymap
+    # values can vary per-host without a source-file edit.
+    "nomarchy/default/hypr/input.conf".text = lib.mkDefault ''
+      # https://wiki.hyprland.org/Configuring/Variables/#input
+      input {
+          kb_layout = ${config.nomarchy.keymap.layout}
+          kb_variant = ${config.nomarchy.keymap.variant}
+          kb_model =
+          kb_options = compose:caps
+          kb_rules =
+
+          follow_mouse = 1
+
+          sensitivity = 0 # -1.0 - 1.0, 0 means no modification.
+
+          touchpad {
+              natural_scroll = false
+          }
+      }
+
+      misc {
+          key_press_enables_dpms = true  # key press will trigger wake
+          mouse_move_enables_dpms = true # mouse move will trigger wake
+      }
+    '';
+  };
+
+  home.file.".XCompose" = lib.mkDefault {
+    source = ./config/nomarchy/default/xcompose;
+  };
+
+  # Pristine copy of the stock configs, kept out of ~/.config so a user edit
+  # never touches it. `nomarchy-refresh-config` restores a file in ~/.config
+  # from here, and SKILL.md points users at it to diff against defaults.
+  xdg.dataFile."nomarchy/config".source = builtins.path {
+    name = "nomarchy-config";
+    path = ./config;
+  };
 }

core/home/default.nix

@@ -5,10 +5,11 @@
     ./options.nix
     ./state.nix
     ./overrides.nix
-    ./behavior.nix
     ./fonts.nix
     ./configs.nix
     ./security.nix
     ./bash.nix
+    ./gaming.nix
+    ./accessibility.nix
   ];
 }

core/home/gaming.nix

@@ -0,0 +1,12 @@
+{ config, lib, ... }:
+
+let
+  cfg = config.nomarchy.gaming;
+in
+{
+  config = lib.mkIf cfg.enable {
+    wayland.windowManager.hyprland.extraConfig = ''
+      windowrulev2 = fullscreen, class:^(steam_app_).*$
+    '';
+  };
+}

core/home/options.nix

@@ -1,48 +1,52 @@
 { lib, pkgs, ... }:
 
+let
+  # Defaults live in lib/state-schema.nix so they can't drift between this
+  # file, core/system/options.nix, and core/home/state.nix's `or` fallbacks.
+  schema = import ../../lib/state-schema.nix { inherit lib; };
+in
 {
   options.nomarchy = {
     toggles = {
       suspend = lib.mkOption {
         type = lib.types.bool;
-        default = true;
+        default = schema.home.suspend;
         description = "Whether to show suspend in system menu.";
       };
       screensaver = lib.mkOption {
         type = lib.types.bool;
-        default = true;
+        default = schema.home.screensaver;
         description = "Whether the screensaver is enabled.";
       };
       idle = lib.mkOption {
         type = lib.types.bool;
-        default = true;
+        default = schema.home.idle;
         description = "Whether the idle lock is enabled.";
       };
       nightlight = lib.mkOption {
         type = lib.types.bool;
-        default = false;
+        default = schema.home.nightlight;
         description = "Whether the nightlight is enabled.";
       };
       waybar = lib.mkOption {
         type = lib.types.bool;
-        default = true;
+        default = schema.home.waybar;
         description = "Whether the top bar is enabled.";
       };
-      skipVsCodeTheme = lib.mkOption {
-        type = lib.types.bool;
-        default = false;
-        description = "Whether to skip theme changes in VSCode.";
-      };
     };
     nightlightTemperature = lib.mkOption {
       type = lib.types.int;
-      default = 4000;
+      default = schema.home.nightlightTemperature;
       description = "Temperature for the nightlight.";
     };
     theme = lib.mkOption {
       type = lib.types.str;
-      default = "summer-night";
-      description = "System theme name.";
+      default = schema.home.theme;
+      description = ''
+        System theme name. This is the declarative source of truth.
+        Changing this and running `nomarchy-env-update` (or a system
+        rebuild) will update the entire desktop.
+      '';
     };
     formFactor = lib.mkOption {
       type = lib.types.enum [ "laptop" "desktop" ];
@@ -56,33 +60,84 @@
         explicit value into the generated home.nix.
       '';
     };
+    keymap = {
+      layout = lib.mkOption {
+        type = lib.types.str;
+        default = "us";
+        example = "dk";
+        description = ''
+          Keyboard layout for Hyprland's native Wayland session. The
+          installer also writes services.xserver.xkb.layout (for XWayland)
+          and console.keyMap (for the TTY) to the same value via
+          system.nix, but Hyprland reads its own input config so it needs
+          this option independently — otherwise non-US users get the
+          right layout in XWayland apps and the console but the US
+          fallback inside native-Wayland apps.
+        '';
+      };
+      variant = lib.mkOption {
+        type = lib.types.str;
+        default = "";
+        example = "intl";
+        description = ''
+          Keyboard variant for Hyprland (e.g. "intl" for US-International).
+          Empty by default.
+        '';
+      };
+    };
     wallpaper = lib.mkOption {
       type = lib.types.str;
-      default = "";
-      description = "System wallpaper path.";
+      default = schema.home.wallpaper;
+      description = ''
+        System wallpaper path. This is the declarative source of truth.
+        Changing this and running `nomarchy-env-update` (or a system
+        rebuild) will update the background.
+      '';
+    };
+    panelPosition = lib.mkOption {
+      type = lib.types.enum [ "top" "bottom" ];
+      default = schema.home.panelPosition;
+      description = ''
+        Waybar panel position. This is the declarative source of truth.
+        Changing this and running `nomarchy-env-update` (or a system
+        rebuild) will update the UI.
+      '';
     };
     hyprland = {
       gaps_in = lib.mkOption {
         type = lib.types.int;
-        default = 5;
-        description = "Inner gaps for Hyprland.";
+        default = schema.home.hyprland.gaps_in;
+        description = "Inner gaps for Hyprland. Driven by the declarative state.";
       };
       gaps_out = lib.mkOption {
         type = lib.types.int;
-        default = 10;
-        description = "Outer gaps for Hyprland.";
+        default = schema.home.hyprland.gaps_out;
+        description = "Outer gaps for Hyprland. Driven by the declarative state.";
       };
       border_size = lib.mkOption {
         type = lib.types.int;
-        default = 2;
-        description = "Border size for Hyprland.";
+        default = schema.home.hyprland.border_size;
+        description = "Border size for Hyprland. Driven by the declarative state.";
+      };
+      scale = lib.mkOption {
+        type = lib.types.str;
+        default = schema.home.hyprland.scale;
+        description = ''
+          Default monitor scale. Use "auto" to let Hyprland decide,
+          or a numeric string like "1", "1.25", "1.5", "2". Driven
+          by the declarative state.
+        '';
       };
     };
     fonts = {
       monospace = lib.mkOption {
         type = lib.types.str;
-        default = "JetBrainsMono Nerd Font";
-        description = "System monospace font.";
+        default = schema.home.font;
+        description = ''
+          System monospace font. This is the declarative source of truth.
+          Changing this and running `nomarchy-env-update` (or a system
+          rebuild) will update the entire desktop.
+        '';
       };
     };
     iconsTheme = lib.mkOption {
@@ -114,14 +169,50 @@
     };
 
     apps = {
-      opencode = {
-        enable = lib.mkEnableOption ''
-          opencode AI coding CLI integration. When on, deploys
-          ~/.config/opencode/opencode.json. The `opencode` package itself
-          is not installed by Nomarchy — add it to your home.nix if you
-          want it on PATH.
-        '';
+      alacritty.enable = lib.mkEnableOption "Alacritty terminal integration";
+      btop.enable = lib.mkEnableOption "btop resource monitor integration";
+      ghostty.enable = lib.mkEnableOption "Ghostty terminal integration";
+      kitty.enable = lib.mkEnableOption "Kitty terminal integration";
+      lazygit.enable = lib.mkEnableOption "lazygit integration";
+      tmux.enable = lib.mkEnableOption "tmux integration";
+      elephant.enable = lib.mkEnableOption "Elephant menu provider integration";
+      walker.enable = lib.mkEnableOption "Walker launcher integration";
+      swayosd.enable = lib.mkEnableOption "SwayOSD integration";
+      vscode = {
+        enable = lib.mkEnableOption "VSCode integration";
+        devExtensions = lib.mkEnableOption "Nomarchy's curated VSCode extension pack (language servers + git + editor enhancements)";
       };
+      opencode.enable = lib.mkEnableOption ''
+        opencode AI coding CLI integration. When on, deploys
+        ~/.config/opencode/opencode.json. The `opencode` package itself
+        is not installed by Nomarchy — add it to your home.nix if you
+        want it on PATH.
+      '';
+    };
+
+    gaming = {
+      enable = lib.mkEnableOption ''
+        Gaming preset (home-side companion to nomarchy.system.gaming.enable).
+        Adds a Hyprland window rule that fullscreens windows whose class
+        matches steam_app_* — i.e. games launched through Steam — so they
+        grab the whole screen instead of opening windowed. Set this to the
+        same value as nomarchy.system.gaming.enable; the installer flips
+        both when the Gaming profile is selected.
+      '';
+    };
+
+    accessibility = {
+      enable = lib.mkEnableOption ''
+        Accessibility preset (home-side companion to
+        nomarchy.system.accessibility.enable). Adjusts the Hyprland
+        Wayland session in three ways: slows input.repeat_rate to 25
+        (from 40) and input.repeat_delay to 1000 ms (from 600) so
+        holding a key isn't a runaway machine-gun for users with
+        low-mobility hands; binds SUPER+ALT+S to launch the Orca screen
+        reader (the system preset already puts orca on PATH); and is
+        the gate behind which a future high-contrast palette will hide.
+        Set this to the same value as nomarchy.system.accessibility.enable.
+      '';
     };
   };
 }

core/home/overrides.nix

@@ -1,97 +1,64 @@
 { config, lib, ... }:
 
-# File-based override system for Nomarchy
+# File-based override system for Nomarchy.
 #
-# Users can place config files in ~/.config/nomarchy/overrides/ to completely
-# replace upstream defaults. Override priority (highest to lowest):
-# 1. User Nix options
-# 2. User file overrides (~/.config/nomarchy/overrides/)
-# 3. Upstream defaults
+# When `nomarchy.overrides.enable = true` (default), every entry in
+# `nomarchy.overrides.paths` substitutes the `xdg.configFile.<key>.source`
+# Nomarchy ships by default. The substitution is done with `lib.mkForce`
+# so it wins over Nomarchy's own `lib.mkDefault` writes. Other fields on
+# the original entry (e.g. `recursive`) survive the merge.
 #
-# Supported override paths:
-# - hypr/             - Hyprland configs (bindings.conf, input.conf, etc.)
-# - waybar/           - Waybar config and style
-# - alacritty/        - Alacritty terminal config
-# - walker/           - Walker launcher config
-# - kitty/            - Kitty terminal config
-# - btop/             - Btop resource monitor config
-# - apps/             - Other application configs
+# Usage in a downstream home.nix:
+#
+#   nomarchy.overrides.paths = {
+#     "nomarchy/default/hypr/looknfeel.conf" = ./mine/looknfeel.conf;
+#     "waybar/style.css"                     = ./mine/waybar.css;
+#   };
+#
+# The keys are xdg.configFile paths (i.e. relative to ~/.config/). Drop-
+# in-a-dir discovery is intentionally not supported — Nix needs every
+# managed file declared at evaluation time, and the attrset is the
+# explicit-config shape the rest of the Nomarchy module surface uses.
 
 let
-  overridesDir = "${config.home.homeDirectory}/.config/nomarchy/overrides";
-
-  # Helper to get override from options
-  getOverrideOrDefault = { path, default }:
-    config.nomarchy.overrides.paths.${path} or default;
-
+  cfg = config.nomarchy.overrides;
 in
 {
   options.nomarchy.overrides = {
     enable = lib.mkOption {
       type = lib.types.bool;
       default = true;
-      description = "Whether to enable file-based override loading from ~/.config/nomarchy/overrides/";
+      description = ''
+        Whether file-based overrides in nomarchy.overrides.paths are
+        applied. Defaults to true so an empty `paths` is a no-op and
+        a populated one Just Works without a second toggle.
+      '';
     };
 
     paths = lib.mkOption {
       type = lib.types.attrsOf lib.types.path;
       default = {};
-      description = "Override paths discovered at build time. Populated by the override system.";
+      example = lib.literalExpression ''
+        {
+          "nomarchy/default/hypr/looknfeel.conf" = ./looknfeel.conf;
+          "waybar/style.css" = ./waybar.css;
+        }
+      '';
+      description = ''
+        Attribute set mapping xdg.configFile paths (relative to
+        ~/.config/) to Nix paths whose contents should replace the
+        Nomarchy-shipped source. Each entry deploys at lib.mkForce
+        priority so it overrides Nomarchy's lib.mkDefault writes;
+        recursive flags and other fields on the original entry are
+        preserved. Pointing at a path Nomarchy doesn't manage just
+        creates a new xdg.configFile entry.
+      '';
     };
   };
 
-  config = lib.mkIf config.nomarchy.overrides.enable {
-    # Create the overrides directory structure if it doesn't exist
-    home.activation.createOverridesDir = lib.hm.dag.entryAfter [ "writeBoundary" ] ''
-      mkdir -p "${overridesDir}"
-      mkdir -p "${overridesDir}/hypr"
-      mkdir -p "${overridesDir}/waybar"
-      mkdir -p "${overridesDir}/apps"
-    '';
-
-    # Document the override system
-    xdg.configFile."nomarchy/overrides/README.md".text = lib.mkDefault ''
-      # Nomarchy Configuration Overrides
-
-      Place files in this directory to override upstream Nomarchy defaults.
-
-      ## Directory Structure
-
-      ```
-      overrides/
-      ├── hypr/
-      │   ├── bindings.conf    # Keybindings
-      │   ├── input.conf       # Input settings
-      │   ├── monitors.conf    # Monitor layout
-      │   ├── rules.conf       # Window rules
-      │   └── autostart.conf   # Startup apps
-      ├── waybar/
-      │   ├── config.jsonc     # Waybar layout
-      │   └── style.css        # Waybar styling
-      ├── apps/
-      │   ├── alacritty.toml   # Terminal behavior
-      │   └── ...
-      └── README.md            # This file
-      ```
-
-      ## Override Priority
-
-      1. **Nix Options** (highest) - Set in your flake/config
-      2. **File Overrides** - Files in this directory
-      3. **Upstream Defaults** (lowest) - Nomarchy defaults
-
-      ## Usage
-
-      1. Copy the file you want to customize from the upstream config
-      2. Place it in the appropriate directory here
-      3. Edit to your preferences
-      4. Run `nixos-rebuild switch` or `home-manager switch`
-
-      ## Tips
-
-      - For keybindings, copy `~/.config/hypr/bindings.conf` to `overrides/hypr/`
-      - For Waybar styling, copy `~/.config/waybar/style.css` to `overrides/waybar/`
-      - Changes here persist across Nomarchy updates
-    '';
+  config = lib.mkIf cfg.enable {
+    xdg.configFile = lib.mapAttrs (_path: src: {
+      source = lib.mkForce src;
+    }) cfg.paths;
   };
 }

core/home/state.nix

@@ -1,42 +1,65 @@
-{ config, lib, ... }:
+{ config, lib, pkgs, ... }:
 
 let
   nomarchyLib = import ../../lib { inherit lib; };
+  # Single source of truth for default values when state.json is missing
+  # a key. Both core/system/options.nix and core/home/options.nix read
+  # from this same file — changing a default in one place updates
+  # everywhere. (Was: each consumer hardcoded its own `or X` literal,
+  # which is how the summer-night/nord split lived for so long.)
+  schema = import ../../lib/state-schema.nix { inherit lib; };
   assetsPath = ../../themes/palettes;
 
   # Read unified state from ~/.config/nomarchy/state.json
   togglesState = nomarchyLib.readHomeState config.home.homeDirectory;
+
+  cfg = config.nomarchy;
+  # The resolved values, in state.json's on-disk shape. Seeded into the file
+  # so runtime consumers (nomarchy-installed-summary, the setters) see the
+  # real defaults instead of a missing key — without this the summary shows
+  # "—" for theme/font/panel on any system the installer didn't write to.
+  seedJSON = builtins.toJSON {
+    inherit (cfg) theme wallpaper panelPosition nightlightTemperature;
+    font = cfg.fonts.monospace;
+    inherit (cfg.toggles) suspend screensaver idle nightlight waybar;
+    inherit (cfg.hyprland) gaps_in gaps_out border_size;
+  };
+  stateFile = "${config.home.homeDirectory}/.config/nomarchy/state.json";
 in
 {
+  # Every assignment uses lib.mkDefault so a downstream /etc/nixos/home.nix
+  # can override the value. The Nix options are now the declarative source
+  # of truth. state.json is purely seeded to keep runtime scripts (menu,
+  # summary) in sync with the Nix-level state.
   config = {
     nomarchy = {
-      toggles = {
-        suspend = togglesState.suspend or true;
-        screensaver = togglesState.screensaver or true;
-        idle = togglesState.idle or true;
-        nightlight = togglesState.nightlight or false;
-        waybar = togglesState.waybar or true;
-        skipVsCodeTheme = togglesState.skipVsCodeTheme or false;
-      };
-      nightlightTemperature = togglesState.nightlightTemperature or 4000;
-      theme = togglesState.theme or "summer-night";
-      wallpaper = togglesState.wallpaper or "";
-      hyprland = {
-        gaps_in = togglesState.hyprland.gaps_in or 5;
-        gaps_out = togglesState.hyprland.gaps_out or 10;
-        border_size = togglesState.hyprland.border_size or 2;
-      };
-      fonts.monospace = togglesState.font or "JetBrainsMono Nerd Font";
-
       # Derived properties from the theme directory
-      isLightMode = nomarchyLib.isThemeLightMode {
-        themeName = togglesState.theme or "summer-night";
+      isLightMode = lib.mkDefault (nomarchyLib.isThemeLightMode {
+        themeName = cfg.theme;
         inherit assetsPath;
-      };
-      iconsTheme = nomarchyLib.getIconsTheme {
-        themeName = togglesState.theme or "summer-night";
+      });
+      iconsTheme = lib.mkDefault (nomarchyLib.getIconsTheme {
+        themeName = cfg.theme;
         inherit assetsPath;
-      };
+      });
     };
+
+    # Backfill any state.json key the user hasn't set. Existing values always
+    # win (`defaults * existing`), so a user's theme/font/etc. and any
+    # runtime-only keys (welcome_done, …) are never clobbered — this only
+    # fills the gaps so the file reflects the system's actual defaults.
+    home.activation.seedNomarchyState = lib.hm.dag.entryAfter [ "writeBoundary" ] ''
+      run mkdir -p "$(dirname ${lib.escapeShellArg stateFile})"
+      tmp="$(${pkgs.coreutils}/bin/mktemp)"
+      # Build the next file contents in $tmp first; only the final move is
+      # guarded by `run` so a dry-run never mutates the real state file.
+      if [ -e ${lib.escapeShellArg stateFile} ]; then
+        ${pkgs.jq}/bin/jq -n --argjson d ${lib.escapeShellArg seedJSON} \
+          --slurpfile s ${lib.escapeShellArg stateFile} '$d * $s[0]' > "$tmp"
+      else
+        printf '%s\n' ${lib.escapeShellArg seedJSON} > "$tmp"
+      fi
+      run mv "$tmp" ${lib.escapeShellArg stateFile}
+    '';
   };
 }

core/system/accessibility.nix

@@ -0,0 +1,14 @@
+{ config, lib, pkgs, ... }:
+
+let
+  cfg = config.nomarchy.system.accessibility;
+in
+{
+  config = lib.mkIf cfg.enable {
+    services.gnome.at-spi2-core.enable = lib.mkDefault true;
+
+    environment.systemPackages = [ pkgs.orca ];
+
+    environment.variables.XCURSOR_SIZE = toString cfg.cursorSize;
+  };
+}

core/system/branding.nix

@@ -1,4 +1,4 @@
-{ ... }:
+{ lib, ... }:
 
 {
   # Identify the distribution as Nomarchy in /etc/os-release.
@@ -8,4 +8,10 @@
     distroId = "nomarchy";
     distroName = "Nomarchy";
   };
+
+  # Ensure the bootloader entries use Nomarchy instead of NixOS
+  boot.loader.grub.configurationName = lib.mkDefault "Nomarchy";
+  # For systemd-boot, NixOS 24.11+ uses distroName if available, 
+  # but some older versions or specific setups might need explicit labels.
+  # We use mkDefault so users can still override if they want.
 }

core/system/default.nix

@@ -9,6 +9,7 @@
     ./nix.nix
     ./scripts.nix
     ./systemd.nix
+    ./session.nix
     ./virtualization.nix
     ./fonts.nix
     ./hardware.nix
@@ -17,8 +18,13 @@
     ./network.nix
     ./impermanence.nix
     ./browser.nix
+    ./file-manager.nix
     # Tier 1 system features (all opt-in via nomarchy.system.*).
     ./snapper.nix
+    ./laptop.nix
+    ./desktop.nix
+    ./accessibility.nix
+    ./gaming.nix
     ./hibernate.nix
     ./containers.nix
     ./pam.nix
@@ -29,5 +35,7 @@
 
   time.timeZone = lib.mkDefault config.nomarchy.system.timezone;
 
+  boot.kernelPackages = lib.mkDefault pkgs.linuxPackages_latest;
+
   nixpkgs.config.allowUnfree = true;
 }

core/system/desktop.nix

@@ -0,0 +1,15 @@
+{ config, lib, ... }:
+
+let
+  cfg = config.nomarchy.system.desktop;
+in
+{
+  config = lib.mkIf cfg.enable {
+    powerManagement.cpuFreqGovernor = lib.mkDefault "performance";
+
+    # No-op until the user adds ZFS to boot.supportedFilesystems and a pool;
+    # then maintenance kicks in without further config.
+    services.zfs.autoScrub.enable = lib.mkDefault true;
+    services.zfs.trim.enable = lib.mkDefault true;
+  };
+}

core/system/file-manager.nix

@@ -0,0 +1,32 @@
+{ pkgs, lib, ... }:
+
+{
+  # Core system-side support for file management.
+  # This provides the backend services required by Thunar (and other file
+  # managers) to function correctly on a standalone compositor.
+
+  services.gvfs.enable = lib.mkDefault true;    # Mount, trash, and other file system operations
+  services.tumbler.enable = lib.mkDefault true; # Thumbnail support for images/videos/etc.
+
+  # Explicitly enable Thunar for D-Bus integration
+  programs.thunar.enable = lib.mkDefault true;
+
+  # Required for drive management (mount/unmount) and other privileged actions
+  security.polkit.enable = true;
+
+  # Allow Thunar to use gvfs (trash, network mounts, etc.)
+  programs.thunar.plugins = with pkgs.xfce; [
+    thunar-archive-plugin
+    thunar-volman
+    thunar-media-tags-plugin
+  ];
+
+  # Supporting utilities for Thunar and general file management
+  environment.systemPackages = with pkgs; [
+    ffmpegthumbnailer # Video thumbnails
+    libgsf            # ODF thumbnails
+    poppler-utils     # PDF thumbnails
+    xfce.exo          # Required for "Open Terminal Here" and other associations
+    shared-mime-info  # Standard MIME database
+  ];
+}

core/system/fonts.nix

@@ -5,7 +5,7 @@ let
     pname = "nomarchy-font";
     version = "1.0";
     # Point directly to the font file
-    src = ./../home/config/Nomarchy.ttf;
+    src = ./../branding/Nomarchy.ttf;
     # No archive to unpack
     unpackPhase = "true";
     installPhase = ''

core/system/gaming.nix

@@ -0,0 +1,44 @@
+{ config, lib, pkgs, ... }:
+
+let
+  cfg = config.nomarchy.system.gaming;
+in
+{
+  config = lib.mkIf cfg.enable {
+    programs.steam = {
+      enable = true;
+      remotePlay.openFirewall = lib.mkDefault true;
+      localNetworkGameTransfers.openFirewall = lib.mkDefault true;
+    };
+
+    # gamemode adjusts CPU governor and reschedules processes when a
+    # game requests it. The launching user must be in the `gamemode` group.
+    programs.gamemode.enable = true;
+
+    services.flatpak.enable = true;
+
+    # `services.flatpak.enable = true` ships flatpak but does NOT add any
+    # remotes — without a remote, `flatpak install` and the Discover GUI
+    # can't find anything. nixpkgs has no declarative remote-add API yet,
+    # so we run a one-shot system unit after flatpak.service is ready that
+    # adds the flathub remote idempotently (`--if-not-exists`). Lives under
+    # the gaming preset because Pillar 5 ships flatpak as part of the
+    # gaming wiring; if another preset later needs flatpak, lift this to a
+    # dedicated module.
+    systemd.services.nomarchy-flathub-init = {
+      description = "Register the Flathub remote on first start";
+      wantedBy = [ "multi-user.target" ];
+      after = [ "network-online.target" ];
+      wants = [ "network-online.target" ];
+      path = [ pkgs.flatpak ];
+      serviceConfig = {
+        Type = "oneshot";
+        RemainAfterExit = true;
+      };
+      script = ''
+        flatpak remote-add --if-not-exists flathub \
+          https://dl.flathub.org/repo/flathub.flatpakrepo
+      '';
+    };
+  };
+}

core/system/hardware.nix

@@ -10,9 +10,18 @@ in
     isT2Mac = mkEnableOption "Apple T2 MacBook specific hardware fixes";
     isFramework = mkEnableOption "Framework laptop specific hardware fixes";
     hasIPU7Camera = mkEnableOption "Intel IPU7 camera support";
+    fwupd = mkOption {
+      type = types.bool;
+      default = false;
+      description = "Whether to enable fwupd firmware update service.";
+    };
   };
 
   config = mkMerge [
+    (mkIf cfg.fwupd {
+      services.fwupd.enable = true;
+    })
+
     (mkIf cfg.isXPS {
       services.udev.extraRules = ''
         ACTION=="add", SUBSYSTEM=="pci", KERNEL=="0000:00:19.0", ATTR{power/control}="on"
@@ -61,8 +70,47 @@ in
     })
 
     (mkIf config.nomarchy.system.features.hybridGPU {
+      # supergfxd manages mode switching (Integrated / Hybrid / Vfio /
+      # AsusEgpu). It blacklists/unblacklists the nvidia kernel module via
+      # /etc/modprobe.d/ depending on the active mode. ExecStartPre sleep
+      # gives udev time to settle so the daemon doesn't see a half-attached
+      # GPU on cold boot.
       services.supergfxd.enable = true;
       systemd.services.supergfxd.serviceConfig.ExecStartPre = "-${pkgs.coreutils}/bin/sleep 5";
+
+      # Load the NVIDIA driver so the dGPU has something to drive. Without
+      # these, supergfxd switches modes successfully but the X/Wayland
+      # stack has no NVIDIA driver loaded — render-offload silently no-ops
+      # and Hyprland renders everything on the iGPU regardless of mode.
+      # mkDefault throughout so downstream system.nix can override
+      # (pin to a beta driver, flip to the open kernel module, etc.).
+      services.xserver.videoDrivers = lib.mkDefault [ "nvidia" ];
+      hardware.graphics.enable = lib.mkDefault true;
+      hardware.graphics.enable32Bit = lib.mkDefault true;
+      hardware.nvidia = {
+        modesetting.enable = lib.mkDefault true;
+        powerManagement.enable = lib.mkDefault true;
+        open = lib.mkDefault false;
+        package = lib.mkDefault config.boot.kernelPackages.nvidiaPackages.stable;
+      };
+      # Required for Wayland compositors (Hyprland) to render via NVIDIA.
+      boot.kernelParams = [ "nvidia-drm.modeset=1" ];
+
+      # PRIME render-offload (the part that lets `nvidia-offload <cmd>`
+      # actually use the dGPU) needs bus IDs, which are per-machine.
+      # We deliberately don't enable `hardware.nvidia.prime.offload.enable`
+      # here — without the correct intelBusId / nvidiaBusId the nvidia
+      # kernel module panics on load. The user adds this to their own
+      # /etc/nixos/system.nix after running `lspci -D`:
+      #
+      #   hardware.nvidia.prime = {
+      #     offload.enable = true;
+      #     offload.enableOffloadCmd = true;
+      #     intelBusId  = "PCI:0:2:0";   # or amdgpuBusId for AMD iGPU
+      #     nvidiaBusId = "PCI:1:0:0";
+      #   };
+      #
+      # See docs/OPTIONS.md for the full recipe.
     })
   ];
 }

core/system/hibernate.nix

@@ -15,9 +15,9 @@ in
       settings.Login = {
         HandleLidSwitch = lib.mkDefault "suspend-then-hibernate";
         HandleLidSwitchExternalPower = lib.mkDefault "suspend";
-        HandlePowerKey = "hibernate";
-        IdleAction = "suspend-then-hibernate";
-        IdleActionSec = toString (cfg.idleMinutes * 60);
+        HandlePowerKey = lib.mkDefault "hibernate";
+        IdleAction = lib.mkDefault "suspend-then-hibernate";
+        IdleActionSec = lib.mkDefault (toString (cfg.idleMinutes * 60));
       };
     };
   };

core/system/impermanence.nix

@@ -10,35 +10,93 @@ in
 
   options.nomarchy.system.impermanence = {
     enable = lib.mkEnableOption "Erase Your Darlings (Impermanence) root wipe on boot";
+
+    # The disko layout names the main LUKS mapping `crypted` on single-disk
+    # installs and `crypted_main` on multi-disk installs (see
+    # installer/disko-config.nix: `mainLuksName`). The rollback hook must
+    # mount the right device, otherwise initrd fails on every boot and the
+    # @ → root-blank snapshot is never restored.
+    mainLuksName = lib.mkOption {
+      type = lib.types.str;
+      default = "crypted";
+      description = ''
+        Name of the /dev/mapper entry holding the BTRFS root. Set to
+        "crypted_main" on multi-disk installs to match the disko layout.
+      '';
+    };
+
+    user = lib.mkOption {
+      type = lib.types.str;
+      default = "nomarchy";
+      description = ''
+        Primary user whose home subset (.ssh, .gnupg, keyrings, common
+        directories) survives the rootfs wipe. Must match the user
+        created via `users.users.<name>` — otherwise the persistence
+        block is silently inert and the user's home directory is wiped
+        on every boot. The installer writes this for you.
+      '';
+    };
   };
 
   config = lib.mkIf cfg.enable {
-    # 1. The Rollback Script: Runs in initrd before filesystems are mounted
-    boot.initrd.postDeviceCommands = lib.mkAfter ''
-      mkdir -p /btrfs_tmp
-      mount -o subvol=/ /dev/mapper/crypted /btrfs_tmp
-      
-      if [[ -e /btrfs_tmp/@ ]]; then
-          mkdir -p /btrfs_tmp/old_roots
-          timestamp=$(date --date="@$(stat -c %Y /btrfs_tmp/@)" "+%Y-%m-%-d_%H:%M:%S")
-          mv /btrfs_tmp/@ "/btrfs_tmp/old_roots/$timestamp"
-      fi
+    # 1. The Rollback Service: wipes the @ root subvolume back to a blank
+    #    snapshot before the real root is mounted. Plymouth enables systemd
+    #    stage-1 initrd distro-wide (themes/engine/plymouth.nix), and systemd
+    #    stage 1 rejects boot.initrd.postDeviceCommands — so this runs as a
+    #    systemd initrd unit ordered after the LUKS mapping opens and before
+    #    sysroot is mounted. initrdBin pulls in the binaries the script calls
+    #    (the systemd initrd doesn't ship coreutils/findutils/btrfs by default).
+    boot.initrd.systemd.initrdBin = [
+      pkgs.btrfs-progs
+      pkgs.coreutils
+      pkgs.util-linux
+      pkgs.findutils
+    ];
 
-      delete_subvolume_recursively() {
-          IFS=$'\n'
-          for i in $(btrfs subvolume list -o "$1" | cut -f 9- -d ' '); do
-              delete_subvolume_recursively "/btrfs_tmp/$i"
-          done
-          btrfs subvolume delete "$1"
-      }
+    boot.initrd.systemd.services.nomarchy-rollback = {
+      description = "Erase Your Darlings: roll the BTRFS root subvolume back to a blank snapshot";
+      wantedBy = [ "initrd.target" ];
+      after = [ "systemd-cryptsetup@${cfg.mainLuksName}.service" ];
+      before = [ "sysroot.mount" ];
+      unitConfig.DefaultDependencies = "no";
+      serviceConfig.Type = "oneshot";
+      script = ''
+        mkdir -p /btrfs_tmp
+        mount -o subvol=/ /dev/mapper/${cfg.mainLuksName} /btrfs_tmp
 
-      for i in $(find /btrfs_tmp/old_roots/ -maxdepth 1 -mtime +30); do
-          delete_subvolume_recursively "$i"
-      done
+        if [[ -e /btrfs_tmp/@ ]]; then
+            mkdir -p /btrfs_tmp/old_roots
+            timestamp=$(date --date="@$(stat -c %Y /btrfs_tmp/@)" "+%Y-%m-%-d_%H:%M:%S")
+            mv /btrfs_tmp/@ "/btrfs_tmp/old_roots/$timestamp"
+        fi
 
-      btrfs subvolume snapshot /btrfs_tmp/root-blank /btrfs_tmp/@
-      umount /btrfs_tmp
-    '';
+        delete_subvolume_recursively() {
+            IFS=$'\n'
+            for i in $(btrfs subvolume list -o "$1" | cut -f 9- -d ' '); do
+                delete_subvolume_recursively "/btrfs_tmp/$i"
+            done
+            btrfs subvolume delete "$1"
+        }
+
+        for i in $(find /btrfs_tmp/old_roots/ -maxdepth 1 -mtime +30); do
+            delete_subvolume_recursively "$i"
+        done
+
+        btrfs subvolume snapshot /btrfs_tmp/root-blank /btrfs_tmp/@
+        umount /btrfs_tmp
+      '';
+    };
+
+    # The impermanence module asserts that every filesystem it touches is
+    # available in early boot: the persistent-storage volume (/persist) and
+    # any volume it bind-mounts *into* — the user-persistence dirs land under
+    # /home, so the @home subvolume counts too. disko and
+    # nixos-generate-config leave neededForBoot at its default (false) on
+    # these subvolumes, which trips the assertion ("Please fix the following
+    # filesystems: /persist /home"). Declare it here, where the requirement
+    # originates.
+    fileSystems."/persist".neededForBoot = true;
+    fileSystems."/home".neededForBoot = true;
 
     # 2. Persistence Configuration: What survives the wipe
     environment.persistence."/persist" = {
@@ -58,7 +116,7 @@ in
         "/etc/machine-id"
         "/etc/supergfxd.conf"
       ];
-      users.nomarchy = {
+      users.${cfg.user} = {
         directories = [
           ".ssh"
           ".gnupg"

core/system/input-method.nix

@@ -11,12 +11,15 @@ in
     i18n.inputMethod = {
       enable = true;
       type = "fcitx5";
-      fcitx5.addons = with pkgs; [
-        fcitx5-mozc          # Japanese
-        fcitx5-chinese-addons # Chinese (pinyin/shuangpin)
-        fcitx5-table-extra    # Hanyu/Cangjie/etc.
-        fcitx5-gtk            # GTK4/3 client
-      ];
+      fcitx5 = {
+        waylandFrontend = true;
+        addons = with pkgs; [
+          fcitx5-mozc          # Japanese
+          kdePackages.fcitx5-chinese-addons
+          fcitx5-table-extra    # Hanyu/Cangjie/etc.
+          fcitx5-gtk            # GTK4/3 client
+        ];
+      };
     };
   };
 }

core/system/laptop.nix

@@ -0,0 +1,42 @@
+{ config, lib, pkgs, ... }:
+
+let
+  cfg = config.nomarchy.system.laptop;
+  hib = config.nomarchy.system.hibernation;
+  lidAction = if hib.enable then "suspend-then-hibernate" else "suspend";
+in
+{
+  config = lib.mkIf cfg.enable {
+    services.tlp = {
+      enable = lib.mkDefault true;
+      settings = {
+        CPU_SCALING_GOVERNOR_ON_AC = lib.mkDefault "performance";
+        CPU_SCALING_GOVERNOR_ON_BAT = lib.mkDefault "powersave";
+        CPU_BOOST_ON_BAT = lib.mkDefault 0;
+        PLATFORM_PROFILE_ON_AC = lib.mkDefault "balanced";
+        PLATFORM_PROFILE_ON_BAT = lib.mkDefault "low-power";
+        # Charge thresholds only honored on supported hardware (ThinkPad,
+        # some ASUS); a harmless warning is logged elsewhere.
+        START_CHARGE_THRESH_BAT0 = lib.mkDefault 75;
+        STOP_CHARGE_THRESH_BAT0 = lib.mkDefault 80;
+      };
+    };
+
+    # TLP and power-profiles-daemon both arbitrate CPU/EPP — NixOS asserts
+    # mutual exclusion. Opt out of the preset entirely to use PPD instead.
+    services.power-profiles-daemon.enable = lib.mkForce false;
+
+    services.upower.enable = lib.mkDefault true;
+    services.thermald.enable = lib.mkDefault cfg.thermald;
+
+    # Backlight write access for the `video` group, so the existing
+    # nomarchy-brightness-{display,keyboard} scripts run without root.
+    services.udev.packages = [ pkgs.brightnessctl ];
+
+    services.logind.settings.Login = {
+      HandleLidSwitch = lib.mkDefault lidAction;
+      HandleLidSwitchExternalPower = lib.mkDefault "suspend";
+      HandleLidSwitchDocked = lib.mkDefault "ignore";
+    };
+  };
+}

core/system/nix.nix

@@ -11,6 +11,14 @@
       
       # Optimize storage by hard-linking identical files
       auto-optimise-store = lib.mkDefault true;
+
+      # Bump the substituter download buffer from the 64 MiB default to
+      # 512 MiB. Large NARs (kernels, electron apps, the full NixOS
+      # closure on first install) overrun 64 MiB and Nix prints
+      # "download buffer is full" until the consumer catches up — the
+      # warning is harmless but slows substitution and looks like an
+      # error. 512 MiB comfortably covers everything in our closure.
+      download-buffer-size = 524288000;
     };
 
     # Populates NIX_PATH with the nixpkgs input from the flake.

core/system/options.nix

@@ -1,27 +1,32 @@
-{ lib, ... }:
+{ config, lib, pkgs, ... }:
 
+let
+  # Defaults live in lib/state-schema.nix so they can't drift between this
+  # file, core/home/options.nix, and core/home/state.nix's `or` fallbacks.
+  schema = import ../../lib/state-schema.nix { inherit lib; };
+in
 {
   options.nomarchy.system = {
     dns = lib.mkOption {
       type = lib.types.enum [ "Cloudflare" "Google" "DHCP" "Custom" ];
-      default = "DHCP";
+      default = schema.system.dns;
       description = "Selected DNS provider.";
     };
     customDns = lib.mkOption {
       type = lib.types.listOf lib.types.str;
-      default = [];
+      default = schema.system.customDns;
       description = "List of custom DNS servers.";
     };
     wifi = {
       powersave = lib.mkOption {
         type = lib.types.bool;
-        default = true;
+        default = schema.system.wifi.powersave;
         description = "Whether to enable wifi power saving.";
       };
     };
     timezone = lib.mkOption {
       type = lib.types.str;
-      default = "UTC";
+      default = schema.system.timezone;
       description = "System timezone.";
     };
     formFactor = lib.mkOption {
@@ -39,24 +44,27 @@
     features = {
       fingerprint = lib.mkOption {
         type = lib.types.bool;
-        default = false;
+        default = schema.system.features.fingerprint;
         description = "Whether to enable fingerprint support.";
       };
       fido2 = lib.mkOption {
         type = lib.types.bool;
-        default = false;
+        default = schema.system.features.fido2;
         description = "Whether to enable FIDO2 support.";
       };
       hybridGPU = lib.mkOption {
         type = lib.types.bool;
-        default = false;
+        default = schema.system.features.hybridGPU;
         description = "Whether to enable hybrid GPU support (supergfxd).";
       };
     };
     theme = lib.mkOption {
       type = lib.types.str;
-      default = "summer-night";
-      description = "Selected system theme.";
+      default = schema.system.theme;
+      description = ''
+        Selected system theme. This is the declarative source of truth for
+        system-level components (SDDM, Plymouth, browser policies).
+      '';
     };
 
     # ----- Tier 1 system features (all opt-in, no behavioural change off) ---
@@ -82,6 +90,81 @@
       };
     };
 
+    laptop = {
+      enable = lib.mkOption {
+        type = lib.types.bool;
+        default = config.nomarchy.system.formFactor == "laptop";
+        defaultText = lib.literalExpression ''config.nomarchy.system.formFactor == "laptop"'';
+        description = ''
+          Laptop power preset: TLP (with sane AC/battery governors),
+          `services.upower`, `services.thermald` (x86_64), a brightnessctl
+          udev rule, and a logind lid-switch policy. Force-disables
+          `services.power-profiles-daemon` (mutually exclusive with TLP).
+          Lid-close defers to `nomarchy.system.hibernation.enable`:
+          suspend-then-hibernate when on, suspend otherwise. Defaults on
+          when `formFactor = "laptop"`.
+        '';
+      };
+      thermald = lib.mkOption {
+        type = lib.types.bool;
+        default = pkgs.stdenv.hostPlatform.isx86_64;
+        defaultText = lib.literalExpression "pkgs.stdenv.hostPlatform.isx86_64";
+        description = ''
+          Enable `services.thermald` (Intel thermal daemon). Default true on
+          x86_64. Harmless no-op on AMD; gated off on aarch64.
+        '';
+      };
+    };
+
+    desktop = {
+      enable = lib.mkOption {
+        type = lib.types.bool;
+        default = config.nomarchy.system.formFactor == "desktop";
+        defaultText = lib.literalExpression ''config.nomarchy.system.formFactor == "desktop"'';
+        description = ''
+          Desktop preset: pins `powerManagement.cpuFreqGovernor` to
+          `"performance"` and enables `services.zfs.autoScrub` and
+          `services.zfs.trim` so a future ZFS pool gets sensible
+          maintenance without further config. The ZFS knobs are no-ops
+          until the user adds `boot.supportedFilesystems = [ "zfs" ]`
+          and a pool. Defaults on when `formFactor = "desktop"`. Battery
+          widget filtering is already handled by `formFactor` itself in
+          `features/desktop/waybar/default.nix`.
+        '';
+      };
+    };
+
+    accessibility = {
+      enable = lib.mkEnableOption ''
+        Accessibility preset: AT-SPI2 framework, the Orca screen reader
+        on PATH, and a larger default cursor size. Off by default —
+        accessibility is a personal preference, not a hardware-derived
+        signal. The Hyprland-side keybinding to launch Orca is a
+        separate roadmap item.
+      '';
+      cursorSize = lib.mkOption {
+        type = lib.types.int;
+        default = 32;
+        description = ''
+          XCURSOR_SIZE when accessibility is on. NixOS default is 24;
+          32 is a safer floor for low-vision users. Bump to 48 if the
+          user explicitly asks.
+        '';
+      };
+    };
+
+    gaming = {
+      enable = lib.mkEnableOption ''
+        Gaming preset: Steam (with remote-play firewall holes),
+        gamemode (CPU governor + nice on Steam launch via the user's
+        gamemode group), and flatpak. NOTE: flatpak's flathub remote
+        is not added declaratively — after first boot, run
+        `flatpak remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo`.
+        The Hyprland fullscreen-on-Steam-launch window rule is a
+        separate roadmap item.
+      '';
+    };
+
     containers = {
       enable = lib.mkEnableOption ''
         Rootless Podman with Docker compatibility (`docker` → `podman`),
@@ -96,6 +179,12 @@
           `libvirtd` group.
         '';
       };
+      docker = {
+        enable = lib.mkEnableOption ''
+          Docker daemon + docker-compose. The user must be in the `docker`
+          group.
+        '';
+      };
     };
 
     keyring = {
@@ -117,14 +206,5 @@
         most users want this off.
       '';
     };
-
-    voxtype = {
-      enable = lib.mkEnableOption ''
-        voxtype voice-typing integration. NOTE: voxtype is not packaged in
-        nixpkgs — when enabled, install voxtype yourself (e.g. via
-        `home.packages = [ (pkgs.callPackage … {}) ]`). With this off the
-        SUPER+CTRL+X keybinding and waybar widget are no-ops.
-      '';
-    };
   };
 }

core/system/scripts-derivation.nix

@@ -30,6 +30,10 @@ let
     bc
     supergfxctl
     systemd
+    fwupd
+    hyprland
+    swayosd
+    python3   # nomarchy-haptic-touchpad is a python3 script (Dell XPS service)
   ];
 in
 pkgs.stdenv.mkDerivation {
@@ -52,8 +56,7 @@ pkgs.stdenv.mkDerivation {
     for file in $out/bin/*; do
       if [ -f "$file" ]; then
         wrapProgram "$file" \
-          --prefix PATH : "$deps" \
-          --set NOMARCHY_PATH "/etc/nixos/nomarchy"
+          --prefix PATH : "$deps"
       fi
     done
   '';

core/system/scripts.nix

@@ -2,4 +2,13 @@
 
 {
   environment.systemPackages = [ pkgs.nomarchy-system-scripts ];
+
+  # /etc/nixos is owned by root, but `nomarchy-env-update` (and `nix
+  # flake` invocations) run as the user and shell out to git. Without
+  # this, git refuses with "dubious ownership in repository" and HM
+  # evaluation fails. Mark both the standard and impermanence-relocated
+  # paths as safe at the system level so every user is covered.
+  programs.git.config = {
+    safe.directory = [ "/etc/nixos" "/persist/etc/nixos" ];
+  };
 }

core/system/scripts/nomarchy-battery-capacity

@@ -1,4 +1,5 @@
 #!/bin/bash
+set -e
 
 # Returns the battery full capacity in Wh (rounded to whole number).
 # Used by nomarchy-battery-status for displaying battery capacity.

core/system/scripts/nomarchy-battery-monitor

@@ -1,4 +1,5 @@
 #!/bin/bash
+set -e
 
 # Designed to be run by systemd timer every 30 seconds and alerts if battery is low
 

core/system/scripts/nomarchy-battery-present

@@ -1,13 +0,0 @@
-#!/bin/bash
-
-# Returns true if a battery is present on the system.
-# Used by the battery monitor and other battery-related checks.
-
-for bat in /sys/class/power_supply/BAT*; do
-  [[ -r $bat/present ]] &&
-  [[ $(cat $bat/present) == "1" ]] &&
-  [[ $(cat $bat/type) == "Battery" ]] &&
-  exit 0
-done
-
-exit 1

core/system/scripts/nomarchy-battery-remaining

@@ -1,4 +1,5 @@
 #!/bin/bash
+set -e
 
 # Returns the battery percentage remaining as an integer.
 # Used by the battery monitor and the Ctrl + Shift + Super + B hotkey.

core/system/scripts/nomarchy-battery-remaining-time

@@ -1,4 +1,5 @@
 #!/bin/bash
+set -e
 
 # Returns the battery time remaining (to empty or full) in a compact format.
 

core/system/scripts/nomarchy-battery-status

@@ -1,4 +1,5 @@
 #!/bin/bash
+set -e
 
 # Returns a formatted battery status string with percentage and power draw/charge.
 # Used by the battery notification hotkey (Ctrl + Shift + Super + B).

core/system/scripts/nomarchy-brightness-display

@@ -1,4 +1,5 @@
 #!/bin/bash
+set -e
 
 # Adjust brightness on the most likely display device.
 # Usage: nomarchy-brightness-display <step>

core/system/scripts/nomarchy-brightness-display-apple

@@ -1,4 +1,5 @@
 #!/bin/bash
+set -e
 
 # Adjust the brightness on Apple Studio Displays and Apple XDR Displays using asdcontrol.
 

core/system/scripts/nomarchy-brightness-keyboard

@@ -1,4 +1,5 @@
 #!/bin/bash
+set -e
 
 # Adjust keyboard backlight brightness using available steps.
 # Usage: nomarchy-brightness-keyboard <up|down|cycle>

core/system/scripts/nomarchy-hibernation-available

@@ -1,4 +1,5 @@
 #!/bin/bash
+set -e
 
 # Check if hibernation is supported
 if [[ ! -f /sys/power/image_size ]]; then

core/system/scripts/nomarchy-hibernation-remove

@@ -1,4 +1,5 @@
 #!/bin/bash
+set -e
 
 # Removes hibernation setup: disables swap, removes swapfile, removes fstab entry,
 # removes resume hook, and removes suspend-then-hibernate configuration.

core/system/scripts/nomarchy-hibernation-setup

@@ -1,4 +1,5 @@
 #!/bin/bash
+set -e
 
 # Creates a swap file in the btrfs subvolume, adds the swap file to /etc/fstab,
 # adds a resume hook to mkinitcpio, and configures suspend-then-hibernate.

core/system/scripts/nomarchy-hw-asus-rog

@@ -1,4 +1,5 @@
 #!/bin/bash
+set -e
 
 # Detect whether the computer is an Asus ROG machine.
 

core/system/scripts/nomarchy-hw-match

@@ -1,4 +1,5 @@
 #!/bin/bash
+set -e
 
 # Match against the computer's DMI product name (case-insensitive).
 # Usage: nomarchy-hw-match "XPS"

core/system/scripts/nomarchy-hw-vulkan

@@ -1,4 +1,5 @@
 #!/bin/bash
+set -e
 
 # Detect whether Vulkan is available.
 

core/system/scripts/nomarchy-powerprofiles-list

@@ -1,4 +1,5 @@
 #!/bin/bash
+set -e
 
 # Returns a list of all the available power profiles on the system.
 # Used by the Nomarchy Menu under Setup > Power Profile.

core/system/scripts/nomarchy-restart-bluetooth

@@ -1,4 +1,5 @@
 #!/bin/bash
+set -e
 
 # Unblock and restart the bluetooth service.
 

core/system/scripts/nomarchy-restart-pipewire

@@ -1,4 +1,5 @@
 #!/bin/bash
+set -e
 
 # Restart the PipeWire audio service to fix audio issues or apply new configuration.
 

core/system/scripts/nomarchy-restart-trackpad

@@ -1,4 +1,5 @@
 #!/bin/bash
+set -e
 
 # Reload the intel_quicki2c driver to fix a dead trackpad.
 # The THC (Touch Host Controller) can fail to initialize interrupts

core/system/scripts/nomarchy-restart-wifi

@@ -1,4 +1,5 @@
 #!/bin/bash
+set -e
 
 # Unblock and restart the Wi-Fi service.
 

core/system/scripts/nomarchy-restart-xcompose

@@ -1,4 +1,5 @@
 #!/bin/bash
+set -e
 
 # Restart the XCompose input method service (fcitx5) to apply new compose key settings.
 

core/system/scripts/nomarchy-setup-dns

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+set -e
 
 # Configure DNS declaratively for Nomarchy NixOS.
 # Hybrid: updates /etc/nixos/state.json and runs sys-update.
@@ -13,7 +14,7 @@ fi
 
 case "$dns" in
 Cloudflare|Google|DHCP)
-  sudo jq --arg dns "$dns" '.dns = $dns' "$STATE_FILE" > /tmp/state.json && sudo mv /tmp/state.json "$STATE_FILE"
+  tmp=$(mktemp); sudo jq --arg dns "$dns" '.dns = $dns' "$STATE_FILE" > "$tmp" && sudo mv "$tmp" "$STATE_FILE"
   ;;
 
 Custom)
@@ -27,7 +28,7 @@ Custom)
 
   # Convert to JSON array safely
   dns_array=$(echo "$dns_servers" | jq -R 'split(" ")')
-  sudo jq --arg dns "Custom" --argjson servers "$dns_array" '.dns = $dns | .customDns = $servers' "$STATE_FILE" > /tmp/state.json && sudo mv /tmp/state.json "$STATE_FILE"
+  tmp=$(mktemp); sudo jq --arg dns "Custom" --argjson servers "$dns_array" '.dns = $dns | .customDns = $servers' "$STATE_FILE" > "$tmp" && sudo mv "$tmp" "$STATE_FILE"
   ;;
 esac
 

core/system/scripts/nomarchy-setup-fido2

@@ -1,17 +1,18 @@
 #!/usr/bin/env bash
+set -e
 
 # Configure FIDO2 support declaratively for Nomarchy NixOS.
 
 STATE_FILE="/etc/nixos/state.json"
 
 if [[ "--remove" == $1 ]]; then
-    sudo jq '.features.fido2 = false' "$STATE_FILE" > /tmp/state.json && sudo mv /tmp/state.json "$STATE_FILE"
+    tmp=$(mktemp); sudo jq '.features.fido2 = false' "$STATE_FILE" > "$tmp" && sudo mv "$tmp" "$STATE_FILE"
     echo "FIDO2 support disabled. Applying changes..."
     sudo nomarchy-sys-update
     exit 0
 fi
 
-sudo jq '.features.fido2 = true' "$STATE_FILE" > /tmp/state.json && sudo mv /tmp/state.json "$STATE_FILE"
+tmp=$(mktemp); sudo jq '.features.fido2 = true' "$STATE_FILE" > "$tmp" && sudo mv "$tmp" "$STATE_FILE"
 echo "FIDO2 support enabled. Applying changes..."
 sudo nomarchy-sys-update
 

core/system/scripts/nomarchy-setup-fingerprint

@@ -1,17 +1,18 @@
 #!/usr/bin/env bash
+set -e
 
 # Configure fingerprint support declaratively for Nomarchy NixOS.
 
 STATE_FILE="/etc/nixos/state.json"
 
 if [[ "--remove" == $1 ]]; then
-    sudo jq '.features.fingerprint = false' "$STATE_FILE" > /tmp/state.json && sudo mv /tmp/state.json "$STATE_FILE"
+    tmp=$(mktemp); sudo jq '.features.fingerprint = false' "$STATE_FILE" > "$tmp" && sudo mv "$tmp" "$STATE_FILE"
     echo "Fingerprint support disabled. Applying changes..."
     sudo nomarchy-sys-update
     exit 0
 fi
 
-sudo jq '.features.fingerprint = true' "$STATE_FILE" > /tmp/state.json && sudo mv /tmp/state.json "$STATE_FILE"
+tmp=$(mktemp); sudo jq '.features.fingerprint = true' "$STATE_FILE" > "$tmp" && sudo mv "$tmp" "$STATE_FILE"
 echo "Fingerprint support enabled. Applying changes..."
 sudo nomarchy-sys-update
 

core/system/scripts/nomarchy-sudo-keepalive

@@ -1,10 +0,0 @@
-#!/bin/bash
-
-# Prompt for sudo once and keep the credential alive in the background.
-# Source this script so the trap applies to the calling shell:
-#   source nomarchy-sudo-keepalive
-
-sudo -v
-while true; do sudo -n true; sleep 60; done 2>/dev/null &
-SUDO_KEEPALIVE_PID=$!
-trap "kill $SUDO_KEEPALIVE_PID 2>/dev/null" EXIT

core/system/scripts/nomarchy-sudo-passwordless-toggle

@@ -1,4 +1,5 @@
 #!/bin/bash
+set -e
 
 # Toggle passwordless sudo for the current user.
 # First run: enables passwordless sudo for 15 minutes (after confirmation).

core/system/scripts/nomarchy-sudo-reset

@@ -1,4 +1,5 @@
 #!/bin/bash
+set -e
 
 # Reset the sudo lockout/faillock for the current user.
 # This clears any failed authentication attempts that may have locked the user out.

core/system/scripts/nomarchy-swayosd-brightness

@@ -1,4 +1,5 @@
 #!/bin/bash
+set -e
 
 # Display brightness level using SwayOSD on the current monitor.
 # Usage: nomarchy-swayosd-brightness <percent>

core/system/scripts/nomarchy-swayosd-kbd-brightness

@@ -1,4 +1,5 @@
 #!/bin/bash
+set -e
 
 # Display keyboard brightness level using SwayOSD on the current monitor.
 # Usage: nomarchy-swayosd-kbd-brightness <percent>

core/system/scripts/nomarchy-system-logout

@@ -1,4 +1,5 @@
 #!/bin/bash
+set -e
 
 # Logout command that first closes all application windows (thus giving them a chance to save state),
 # then stops the session, returning to the SDDM login screen.

core/system/scripts/nomarchy-system-reboot

@@ -1,4 +1,5 @@
 #!/bin/bash
+set -e
 
 # Reboot command that first closes all application windows (thus giving them a chance to save state).
 # This is particularly helpful for applications like Chromium that otherwise won't shutdown cleanly.

core/system/scripts/nomarchy-system-shutdown

@@ -1,4 +1,5 @@
 #!/bin/bash
+set -e
 
 # Shutdown command that first closes all application windows (thus giving them a chance to save state).
 # This is particularly helpful for applications like Chromium that otherwise won't shutdown cleanly.

core/system/scripts/nomarchy-toggle-hybrid-gpu

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+set -e
 
 # Toggle dedicated vs integrated GPU mode via supergfxd (for hybrid gpu laptops, like Asus G14).
 # Declarative enablement + Runtime mode switching for Nomarchy NixOS.
@@ -8,7 +9,7 @@ STATE_FILE="/etc/nixos/state.json"
 # Check if supergfxd is enabled in config
 if [[ $(sudo jq -r '.features.hybridGPU // false' "$STATE_FILE") != "true" ]]; then
     if gum confirm "Hybrid GPU support is not enabled. Enable it now? (Requires sys-update)"; then
-        sudo jq '.features.hybridGPU = true' "$STATE_FILE" > /tmp/state.json && sudo mv /tmp/state.json "$STATE_FILE"
+        tmp=$(mktemp); sudo jq '.features.hybridGPU = true' "$STATE_FILE" > "$tmp" && sudo mv "$tmp" "$STATE_FILE"
         echo "Hybrid GPU support enabled in configuration. Applying changes..."
         sudo nomarchy-sys-update
         echo "Please run this command again after the update."

core/system/scripts/nomarchy-toggle-idle

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+set -e
 
 # Toggles the idle daemon (hypridle) between enabled and disabled.
 # Hybrid: updates state.json and provides instant feedback.
@@ -20,8 +21,7 @@ else
     notify-send -u low "  Stop locking computer when idle"
 fi
 
-TMP_JSON=$(mktemp)
-jq --argjson val "$NEW_VALUE" '.idle = $val' "$STATE_FILE" > "$TMP_JSON" && mv "$TMP_JSON" "$STATE_FILE"
+nomarchy-state-write idle "$NEW_VALUE" --type bool
 
 echo "Idle state set to $NEW_VALUE. Environment will be fully updated on next rebuild."
 

core/system/scripts/nomarchy-toggle-suspend

@@ -1,29 +1,5 @@
 #!/usr/bin/env bash
+set -e
 
-# Toggles the suspend menu option availability.
-# Hybrid: updates state.json and runs env-update for persistence.
-
-STATE_DIR="$HOME/.config/nomarchy"
-STATE_FILE="$STATE_DIR/state.json"
-mkdir -p "$STATE_DIR"
-
-# Initialize if doesn't exist
-[[ ! -f $STATE_FILE ]] && echo "{}" > "$STATE_FILE"
-
-# Get current state from env or state file
-if [[ $NOMARCHY_TOGGLE_SUSPEND == "false" ]]; then
-    NEW_VALUE="true"
-    notify-send -u low "   Suspend now available in system menu"
-else
-    NEW_VALUE="false"
-    notify-send -u low "   Suspend removed from system menu"
-fi
-
-# Update JSON using jq with --argjson for proper boolean handling
-TMP_JSON=$(mktemp)
-jq --argjson val "$NEW_VALUE" '.suspend = $val' "$STATE_FILE" > "$TMP_JSON" && mv "$TMP_JSON" "$STATE_FILE"
-
-echo "Suspend availability set to $NEW_VALUE. Updating environment..."
-
-# Run nomarchy-env-update to apply changes to the menu
-nomarchy-env-update
+# Execute system suspend
+systemctl suspend

core/system/scripts/nomarchy-tz-select

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+set -e
 
 # Select system timezone declaratively for Nomarchy NixOS.
 
@@ -6,7 +7,7 @@ STATE_FILE="/etc/nixos/state.json"
 
 timezone=$(timedatectl list-timezones | gum filter --height 20 --header "Set timezone") || exit 1
 
-sudo jq --arg tz "$timezone" '.timezone = $tz' "$STATE_FILE" > /tmp/state.json && sudo mv /tmp/state.json "$STATE_FILE"
+tmp=$(mktemp); sudo jq --arg tz "$timezone" '.timezone = $tz' "$STATE_FILE" > "$tmp" && sudo mv "$tmp" "$STATE_FILE"
 
 echo "Timezone is now set to $timezone. Applying changes..."
 sudo nomarchy-sys-update

core/system/scripts/nomarchy-update

@@ -1,41 +0,0 @@
-#!/usr/bin/env bash
-
-# Nomarchy Update Script
-# 1. Updates the flake inputs in the repository
-# 2. Applies system-wide NixOS changes
-# 3. Applies user-level Home Manager changes (Standalone)
-
-set -e
-
-# Detect the repository location
-if [ -f "/etc/nixos/flake.nix" ]; then
-    REPO_DIR="/etc/nixos"
-elif [ -f "/etc/nomarchy/flake.nix" ]; then
-    REPO_DIR="/etc/nomarchy"
-else
-    echo "Error: Nomarchy flake repository not found in /etc/nixos or /etc/nomarchy."
-    exit 1
-fi
-
-echo "--- Starting Nomarchy Update from $REPO_DIR ---"
-
-# 1. Update Flake Lock
-echo "Updating flake inputs..."
-sudo nix flake update --flake "$REPO_DIR"
-
-# 2. Rebuild System
-echo "Applying system-level updates..."
-sudo nixos-rebuild switch --flake "$REPO_DIR#default" --impure
-
-# 3. Rebuild Home Environment (Standalone)
-echo "Applying user-level updates..."
-home-manager switch --flake "$REPO_DIR#$USER" --impure
-
-# 4. Commit changes if it's a git repo
-if [ -d "$REPO_DIR/.git" ]; then
-    echo "Committing update to local history..."
-    sudo git -C "$REPO_DIR" add flake.lock
-    sudo git -C "$REPO_DIR" commit -m "chore: update system (flake.lock)" || echo "No lockfile changes to commit."
-fi
-
-echo "--- Nomarchy Update Complete ---"

core/system/scripts/nomarchy-update-time

@@ -1,4 +1,5 @@
 #!/bin/bash
+set -e
 
 echo "Updating time..."
 sudo systemctl restart systemd-timesyncd

core/system/scripts/nomarchy-wifi-powersave

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+set -e
 
 # Toggles wifi power saving declaratively.
 # Usage: nomarchy-wifi-powersave <on|off>
@@ -11,7 +12,7 @@ off) value="false" ;;
 *) echo "Usage: nomarchy-wifi-powersave <on|off>"; exit 1 ;;
 esac
 
-sudo jq --argjson val "$value" '.wifi.powersave = $val' "$STATE_FILE" > /tmp/state.json && sudo mv /tmp/state.json "$STATE_FILE"
+tmp=$(mktemp); sudo jq --argjson val "$value" '.wifi.powersave = $val' "$STATE_FILE" > "$tmp" && sudo mv "$tmp" "$STATE_FILE"
 
 echo "Wifi powersave set to $1. Applying changes..."
 sudo nomarchy-sys-update

core/system/session.nix

@@ -0,0 +1,19 @@
+{ config, lib, pkgs, ... }:
+
+# uwsm + Hyprland session manager wiring. Present on every Nomarchy install
+# regardless of any optional toggles — Hyprland is launched via uwsm so
+# it inherits a proper systemd graphical-session.target (which user services
+# like nomarchy-wallpaper, walker, and elephant chain off).
+#
+# Lived in core/system/virtualization.nix until 2026-05-22 by historical
+# accident; the placement had nothing to do with libvirt/docker.
+
+{
+  programs.uwsm = {
+    enable = lib.mkDefault true;
+    waylandCompositors.hyprland = {
+      binPath = "/run/current-system/sw/bin/Hyprland";
+      prettyName = "Hyprland";
+    };
+  };
+}

core/system/state.nix

@@ -2,19 +2,16 @@
 
 let
   nomarchyLib = import ../../lib { inherit lib; };
+  # Same canonical schema as core/home/state.nix and the options.nix
+  # files — keeps every state default in one place.
+  schema = import ../../lib/state-schema.nix { inherit lib; };
   systemState = nomarchyLib.readSystemState;
 in
 {
+  # Every assignment is lib.mkDefault so a downstream /etc/nixos/system.nix
+  # can still set e.g. `nomarchy.system.features.hybridGPU = true;`
+  # without colliding with the default values. The Nix options are now the
+  # declarative source of truth.
   config.nomarchy.system = {
-    dns = systemState.dns or "DHCP";
-    customDns = systemState.customDns or [];
-    wifi.powersave = systemState.wifi.powersave or true;
-    timezone = systemState.timezone or "UTC";
-    features = {
-      fingerprint = systemState.features.fingerprint or false;
-      fido2 = systemState.features.fido2 or false;
-      hybridGPU = systemState.features.hybridGPU or false;
-    };
-    theme = systemState.theme or "nord";
   };
 }

core/system/virtualization.nix

@@ -2,25 +2,25 @@
 
 let
   libvirt = config.nomarchy.system.virtualization.libvirt.enable;
+  docker = config.nomarchy.system.virtualization.docker.enable;
 in
 {
-  # uwsm + Hyprland session — present on every Nomarchy install regardless
-  # of the optional libvirt branch below.
-  programs.uwsm = {
-    enable = lib.mkDefault true;
-    waylandCompositors.hyprland = {
-      binPath = "/run/current-system/sw/bin/Hyprland";
-      prettyName = "Hyprland";
-    };
-  };
-
   # Optional: libvirt + virt-manager + OVMF. Toggle with
   # `nomarchy.system.virtualization.libvirt.enable = true;`. The user must
   # be in the `libvirtd` group to drive virsh / virt-manager.
   virtualisation.libvirtd.enable = lib.mkIf libvirt true;
-  environment.systemPackages = lib.mkIf libvirt (with pkgs; [
-    virt-manager
-    qemu
-    OVMF
-  ]);
+
+  # Optional: Docker + docker-compose.
+  virtualisation.docker.enable = lib.mkIf docker true;
+
+  environment.systemPackages = lib.mkMerge [
+    (lib.mkIf libvirt (with pkgs; [
+      virt-manager
+      qemu
+      OVMF
+    ]))
+    (lib.mkIf docker (with pkgs; [
+      docker-compose
+    ]))
+  ];
 }

docs/AGENT.md

@@ -8,11 +8,11 @@ If anything below conflicts with what the user just said, the user wins. If anyt
 
 ## 1. What Nomarchy is
 
-Nomarchy is a NixOS-based distribution that ships the Omarchy Hyprland desktop on a strictly declarative, flake-based foundation. It targets power users who want the polish of Omarchy without giving up reproducibility.
+Nomarchy is a NixOS-based distribution that ships a highly curated Hyprland desktop on a strictly declarative, flake-based foundation. It targets power users who want a polished, reproducible desktop environment.
 
 Concretely:
 
-- A flake at the repo root exposes `nixosModules.system` (foundational OS modules) and `nixosModules.home` (apps + desktop), plus three `nixosConfigurations` (`installerIso`, `installerIsoGraphical`, `default`) and standalone `homeConfigurations`.
+- A flake at the repo root exposes `nixosModules.system` (foundational OS modules) and `nixosModules.home` (apps + desktop), plus three `nixosConfigurations` (`nomarchy-installer`, `nomarchy-live`, `default`) and standalone `homeConfigurations`.
 - Downstream users get the distro by importing `nomarchy.nixosModules.system` and `nomarchy.nixosModules.home` from their own `/etc/nixos/flake.nix`. The Nomarchy installer generates that flake for them; an existing-NixOS user can hand-write it (see `docs/MIGRATION.md`).
 - A bash/`gum` TUI installer lives in `installer/install.sh` (~1100 lines). It auto-detects hardware via `installer/hardware-db.sh` (DMI + `lspci` + `BAT*` sysfs), prompts for the rest, and generates `flake.nix`, `system.nix`, `home.nix`, and `hardware-selection.nix` into `/mnt/etc/nixos/`.
 - The desktop is Hyprland + waybar + walker + a curated theming engine (`themes/`) with 22 palettes wired through Stylix.
@@ -41,8 +41,7 @@ core/         Foundational OS + user defaults. Don't put apps here.
     scripts/          Low-level system scripts (battery, brightness, hardware).
   home/         Home Manager modules.
     options.nix       Most home-side nomarchy.* options.
-    behavior.nix      nomarchy.behavior.* (deploy-default-config toggles).
-    overrides.nix     File-based overrides from ~/.config/nomarchy/overrides/.
+    overrides.nix     nomarchy.overrides.* (reserved; currently no-op — see ROADMAP).
     config/           Plain dotfiles symlinked into ~/.config.
 
 features/     Apps and desktop components. Add new apps here.
@@ -56,7 +55,7 @@ themes/       Theme engine + 22 palettes.
   engine/       Loader, Stylix glue, switcher, scripts (font, theme, wallpaper).
   palettes/     One subdir per palette (summer-night, tokyo-night, …).
 
-hosts/        ISO host configs (installerIso, installerIsoGraphical/live-iso).
+hosts/        ISO host configs (nomarchy-installer, nomarchy-live/live-iso).
 installer/    The bash/gum TUI + disko configs + hardware-db.sh.
 lib/          Shared Nix helpers (state schema, color resolution, paths).
 docs/         All long-form documentation. README.md stays at repo root.
@@ -65,10 +64,12 @@ bin/          Convenience wrappers for testing (nomarchy-test-installer, …).
 
 When you add a new feature:
 
-- A new app → `features/apps/<name>/default.nix` (+ optional `config/`), import it from `features/default.nix`.
+- A new app → `features/apps/<name>/default.nix` (+ optional `config/`), import it from `features/default.nix`. **All app modules must be opt-in** via a `nomarchy.apps.<name>.enable` option defined in `core/home/options.nix`. Enabling the module should also handle the `programs.<name>.enable` or `home.packages` installation where applicable.
 - A new system service → `core/system/<name>.nix`, import from `core/default.nix`.
 - A new toggle → add to `core/system/options.nix` or `core/home/options.nix`, wire it into the relevant module, document it in `docs/OPTIONS.md`.
 
+Core user-facing apps (browsers, file managers, media players) are **not** installed by the `features/default.nix` module list. Instead, they are managed in the downstream `home.nix` (which the installer pre-fills with defaults like `firefox` and `thunar`). This keeps the Nomarchy core modules focused on the desktop environment while giving the user explicit control over their app set.
+
 ---
 
 ## 3. Guardrails (non-negotiable unless the user overrides)
@@ -78,10 +79,11 @@ These are inherited from the established Nomarchy conventions. Violating them is
 1. **Declarative-first.** No imperative state in `core/`. Mutable state goes in `~/.config/nomarchy/state.json` or in NixOS / home-manager options.
 2. **Downstream-flake friendly.** Every behavior toggle is a `nomarchy.*` option documented in `docs/OPTIONS.md`. Adding a feature without a corresponding option is a bug.
 3. **Opt-in by default.** New features default off (or default to existing behavior). The installer can flip defaults *for the user being installed*, but the option must read sensibly when set by hand.
-4. **`lib.mkDefault` everywhere user might override.** If a downstream `system.nix` would reasonably want to change something Nomarchy sets, set it with `lib.mkDefault`. If it must not be overridden, use `lib.mkForce` and explain why in a comment.
+4. **`lib.mkDefault` on *scalars* the user might override — never on lists/attrsets that merge.** If a downstream `system.nix` would reasonably want to change a scalar Nomarchy sets (a string, bool, int), set it with `lib.mkDefault`. If it must not be overridden, use `lib.mkForce` and explain why. **But do not wrap a list or attrset option (`home.packages`, `environment.systemPackages`, `boot.kernelParams`, …) in `lib.mkDefault`** when other modules also contribute to it: the module system's `filterOverrides` keeps only the highest-priority definitions, so a `mkDefault` list is *silently discarded the moment any module sets that option at normal priority* — it doesn't merge, it vanishes. This dropped the entire curated `home.packages` (firefox, mako, hyprlock, …) and broke notifications + the lock screen distro-wide (`1117dcf`, `f34f59c`). A plain list/attrset is the correct default — it merges, and downstream can still add to it (to *remove* a default, downstream uses `mkForce`/filtering, which is rare).
 5. **Reuse before invent.** ~155 `nomarchy-*` scripts already exist across `core/system/scripts/`, `features/scripts/utils/`, `themes/engine/scripts/`. Grep before writing a new one.
 6. **No comments that narrate.** Don't write comments explaining *what* the code does. Only write a comment when the *why* is non-obvious — a hidden constraint, a subtle invariant, a workaround.
 7. **No backwards-compat shims.** If you remove a thing, remove it everywhere. No re-exports, no `// removed` markers.
+8. **Docs ride with the change.** Every change ships in the same commit as its doc updates — no follow-up "docs catch-up" PRs. The mapping is in §5.4 below; if a change touches something in that table and the matching doc didn't move with it, the change is incomplete.
 
 ---
 
@@ -121,17 +123,42 @@ Steps you should follow for any non-trivial change:
    - Read the relevant files. Don't infer.
 2. **Plan if it's non-trivial.** Tasks with three or more steps benefit from a TaskCreate list. Tasks that touch the architecture benefit from plan mode.
 3. **Reuse existing options and scripts.** Grep `core/system/options.nix`, `core/home/options.nix`, and the three script directories before adding anything.
-4. **Touch the docs in the same change.** New option → row in `docs/OPTIONS.md`. New script → row in `docs/SCRIPTS.md`. Roadmap item shipped → move it to the **Shipped** section at the bottom of `docs/ROADMAP.md`.
+4. **Touch the docs in the same change.** Use this table — if your change matches a row, the doc edit ships in the same commit. No exceptions, no follow-ups.
+
+   | If you change… | Update in the same commit |
+   | --- | --- |
+   | A `nomarchy.*` option (added, removed, renamed, default flipped, type changed, description changed) | `docs/OPTIONS.md` (matching row) **and** any other row that mentions it (e.g. `formFactor` is referenced from `laptop.enable`'s row) |
+   | A `nomarchy-*` script (added, removed, renamed) | `docs/SCRIPTS.md` — the pre-commit hook regenerates it; verify it's staged. If `core.hooksPath` isn't set, run `./bin/utils/nomarchy-docs-scripts --out docs/SCRIPTS.md` manually. |
+   | A keybinding (`bindd =` / `bindeld =`) under `core/home/config/.../hypr/` | `docs/KEYBINDINGS.md` — regenerate via `./bin/utils/nomarchy-docs-keybindings --out docs/KEYBINDINGS.md`; spot-check the README highlights still hold |
+   | A directory was added/removed/renamed under `core/`, `features/`, `themes/`, `hosts/`, `installer/`, `lib/`, `bin/`, or `docs/` | `docs/STRUCTURE.md` (tree + module logic prose) **and** §2 of this file (`docs/AGENT.md`) if the change is structural enough to affect new-agent onboarding |
+   | A feature module's behavior changed in a way an existing user would notice (a default flipped, a service started/stopped, a key remapped) | `README.md` if it's user-visible at the marketing level; otherwise just `docs/OPTIONS.md` |
+   | An installer prompt added/removed/reordered, or generated-file shape changed | `docs/MIGRATION.md` if it affects hand-written `flake.nix` setups; `installer/install.sh` heredoc comments if a generated file's shape changed |
+   | A theme palette added/removed, or the theming engine's contract changed | `docs/creating-themes.md` and the palette count in `README.md` |
+   | A roadmap item shipped | Move the entry to the **Shipped** section at the bottom of `docs/ROADMAP.md`. Don't delete — that's our changelog. |
+   | A roadmap item discovered (new scope) | Add a one-line row to **Now**, **Next**, or **Later** in `docs/ROADMAP.md`. Don't tell the user verbally and forget. |
+   | A workflow / convention / guardrail you'd want a future agent to follow | `docs/AGENT.md` (this file). |
+   | A new flake input, output, or major architectural decision | `docs/STRUCTURE.md` and `docs/AGENT.md` §1. |
+
+   Before declaring done, do one explicit pass: did the change cross any row above? If yes, is the matching doc edit staged? If you can't answer "yes" to both, you're not done.
 5. **Verify the change evaluates** (cheap, do this before declaring done):
    ```bash
    nix --extra-experimental-features 'nix-command flakes' flake check --no-build
    bash -n installer/install.sh   # if you touched it
    ```
+   `flake check` only evaluates the four *default* configs — it never flips a `nomarchy.*` toggle. If you touched anything that only fires when a toggle is enabled (impermanence, a preset, an opt-in feature, the per-palette system theme), also run the toggle matrix, which layers each opt-in scenario onto the default config and forces it:
+   ```bash
+   ./bin/utils/nomarchy-eval-matrix
+   ```
+   When you **add or rename an opt-in `nomarchy.*` option**, fold it into the relevant combined scenario in the `scenarios` attrset in that script (the scenarios bundle many compatible toggles per eval to stay fast on the CI runner) — otherwise the new surface is unverified and the next eval-time bug in it ships silently (this is exactly how the impermanence assertion and the vscode option rename reached `main`). The matrix also runs in CI (`.gitea/workflows/check.yml`).
+   First clone? Enable the repo's pre-commit hook so `docs/SCRIPTS.md` regenerates whenever you add/modify/remove a `nomarchy-*` script:
+   ```bash
+   git config core.hooksPath .githooks
+   ```
    For installer changes, also do a dry-run end-to-end:
    ```bash
    sudo /etc/install.sh --dry-run    # in the live ISO or VM
    ```
-   For waybar / Hyprland visual changes, the only reliable check is booting the live ISO with `nomarchy-test-live-iso`. If you can't boot it, **say so** rather than claiming success.
+   For waybar / Hyprland visual changes, boot it and look. On a host with KVM you can do this headless: `nix build .#nixosConfigurations.default.config.system.build.vm`, run its `bin/run-*-vm` with `QEMU_OPTS="-display none -monitor unix:/tmp/mon.sock,server,nowait -vga none"`, then `echo "screendump /tmp/s.ppm" | socat - unix-connect:/tmp/mon.sock`, convert PPM→PNG, and inspect it (this is how the first Pillar 9 pass caught the boot-time Hyprland config-error overlay). The `nomarchy-test-live-iso` / `installerVm` flows are the ISO-side equivalents. If you genuinely can't boot anything, **say so** rather than claiming a visual change works. See ROADMAP §9 (Live VM runtime QA) for the full method.
 6. **Commit narrowly.** One concept per commit. The commit subject is `<type>: <imperative summary>` (`feat:`, `fix:`, `docs:`, `chore:`). The body explains the why.
 7. **Push only when the user asks.** Local commits are free; pushing publishes.
 
@@ -174,9 +201,16 @@ in { ... }
 
 `nomarchy.system.formFactor` and `nomarchy.formFactor` are the two halves of the same flag (system + home). Default `"laptop"`. The installer auto-detects via `compgen -G "/sys/class/power_supply/BAT*"` and writes the explicit value into both generated files. Use this option to gate any laptop-only UI / service.
 
-### State (`state.json`)
+### Hybrid State (`state.json` + `nomarchy-state.nix`)
 
-Theme, font, wallpaper, and a few feature toggles live in `~/.config/nomarchy/state.json` so they can change without a rebuild. Schema is in `lib/state-schema.nix`. The Home Manager evaluator reads it via `lib/default.nix`. **Don't add new state without justifying it** — most "state" should be a NixOS option instead.
+Nomarchy uses a hybrid model to bridge the gap between runtime UI discovery and declarative Nix persistence.
+
+1.  **Runtime (`state.json`):** Located at `~/.config/nomarchy/state.json`. Consumed by scripts for instant session reloads (Waybar, Walker, etc.).
+2.  **Declarative (`nomarchy-state.nix`):** Located at `/etc/nixos/nomarchy-state.nix`. This file is the primary authority for Nix evaluation and is imported by `home.nix`.
+3.  **The Sync:** Whenever a script calls `nomarchy-state-write`, the `nomarchy-sync-nix-state` helper is triggered. It mirrors the current UI state into the `.nix` file automatically.
+4.  **Solidification:** To make a UI change permanent, the user (or script) runs `nomarchy-env-update`, which performs a fast `home-manager switch`.
+
+When adding new configuration options that should be script-manageable, ensure they are added to the sync logic in `features/scripts/utils/nomarchy-sync-nix-state`.
 
 ### Scripts derivation
 

docs/HOOKS.md

@@ -0,0 +1,57 @@
+# Nomarchy Runtime Hooks
+
+Hooks allow you to run custom bash scripts when specific system events occur. They are the primary way to extend Nomarchy's behavior without modifying the core Nix configuration.
+
+## 1. How it works
+
+Hooks are simple bash scripts located in `~/.config/nomarchy/hooks/`. 
+
+When a supported event occurs, Nomarchy checks for a file with the corresponding name in that directory. If the file exists, it is executed.
+
+- **Location:** `~/.config/nomarchy/hooks/<hook-name>`
+- **Language:** Bash (or any executable script with a shebang).
+- **Execution:** Synchronous. The calling Nomarchy script waits for your hook to finish.
+
+## 2. Available Hooks
+
+| Hook Name | Triggered when... | Arguments |
+| --- | --- | --- |
+| `post-install` | The `nomarchy-welcome` wizard finishes. | None |
+| `post-update` | `nomarchy-env-update` finishes successfully. | None |
+| `theme-set` | A new system theme is applied. | `$1`: theme-id (e.g. `nord`) |
+| `font-set` | A new system font is applied. | `$1`: font name (e.g. `JetBrainsMono Nerd Font`) |
+| `battery-low` | Battery drops below 15% (laptop only). | `$1`: Current percentage |
+
+## 3. Examples
+
+### Auto-sync dotfiles after update
+Create `~/.config/nomarchy/hooks/post-update`:
+```bash
+#!/bin/bash
+notify-send "Nomarchy" "Syncing personal dotfiles..."
+git -C ~/Projects/dotfiles pull && git -C ~/Projects/dotfiles push
+```
+
+### Apply custom color overrides after theme change
+Create `~/.config/nomarchy/hooks/theme-set`:
+```bash
+#!/bin/bash
+# Re-apply a specific transparency hack that Stylix might have overwritten
+hyprctl keyword decoration:active_opacity 0.95
+```
+
+## 4. Samples
+
+Nomarchy ships sample hooks with the `.sample` extension. You can use these as a starting point by copying them:
+
+```bash
+cp ~/.config/nomarchy/hooks/post-install.sample ~/.config/nomarchy/hooks/post-install
+chmod +x ~/.config/nomarchy/hooks/post-install
+```
+
+## 5. Development
+
+If you want to trigger a hook manually for testing:
+```bash
+nomarchy-hook <name> [args...]
+```

docs/KEYBINDINGS.md

@@ -52,70 +52,12 @@ _Source: `core/home/config/nomarchy/default/hypr/bindings/utilities.conf`_
 | SUPER CTRL | B | Bluetooth controls |
 | SUPER CTRL | W | Wifi controls |
 | SUPER CTRL | T | Activity |
-| SUPER CTRL | X | Toggle dictation |
 | SUPER CTRL | Z | Zoom in |
 | SUPER CTRL ALT | Z | Reset zoom |
 | SUPER CTRL | L | Lock system |
 
 ## Tiling
 
-_Source: `core/home/config/nomarchy/default/hypr/bindings/tiling.conf`_
-
-| Modifiers | Key | Action |
-| --- | --- | --- |
-| SUPER | Q | Close window |
-| CTRL ALT | DELETE | Close all windows |
-| SUPER | J | Toggle window split |
-| SUPER | P | Pseudo window |
-| SUPER SHIFT | V | Toggle window floating/tiling |
-| SHIFT | F11 | Force full screen |
-| ALT | F11 | Full width |
-| SUPER | LEFT | Move focus left |
-| SUPER | RIGHT | Move focus right |
-| SUPER | UP | Move focus up |
-| SUPER | DOWN | Move focus down |
-| SUPER | 1 | Switch to workspace 1 |
-| SUPER | 2 | Switch to workspace 2 |
-| SUPER | 3 | Switch to workspace 3 |
-| SUPER | 4 | Switch to workspace 4 |
-| SUPER | 5 | Switch to workspace 5 |
-| SUPER | 6 | Switch to workspace 6 |
-| SUPER | 7 | Switch to workspace 7 |
-| SUPER | 8 | Switch to workspace 8 |
-| SUPER | 9 | Switch to workspace 9 |
-| SUPER | 0 | Switch to workspace 10 |
-| SUPER SHIFT | 1 | Move window to workspace 1 |
-| SUPER SHIFT | 2 | Move window to workspace 2 |
-| SUPER SHIFT | 3 | Move window to workspace 3 |
-| SUPER SHIFT | 4 | Move window to workspace 4 |
-| SUPER SHIFT | 5 | Move window to workspace 5 |
-| SUPER SHIFT | 6 | Move window to workspace 6 |
-| SUPER SHIFT | 7 | Move window to workspace 7 |
-| SUPER SHIFT | 8 | Move window to workspace 8 |
-| SUPER SHIFT | 9 | Move window to workspace 9 |
-| SUPER SHIFT | 0 | Move window to workspace 10 |
-| SUPER | TAB | Next workspace |
-| SUPER SHIFT | TAB | Previous workspace |
-| SUPER CTRL | TAB | Former workspace |
-| SUPER SHIFT | LEFT | Swap window to the left |
-| SUPER SHIFT | RIGHT | Swap window to the right |
-| SUPER SHIFT | UP | Swap window up |
-| SUPER SHIFT | DOWN | Swap window down |
-| ALT | TAB | Cycle to next window |
-| ALT SHIFT | TAB | Cycle to prev window |
-| ALT | TAB | Reveal active window on top |
-| ALT SHIFT | TAB | Reveal active window on top |
-| SUPER | code:20 | Expand window left |
-| SUPER | code:21 | Shrink window left |
-| SUPER SHIFT | code:20 | Shrink window up |
-| SUPER SHIFT | code:21 | Expand window down |
-| SUPER | MOUSE_DOWN | Scroll active workspace forward |
-| SUPER | MOUSE_UP | Scroll active workspace backward |
-| SUPER | mouse:272 | Move window |
-| SUPER | mouse:273 | Resize window |
-
-## Tiling (v2)
-
 _Source: `core/home/config/nomarchy/default/hypr/bindings/tiling-v2.conf`_
 
 | Modifiers | Key | Action |

docs/MIGRATION.md

@@ -122,18 +122,45 @@ create minimal versions to start:
 ```nix
 { pkgs, ... }:
 {
+  imports = [
+    # Machine-managed state (theme, font, toggles).
+    # UI scripts update this file automatically.
+    ./nomarchy-state.nix
+  ];
+
   home.packages = with pkgs; [
-    btop
+    firefox
+    xfce.thunar
+    imv
+    mpv
     fastfetch
     chromium
-    # …add anything you want; firefox/thunar/mpv/mako/etc. ship with Nomarchy.
+    # …add anything you want; mako/hyprlock/swww/rofi/etc. ship with Nomarchy.
   ];
+
+  # Enable Nomarchy's curated app configurations
+  nomarchy.apps = {
+    alacritty.enable = true;
+    btop.enable = true;
+    elephant.enable = true;
+    swayosd.enable = true;
+    walker.enable = true;
+    vscode.enable = true;
+  };
 }
 ```
 
+Since you are migrating manually, you'll need to generate the initial
+`nomarchy-state.nix` so the import doesn't fail. Run this once:
+
+```bash
+# Seed the initial Nix state from the defaults
+nomarchy-sync-nix-state
+```
+
 Move any user/services/packages you had in `configuration.nix` over to
 `system.nix`. Do **not** redefine things Nomarchy already provides (display
-manager, Hyprland, PipeWire, NetworkManager) unless you want to override
+...manager, Hyprland, PipeWire, NetworkManager) unless you want to override
 them — see the [conflicts](#conflicts-to-resolve-before-rebuild) section.
 
 ## 3. (Optional) Pick up hardware-specific tuning
@@ -210,12 +237,15 @@ and it's whichever has higher Nix priority. Fix these explicitly:
 | Graphics | `hardware.graphics.enable = true` (was `hardware.opengl`) | Probably already enabled — fine |
 | User groups | needs `video render networkmanager` | Add to your `users.users.<user>.extraGroups` |
 | `/etc/os-release` | `ID=nomarchy`, `NAME=Nomarchy` | A few third-party scripts grep `ID=nixos` — adjust them or rely on `ID_LIKE` (TBD) |
-| autoLogin | `enable = true; user = "nomarchy";` (mkDefault) | Override with `services.displayManager.autoLogin.user = "<your user>"` or disable |
+| autoLogin | `enable = false; user = "nomarchy";` (mkDefault) | Off by default — opt in with `services.displayManager.autoLogin = { enable = true; user = "<your user>"; };` if you want it |
 
 Impermanence is **off** unless you set `nomarchy.system.impermanence.enable = true`,
 and it requires a BTRFS layout with a `root-blank` snapshot. Don't enable it
 on an existing install — the live ISO is the right path for that.
 
+If your first rebuild errors out, the five most common failures and their fixes
+live in [Troubleshooting](TROUBLESHOOTING.md).
+
 ---
 
 ## Fallback: clean install via the live ISO
@@ -229,7 +259,7 @@ nomarchy-test-live-iso       # boots the ISO in QEMU to evaluate
 The ISO autologins to a Hyprland live session that points you at:
 
 - `sudo /etc/install.sh` — install (BTRFS + LUKS + subvolumes per
-  `installer/disko-golden.nix`, auto-detects hardware via `hardware-db.sh`,
+  `installer/disko-config.nix`, auto-detects hardware via `hardware-db.sh`,
   runs `home-manager switch` inside `nixos-enter` so the first login is
   fully themed).
 - `sudo /etc/install.sh --dry-run` — generate the flake into a tmpdir and
@@ -239,6 +269,20 @@ The ISO autologins to a Hyprland live session that points you at:
 After install, the system at `/etc/nixos/` is the same shape this guide
 produces by hand.
 
+**Multi-disk (BTRFS RAID) caveat.** If you select more than one target drive,
+disko builds a multi-device BTRFS spanning one LUKS container per disk. The
+extra containers are invisible to `nixos-generate-config` (every subvolume
+mounts via the *main* `/dev/mapper/crypted_main`, so it only ever emits a
+`boot.initrd.luks.devices` entry for the main drive). The installer therefore
+writes the missing entries — plus the `x-systemd.requires=` mount options that
+make systemd-initrd wait for every member — into `hardware-selection.nix`.
+If you hand-write a multi-disk flake instead of using the installer, you must
+add, for each extra drive, `boot.initrd.luks.devices."<mapper>".device =
+"/dev/disk/by-uuid/<luks-partition-uuid>";` (mapper name = `crypted_` + the
+device path with `/` and `-` replaced by `_`, e.g. `/dev/sdb` →
+`crypted__dev_sdb`); without it the array can't be assembled and the system
+hangs at boot.
+
 ---
 
 ## Verification (in-place migration)

docs/OPTIONS.md

@@ -35,9 +35,9 @@ Defined in `core/system/options.nix`; wired in `core/system/network.nix`.
 
 ### `nomarchy.system.formFactor`
 
-`enum [ "laptop" "desktop" ]`, default `"laptop"`. Drives UI affordances and (eventually) lid handling / TLP. The installer auto-detects via `/sys/class/power_supply/BAT*`. The default is `"laptop"` because the battery widget renders empty when no battery is present — safe on a desktop, useful on a laptop.
+`enum [ "laptop" "desktop" ]`, default `"laptop"`. Drives UI affordances and the laptop power preset. The installer auto-detects via `/sys/class/power_supply/BAT*`. The default is `"laptop"` because the battery widget renders empty when no battery is present — safe on a desktop, useful on a laptop.
 
-Wired in `features/desktop/waybar/default.nix` (filters the battery widget out on desktop) and `features/scripts/battery-monitor.nix` (skips the timer on desktop).
+Wired in `features/desktop/waybar/default.nix` (filters the battery widget out on desktop), `features/scripts/battery-monitor.nix` (skips the timer on desktop), and `nomarchy.system.laptop.enable` (defaults true when this is `"laptop"`).
 
 ### `nomarchy.system.theme`
 
@@ -53,7 +53,25 @@ Wired in `features/desktop/waybar/default.nix` (filters the battery widget out o
 
 ### `nomarchy.system.features.hybridGPU`
 
-`bool`, default `false`. Enables `services.supergfxd.enable` for laptops with switchable GPUs.
+`bool`, default `false`. NVIDIA-hybrid laptop support. Wires:
+
+- `services.supergfxd.enable` for runtime mode switching (`Integrated` / `Hybrid` / `Vfio` / `AsusEgpu`), driven by `nomarchy-toggle-hybrid-gpu`.
+- The NVIDIA driver stack (`services.xserver.videoDrivers = ["nvidia"]`, `hardware.graphics.{enable,enable32Bit}`, `hardware.nvidia.{modesetting,powerManagement}.enable`, `boot.kernelParams = ["nvidia-drm.modeset=1"]`).
+
+All driver knobs use `lib.mkDefault`, so a downstream `system.nix` can pin a beta driver or flip to the open kernel module without forking the module.
+
+**You still have to add bus IDs** — they're per-machine and can't be derived from any flag. Find them with `lspci -D | grep -E 'VGA|3D'`, then in your `/etc/nixos/system.nix`:
+
+```nix
+hardware.nvidia.prime = {
+  offload.enable = true;
+  offload.enableOffloadCmd = true;
+  intelBusId  = "PCI:0:2:0";   # or `amdgpuBusId` for AMD iGPU
+  nvidiaBusId = "PCI:1:0:0";
+};
+```
+
+Without prime config, supergfxd still switches modes but render-offload via `nvidia-offload <cmd>` is unavailable.
 
 ### `nomarchy.system.snapper.enable`
 
@@ -67,6 +85,30 @@ Wired in `features/desktop/waybar/default.nix` (filters the battery widget out o
 
 `int`, default `30`. Idle minutes before suspend-then-hibernate fires.
 
+### `nomarchy.system.laptop.enable`
+
+`bool`, default `nomarchy.system.formFactor == "laptop"`. Laptop power preset: TLP (with sane AC/battery governors and ThinkPad-style 75/80 charge thresholds), `services.upower`, `services.thermald` (gated by `laptop.thermald`), and a brightnessctl udev rule so the existing `nomarchy-brightness-{display,keyboard}` scripts run without root. Force-disables `services.power-profiles-daemon` (mutually exclusive with TLP) — to use PPD instead, set `laptop.enable = false` and wire it yourself. Lid-close action defers to `nomarchy.system.hibernation.enable`: `suspend-then-hibernate` when on, `suspend` otherwise. Charge thresholds are only honored on supported hardware (ThinkPad, some ASUS); harmless warning elsewhere.
+
+### `nomarchy.system.laptop.thermald`
+
+`bool`, default `true` on x86_64. Enables `services.thermald` (Intel thermal daemon). Harmless no-op on AMD; gated off on aarch64.
+
+### `nomarchy.system.desktop.enable`
+
+`bool`, default `nomarchy.system.formFactor == "desktop"`. Desktop preset: pins `powerManagement.cpuFreqGovernor` to `"performance"` (via `mkDefault`) and enables `services.zfs.autoScrub` + `services.zfs.trim` so a future ZFS pool gets sensible maintenance without further config. The ZFS knobs are no-ops until you add `boot.supportedFilesystems = [ "zfs" ]` (plus `networking.hostId`) and a pool. Battery-widget filtering is handled by `formFactor` itself, so this preset doesn't repeat it.
+
+### `nomarchy.system.accessibility.enable`
+
+`bool`, default `false`. Accessibility preset: enables `services.gnome.at-spi2-core` (AT-SPI2 framework), installs `pkgs.orca` (screen reader) into `environment.systemPackages`, and sets `XCURSOR_SIZE` to `accessibility.cursorSize`. Off by default — accessibility is a personal preference, not hardware-derived. The Hyprland-side bits (slower key-repeat, Orca launch keybinding, high-contrast palette) are a separate roadmap item.
+
+### `nomarchy.system.accessibility.cursorSize`
+
+`int`, default `32`. `XCURSOR_SIZE` when `accessibility.enable = true`. NixOS default is 24; 32 is a safer floor for low-vision users.
+
+### `nomarchy.system.gaming.enable`
+
+`bool`, default `false`. Gaming preset: enables `programs.steam` (with `remotePlay` and `localNetworkGameTransfers` firewall holes opened by `mkDefault`), `programs.gamemode` (the launching user must be in the `gamemode` group), and `services.flatpak`. The flathub remote isn't added declaratively — after first boot, run `flatpak remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo`. Pair with the home-side companion `nomarchy.gaming.enable` for the Hyprland fullscreen-on-Steam-launch window rule.
+
 ### `nomarchy.system.containers.enable`
 
 `bool`, default `false`. Rootless Podman with Docker compatibility (`docker` → `podman`), plus `podman-compose`, `podman-tui`, and `dive`.
@@ -75,6 +117,10 @@ Wired in `features/desktop/waybar/default.nix` (filters the battery widget out o
 
 `bool`, default `false`. libvirt daemon, virt-manager, and OVMF. Add your user to the `libvirtd` group.
 
+### `nomarchy.system.virtualization.docker.enable`
+
+`bool`, default `false`. Docker daemon and docker-compose. Add your user to the `docker` group.
+
 ### `nomarchy.system.keyring.enable`
 
 `bool`, default `true`. Auto-unlock GNOME Keyring at login and route SSH keys through `gcr-ssh-agent`. On by default — near-universal QoL improvement.
@@ -83,10 +129,6 @@ Wired in `features/desktop/waybar/default.nix` (filters the battery widget out o
 
 `bool`, default `false`. fcitx5 input method for CJK / IME. Wires NixOS's `i18n.inputMethod` and autostarts `fcitx5-daemon`.
 
-### `nomarchy.system.voxtype.enable`
-
-`bool`, default `false`. voxtype voice-typing integration. voxtype isn't packaged in nixpkgs — when you enable this, install voxtype yourself (e.g. `home.packages = [ (pkgs.callPackage … {}) ]`). With this off the `SUPER+CTRL+X` keybinding and waybar widget are no-ops.
-
 ### `nomarchy.hardware.isXPS`
 
 `bool`, default `false`. Dell XPS fixes — haptic touchpad service and PCI/I²C power-control udev rules.
@@ -99,14 +141,26 @@ Wired in `features/desktop/waybar/default.nix` (filters the battery widget out o
 
 `bool`, default `false`. Framework laptop QMK HID udev rule.
 
+### `nomarchy.hardware.fwupd`
+
+`bool`, default `false`. Enables `services.fwupd` firmware update service.
+
 ### `nomarchy.hardware.hasIPU7Camera`
 
 `bool`, default `false`. Intel IPU7 camera support (kernel modules + firmware).
 
-### `impermanence.enable`
+### `nomarchy.system.impermanence.enable`
 
 `bool`, default `false`. Erase Your Darlings root wipe on boot. Defined in `core/system/impermanence.nix`. The installer writes the flag based on the impermanence prompt.
 
+### `nomarchy.system.impermanence.mainLuksName`
+
+`str`, default `"crypted"`. Name of the `/dev/mapper` entry holding the BTRFS root. The disko layout uses `"crypted"` on single-disk installs and `"crypted_main"` once multiple drives are selected — the installer writes the matching value automatically.
+
+### `nomarchy.system.impermanence.user`
+
+`str`, default `"nomarchy"`. Primary user whose home subset (`.ssh`, `.gnupg`, `.local/share/keyrings`, `Documents`, `Downloads`, `Pictures`, `Videos`, `Projects`) survives the rootfs wipe. Must match the user created via `users.users.<name>` — otherwise the persistence block is silently inert and the user's home directory is wiped on every boot. The installer writes this for you.
+
 ---
 
 ## Home Manager options (`home.nix`)
@@ -115,10 +169,22 @@ Wired in `features/desktop/waybar/default.nix` (filters the battery widget out o
 
 `str`, default `"summer-night"`. Active theme name. Available themes are the directories under `themes/palettes/`.
 
+### `nomarchy.panelPosition`
+
+`enum ["top", "bottom"]`, default `"top"`. Waybar panel position.
+
+### `nomarchy.hyprland.gaps_in` / `nomarchy.hyprland.gaps_out` / `nomarchy.hyprland.border_size`
+
+`int`, defaults `5` / `10` / `2`. Hyprland window inner gaps, outer gaps, and active-border width (px). Map to Hyprland's `general.{gaps_in,gaps_out,border_size}` in `features/desktop/hyprland/default.nix`. Defaults come from `lib/state-schema.nix` and are read from `~/.config/nomarchy/state.json`, so they can be retuned without a rebuild; set them here to make a choice permanent.
+
 ### `nomarchy.formFactor`
 
 `enum [ "laptop" "desktop" ]`, default `"laptop"`. Mirror of `nomarchy.system.formFactor`. Filters laptop-only widgets out of waybar (battery) when set to `"desktop"`. The installer writes both system and home values together.
 
+### `nomarchy.keymap.layout` / `nomarchy.keymap.variant`
+
+`str` / `str`, defaults `"us"` / `""`. Keyboard layout and variant for Hyprland's native Wayland session. `system.nix` writes `services.xserver.xkb.layout` (XWayland) and `console.keyMap` (TTY) to the same value, but Hyprland reads its own input config so this option must be set independently — otherwise a non-US user gets the right layout in XWayland apps and the console but the US fallback inside native-Wayland apps. The installer writes both fields into the generated `home.nix` alongside `nomarchy.formFactor`. Example: `nomarchy.keymap = { layout = "dk"; variant = ""; };`.
+
 ### `nomarchy.wallpaper`
 
 `str`, default `""`. Absolute path to a wallpaper override. Empty string means "use the active theme's default wallpaper".
@@ -143,10 +209,6 @@ Wired in `features/desktop/waybar/default.nix` (filters the battery widget out o
 
 `bool`, default `true`. Whether the top bar is deployed at all.
 
-### `nomarchy.toggles.skipVsCodeTheme`
-
-`bool`, default `false`. Skip theme overrides in VSCode — useful if you manage VSCode themes yourself.
-
 ### `nomarchy.nightlightTemperature`
 
 `int`, default `4000`. Nightlight color temperature (Kelvin).
@@ -169,11 +231,11 @@ Wired in `features/desktop/waybar/default.nix` (filters the battery widget out o
 
 ### `nomarchy.iconsTheme`
 
-`str`, default `"Yaru-blue"`. GTK/Qt icon theme name.
+`str`, default derived from the active theme (falls back to `"Yaru-blue"`). GTK/Qt icon theme name. `core/home/state.nix` computes this from the theme's palette metadata; override to pin a specific icon theme regardless of palette.
 
 ### `nomarchy.isLightMode`
 
-`bool`, default `false`. Whether the active theme is a light theme. Affects nightlight defaults and a few app theme decisions.
+`bool`, default derived from the active theme. Whether the active theme is a light theme. `core/home/state.nix` computes this from the theme directory; affects nightlight defaults and a few app theme decisions. Override only if you need to force a specific value.
 
 ### `nomarchy.cursor.name`
 
@@ -185,47 +247,90 @@ Wired in `features/desktop/waybar/default.nix` (filters the battery widget out o
 
 ### `nomarchy.configOverrides`
 
-`nullOr path`, default `null`. Path to a directory containing config overrides. See "Overrides" below.
+`nullOr path`, default `null`. Path to a replacement config directory. When set, the items listed in `core/home/configs.nix` (`fastfetch`, `fcitx5`, `fontconfig`, `git`, `imv`, `nautilus-python`, `nomarchy`, `nomarchy-skill`, `uwsm`, `wiremix`, plus the loose files) are read from `<this-path>/<name>` instead of the bundled defaults. Distinct from `nomarchy.overrides.*` below — `configOverrides` is a working *bulk* redirect; `overrides.paths` is a *per-file* attrset map.
 
-### `nomarchy.behavior.hyprland.bindings`
+### `nomarchy.apps.alacritty.enable`
 
-`bool`, default `true`. Deploy the default Hyprland keybindings. Set to `false` if you want to write `bindings.conf` from scratch.
+`bool`, default `false`. Enables Nomarchy's curated Alacritty configuration. The installer enables this by default.
 
-### `nomarchy.behavior.hyprland.input`
+### `nomarchy.apps.btop.enable`
 
-`bool`, default `true`. Deploy default input settings (kb_layout, mouse accel, etc).
+`bool`, default `false`. Enables Nomarchy's curated btop configuration (themed color scheme, vim keys). The installer enables this by default.
 
-### `nomarchy.behavior.hyprland.windowRules`
+### `nomarchy.apps.ghostty.enable`
 
-`bool`, default `true`. Deploy default window rules.
+`bool`, default `false`. Deploys Nomarchy's curated Ghostty configuration.
 
-### `nomarchy.behavior.hyprland.autostart`
+### `nomarchy.apps.kitty.enable`
 
-`bool`, default `true`. Deploy the default `autostart.conf` (hypridle, mako, swayosd, nm-applet, etc).
+`bool`, default `false`. Deploys Nomarchy's curated Kitty configuration.
+
+### `nomarchy.apps.lazygit.enable`
+
+`bool`, default `false`. Deploys Nomarchy's curated lazygit configuration.
+
+### `nomarchy.apps.tmux.enable`
+
+`bool`, default `false`. Deploys Nomarchy's curated tmux configuration.
+
+### `nomarchy.apps.elephant.enable`
+
+`bool`, default `false`. Enables Nomarchy's curated Elephant menu provider integration (required for the theme picker and background selector). The installer enables this by default.
+
+### `nomarchy.apps.walker.enable`
+
+`bool`, default `false`. Enables Nomarchy's curated Walker launcher configuration. The installer enables this by default.
+
+### `nomarchy.apps.swayosd.enable`
+
+`bool`, default `false`. Enables Nomarchy's curated SwayOSD configuration. The installer enables this by default.
+
+### `nomarchy.apps.vscode.enable`
+
+`bool`, default `false`. Enables Nomarchy's curated VSCode configuration (theming, fonts). The installer enables this by default.
+
+### `nomarchy.apps.vscode.devExtensions`
+
+`bool`, default `false`. Install Nomarchy's curated VSCode extension pack (language servers + git + editor enhancements). The palette theme extensions are *always* installed when `vscode.enable` is true — every palette except `ethereal`, `hackerman`, and `vantablack` resolves its `workbench.colorTheme` via either `pkgs.vscode-extensions` (catppuccin/nord/tokyo-night/rose-pine/gruvbox) or `pkgs.vscode-utils.extensionFromVscodeMarketplace` with version + sha256 pinned (sainnhe.everforest, qufiwefefwoyn.kanagawa, monokai.theme-monokai-pro-vscode, oldjobobo.{lumon,miasma,retro-82}, shadesOfBuntu.flexoki-light, jovejonovski.ocean-green, TahaYVR.matteblack, Bjarne.white-theme). The three palettes whose theme extension isn't on the marketplace fall back to VSCode's default theme; see the ROADMAP Later row.
 
 ### `nomarchy.apps.opencode.enable`
 
 `bool`, default `false`. opencode AI coding CLI integration. Deploys `~/.config/opencode/opencode.json`. The `opencode` package itself is **not** installed by Nomarchy — add it to your `home.packages`.
 
-### `nomarchy.vscode.devExtensions`
+### `nomarchy.gaming.enable`
 
-`bool`, default `false`. Install Nomarchy's curated VSCode extension pack (Nix, language servers, theme variants).
+`bool`, default `false`. Home-side companion to `nomarchy.system.gaming.enable`. Adds a Hyprland `windowrulev2 = fullscreen, class:^(steam_app_).*$` so games launched through Steam grab the whole screen instead of opening windowed. Set to the same value as the system option; the installer flips both when the Gaming profile is selected.
+
+### `nomarchy.accessibility.enable`
+
+`bool`, default `false`. Home-side companion to `nomarchy.system.accessibility.enable`. Three Hyprland-side adjustments: slows `input.repeat_rate` to `25` (default `40`) and `input.repeat_delay` to `1000` ms (from `600`) so holding a key isn't a runaway machine-gun for low-mobility users; binds `SUPER+ALT+S` to launch the Orca screen reader (the system preset already puts `orca` on PATH). Set to the same value as the system option. Update the bullet in `docs/ROADMAP.md` if a high-contrast palette ships as a `themes/palettes/` entry — it'll be gated on this option.
 
 ### `nomarchy.themeLoader.enable`
 
-`bool`, default `true`. Auto-load theme-specific app configs (btop, waybar, mako, kitty, alacritty) from the active theme. Disable if you want to provide your own.
+`bool`, default `true`. Auto-load theme-specific app configs from the active theme's `apps/` directory. Disable if you want to provide your own.
 
-### `nomarchy.themeLoader.apps.{btop,waybar,mako,kitty,alacritty}`
+### `nomarchy.themeLoader.apps.btop`
 
-`bool`, default `true` each. Per-app toggles for the theme loader — pick which apps follow the active theme.
+`bool`, default `true`. Deploy the active theme's `apps/btop.theme` to `~/.config/btop/themes/nomarchy.theme`. The only per-app toggle in this group — waybar themes inline from `colorScheme` in `features/desktop/waybar`; kitty and alacritty are themed by stylix targets (`themes/engine/stylix.nix`); mako has no theme integration yet.
 
 ### `nomarchy.overrides.enable`
 
-`bool`, default `true`. Enable file-based overrides loaded from `~/.config/nomarchy/overrides/`. With this on, Nomarchy looks for matching files in that directory and substitutes them for the bundled defaults.
+`bool`, default `true`. Whether the entries in `nomarchy.overrides.paths` are applied. Default `true` so an empty `paths` is a no-op and a populated one Just Works without a second toggle.
 
 ### `nomarchy.overrides.paths`
 
-`attrsOf path`, default `{}`. Override paths discovered at build time. Populated by the override system — you don't normally set this directly.
+`attrsOf path`, default `{}`. Per-file overrides. Each key is an `xdg.configFile` path (relative to `~/.config/`); each value is a Nix path whose contents replace the Nomarchy-shipped source. Substitution is done with `lib.mkForce` so it wins over Nomarchy's own `lib.mkDefault` writes. Other fields on the original entry (`recursive` etc.) survive the merge. Overriding a path Nomarchy doesn't manage just creates a new `xdg.configFile` entry.
+
+Example:
+
+```nix
+nomarchy.overrides.paths = {
+  "nomarchy/default/hypr/looknfeel.conf" = ./looknfeel.conf;
+  "waybar/style.css"                     = ./waybar.css;
+};
+```
+
+Drop-in-a-dir discovery (a runtime walk of `~/.config/nomarchy/overrides/`) is intentionally not supported — Nix needs every managed file declared at evaluation time, and the attrset is the explicit-config shape the rest of the Nomarchy module surface uses.
 
 ---
 
@@ -257,15 +362,17 @@ Wired in `features/desktop/waybar/default.nix` (filters the battery widget out o
 }
 ```
 
-### Disable Nomarchy's default Hyprland keybindings to ship your own
+### Ship your own Hyprland keybindings instead of Nomarchy's defaults
+
+Nomarchy deploys its `bindings.conf` with `lib.mkDefault`, so a higher-priority assignment from your own `home.nix` wins:
 
 ```nix
 {
-  nomarchy.behavior.hyprland.bindings = false;
+  xdg.configFile."hypr/bindings.conf".source = ./my-bindings.conf;
 }
 ```
 
-Then put your own `bindings.conf` at `~/.config/nomarchy/overrides/hypr/bindings.conf` (with `nomarchy.overrides.enable = true;`, which is the default).
+The same pattern works for any file Nomarchy deploys via `xdg.configFile.<path>.source = lib.mkDefault …` — point at your own file and skip the default.
 
 ---
 
@@ -275,7 +382,6 @@ Then put your own `bindings.conf` at `~/.config/nomarchy/overrides/hypr/bindings
 - `core/system/hardware.nix` — `nomarchy.hardware.*`
 - `core/system/impermanence.nix` — `impermanence.enable`
 - `core/home/options.nix` — most home-side `nomarchy.*` options
-- `core/home/behavior.nix` — `nomarchy.behavior.*`
 - `core/home/overrides.nix` — `nomarchy.overrides.*`
 - `themes/engine/loader.nix` — `nomarchy.themeLoader.*`
 - `features/apps/vscode.nix` — `nomarchy.vscode.*`

docs/ROADMAP.md

@@ -6,7 +6,7 @@ If you're new here, also read [`docs/STRUCTURE.md`](STRUCTURE.md) and [`docs/OPT
 
 ## 1. Vision & guardrails
 
-Nomarchy is a NixOS-based distribution that gives you the Omarchy desktop (Hyprland + waybar + walker + a curated theming engine) on a strictly declarative, flake-based foundation. Goal: power-user polish without giving up reproducibility.
+Nomarchy is a NixOS-based distribution that gives you a polished Hyprland desktop (Hyprland + waybar + walker + a curated theming engine) on a strictly declarative, flake-based foundation. Goal: power-user polish without giving up reproducibility.
 
 Guardrails (apply when adding anything):
 
@@ -19,31 +19,23 @@ Guardrails (apply when adding anything):
 
 ### Now (ready to pick up)
 
-- **Software-profile multi-select in the installer.** Carryover from the old TODO. Add a `gum choose --no-limit` step in `installer/install.sh` (between hardware and impermanence) for opt-in profiles (Dev, Gaming, Office, Media, …). Each profile maps to a list of `home.packages` and optional `nomarchy.system.*` toggles emitted into the generated `home.nix`/`system.nix`.
-- **Audit Phase B (per-batch).** Phase A populated [`docs/SCRIPTS.md`](SCRIPTS.md) with 158 `kept`, 75 `missing`, and 45 `unused?` rows via the new `bin/utils/nomarchy-docs-scripts` generator. Phase B is the per-batch porting/removal: pick ~10 rows tagged `missing` or `unused?`, decide `port-from-omarchy` / `delete-dead` / `stub-with-notify`, and ship as one PR per batch.
-- **Form-factor → laptop preset auto-enable.** When the installer writes `nomarchy.system.formFactor = "laptop"`, also flip on a yet-to-be-built laptop preset (TLP, brightness keys, lid handling). The option exists; the preset module doesn't.
+_(empty — all entries shipped or moved to Later)_
 
 ### Next (bigger lifts that build on Now)
 
-- **Laptop preset module** (`core/system/laptop.nix`). Gated on `formFactor = "laptop"`. Wires TLP defaults, `services.upower`, `services.thermald` where applicable, brightness key handlers, and a sane logind lid-switch policy that defers to `nomarchy.system.hibernation.enable`.
-- **Desktop preset module.** CPU governor `performance` by default, no battery widget (already done), ZFS-friendly defaults for users who later add a pool.
-- **Accessibility preset.** Larger cursor, slower key-repeat defaults, `services.orca`, screen reader keybinding, high-contrast theme variant.
-- **Gaming preset.** `programs.steam.enable`, `programs.gamemode.enable`, `services.flatpak.enable` with a curated remote, and a Hyprland window-rule to fullscreen Steam-launched apps.
-- **First-run welcome wizard.** Extend `nomarchy-welcome` from a one-shot greeter into a guided picker: theme, panel position, monospace font, "what's a sane home.nix to start with?". Runs once, persists "done" in `state.json`.
-- **Plymouth theme variants per palette.** Currently one Plymouth theme; could template per-palette so the boot splash matches the active theme.
-- **`docs/TROUBLESHOOTING.md`.** The five most common rebuild errors (`option ... already declared`, `attribute ... missing`, Stylix target conflicts, home-manager backupFileExtension churn, impermanence path missing) with copy-paste fixes.
-- **Installer pre-flight resume polish.** If the user Ctrl-Cs mid-install and runs `--resume`, re-show the review screen before re-prompting for any unsaved fields.
-
 ### Later (speculative or research-shaped)
 
-- **Declarative-state migration.** Move the bits of `state.json` that don't actually need runtime mutability (theme, font, isLightMode) into NixOS / home-manager options, leaving only genuinely runtime-only state behind. Reduces the "two sources of truth" surface.
-- **Rolling vs pinned channel choice in the installer.** Today the generated flake pins `nomarchy` to a rev. Offer a "rolling" option that follows `main` and a `nomarchy-rollback` helper for stuck rebuilds.
+- **Rolling vs pinned channel choice in the installer.**
+ Today the generated flake pins `nomarchy` to a rev. Offer a "rolling" option that follows `main` and a `nomarchy-rollback` helper for stuck rebuilds.
 - **Theme creation wizard.** A `nomarchy-theme-new` script that scaffolds a new palette from a base16 hex set (or by sampling a wallpaper), runs `nomarchy-themes-prebuild`, and opens a PR template.
-- **CI matrix on Forgejo Actions.** On every push: `nix flake check`, build `installerIso`, `installerIsoGraphical`, `default`. On tag: publish ISOs as release artefacts.
+- **CI matrix on Forgejo Actions.** On every push: `nix flake check`, build `nomarchy-installer`, `nomarchy-live`, `default`. On tag: publish ISOs as release artefacts.
 - **Golden-image VM tests per palette.** A `nixosTest` per palette that boots the `default` config, takes a screenshot, and diffs against a golden image. Catches Stylix regressions before they hit users.
 - **Forgejo release pipeline.** `vYY.MM.x` tags matching the upstream NixOS channel; the pipeline pushes the three ISOs and an updated `flake.lock` snapshot.
 - **Optional `nomarchy-installer-vm`** rebuilt as a real flake app (not a one-off shell script) so users can install Nomarchy into a libvirt VM declaratively.
 - **Surface support module** via the relevant `nixos-hardware` profile + Surface kernel patches behind a `nomarchy.hardware.isSurface` toggle.
+- **High-contrast accessibility palette.** New `themes/palettes/high-contrast/` hitting WCAG AAA-grade contrast — pure-black background, pure-white foreground, saturated ANSI colors for distinction. Ships its own `colors.toml`, `icons.theme` (pick a high-contrast icon family or document the gap), and one solid-black `backgrounds/` entry. Pairs with `nomarchy.accessibility.enable` (Shipped 2026-05-22) but stays manually selected via `nomarchy-theme-set high-contrast` so the home option doesn't silently overwrite the user's existing theme choice. Split out of the original Accessibility row because it's a design task (24-colour WCAG palette + icon family choice) that wants its own review.
+- **Publish or replace `Bjarne.{ethereal,hackerman,vantablack}-nomarchy` VSCode theme extensions.**
+ The `ethereal`, `hackerman`, and `vantablack` palettes' `apps/vscode.json` files reference VSCode theme extensions under the `Bjarne` publisher that don't exist on the VSCode marketplace (verified via the marketplace extensionquery API on 2026-05-22). With the rest of the palette-extension pinning shipped, these three palettes are the only ones where VSCode still falls back to its default theme. Options: (a) publish the three extensions to the marketplace under the `Bjarne` publisher (or whatever the maintainer's account is) and add them to `features/apps/vscode.nix`'s `marketplaceExtensions` list; (b) package them locally as standalone `pkgs.vscode-utils.buildVscodeExtension` derivations sourced from a Nomarchy-hosted repo; (c) retarget the three palettes' `apps/vscode.json` to an existing marketplace-published theme that visually matches.
 
 ## 3. Pillar: Script & menu audit
 
@@ -80,31 +72,30 @@ Each PR description should reference the row(s) in `docs/SCRIPTS.md` it closes,
 
 ## 4. Pillar: Installer
 
-- Software-profile multi-select (Now).
+- "What's installed?" summary screen on boot of a freshly-installed system, sourced from `state.json` + `nomarchy-system-scripts` introspection (Shipped).
 - Richer disk metadata (Shipped).
-- Form-factor → laptop preset (Now, depends on Pillar 5).
-- `disko-golden.nix` variants for software-RAID and BTRFS-pool-as-root.
-- Pre-flight resume polish (Next).
-- "What's installed?" summary screen on boot of a freshly-installed system, sourced from `state.json` + `nomarchy-system-scripts` introspection.
-- Optional non-LUKS branch in the installer for users who explicitly opt out of FDE.
+- `disko-golden.nix` variants for software-RAID and BTRFS-pool-as-root (Shipped).
+- Pre-flight resume polish (Shipped).
+- Software-profile multi-select (Shipped).
+- Form-factor → laptop preset (Shipped).
 
 ## 5. Pillar: Power, hardware, presets
 
-- Laptop preset (Next): TLP, upower, brightness, lid, hypridle tuning.
-- Desktop preset (Next): performance governor, no laptop UI (already filtered), ZFS hooks.
-- Accessibility preset (Next).
-- Gaming preset (Next).
-- Vendor matchers in `installer/hardware-db.sh`: Steam Deck, Surface, ROG Ally, Snapdragon X laptops.
+- Auto-detect dGPU presence in `installer/hardware-db.sh` and pre-fill `hardware.nvidia.prime.{intel,nvidia}BusId` in the generated `system.nix` (driver stack itself is Shipped — see entry below).
 - Surface support behind `nomarchy.hardware.isSurface` (Later).
-- Auto-detect dGPU presence and offer `programs.envycontrol`-style switching for the hybrid case (already gated behind `nomarchy.system.features.hybridGPU`, but the wiring is minimal).
+- Laptop preset: TLP, upower, brightness, lid, hypridle tuning (Shipped).
+- Desktop preset: performance governor, no laptop UI (already filtered), ZFS hooks (Shipped).
+- Accessibility preset (Shipped).
+- Gaming preset (Shipped).
+- Vendor matchers in `installer/hardware-db.sh` (Shipped — ROG Ally added; Surface/Framework/Lenovo entries corrected; Steam Deck + Snapdragon X documented as nixos-hardware-unsupported. CI now lints DB references).
 
 ## 6. Pillar: Onboarding & docs
 
-- `nomarchy-welcome` first-run wizard (Next).
+- `nomarchy-welcome` first-run wizard (Shipped).
 - `docs/KEYBINDINGS.md` auto-generator (Shipped).
-- `docs/TROUBLESHOOTING.md` (Next).
-- `docs/index.md` (or just enrich `README.md`) so `OPTIONS.md`, `STRUCTURE.md`, `MIGRATION.md`, `ROADMAP.md`, `SCRIPTS.md`, and `creating-themes.md` are all one click from the front page.
-- `nomarchy-manual` — orphaned reference today; either implement as a curated `xdg-open` to the docs index, or delete.
+- `docs/TROUBLESHOOTING.md` (Shipped).
+- `docs/index.md` / README docs index (Shipped — `README.md` links every doc in `docs/`).
+- `nomarchy-manual` — opens the local `~/.local/share/nomarchy/README.md` via `xdg-open` (Shipped).
 
 ## 7. Pillar: Test, CI, release
 
@@ -116,7 +107,65 @@ Each PR description should reference the row(s) in `docs/SCRIPTS.md` it closes,
 - `nixosTest` per palette: boots `default` in a VM, screenshots the SDDM splash and the Hyprland desktop, diffs vs golden. Failure surfaces as CI red.
 - A small `bin/utils/nomarchy-bench-iso-build` that records ISO build time + size into a per-commit JSON so we notice regressions.
 
-## 8. Process notes
+## 8. Pillar: QA audit — features & components
+
+Nomarchy now spans an installer, ~159 `nomarchy-*` scripts, a Hyprland desktop stack (Hyprland + waybar + walker + nightlight + idle), curated apps, a 22-palette theme engine, and two ISO hosts. Pillar 3 audited script *existence*; this pillar audits feature *behavior*. The goal: walk every shipped feature end-to-end on a real install, fix every bug or surprise inline when small, and capture the rest as new roadmap rows.
+
+Runs as **per-component sweeps**. One PR per component, branch `wave/qa-<component>`. Don't grow scope mid-PR — bugs that need a new option, refactor, or missing module become a new **Now**/**Next** row.
+
+Components (each is one sweep):
+
+1. **Installer** — `installer/install.sh`, `installer/hardware-db.sh`, disko configs. Fresh install + `--resume` + `--dry-run`, on laptop and desktop, with FDE (non-LUKS branch is Later). Verify every generated file (`flake.nix`, `system.nix`, `home.nix`, `hardware-selection.nix`, `state.json`) is correct and idempotent.
+2. **First-boot UX** — `nomarchy-welcome`, generated `home.nix`, SDDM and Plymouth metadata, default theme/font/panel position. Re-run on a clean VM; note every prompt that confuses and every default that's wrong.
+3. **Core system modules** — `core/system/*` (laptop, desktop, accessibility, gaming, hybridGPU, impermanence, network, hardware, branding). For each: enable → rebuild → observe the claimed effect → disable → rebuild → observe it's gone. Cross-check against `docs/OPTIONS.md`.
+4. **Core home modules** — `core/home/*` (options, state, behavior, overrides, deployed config). Verify every home-side `nomarchy.*` option does what its description claims; confirm `~/.config/nomarchy/overrides/` actually overrides.
+5. **Desktop stack** — Hyprland (keybindings, window rules, monitors, input), waybar (every module × both panel positions × both form factors), walker (every launcher mode), idle, nightlight, notifications (mako). Reconcile `docs/KEYBINDINGS.md` against runtime.
+6. **Apps** — `features/apps/*`. Each app: launches, themed via Stylix, configured as expected. Catches the "we package it but nobody configured it" class.
+7. **Theme engine + palettes** — `nomarchy-theme-set` across all 22 palettes, font and wallpaper switchers, light-mode toggle. Verify per-palette Stylix targets render correctly across SDDM, Plymouth, GTK, Qt, terminals, browsers, waybar, walker.
+8. **Scripts (runtime behavior)** — Pillar 3 confirmed existence; this sweep runs every user-visible script (especially every `nomarchy-menu` entry) on current NixOS and confirms it actually does the thing.
+9. **ISOs** — boot `nomarchy-installer` and `nomarchy-live`; verify the `nomarchy-test-live-iso` flow; check the installer ISO ships every tool `install.sh` calls (regression class: `hardware-db.sh` missing, already shipped).
+10. **Lib + state schema** — `lib/state-schema.nix`, color resolution, path helpers. Cross every codepath that produces `state.json` (installer, welcome wizard, hand-edit) against the schema; confirm bad inputs are rejected with a useful message.
+
+Per-PR deliverable:
+
+- PR body lists what was tested, what was broken, what was fixed inline, what was deferred (with the new roadmap row linked).
+- Doc updates ride with the change per `docs/AGENT.md` §5.4.
+- Don't bundle fixes across components — keep one component per branch so reviewers can spot-check end-to-end without context-switching.
+
+Pillar is **done** when every component has a closed `wave/qa-<component>` PR and the roadmap captures every deferred finding.
+
+## 9. Pillar: Live VM runtime QA
+
+Pillar 8 audited feature *code* (read-and-reason) and shipped a first VM-boot smoke pass. This pillar runs the distro **live in a VM and interacts with it** — driving menus, switching themes, launching apps, running every script — to confirm what actually works versus what only looks right in the source. It is the runtime counterpart to Pillar 8's static sweeps and the new home for every "needs runtime verification" note that the Component 1–10 closeouts deferred.
+
+### Method (how to drive the VM)
+
+- **Build + boot.** `nix build .#nixosConfigurations.default.config.system.build.vm`, then run its `bin/run-*-vm` with `QEMU_OPTS="-display none -monitor unix:/tmp/mon.sock,server,nowait -vga none"`. The `default` config autologins to Hyprland (virtio-vga, KMS via `core/system/vm-guest.nix`).
+- **Observe.** Capture the framebuffer with the QEMU monitor's `screendump /path.ppm` over the monitor socket (`echo "screendump …" | socat - unix-connect:/tmp/mon.sock`), convert PPM→PNG, and eyeball. Crop regions for legibility. This is how the first pass caught the boot-time Hyprland config-error overlay.
+- **Drive.** The QEMU monitor's `sendkey` injects keystrokes — open the menu (`SUPER`), trigger keybindings, type into a terminal. For bulk script/command testing, prefer a throwaway VM variant with `services.openssh` + a known credential + a host port-forward: SSH is far faster and scriptable than `sendkey`+screenshot. Add it to a test overlay, never to the shipped config.
+- **State.** Delete the VM's `*.qcow2` between runs to force a clean first-boot home-manager deploy; keep it to test persistence.
+
+### Components (each is one batch — "do it, then look")
+
+1. **First-boot UX** — `nomarchy-welcome` start to finish: every prompt, the installed-summary table, the theme/font/panel pickers actually applying. (First pass fixed the `compgen` bug here.)
+2. **Scripts & commands** — run every `nomarchy-*` user command (~159) and record exit status + visible behaviour. Catches the "wrapped bash lacks a builtin" / "binary not on PATH" classes that only bite at runtime, not at eval.
+3. **The menu** — walk every `nomarchy-menu` entry and submenu (23 functions); confirm each *does* the thing, not just opens.
+4. **Theme engine** — `nomarchy-theme-set` through all 22 palettes; per palette, screenshot waybar + walker + a terminal + a GTK app + the greeter + Plymouth and confirm Stylix renders everywhere. Plus the font and wallpaper switchers, light-mode toggle, and `nomarchy-theme-next`.
+5. **Desktop stack** — every keybinding fires (reconcile against `docs/KEYBINDINGS.md`); waybar across both panel positions × both form factors; walker launcher modes; idle / nightlight / screensaver timeouts; mako notifications.
+6. **Apps** — launch each `features/apps/*` app; confirm it opens and is themed.
+7. **Options loop** — for each `nomarchy.*` option: set → rebuild → observe the claimed effect → unset → observe it's gone. The Pillar 7 eval matrix only proves an option *evaluates*; this proves it *does something*.
+8. **Installer** — boot `installerVm`; drive `install.sh` through `--dry-run` and a real install into a second disk image; verify every generated file (`flake.nix`, `system.nix`, `home.nix`, `hardware-selection.nix`, `state.json`).
+9. **Form-factor split** — repeat the desktop-sensitive checks on a laptop-flavoured VM (QEMU `BAT` battery emulation) to catch laptop-only UI/services.
+
+### Deliverable
+
+- Per batch: a short report — what was run, what worked, what broke, what was fixed inline (with screenshot/log evidence where it matters), what was deferred as a new row.
+- Small bugs fixed inline; anything needing a new option / module / refactor becomes a new **Now**/**Next** row, not grafted on.
+- Commit direct-to-main per the QA-sweep workflow (or `wave/vmqa-<component>` if PRs are wanted). Doc updates ride with the change per `docs/AGENT.md` §5.4.
+
+Pillar is **done** when every component has had a live VM pass and the roadmap captures every deferred finding.
+
+## 10. Process notes
 
 - **Branch naming:** `wave/<pillar>-<short-slug>`. Examples: `wave/audit-pkg-scripts`, `wave/installer-disk-metadata`, `wave/laptop-preset`.
 - **One PR per audit batch.** Reference rows in `docs/SCRIPTS.md`. Smaller PRs review faster.
@@ -128,6 +177,101 @@ Each PR description should reference the row(s) in `docs/SCRIPTS.md` it closes,
 
 (Move items here when they land — keep them brief, link the commit/PR.)
 
+- _2026-06-02_ — **Installer: real-hardware install was broken at "Creating system configuration" (every install, single or multi disk).** `generate_state` evaluates `lib/state-schema.nix` by calling `builtins.getFlake "$NOMARCHY_REPO"` to load `nixpkgs.lib`, with `NOMARCHY_REPO=/etc/nomarchy`. On the live ISO that's a symlink chain (`/etc/nomarchy → /etc/static/nomarchy → /nix/store/…-source`), and Nix 2.31+ rejects `getFlake` on a symlink path (`error: path '…-source' is a symlink`) — aborting the install right after hardware config generation. Reproduced the exact error in a live VM (Nix 2.31.4). **Fix:** resolve the repo to its real store directory with `realpath` at detection (`install.sh:261`). The dev-checkout branch already used `realpath`, so only the live-ISO path was affected. Verified the resolved path makes `getFlake` + the state-schema eval succeed in-VM.
+- _2026-06-02_ — **Installer: multi-disk LUKS installs could not boot.** disko correctly builds a multi-device BTRFS (`-d single -m raid1`) across one LUKS container per disk, but `nixos-generate-config` only emits `boot.initrd.luks.devices` for the *main* drive (every subvolume mounts via `/dev/mapper/crypted_main`; the other members are invisible through the device-mapper path it traces). The installed system unlocked only the main drive, the array never assembled, and boot hung — invisible single-disk, fatal multi-disk (matches a real-hardware report). It also dropped the `x-systemd.requires=` mount options disko sets. **Fix:** `generate_flake_config` now writes the missing `boot.initrd.luks.devices.<mapper>` entries (UUID via the disko partlabel) and re-asserts the `x-systemd.requires=` options for every BTRFS mount into `hardware-selection.nix`. **Verified end-to-end:** booted a 3-disk (1 main + 2 extra) UEFI QEMU VM, ran the exact disko + `nixos-generate-config` path to confirm the bug, applied the fix, did a real minimal `nixos-install` onto the array, and rebooted from the disks — the system unlocked all three containers with a single passphrase (systemd-initrd caches it), assembled the 3-device BTRFS, and reached login (`btrfs filesystem show / → Total devices 3`). `docs/MIGRATION.md` updated with the hand-written-flake caveat.
+- _2026-05-31_ — **Ironclad: Overlap & Conflict Proofing complete.** Verified that manual Nix overrides in `home.nix` take precedence over UI choices without causing evaluation errors. **Fixed:** Updated `nomarchy-sync-nix-state` and the installer to wrap all machine-generated values in `nomarchy-state.nix` with `lib.mkDefault`. This ensures a user can manually set `nomarchy.theme = "catppuccin"` in their config, safely overriding the UI state without triggering "conflicting definition values" errors in the module system.
+- _2026-05-31_ — **Ironclad: Input Method (Fcitx5) Functional Pass complete.** Verified that non-ASCII input (Pinyin/Mozc) is functional in the live VM. **Fixed:** Enabled `i18n.inputMethod.fcitx5.waylandFrontend = true` in `core/system/input-method.nix` to properly bind Fcitx5 to the Wayland text-input protocol, resolving missing environment variable issues and ensuring the candidate window renders correctly in Hyprland.
+- _2026-05-31_ — **Ironclad: Multi-Monitor Integrity complete.** Verified Hyprland, Waybar, and Walker behavior on dual-screen setups (simulated via dual `virtio-vga` VM devices). **Fixed:** Removed a hardcoded `"output": "DP-2"` parameter from the `summer-day` Waybar configuration, ensuring the bar spawns seamlessly across all connected monitors. Confirmed Walker inherently follows the active monitor as expected.
+- _2026-05-31_ — **Ironclad: Offline Resilience complete.** Audited the system for network-induced hangs by booting a live VM with `-net none`. **Fixed:** `nomarchy-upload-log` (added a 5s connect timeout to `curl` to fail fast when ix.io is unreachable) and `nomarchy-update-available` (added a fast-fail ping check so Waybar doesn't hang executing `nix flake metadata` while offline). **Restored:** recreated `nomarchy-update` (syncs the local git repo and calls `nomarchy-sys-update`) and `nomarchy-update-time` (restarts `systemd-timesyncd`), which were referenced in the menu but missing from the filesystem. The system now remains fully responsive without internet access.
+- _2026-05-31_ — **Flake Update logic fixed & Rolling Release path established.** Rewrote `nomarchy-update` to properly interact with the downstream `flake.nix` inputs. Instead of attempting a `git pull`, it now strips the initial installation pin (`?rev=<hash>`) to seamlessly transition the user to a rolling release, and then runs `nix flake update` to bump `flake.lock`. Rewrote `nomarchy-update-available` to correctly query the upstream git repository and compare its `HEAD` against the local lockfile, ensuring the Waybar update icon only appears when an actual update is pending.
+- _2026-05-31_ — **Deep Runtime Polish: State-Sync Stress Test complete.** Verified the robustness of the hybrid declarative state system (`nomarchy-state.nix`) via an automated chaos test in a live VM (250 parallel writes across 5 concurrent workers). **Bug fixed:** identified and resolved a critical race condition where the Nix sync script was being called outside the `flock` lock in `nomarchy-state-write`. Moving the sync inside the protected block ensured atomic updates to both JSON and Nix state files. Verification confirmed 100% integrity and zero desyncs under heavy load.
+- _2026-05-31_ — **Deep Runtime Polish: Keybinding vs. Tooltip Reconciliation complete.** Audited the system to ensure documentation, tooltips, and live behavior are in sync. **Waybar:** fixed a major discrepancy in the Nomarchy Menu tooltip (was `Super + Alt + Space`, corrected to `Super + Shift + Space`) and added keybinding hints to all core modules (Wifi, Bluetooth, Battery, CPU, Audio, Clock) for better discoverability. **Rofi:** fixed a stale `terminal: "kitty"` setting in the `summer-day` and `summer-night` themes, retargeting them to Nomarchy's default `alacritty`. **Standardization:** updated the `summer-day` theme to use the standard `nomarchy-launch-audio` action, ensuring consistent behavior across all palettes.
+- _2026-05-31_ — **Deep Runtime Polish: Interactive Script Audit (Round 2) complete.** Verified complex interactive scripts (`nomarchy-welcome`, `nomarchy-menu`, theme/font/wallpaper pickers) inside a real Alacritty window in a live VM. Confirmed `gum` renders correctly with readable contrast across themes. Verified that the hybrid state sync (Batch 1) correctly handles real-time UI inputs.
+- _2026-05-31_ — **Deep Runtime Polish: App Integration complete.** Successfully verified and improved the NixOS integration for core apps. **Thunar:** enabled `gvfs`, `tumbler`, and `polkit` (required for drive management); added archive, volume, and media-tags plugins; installed supporting thumbnailers and MIME databases. **Mako:** added `on-click` handlers to notification rules for keyboard accessibility; refactored `nomarchy-notification-dismiss` to robustly handle JSON/human output from `makoctl list`. **VSCode:** verified that `nomarchy.fonts.monospace` and `nomarchy.theme` correctly propagate to user settings and extensions.
+- _2026-05-31_ — **Declarative-state migration: complete.** Implemented a hybrid model where runtime UI choices (theme, font, panel position, gaps, toggles) are automatically mirrored from `state.json` into a machine-managed `/etc/nixos/nomarchy-state.nix` file. This file is imported by `home.nix`, making UI changes declarative and permanent across rebuilds. Updated `nomarchy-state-write` and all setter scripts to trigger the sync automatically. The installer now generates this initial bridge, closing the "two sources of truth" gap for the entire UI surface.
+- _2026-05-31_ — **Declarative monitor scaling.** Replaced static `monitors.conf` with a Nix-generated file driven by `nomarchy.hyprland.scale` (default `"auto"`). Added a scale picker to `nomarchy-welcome` to handle HiDPI displays during first-boot.
+
+- _2026-05-31_ — **Calendar app shipped.** Added `calcurse` (TUI calendar) to the core `features` module and wired all Waybar clock modules (`clock` in base, `clock#date` in themes) to launch it via `nomarchy-launch-or-focus-tui`. Provides a functional calendar across the entire distro.
+- _2026-05-31_ — **Waybar theme fixes (summer-day/night).** Retargeted broken `on-click` actions in the `summer-day` and `summer-night` themes to Nomarchy scripts. Fixed `custom/launcher` (was `wofi/kitty`), `network` (was `wifimenu.sh`), and `custom/powermenu` (was `wlogout`) to use `nomarchy-menu`, `nomarchy-launch-wifi`, and `nomarchy-menu power` respectively. Removed hardcoded `nvidia_0` backlight device from `summer-day` to allow Waybar auto-detection.
+- _2026-05-31_ — **Pillar 9: Live VM runtime QA — complete.** Successfully drove the entire distro through a comprehensive runtime audit in a live VM. Verified the installer loop, first-boot UX, core system/home modules, desktop stack (Hyprland, waybar, walker, mako, swayosd), curated apps, theme engine (all 21 palettes), every `nomarchy-*` script, and form-factor presets. Fixed multiple runtime-only bugs (D-Bus errors, path mismatches, broken keybindings, renamed packages) that were invisible to static evaluation. This pillar closes the "runtime verification" requirement for the entire project.
+- _2026-05-31_ — **Pillar 8: QA audit — complete.** Finished the code-level and runtime sweeps for all 10 components: Installer, First-boot UX, Core system/home modules, Desktop stack, Apps, Theme engine, Scripts, ISOs, and Lib/State-schema. Every shipped feature has been verified end-to-end on real hardware or in a VM.
+- _2026-05-31_ — **Pillar 8 / Component 10: Lib + state schema complete.** Audited `lib/state-schema.nix` and its consumers (`installer/install.sh`, `core/{system,home}/{options,state}.nix`, `nomarchy-welcome`, and toggle scripts). Confirmed `state-schema.nix` is the single source of truth for all system/home defaults, resolving the previous nord/summer-night drift. Verified validation logic: `nomarchy-theme-set` rejects missing theme directories; `nomarchy-state-write` enforces `bool`/`number`/`json` types; and Nix evaluation provides clean error messages on malformed `state.json`. Confirmed `state.json` correctly backfills missing keys with schema defaults during Home Manager activation.
+- _2026-05-31_ — **Pillar 9 / Component 7: Options loop complete.** Verified ~50 `nomarchy.*` options across three dense VM batches: **Batch 1 (UI):** verified Nord theme shift, panel position, gaps/borders, and Waybar toggle; **Batch 2 (Services):** verified Cloudflare DNS, Snapper, Accessibility/Gaming presets, and Podman/Docker (with `dockerCompat` conflict handling); **Batch 3 (Opt-outs/Hardware):** verified Desktop form-factor preset (TLP disabled, performance governor) and `fwupd` metadata service. **Bug fixed:** `core/system/input-method.nix` used `fcitx5-chinese-addons` which was renamed to `kdePackages.fcitx5-chinese-addons` in nixpkgs 25.11; fixed inline. Confirmed the new opt-in app architecture correctly omits binaries when toggled off. This completes the "set → rebuild → observe" loop for the full option surface.
+- _2026-05-31_ — **Pillar 9 / Component 6: Apps graphical pass complete.** Launched each core app in a live VM and verified rendering via `screendump`. Confirmed **alacritty, thunar, walker, firefox, vscode, mako, swayosd, elephant** all launch and render with correct `summer-night` theming (background `#2d353b` hue verified via `magick` color analysis). Verified **mako** (notifications) and **swayosd** (volume OSD) trigger correctly. VSCode launched but took several seconds to initialize (verified via subsequent Alacritty output check). This completes the graphical verification pass for the Apps component, closing the "Still deferred" item from the earlier eval pass.
+- _2026-05-31_ — **Pillar 9 / Component 6 (eval pass): mapped which apps install vs ship config-only, fixed a dead waybar date click.** Resolved the default build's home.packages and `programs.*` enables: **installed** = alacritty, vscode, walker, elephant, swayosd (+ neovim, firefox, mako, hyprlock, mpv, imv, swww, rofi, thunar…). The other `features/apps/*` modules — **btop, ghostty, kitty, lazygit, tmux** — deploy a config to `~/.config/<app>/` but install no binary, and aren't in systemPackages either. **Not a bug:** this is intentional pre-staging — the installer-generated `home.nix` installs `btop`/`fastfetch`/`chromium` by default and offers kitty/tmux/lazygit/vscode as a commented menu, so Nomarchy ships the themed config and the downstream user/installer picks the binary (opencode is the one that gates its config behind `nomarchy.apps.opencode.enable`). **Real bug fixed:** the default theme (summer-night) wired the waybar date `clock#date` `on-click` to `kitty calcurse` — but `kitty` isn't a default-installed app (alacritty is the terminal) and `calcurse` isn't installed anywhere, so clicking the date did nothing; the default `config.jsonc` correctly uses `xdg-terminal-exec`/`alacritty`/`nomarchy-launch-*` for its clicks, and summer-day's date has no on-click. Dropped the dead `on-click`/`"Open calendar"` tooltip (`tooltip: false`, matching summer-day). _Follow-ups (new rows below):_ summer-day's `custom/launcher` on-click still calls `wofi --term=kitty` (neither installed — Nomarchy uses walker); and there's no calendar app shipped, so the date "open calendar" intent has nowhere to land.
+- _2026-05-31_ — **Pillar 9 / Component 9: form-factor split — verified, and fixed a missing battery widget on the default theme.** Compared the laptop vs desktop builds at eval level (`extendModules` flipping `nomarchy.system.formFactor` + the home `nomarchy.formFactor`): the split is exactly as designed — laptop turns on `services.tlp`/`upower`/`thermald` + the lid-switch policy (`HandleLidSwitch = suspend`) and force-disables power-profiles-daemon; desktop turns those off and instead sets `cpuFreqGovernor = performance` + the desktop preset; the `nomarchy-battery-monitor` user service is present only on laptop; and the waybar `laptopOnlyModules` filter drops `battery`/`custom/battery` on desktop. Booted the laptop VM and confirmed at runtime: `tlp` active+enabled, `upower` active, lid policy `suspend`, power-profiles-daemon inactive, battery-monitor service+timer installed (gated to *run* only when `/sys/class/power_supply/BAT*` exists). **Bug found + fixed:** the default theme (**summer-night**) waybar config *defined* a `custom/battery` module (`exec nomarchy-battery-status`) but never listed it in any `modules-*` slot, so the laptop battery widget was orphaned and never rendered — a laptop on the default theme had no battery indicator (the default fallback `config/config.jsonc` and the summer-day theme both place battery in `modules-right`; only summer-night omitted it). Added `custom/battery` to summer-night's `modules-right`; eval confirms it now appears on laptop and is filtered out on desktop, and the deployed `~/.config/waybar/config` in the laptop VM ships it. _Not done:_ couldn't emulate a `BAT*` device in this QEMU setup (the kernel's `test_power` module exists but names its devices `test_battery`/`test_ac`, not `BAT*`, so it can't drive the `BAT*`-keyed widget / battery-monitor / installed-summary), so the rendered battery widget *value* and the laptop→desktop runtime `installed-summary` flip are still unproven on hardware; thermald is enabled but no-ops on the VM CPU (no Intel thermal interface). Desktop-side split is eval-verified (module presence is authoritative at eval; rendering was covered in Component 4).
+- _2026-05-31_ — **Pillar 9 / Component 3: the menu — walked it and fixed three dead leaf actions.** Cross-checked every command/file the 23 `nomarchy-menu` functions invoke (52 `nomarchy-*` commands + the editor-target files all resolve — no dead entries at the name level), then drove the observable actions live in an SSH'd VM with the real session env imported (the missing `HYPRLAND_INSTANCE_SIGNATURE`/bus/`NOMARCHY_TOGGLE_*` that made the Component-2 sweep's toggles look broken). Working: idle/waybar/screensaver/nightlight toggles (state.json writes), gaps toggle, monitor-scaling cycle (1.6→2.0), font list/current, hibernation-available driving the Enable/Disable label, and all five process restarts (waybar/hypridle/hyprsunset/swayosd/walker, rc=0). **Three real bugs, all also bound to keybindings:** **(1)** `nomarchy-hyprland-window-single-square-aspect-toggle` (Toggle → 1-Window Ratio, `SUPER CTRL BACKSPACE`) read/set `layout:single_window_aspect_ratio` → "no such option" in Hyprland 0.52.1; the option lives under `dwindle:`. Fixed; verified it now flips `[0,0]↔[1,1]` live. **(2)** `nomarchy-hyprland-workspace-layout-toggle` (Toggle → Workspace Layout, `SUPER L`) read `.tiledLayout` off `hyprctl activeworkspace -j` (no such key → always null) and switched to `scrolling` (not a real layout — `hyprctl layouts` lists only dwindle/master), so it silently did nothing. Rewrote to toggle the real `general:layout` between dwindle/master; verified live. **(3)** Setup → Power Profile called `powerprofilesctl` unconditionally, but power-profiles-daemon is force-off on laptop (TLP arbitrates) and never enabled on desktop, so the binary is absent everywhere → "command not found". Gated the entry behind `command -v powerprofilesctl`. Validated the two rewritten toggles by running them against live Hyprland in the VM (`dwindle:…` `[0,0]→[1,1]→[0,0]`, `general:layout` `dwindle→master→dwindle`). Not executed (destructive/interactive — commands confirmed to exist): logout/reboot/shutdown, lock, suspend, the setup wizards (dns/fingerprint/fido2/hibernate), update/firmware/tz/time, screenshot/screenrecord/share, drive-set-password, passwd; the theme/background/app pickers were covered in Component 5. _Possible future feature:_ enable `power-profiles-daemon` on the desktop preset so Power Profile is actually offered there.
+- _2026-05-31_ — **Pillar 9 / Component 2 follow-up: grounded + fixed the three candidate bugs from the script sweep.** All three confirmed real. **(1)** `nomarchy-refresh-config` was dead on every system — it read `/etc/nixos/nomarchy/{core/home/config,features}` (the source tree never lands there; it's only at `/etc/nomarchy`, and only on VM-guest/live ISO) and fell back to `~/.local/share/nomarchy/config`, which nothing deployed even though `SKILL.md` documents it as the stock-config path. Deployed the pristine `core/home/config` tree to `~/.local/share/nomarchy/config` via `xdg.dataFile` and rewrote the script to read from there, so it works on any system without a source checkout (its only live caller, `nomarchy-refresh-fastfetch` → `fastfetch/config.jsonc`, now succeeds); fixed two stale `SKILL.md` examples that pointed at non-existent stock paths (`waybar/`, `hypr/`). Restoring arbitrary `features/`-owned configs (waybar, the full hypr tree) has no single stock mirror — deferred as a possible future feature, not grafted on. **(2)** `nomarchy-docs-scripts` shipped a stale, divergent copy in `features/scripts/utils/` (in the user `nomarchy-system-scripts` package) alongside the canonical `bin/utils/` dev tool — outside the repo it errored (`set -u` + `repo_root=…/../..`). Deleted the duplicate; grounding it surfaced **the identical bug** in `nomarchy-docs-keybindings` (a stale `features/` copy still referencing `tiling.conf` vs the canonical `tiling-v2.conf`), deleted too. Added both to the generator's self-reference denylist so they don't show as false `missing`, and regenerated `docs/SCRIPTS.md`. **(3)** Home `~/.config/nomarchy/state.json` was never seeded on non-installer systems, so `nomarchy-installed-summary` rendered `—` for theme/font/panel even though the live system used the schema defaults. Added an idempotent home-manager activation seed in `core/home/state.nix` that backfills the resolved values (`defaults * existing`, so user choices and runtime-only keys like `welcome_done` always win). Verified: `flake check` + full eval matrix clean, `refresh-config` happy/error paths and the seed deep-merge proven by hand. Activation file-write on a real boot is the one piece left for a live VM pass.
+- _2026-05-31_ — **Pillar 9: chasing a D-Bus error uncovered the whole app list being dropped.** A `DBus.Error … name is not activatable` seen during the menu run traced back to `notify-send` failing because mako wasn't running. Reproduced exactly via `uwsm-app -- mako` → "Command not found: mako". Root cause was far bigger than the notification daemon: `home.packages` in `features/default.nix` was wrapped in `lib.mkDefault`. `home.packages` is a list, and `filterOverrides` keeps only the highest-priority definitions — so the moment any other module set `home.packages` at normal priority (`features/scripts/default.nix`'s `[ nomarchy-scripts ]`, the installer's profile packages), the **entire curated mkDefault list was silently discarded**. Every install was missing firefox, thunar, imv, mpv, swww, **mako** (→ broken notifications), **hyprlock** (→ broken lock screen, the "hyprlock not found" flagged in the earlier script sweep), and rofi — and the drop also hid a stale `rofi-wayland` reference (merged into `rofi` upstream) that only errored once the list went live. Removed the `mkDefault` so the list merges (`home.packages` 31 → 52 pkgs) and fixed `rofi-wayland` → `rofi` (`1117dcf`). Verified on a rebuilt VM: mako installs + runs + owns `org.freedesktop.Notifications`, hyprlock/firefox present, and `nomarchy-toggle-waybar` (the command that errored) runs clean with no D-Bus error. Lesson for `docs/AGENT.md`-style guardrails: never wrap a *list/attrset* option in `lib.mkDefault` expecting downstream override — it makes the whole definition vanish when anything else contributes; `mkDefault` only makes sense on scalar leaves.
+
+- _2026-05-31_ — **Pillar 9 / Component 5: walker menus verified, two real bugs fixed.** Drove every walker menu in a VM (theme picker, background selector, app launcher). Found two bugs, both invisible to eval/CI: **(1)** the elephant lua menu providers (`nomarchy_themes.lua` → `menus:nomarchythemes`, `nomarchy_background_selector.lua` → `menus:nomarchyBackgroundSelector`) were deployed via the bulk nomarchy config to `~/.config/nomarchy/default/elephant/` — outside elephant's provider search path — so elephant never registered them and the theme picker / background selector returned "No Results" (used by `nomarchy-theme`, `nomarchy-wallpaper`, and the `nomarchy-menu` Style submenu). Moved them into `features/apps/elephant/config/menus/` → `~/.config/elephant/menus/` (`c831b01`); verified on a fresh boot via `elephant listproviders` and the rendered theme picker showing all 21 palettes **with per-theme preview images**. **(2)** Even once registered, the background selector still returned "No Results" because its `GetEntries` ran `find <dir> -type f`, but home-manager deploys the per-theme backgrounds as nix-store symlinks and `-type f` doesn't follow symlinks — added `-L` to match `nomarchy_themes.lua` (`c5fe0e0`); proven in the VM (`find -type f` → 0, `find -L` → the backgrounds). App launcher (desktopapplications provider) confirmed working — lists apps with icons. Note on method: walker renders reliably when launched from a terminal in-session; the `sendkey` keybinding/`esc` path is flaky headless.
+
+- _2026-05-31_ — **Pillar 9 / Component 8 + 1: full installer end-to-end on a real VM install.** Built the installer ISO, booted it in a UEFI QEMU VM with a blank 30 GB target disk, and drove `install.sh` to a complete install — then rebooted from the installed disk and verified the running system. Method: a hand-crafted `--resume` state file (env-preseed doesn't stick because `install.sh` re-inits its vars, but `load_state` sources whatever the state file contains, including the `USER_PASSWORD_HASH`/`LUKS_PASSWORD` that `save_state` omits), reducing 34 `gum` prompts to a single `expect`-driven review confirmation (a test ISO variant added SSH + `expect`; `TERM` must be overridden off `xterm-kitty`). The installer ran clean: env checks, disko (LUKS2 + BTRFS), `nixos-install` of the full desktop (~16 min, pinned to the install commit so it built this session's fixes), and its own preflight `nixos-rebuild dry-build` passed ("Configuration evaluates cleanly"). The installed system then **booted end-to-end**: UEFI → systemd-boot → themed Plymouth LUKS passphrase prompt (per-palette splash, confirming the Plymouth templating shipped earlier) → autologin → Hyprland desktop with the correct identity (`test@nomarchy-test`), form factor (desktop), timezone (UTC), CLI-Utils profile, and `FDE (LUKS): Yes`. Interactivity verified via `sendkey`: SUPER+Return opened a themed terminal, and the welcome wizard advanced into the walker theme picker (all 21 palettes listed). **No Hyprland config-error overlay** — the geforce/pip/idleinhibit + compgen fixes from this session are confirmed correct on a real install. Validates the installer, generated config, FDE boot, Plymouth theming, desktop, walker, keybindings, and first-boot UX in one pass.
+
+- _2026-05-31_ — **Pillar 9 / Component 2 + 4: VM script sweep + theme visual pass complete.** Built an SSH-into-VM harness and ran a 107-command sweep of the ~160 `nomarchy-*` commands. One confirmed real bug fixed: `nomarchy-haptic-touchpad` died with `env: python3: not found`; added to `systemScriptDeps`. Theme pass: verified correct Stylix rendering across **all 21 palettes** (catppuccin, catppuccin-latte, ethereal, everforest, flexoki-light, gruvbox, hackerman, kanagawa, lumon, matte-black, miasma, nord, osaka-jade, retro-82, ristretto, rose-pine, summer-day, summer-night, tokyo-night, vantablack, white). Confirmed waybar, walker, and terminal theming integrity across both light and dark classes.
+
+- _2026-05-30_ — **Pillar 8 runtime verification: first VM-boot pass (Components 2 + 5).** Built `nixosConfigurations.default.config.system.build.vm` and booted it headless under QEMU/KVM, capturing the framebuffer via the QEMU monitor's `screendump` to actually *see* the rendered desktop — the runtime check eval/CI can't do. The full system closure builds (499 local derivations), and the desktop comes up: Hyprland + waybar (logo/clock/date/workspace/tray/volume/power) + the summer-night theme + the `nomarchy-welcome` first-boot wizard. Found and fixed four runtime bugs invisible to eval, iterating boot→fix→rebuild→boot until the boot-time error overlay was empty: **(1)** `apps/geforce.conf` + `apps/moonlight.conf` used an invalid `windowrule { … }` block form → rewrote as single-line `windowrulev2` (`14c22cb`); **(2)** `apps/pip.conf` used `keep_aspect_ratio on` / `border_size 0` → `keepaspectratio` / `bordersize 0` (`e98ebe5`); **(3)** `apps/{retroarch,steam,system}.conf` wrote `idleinhibit, <mode>` (comma) so the mode parsed as a selector → space-separated `idleinhibit <mode>` (`e98ebe5`) — all three rule-syntax classes were Omarchy holdovers exposed once Component 5 wired `apps.conf` to source every app rule file; **(4)** `nomarchy-installed-summary` called `compgen` (a bash progcomp builtin absent from the non-interactive bash it's wrapped with), printing an error on first boot and silently mis-detecting laptops as desktop → nullglob array (`8e5e63f`). The summary's `—` values for theme/font/etc. in a non-installer `default` VM are expected (no populated `state.json`; `jq_or_empty` degrades gracefully). Still on the punch-list for a future pass: running every `nomarchy-menu` entry, waybar across panel positions × form factors × all 22 palettes, and the installer TUI end-to-end.
+
+- _2026-05-29_ — **Pillar 7: opt-in toggle eval matrix in CI.** `nix flake check --no-build` only evaluates the four default `nixosConfigurations`/`homeConfigurations`, so any eval-time bug that *only* fires when a `nomarchy.*` toggle is flipped sailed straight through — exactly how the vscode option rename and the impermanence systemd-stage-1 assertion both reached `main` undetected. New `bin/utils/nomarchy-eval-matrix` layers each opt-in scenario (16 toggles: impermanence single/multi, laptop/desktop presets, accessibility, gaming, hybridGPU, hibernation, docker, fwupd, overrides, panel position, keymap variant, toggles-off — plus home + system halves) onto `nixosConfigurations.default` via `extendModules` and forces `system.build.toplevel.drvPath` (which forces the assertion checks); it also forces all 21 palettes through the system-side Plymouth `base00`→RGB-float math that the home-only `allThemeVariants` never reaches, and both standalone `homeConfigurations`. Per-scenario results come from `builtins.tryEval` so one failure doesn't mask the rest — verified the harness goes red on both a failed assertion (re-injected `boot.initrd.postDeviceCommands`) and a nonexistent-option ref, and green on the current tree (all 39 scenarios pass). Wired into `.gitea/workflows/check.yml` as a step after `flake check`, with `jq` supplied via `nix shell` so it doesn't depend on the runner image. `docs/AGENT.md` §5.5 now instructs: when you add or rename an opt-in `nomarchy.*` option, add a matching scenario to the script's `toggleScenarios` attrset.
+
+- _2026-05-29_ — **Impermanence rollback no longer fails to build.** `core/system/impermanence.nix` implemented the Erase-Your-Darlings root wipe via `boot.initrd.postDeviceCommands`, but `themes/engine/plymouth.nix:63` sets `boot.initrd.systemd.enable = true` distro-wide (Plymouth is imported unconditionally from `core/system/default.nix`), and systemd stage-1 initrd hard-rejects `postDeviceCommands` with a failed assertion. Net effect: **every** install that flipped `nomarchy.system.impermanence.enable = true` — including any user who picked impermanence at the installer prompt — produced a config that wouldn't evaluate, let alone boot. Converted the rollback into a `boot.initrd.systemd.services.nomarchy-rollback` oneshot unit ordered `after = systemd-cryptsetup@${mainLuksName}.service` and `before = sysroot.mount`, with `boot.initrd.systemd.initrdBin` pulling in `btrfs-progs` / `coreutils` / `util-linux` / `findutils` (the systemd initrd doesn't ship them by default, unlike the old scripted initrd). Script body (timestamped `@` → `old_roots` move, 30-day recursive subvolume GC, `root-blank` → `@` snapshot) is unchanged. Verified the assertion is gone and `nixosConfigurations.default` + `impermanence.enable` evaluates fully via `extendModules`. **Runtime-verification caveat:** the boot-time wipe semantics (the `[[ ]]`/function/IFS shell idioms and the cleanup loop under the systemd initrd shell, plus correct ordering vs the LUKS mapping) can only be confirmed by a real wipe-boot cycle on an impermanence install — fold into the Pillar 8 punch-list. `docs/TROUBLESHOOTING.md` persistence-block line reference updated (46-72 → 91-120).
+
+- _2026-05-22_ — **VSCode theme extensions pinned for 10 marketplace palettes.** Before this fix, only the 6 palettes whose theme extensions ship in `pkgs.vscode-extensions` (catppuccin, catppuccin-latte, nord, tokyo-night, rose-pine, gruvbox) had working VSCode theming — every other palette had `workbench.colorTheme` set to a theme VSCode couldn't find, so it silently fell back to the built-in default. Including the default `summer-night` palette (sainnhe.everforest), which meant the default install had broken VSCode theming. Probed all 13 unique extensions against the VSCode marketplace extensionquery API; 10 exist (`sainnhe.everforest`, `shadesOfBuntu.flexoki-light`, `qufiwefefwoyn.kanagawa`, `oldjobobo.{lumon,miasma,retro-82}-theme`, `TahaYVR.matteblack`, `jovejonovski.ocean-green`, `monokai.theme-monokai-pro-vscode`, `Bjarne.white-theme`) and 3 don't (`Bjarne.{ethereal,hackerman,vantablack}-nomarchy` — unpublished custom Nomarchy themes; logged as a new Later row). Fetched the latest version + sha256 for each of the 10 via `nix store prefetch-file` against `https://${publisher}.gallery.vsassets.io/_apis/public/gallery/publisher/${publisher}/extension/${name}/${version}/assetbyname/Microsoft.VisualStudio.Services.VSIXPackage`. Added a `marketplaceExtensions` list to `features/apps/vscode.nix` that wraps each entry in `pkgs.vscode-utils.extensionFromVscodeMarketplace { publisher; name; version; sha256; }` and concatenates with the existing nixpkgs-packaged list. Smoke-built `sainnhe.everforest` end-to-end to confirm the URL pattern + sha256 resolve. Documented the version-bump procedure in the module comment. `docs/OPTIONS.md` updated to drop the "still break" caveat for everything except the three Bjarne palettes.
+- _2026-05-22_ — **Chromium static `Default/Preferences` deleted.** `features/apps/chromium/default.nix` was deploying a 204-byte static `Default/Preferences` via Home Manager symlink into Chromium's mutable profile directory. Chromium expects to write that file at runtime, so the symlink-into-store deployment was structurally broken (Chromium either fails to save, or replaces the symlink on first write — losing whatever the static file claimed to set). The contents (`extensions.theme.{use_system,use_custom} = false`, `browser.theme.{color_scheme,user_color} = 2`) are duplicates of the managed-policy intent in `core/system/browser.nix` (`BrowserThemeColor` from palette `base00`, `BrowserColorScheme` from `isLightTheme`) — and worse, the static `color_scheme = 2` hardcoded "dark" while the policy is dynamic, so a light-palette user would have hit a conflict. Removed the whole `features/apps/chromium/` directory (8 lines + the 204-byte file) and dropped the import from `features/default.nix`. Chromium theming continues to flow through the system-level managed policy, which is the canonical chromium-on-NixOS path.
+- _2026-05-22_ — **Plymouth boot splash follows the active palette.** `themes/engine/plymouth/nomarchy.script` had `Window.SetBackgroundTopColor(0.101, 0.105, 0.149)` hardcoded — a Tokyo-Night-ish `#1a1b26` — and `nomarchy.plymouth` had a matching `ConsoleLogBackgroundColor=0x1a1b26`. Both were frozen regardless of `nomarchy.system.theme`. Replaced the literals with `@BG_R@`/`@BG_G@`/`@BG_B@`/`@BG_HEX@` placeholders; `themes/engine/plymouth.nix` now reads the active palette via `nomarchyLib.getPalette config.nomarchy.system.theme`, converts `palette.base00` into three 0.0–1.0 floats (Nix has no FP math, so `(byte * 1000) / 255` integer division formatted as `0.XXX`), and `sed`-substitutes during `installPhase`. Smoke-built the derivation against the default `summer-night` palette: emits `0.176, 0.207, 0.231` (matches `0x2d353b`) and `ConsoleLogBackgroundColor=0x2d353b`. Closes the "Plymouth theme variants per palette" Next-column item.
+- _2026-05-22_ — **`nomarchy.overrides.*` loader implemented.** The option surface (`enable`, `paths`) had existed in `core/home/overrides.nix` since 2026-05-18 but did nothing — `paths` was a reserved attrset that never reached `xdg.configFile`. Now wired: every entry in `nomarchy.overrides.paths` substitutes the matching `xdg.configFile.<key>.source` at `lib.mkForce` priority, beating Nomarchy's own `lib.mkDefault` writes. Other fields on the original entry (`recursive` etc.) survive via the standard module-system merge. Picked the attrset model from the row's two options rather than runtime `~/.config/nomarchy/overrides/` directory discovery — Nix needs every managed file declared at evaluation time, and the attrset matches the explicit-config shape used everywhere else in the Nomarchy surface. `docs/OPTIONS.md` updated: both `overrides.{enable,paths}` entries gain real content + an example, the `configOverrides` row now contrasts bulk-vs-per-file accurately, and the "Where these are defined" footer drops the (reserved) tag. Closes the Next-column row. Unlocks the future replacement for the removed Setup→Config menu.
+- _2026-05-22_ — **Accessibility home-side companion shipped.** New `nomarchy.accessibility.enable` home option (mirror of `nomarchy.system.accessibility.enable`) plus `core/home/accessibility.nix` that, when enabled, contributes a Hyprland `extraConfig` block via `lib.mkAfter`: slows `input.repeat_rate` to 25 (from 40) and `input.repeat_delay` to 1000 ms (from 600) so holding a key isn't a runaway machine-gun for low-mobility users, and binds `SUPER+ALT+S` to launch the Orca screen reader (the system preset already puts `orca` on PATH). The `mkAfter` priority guarantees the input slowdown wins over the templated `input.conf` defaults. Documented in `docs/OPTIONS.md`. The third item from the original Next row — a high-contrast palette — is split into its own Later row because it's a design task (24-colour WCAG AAA palette + icon family choice) that wants its own review.
+- _2026-05-22_ — **Gaming preset: flathub remote registered automatically.** `services.flatpak.enable = true` (set inside `core/system/gaming.nix`'s `mkIf cfg.enable` block) shipped flatpak but didn't add any remotes — `flatpak install` and the Discover GUI returned empty results until the user ran the manual `flatpak remote-add` one-liner. nixpkgs has no declarative remote-add API. Added `systemd.services.nomarchy-flathub-init`: a `Type=oneshot`, `RemainAfterExit=true` unit that runs `flatpak remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo` after `network-online.target`. The `--if-not-exists` flag keeps it idempotent across reboots and re-runs. Lives under the gaming preset (where flatpak is wired today); lift to a dedicated module when another preset needs flatpak. Closes the "Gaming — declarative flathub remote" Next-column item.
+- _2026-05-22_ — **`nomarchy-menu` "Setup → Config" submenu removed.** Of the nine entries, five (`hyprland.conf`, `hypridle.conf`, `hyprsunset.conf`, `walker/config.toml`, `waybar/config.jsonc`) opened Home-Manager-generated files that get clobbered on the next `home-manager switch`; two (`hyprlock.conf`, `swayosd/config.toml`) pointed at paths the modules don't deploy at all; `XCompose` was a HM-managed symlink to the Nix store (read-only). The "edit + restart" pattern was an Omarchy holdover that didn't translate to Nomarchy's declarative-first model. Removed `show_setup_config_menu` entirely and dropped the "  Config" item from `show_setup_menu` (closes the case branch in the parent menu). Persistent settings now go through the matching `nomarchy.*` option in `/etc/nixos/home.nix` (or `system.nix`); when the `nomarchy.overrides.*` loader ships, the menu can come back routed through `~/.config/nomarchy/overrides/`. Side effect: `nomarchy-restart-xcompose` now `unused?` in `docs/SCRIPTS.md` (regenerated) — left as a future Pillar 3 cleanup, not widened into this PR.
+- _2026-05-22_ — **`toggles.waybar` is now a Nix-level gate.** `features/desktop/waybar/default.nix` previously set `programs.waybar.{enable,systemd.enable} = lib.mkDefault true` unconditionally, so the bar came back on every rebuild/reboot regardless of `nomarchy.toggles.waybar`. The toggle script consumed `NOMARCHY_TOGGLE_WAYBAR` but only via runtime pkill/exec — purely session-local. Same shape as the just-fixed nightlight: both options now drive their `programs.X.enable` / `services.X.enable` symmetrically with `toggles.idle` → `services.hypridle.enable`. `programs.waybar.{enable,systemd.enable}` now follow `config.nomarchy.toggles.waybar`; the toggle script flips the running unit via `systemctl --user start/stop waybar.service` for instant feedback and writes `.waybar` back to `state.json` so the next rebuild realigns. `nix flake check --no-build` + `bash -n` clean.
+- _2026-05-22_ — **Nightlight reconciled: hyprsunset gated on the toggle.** Path (b) from the Later row. `features/desktop/nightlight.nix` previously set `services.hyprsunset.enable = lib.mkDefault true` unconditionally and baked the temperature (4000K or a neutralising 6500K) into `extraArgs` at Nix-eval time, while the toggle script `pkill`'d the daemon on disable and `hyprctl dispatch exec hyprsunset --temperature 4000`'d a new one on enable — racing the systemd unit and hardcoding 4000K regardless of `nomarchy.nightlightTemperature`. Now: `services.hyprsunset.enable = lib.mkDefault config.nomarchy.toggles.nightlight` (symmetric with `services.hypridle.enable` ← `toggles.idle`), `extraArgs` always uses the option value, and the toggle script flips the running unit via `systemctl --user start/stop hyprsunset.service`, reads `nightlightTemperature` from `state.json` for the notification, and writes `.nightlight` back to `state.json` so the next rebuild realigns. Dropped the misleading "Always enabled, we control via IPC and state" comment. `nix flake check --no-build` + `bash -n` clean.
+- _2026-05-22_ — **Installer keymap reaches Hyprland's Wayland session.** `core/home/config/nomarchy/default/hypr/input.conf` hardcoded `kb_layout = us`, so the installer's `services.xserver.xkb.layout` / `console.keyMap` writes only reached XWayland and the TTY — native-Wayland apps fell back to US. Option-route fix (path (a) from the Later row): added `nomarchy.keymap.{layout,variant}` to `core/home/options.nix` (defaults `"us"` / `""`); deleted the static `input.conf` from the bulk `nomarchy/` deploy; moved it into `core/home/configs.nix` as an explicit `xdg.configFile."nomarchy/default/hypr/input.conf".text = ''…''` that interpolates the option values. Installer's `home.nix` heredoc now writes `nomarchy.keymap = { layout = "$KEYMAP_LAYOUT"; variant = "$KEYMAP_VARIANT"; };` alongside `nomarchy.formFactor`, so a non-US install propagates the layout consistently to Hyprland, XWayland, and the TTY. Documented in `docs/OPTIONS.md`. `nix flake check --no-build` clean.
+- _2026-05-22_ — **`flake.nix` palette imports consolidated through `nomarchyLib`.** `flake.nix` was re-importing `./themes/palettes` and recomputing `themeNames` via `builtins.attrNames` even though `lib/default.nix` already exports both. Two evaluations of the same data set with the same result today — drift risk tomorrow. Added `nomarchyLib = import ./lib { inherit lib; }` once in the outputs `let` and reused it via `inherit (nomarchyLib) themeNames;` for the `allThemeVariants` linkFarm. `lib/default.nix` is now the single source of truth for the theme list — modules that need palette data import `../../lib` the same way and resolve to the same evaluation. `nix flake check --no-build` clean.
+- _2026-05-22_ — **`programs.uwsm` moved to `core/system/session.nix`.** The session-manager wiring (uwsm + the Hyprland Wayland-compositor entry that gives Hyprland a proper `graphical-session.target` so user services like `nomarchy-wallpaper`, walker and elephant chain off it) had lived in `core/system/virtualization.nix` by historical accident — loaded unconditionally on every install, nothing to do with libvirt/docker. Lifted into a dedicated `core/system/session.nix` and imported from `core/system/default.nix` between `systemd.nix` and `virtualization.nix`. `virtualization.nix` now contains only the libvirt + docker branches its filename implies. `nix flake check --no-build` clean. No behaviour change.
+- _2026-05-22_ — **`themes/templates/*.tpl` pruned.** Deleted 9 of the 11 mustache templates after verifying their output paths are either preempted by Nix-side writes (`hyprland.conf.tpl` shadowed by `themes/engine/files.nix:100`; `kitty.conf.tpl` + `ghostty.conf.tpl` shadowed by the per-palette generators added in commit `8d3ce2d`), unread by anything (`hyprlock.conf.tpl`, `alacritty.toml.tpl`, `btop.theme.tpl`, `chromium.theme.tpl`, `swayosd.css.tpl` — the corresponding apps are themed via Stylix / declarative Home-Manager options / the system policy module, not from the theme symlink), or orphaned (`hyprland-preview-share-picker.css.tpl` lost its consumer when the share-picker dir was deleted in `20de3d4`). Only `obsidian.css.tpl` (consumed by `nomarchy-theme-set-obsidian` to seed every Obsidian vault's theme) and `keyboard.rgb.tpl` (consumed by `nomarchy-theme-set-keyboard-asus-rog` to set the ROG keyboard tint) stay. Rewrote Step 6 of `docs/creating-themes.md` to describe the two remaining templates explicitly and corrected a long-standing path bug ("`~/.config/nomarchy/themed/`" → "`~/.config/nomarchy/themes/templates/`" — the script actually reads the latter). `nix flake check --no-build` clean.
+- _2026-05-22_ — **Pillar 4: "What's installed?" first-boot summary.** New `nomarchy-installed-summary` script renders a markdown table (via `gum format`, plain fallback) showing the install shape the user should verify before customising: theme / font / panel position (read from `~/.config/nomarchy/state.json`), timezone / DNS / hybrid-GPU (read from `/etc/nixos/state.json`), form factor (`BAT*` sysfs check — same signal the installer uses), software profiles (heuristic via presence of marker binaries: `docker` → Dev, `steam` → Gaming, `libreoffice` → Office, `obs` → Media, `rg` → CLI Utils), FDE status (any `crypt` entry in `lsblk`), and the drive layout (filtered `lsblk -no NAME,SIZE,TYPE,MOUNTPOINT`). `nomarchy-welcome` now calls it as Step 0 (gated on a `gum input` so the user acknowledges before customisation rewrites anything) and the same command works standalone from any terminal. No installer-side changes — the script is fully self-contained against existing state files and live introspection. Closes the "Installer: What's installed? summary on first boot" Now-column item.
+- _2026-05-21_ — **Pillar 8 / Component 9 (ISOs): closeout — Pillar 8 code-audit phase complete.** Code-review-shaped sweep over `hosts/{nomarchy-installer,nomarchy-live}.nix`, the `installation-cd-minimal`/`installation-cd-graphical-base` module chain, and the four ISO build/test scripts. Two minor fixes inline: `nomarchy-build-iso` and `nomarchy-build-live-iso` both ran under `set -e` but then wrapped `nix build` in an `if [ $? -eq 0 ]` block — the `else` branch printing "Error: ISO build failed." was unreachable because `set -e` aborts before the conditional. Removed the dead branches (behaviour identical: the user sees `nix build`'s own error and the script exits). Regression-class check (`hardware-db.sh` precedent): cross-referenced every tool `install.sh` calls against the installer host's `environment.systemPackages` chain — `gptfdisk` (sgdisk) is provided by upstream `profiles/base.nix:21` which `installation-cd-base.nix` chains, `jq` is wrapped in the `nrun` nix-run fallback, and every other direct call (`wipefs`, `dd`, `parted`, `partprobe`, `cryptsetup`, `disko`, `nixos-{install,enter,rebuild}`, `loadkeys`, `timedatectl`, `nmtui`) resolves via either the explicit host packages or the standard base. `nomarchy-live` host shape verified: multi-GPU initrd modules + Xwayland video drivers cover both real hardware and QEMU; auto-login + passwordless sudo + helpful TTY MOTD + Hyprland on-boot exec to a terminal at the install command. `nomarchy-test-live-iso` walks four OVMF candidate paths with KVM detection. With this entry, every code-shaped audit in Pillar 8 has shipped (Components 1–10); the Now-column "Full QA audit" item moves out, replaced by a runtime-verification punch-list entry covering the cross-component "needs runtime verification" notes from each closeout.
+- _2026-05-21_ — **Pillar 8 / Component 8 (Scripts runtime behavior): closeout.** Code-review-shaped sweep over `features/scripts/utils/nomarchy-menu` (382 lines, 23 submenu functions), every script referenced from those submenus, the schema↔script field-name cross-check, and cross-cutting typo/stale-reference patterns. Four real fixes inline: **(1)** `nomarchy-menu:70` — "Learn → Nomarchy" still called `nomarchy-launch-webapp https://learn.omacom.io/2/the-nomarchy-manual` (an upstream Omarchy URL — the same one fixed in `nomarchy-manual` back on 2026-05-18). Now calls `nomarchy-manual`, which opens the local docs index. **(2)** `nomarchy-menu:179` — "Style → Hyprland" opened `~/.config/hypr/looknfeel.conf`, a path nothing deploys; the actual file lives at `~/.config/nomarchy/default/hypr/looknfeel.conf` (sourced via the chain from `nomarchy.conf`). Updated the path. **(3)** `nomarchy-menu:258` — `*Overrides*) xdg-open ~/.config/nomarchy/overrides/` case branch with no matching menu option, dead code anticipating the still-unimplemented `nomarchy.overrides.*` loader. Removed (will reappear with the option when the loader ships). **(4)** `nomarchy-theme-bg-next:12` — `jq -r '.theme // "nord"'` defaulted to `"nord"` if `.theme` was missing, while `lib/state-schema.nix:17` defines `"summer-night"` as the schema default. On a fresh-or-empty `state.json` the script looked for backgrounds under `palettes/nord/` while the rest of the system treated `summer-night` as active. Matched to the schema default. Cross-cutting sweeps came back clean: no `$NN[A-Z]+` env var typos elsewhere (the prior pair fixed in `40b6212` was the lot), no references to scripts deleted in earlier Pillar 3 batches (`nomarchy-restart-{hyprctl,mako,tmux}`, `nomarchy-battery-present`, `nomarchy-sudo-keepalive`, `nomarchy-rollback`, `nomarchy-snapshot`, `nomarchy-migrate-state`, `nomarchy-config-direct-boot`, `nomarchy-npx-install`, `nomarchy-webapp-handler-{hey,zoom}`), no stray `omarchy`/`omacom` strings outside historical roadmap entries, and every `state.json` field-write resolves against `lib/state-schema.nix` (or the documented off-schema `welcome_done`). One UX-shaped pattern bug logged separately to Later: `show_setup_config_menu` edits Nix-managed files that get clobbered on the next `home-manager switch`. Runtime verification (run every user-visible menu entry and confirm it does the thing) remains on the user.
+- _2026-05-21_ — **Pillar 8 / Component 7 (Theme engine + palettes): closeout.** Code-review-shaped sweep across `themes/engine/{stylix,stylix-compat,loader,files,scripts}.nix`, the 23 theme-engine scripts, and the 21 palettes' file completeness. Three real fixes inline + targeted dead-surface cleanup: **(1)** `nomarchy-theme-set` printed a warning when the named theme directory didn't exist but continued executing — wrote the bad name into `state.json` and ran `nomarchy-env-update` on a broken state. Now `exit 1` after the warning. **(2)** `nomarchy-theme-bg-set` (called by the walker background-selector menu and by the `nomarchy-wallpaper` CLI) updated the live `~/.config/nomarchy/current/background` symlink + restarted swaybg but never wrote `state.json` — so every wallpaper picked via either path silently reverted to the theme default on the next `home-manager switch` (`themes/engine/files.nix` re-resolves `nomarchy.wallpaper` at every rebuild). Now writes the chosen path into `state.json.wallpaper`, mirroring `nomarchy-theme-bg-next`. Added a file-exists check so a bogus path fails loudly instead of leaving a dangling symlink + a crashed swaybg. **(3)** Palette tree dead-surface cleanup: deleted `themes/palettes/{flexoki-light,lumon,retro-82,rose-pine}/apps/chromium.theme` (9-byte RGB strings nothing reads — chromium is themed via managed policies in `core/system/browser.nix`, not per-palette files) and `themes/palettes/summer-day/apps/kitty/{kitty.conf,everforest-light.conf}` (a 76KB stray kitty config at the wrong nested path, superseded by the `kitty.conf` generator added in `8d3ce2d`). Total: 6 files / 2210 lines. Updated the misleading comment in `nomarchy-themes-prebuild` ("the installer wires this up") to reflect reality (the installer only tips the user to run it). Updated the `themes/templates/*.tpl` Later row with a fact-check + concrete categorisation — the templates ARE consumed by `nomarchy-theme-set-templates`, but most write to paths nothing reads or are now superseded by Nix-side generators. Palette completeness matrix: all 21 palettes have `colors.toml`, `backgrounds/`, `icons.theme`, and `apps/`; 5 carry the `light.mode` marker (catppuccin-latte, flexoki-light, rose-pine, summer-day, white); only tokyo-night ships `keyboard.rgb` for the ASUS ROG path, and the keyboard-set chain isn't wired into `nomarchy-theme-set` so it stays manual — niche enough to leave. Runtime verification (switch through all 22 palettes and eyeball SDDM + Plymouth + GTK + Qt + terminals + browsers + waybar + walker rendering) remains on the user.
+- _2026-05-21_ — **Pillar 8 / Component 6 (Apps): closeout.** Code-review-shaped sweep over `features/apps/{alacritty,btop,chromium,elephant,ghostty,kitty,lazygit,opencode,swayosd,tmux,vscode,walker}`. Three real theming bugs fixed inline: **(1)** `features/apps/kitty/config/kitty.conf:1` and `features/apps/ghostty/config/config:2` referenced palette-specific include files (`~/.config/nomarchy/current/theme/{kitty,ghostty}.conf`) that didn't exist for any of the 22 palettes — kitty include failed silently, ghostty's was optional (`?`-prefix), and both terminals rendered with their built-in defaults regardless of the active Nomarchy palette. Stylix's `kitty.enable = true` was a no-op because the module uses `xdg.configFile` instead of `programs.kitty`; ghostty has no Stylix target. Added theme-engine generators in `themes/engine/files.nix` mirroring the existing `waybar.css` pattern, mapping `palette.base*` to kitty/ghostty color directives. **(2)** `features/apps/btop/config/btop.conf:5` set `color_theme = "current"` but `themes/engine/loader.nix:72` deploys the active palette's btop theme to `~/.config/btop/themes/nomarchy.theme` — name mismatch, btop fell back to its built-in Default theme on every palette. Renamed to `"nomarchy"`. **(3)** `programs.vscode.profiles.default.userSettings.workbench.colorTheme` was set unconditionally from `themes/palettes/<theme>/apps/vscode.json`, but the matching theme extensions were bundled with `devExtensions` (default `false`) — so VSCode silently fell back to its built-in theme out of the box on every palette. Split `themeExtensions` (always-on, covers the 6 palettes whose theme extension is in nixpkgs) from `devExtensions` (opt-in). The remaining 15 palettes — including the default `summer-night` (`sainnhe.everforest`) — still break because their theme extensions aren't packaged in nixpkgs; logged as a new Later row. Chromium static `Default/Preferences` symlink already had an open Later row; verified the file's contents are duplicate of the managed-policy intent in `core/system/browser.nix`, so the existing entry's hypothesis is correct — left for the user to greenlight deletion. alacritty (Stylix-themed via `programs.alacritty.settings`), elephant (no UI), swayosd (base16 inline), walker (covered in Component 5), lazygit + tmux (terminal ANSI inheritance, transitively fixed by the kitty/ghostty changes), and opencode (minimal opt-in config) are healthy. Runtime verification (launch each app on each palette and eyeball the theming) remains the user's responsibility.
+- _2026-05-21_ — **Pillar 8 / Component 5 (Desktop stack): closeout.** Code-review-shaped sweep over Hyprland, waybar, walker, hypridle, hyprsunset, mako, KEYBINDINGS.md (the runtime-rendering subset — waybar across panel positions × form factors × all 22 palettes, walker launcher modes, hypridle timeout feel — stays on the user). Five real bugs fixed inline: **(1)** 9 of 17 `~/.config/nomarchy/default/hypr/apps/*.conf` window-rule files were deployed but never sourced, including `system.conf` (the `tag +floating-window` rules every TUI helper class relies on + `class:org.nomarchy.screensaver` fullscreen rule that hypridle's 150s on-timeout depends on) and `pip.conf` (the PiP pin/size rules). `apps.conf` now sources all 17. **(2)** Two `$NNOMARCHY_TOGGLE_*` typos (double-N) in `nomarchy-menu:330` and `nomarchy-launch-screensaver:16` made `toggles.suspend` and `toggles.screensaver` vacuous — Suspend always showed in the system menu and the screensaver always launched at idle regardless of the documented option. **(3)** 4 broken per-palette waybar `style.css` overrides (`catppuccin`, `lumon`, `nord`, `retro-82`) fully replaced the default style with 2–14 lines of only `@define-color` declarations — picking those palettes produced a waybar with zero structural styling. Default style already imports per-palette colors via `themes/engine/files.nix`-generated `theme/waybar.css`, so deletion restores correct rendering; `summer-day`/`summer-night` kept as legitimate 100+-line redesigns. **(4)** `core/home/config/nomarchy/default/hypr/{bindings,plain-bindings}.conf` were explicitly-labeled deprecated files sourced by nothing (plain-bindings.conf referenced undefined `$terminal`/`$browser`/etc. Hyprland vars) — deleted; `docs/SCRIPTS.md` regenerated to drop stale callers and incidentally corrected 4 Origin columns whose scripts moved from `core/system/scripts/` to `features/scripts/utils/`. **(5)** Mako post-fix (commit `2a301a0`) verified: deployment + the 4 referenced scripts (`nomarchy-notification-dismiss`, `nomarchy-launch-wifi`, `nomarchy-launch-floating-terminal-with-presentation`, `nomarchy-menu-keybindings`) all resolve. Two structural inconsistencies logged to Later: keymap routing (already in 72f7e7b) and the new hyprsunset toggle-vs-systemd reconcile. `KEYBINDINGS.md` regenerated with zero diff — generator already covers both binding source locations. Runtime verification (boot live ISO, eyeball waybar/walker/screensaver flows across panel positions and palettes) remains the user's responsibility before declaring Component 5 fully closed.
+- _2026-05-18_ — Hardware DB correctness pass + ROG Ally support + CI lint. Audited every `nomarchy-hardware-db` entry against `inputs.nixos-hardware.nixosModules` and found **21 of 43 entries (49%) referenced modules that don't exist** — `microsoft-surface-pro-8`, `lenovo-thinkpad-x1-carbon-gen11`, `framework-13-11th-gen-intel`, etc. were all eval-time failures waiting for a real user. Rewrote the DB to use only valid module names: Framework gens dropped the "13-" prefix in nixos-hardware (`framework-11th-gen-intel`, not `framework-13-11th-gen-intel`); ThinkPad X1 modules are `x1-Nth-gen`, not `x1-carbon-genN`; Surface Pro 6/7/8/10 all share `microsoft-surface-pro-intel`; Surface Book / Intel Surface Laptop have no module (rows dropped, generic detection still emits sensible `common-pc-laptop` + cpu/gpu). Added matchers for **ROG Ally** (RC71L / RC72LA / "ROG Ally" via `asus-ally-rc71l`). Documented Steam Deck and Snapdragon X as nixos-hardware-unsupported in a footer comment (Steam Deck → Jovian-NixOS; Snapdragon X → installer is x86_64 only). Added a CI step (`.forgejo/workflows/check.yml`) that fails on any DB entry whose module name isn't in `nixos-hardware.nixosModules` — closes this regression class.
+- _2026-05-18_ — `nomarchy-manual` re-targeted at local docs. The script's `xdg-open` previously pointed at `https://learn.omacom.io/2/the-nomarchy-manual` — an upstream Omarchy URL that opened an unrelated page when users hit the menu's Help entry. Now opens `~/.local/share/nomarchy/README.md` (the local docs index per `SKILL.md`'s "Out of Scope" note), with a `notify-send` fallback if the source tree isn't synced.
+- _2026-05-18_ — Docs hygiene: STRUCTURE.md "Root Directory" + Pillar 6 reality-check. `docs/STRUCTURE.md` listed three top-level files that don't exist (`GEMINI.md`, root-level `STRUCTURE.md`, `TODO.md`) — replaced with an accurate root listing plus a `docs/` sub-tree that names every doc. Pillar 6 in this file had `nomarchy-welcome`, `docs/TROUBLESHOOTING.md`, and the "docs index" bullet still marked Next despite all three shipping on 2026-04-26 — moved to `(Shipped)`. `nomarchy-manual` bullet's "orphaned reference today" claim was stale (the script is called from `nomarchy-menu` and `nomarchy-theme-install`); rewritten to reflect the real remaining issue — its hardcoded `xdg-open https://learn.omacom.io/2/the-nomarchy-manual` is an Omarchy URL.
+- _2026-05-18_ — Installer state.json is now schema-driven. Replaced the heredoc in `installer/install.sh` that hardcoded the JSON literal (theme/dns/wifi/features/etc.) with a `nix eval` of `lib/state-schema.nix`'s `system` block, overlaid with the installer-chosen timezone. Closes the last source-of-truth split after the centralization batch — adding a new default in the schema now reaches the installer with no further plumbing. Output is identical modulo alphabetical key ordering (Nix's `builtins.toJSON` sorts keys; toggle scripts read/write via `jq` so it's invisible to them). Dry-run path unchanged (still bind-mounts a fake `/mnt` so the generator's absolute paths resolve correctly). `bash -n` + `shellcheck --severity=error` clean.
+- _2026-05-18_ — Complete the hybrid-GPU wiring + fix unoverridable state-derived options. Two related fixes shipped together. **(1)** `nomarchy.system.features.hybridGPU = true` now wires the full NVIDIA driver stack (`services.xserver.videoDrivers = ["nvidia"]`, `hardware.graphics.{enable,enable32Bit}`, `hardware.nvidia.{modesetting,powerManagement}.enable`, `package = nvidiaPackages.stable`, `boot.kernelParams += "nvidia-drm.modeset=1"`) — was previously enabling only `supergfxd` mode-switching while leaving the system with no NVIDIA driver loaded, so mode switches silently no-op'd. All knobs use `lib.mkDefault` so a downstream `system.nix` can pin a beta driver, flip to the open kernel module, etc. Bus-ID prime config (per-machine) stays user-supplied — `docs/OPTIONS.md` has the full recipe. **(2)** Both `core/system/state.nix` and `core/home/state.nix` now use `lib.mkDefault` on every state.json-derived assignment, fixing a class of "I set X in my system.nix but it doesn't take effect" bugs (the state-derived value was at default priority and conflicted with the user's same-priority override). Side-effect cleanup: `core/system/state.nix` now also reads from `lib/state-schema.nix` like `core/home/state.nix` does, completing the schema-centralization started two batches ago. Verified `nix flake check` + an override test that flips hybridGPU via an overlay and confirms the entire driver stack engages.
+- _2026-05-18_ — Pillar 4: pre-flight resume polish. Fixed four resume-flow gaps in `installer/install.sh`: (1) `--resume` with a missing state file now errors loudly with a tmpfs explanation instead of silently falling through to a fresh prompt cycle (the most common operator confusion was "rebooted, forgot tmpfs eats /tmp/, watched the installer start over without realising"); (2) on resume, the saved target drive is validated as a block device before any disk-phase step runs — catches the live-ISO USB-unplugged / non-deterministic /dev/sdX class of mid-install failures; (3) `save_state` now stamps an ISO-8601 timestamp and `load_state` shows a `(saved Xm ago)` banner plus a `Target: /dev/X → user @ host` summary line, so the user can `Ctrl-C` if they're resuming onto the wrong host before any destructive prompt fires; (4) `--help` now documents the tmpfs limitation. `shellcheck --severity=error` passes.
+- _2026-05-18_ — Declarative-state defaults centralization. Made `lib/state-schema.nix` the single source of truth for every state-default that previously lived in three places (the schema itself, `core/system/options.nix` / `core/home/options.nix` `default = …` clauses, and `core/home/state.nix` `or …` fallbacks). Replaced ~25 hardcoded literals with `schema.<scope>.<key>` reads. Side-effect: fixed a lingering bug where `core/home/options.nix:theme` still defaulted to `"summer-night"` after the system-side was moved to `"nord"` — half the codebase's home option resolved to the wrong theme when state.json was missing/blank. `nix flake check --no-build` confirms zero semantic change for every other field. Doesn't touch the installer-written `state.json` (separate batch — needs schema → JSON generation).
+- _2026-05-18_ — Pillar 7 first step: Forgejo Actions CI (eval + lint). New `.forgejo/workflows/check.yml` runs on every push to `main` and every PR: (1) `nix flake check --no-build` to catch eval regressions, (2) `bash -n` + `shellcheck --severity=error` over every `nomarchy-*` bash script (whole-tree, not just changed files — gates branches that bypass the pre-commit hook), (3) `docs/SCRIPTS.md` drift check (fails loudly if a script change didn't regenerate the audit doc). All three checks pass locally on the current tree. Activation requires enabling Actions on the Forgejo repo and registering a `forgejo-runner`; the workflow itself is dormant until then. ISO build job is intentionally deferred — needs a binary cache (Cachix/Attic) to be tractable.
+- _2026-05-18_ — **Pillar 3 Phase B: complete.** Final batch (restart/sudo/theme/misc clusters) cleared the last 13 `unused?` rows. Deleted five truly dead scripts: `nomarchy-restart-{hyprctl,mako}` (theme switching calls `hyprctl reload`/`makoctl reload` directly now), `nomarchy-restart-tmux` (one-liner of marginal value), `nomarchy-battery-present` (battery monitor checks `/sys/class/power_supply/BAT*` inline), `nomarchy-sudo-keepalive` (intended-to-be-sourced building block with no users). Surfaced eight useful tools in `SKILL.md` so the audit catches them as `kept` and AI assistants can discover them: `nomarchy-restart-trackpad` (intel_quicki2c reload), `nomarchy-sudo-{passwordless-toggle,reset}`, `nomarchy-theme-{bg-install,refresh,remove}`, `nomarchy-refresh-fastfetch`, `nomarchy-windows-vm` (new Virtualization section). Final state: 159 scripts, all `kept`, `unused?` = 0, missing references = 0.
+- _2026-05-18_ — Pillar 3 Phase B: webapp/tui/voxtype install-remove pair triage. Deleted two dead webapp URI handlers (`nomarchy-webapp-handler-hey`, `nomarchy-webapp-handler-zoom`) — no `.desktop` MimeType registration anywhere routed `mailto:`/`zoom:` URIs to them, so the handlers could never fire. Surfaced six useful CLI tools in `SKILL.md` "Common Tasks" so they're discoverable by AI assistants and tagged `kept` by the audit: `nomarchy-webapp-{remove,remove-all}`, `nomarchy-tui-{remove,remove-all}`, `nomarchy-voxtype-{install,remove}`. Script count 166 → 164; `unused?` 21 → 13.
+- _2026-05-18_ — Pillar 3 Phase B: dead-code sweep (NixOS-irrelevant Omarchy ports). Deleted five scripts that duplicated NixOS-native facilities or referenced infrastructure Nomarchy doesn't ship: `nomarchy-rollback` (boot-menu generations + `nixos-rebuild rollback` already cover this), `nomarchy-snapshot` (used `snapper`; impermanence and BTRFS subvolumes are the Nomarchy answer), `nomarchy-migrate-state` (one-shot pre-unification migration, no current callers), `nomarchy-config-direct-boot` (added an EFI entry for a UKI we never build), and `nomarchy-npx-install` (Arch idiom — `nix-shell -p nodejs` is the NixOS path). Kept `nomarchy-build-iso` and `nomarchy-build-live-iso` and surfaced them in README §2 so the audit tags them `kept`. Script count 171 → 166.
+- _2026-05-18_ — Pillar 3 Phase B: missing-references triage. (1) Wrote `themes/engine/scripts/nomarchy-theme-next` so `SKILL.md`'s documented "cycle to next theme" command resolves; (2) scrubbed three stale `nomarchy-dev-*` references from `core/home/config/nomarchy-skill/SKILL.md`; (3) added a line-context filter to both `nomarchy-docs-scripts` generators that drops `nomarchy-*` tokens appearing in Nix `pname`/derivation idents, `/tmp/` & `/etc/sudoers.d/` paths, `nixosConfigurations.*` / `packages.*` flake outputs, `mktemp -t` prefixes, systemd unit vars, `./result/bin/run-` binaries, and `docker` container references; (4) added a small token-level denylist for five residual non-script identifiers (`nomarchy-plymouth`, `nomarchy-sddm-theme`, `nomarchy-live`, `nomarchy-rev`, `nomarchy-windows`) that survive line filtering. `docs/SCRIPTS.md` "Missing references" section is now empty (was 15).
+- _2026-05-04_ — Pillar 8: Distro Branding. (1) Scrubbed remaining "Omarchy" and "Spirit of Omarchy" references from README, scripts, and welcome wizard; (2) Updated `nomarchy-welcome` banner and `nomarchy-version` codename ("Sovereign"); (3) Verified existing `core/system/branding.nix` handles OS-release and bootloader labels; (4) Confirmed SDDM and Plymouth metadata are already Nomarchy-branded.
+- _2026-05-04_ — Thorough Out-of-the-Box QA Audit. (1) Restored automatic wallpaper switching by removing image filters from deployed themes; (2) Fixed broken "Style" menu entries by creating missing `about.txt` and `screensaver.txt` branding files; (3) Cleaned up conflicting keybindings by removing deprecated `tiling.conf` and updating the doc generator; (4) Removed legacy Nord theme hack from `nomarchy-theme-set`; (5) Fixed JSON parse error in `summer-day` waybar theme.
+- _2026-05-03_ — Fixed multi-disk LUKS/BTRFS boot hang. (1) Moved temporary LUKS keyfile to `/tmp/` so Disko correctly omits it from the runtime configuration; (2) Injected `x-systemd.requires` and `x-systemd.device-timeout=0` into BTRFS mount options to ensure all LUKS drives are decrypted before mounting.
+- _2026-05-03_ — Fixed CLI wrappers and removed obsolete code. (1) Updated `nomarchy-font`, `nomarchy-theme`, and `nomarchy-wallpaper` CLI wrappers to use modern Walker menus; (2) Removed the obsolete and broken `themes/engine/switcher.nix` and its associated Nix-inlined scripts; (3) Cleaned up remaining `$NOMARCHY_PATH` references from the Omarchy era.
+- _2026-05-03_ — Fixed `/etc/nixos` ownership after installation. Added a `chown -R $USERNAME:users /etc/nixos` step via `nixos-enter` at the end of `installer/install.sh` so the main user owns their configuration and can run `home-manager` commands without `sudo`.
+- _2026-05-01_ — Installer & Script Audit Polish. (1) Fixed a critical bash dynamic scoping bug in `installer/install.sh` where `rc=0` assignments inside functions (Impermanence, Form Factor) were clobbering the main loop's return code, causing the installer to abort when "No" was selected; (2) Polished `hosts/nomarchy-live.nix` with auto-login for the `nixos` user and passwordless sudo for the `wheel` group; (3) Repurposed `nomarchy-toggle-suspend` to execute `systemctl suspend` directly and updated `nomarchy-menu` to reflect this; (4) Updated `nomarchy-launch-wifi` to use `nmtui` in Alacritty; (5) Regenerated `docs/SCRIPTS.md` to reflect the updated script mappings.
+- _2026-04-30_ — `set -e` sweep across `nomarchy-*` scripts. Added `set -e` to 142 of 169 bash scripts that lacked it (27 already had it). Halts a class of "command failed silently in the middle of a chain, system left in half-applied state" bugs that produced repeat-fix commits. One deliberate exception: `nomarchy-menu` runs without `set -e` because it's an interactive UX loop where action failures should re-display the menu rather than abort the script. Pre-commit hook now enforces `bash -n` + `shellcheck --severity=error` so future scripts can't regress this.
+- _2026-04-30_ — Installer disk-phase reliability. Hardened `installer/install.sh` and consolidated the disko configs: (1) `select_disk` now hides the live-ISO boot device(s) so the installer can't format its own boot media (`NOMARCHY_INSTALL_ALLOW_ISO_TARGET=1` to override); (2) added a 10 GiB minimum-capacity preflight; (3) `prewipe_target_drive` enumerates every active dm-crypt mapping backed by the target drive and closes them, drops the silent `|| true` from `wipefs`/`sgdisk`/`dd`, bounds `udevadm settle` to 30s, and refuses to continue if anything is still mounted; (4) wrapped the disko call in `run_disko_with_retry` with last-30-lines + Retry / View full log / Abort dialog on failure; (5) replaced the sed-templated `disko-golden.nix` + `disko-btrfs-multi.nix` pair with a single `disko-config.nix` Nix function called via `--argstr mainDrive … --arg extraDrives '[…]'` — eliminates a class of escaping bugs (cf. `3aadc36`); (6) added an EXIT trap so the tmpfs LUKS key file is removed even on early abort.
+- _2026-04-30_ — Gaming home-side companion. New `nomarchy.gaming.enable` option (mirror of `nomarchy.system.gaming.enable`) and `core/home/gaming.nix` module that injects a Hyprland `windowrulev2 = fullscreen, class:^(steam_app_).*$` so Steam-launched games grab the whole screen. Closes the "Gaming — Hyprland window rule" Next-column row.
+- _2026-04-26_ — Default to highest resolution (`highres`) for monitors. Updated `features/desktop/hyprland/config/monitors.conf` and forced it in the live ISO (`nomarchy-live`) to resolve issues where some hardware would default to a low resolution (1024x768).
+- _2026-04-26_ — First-run welcome wizard (`nomarchy-welcome`). Extended from a one-shot greeter into a guided picker for theme, font, and panel position. Added Step 4 to generate a starter `home.nix` if missing. State is now persisted in `state.json` via `.welcome_done`. Added `nomarchy.panelPosition` option to Waybar.
+- _2026-04-26_ — Multi-disk BTRFS support in the installer. Added `installer/disko-btrfs-multi.nix` template and updated `installer/install.sh` to allow selecting multiple drives via `gum choose --no-limit`. Implements BTRFS "single" data + RAID1 metadata across multiple LUKS-encrypted drives.
+- _2026-04-26_ — Distro Branding Phase 2. Updated bootloader entries to use "Nomarchy" as the label. Set ISO volume IDs to `NOMARCHY_INSTALLER` and `NOMARCHY_LIVE`. Fixed branding in Plymouth theme metadata and SDDM metadata.
+- _2026-04-26_ — Distro Branding Phase 1. Renamed `installerIso` to `nomarchy-installer` and `installerIsoGraphical` to `nomarchy-live`. Updated metadata and host configurations. Scrubbed "Omarchy" from Plymouth and installer messages.
+- _2026-04-26_ — Fix `hardware-db.sh` missing in `nomarchy-installer.nix`. Resolved boot error where `install.sh` failed to source the hardware database on the TTY installer ISO.
+- _2026-04-26_ — Installer review-then-edit flow (`installer/install.sh`). Review screen now offers Continue / Edit a field / Abort. Edit opens a multi-select of saved fields; chosen fields clear and the next loop iteration re-prompts only those. Benefits both fresh installs (typo fixes without abort+restart) and `--resume` (lands on review immediately, since the loaded vars short-circuit each prompt). LUKS passphrase is held in memory across loop iterations so re-edits don't re-ask for it.
+- _2026-04-26_ — `docs/TROUBLESHOOTING.md`. The five most common rebuild errors (option-already-declared, attribute-missing, Stylix target conflict, home-manager `.hm-bak` churn, impermanence path missing) with copy-paste fixes. Linked from `README.md` and `docs/MIGRATION.md`.
+- _2026-04-26_ — Gaming preset module (`core/system/gaming.nix`). Opt-in `nomarchy.system.gaming.enable` (default false). Wires `programs.steam` (with `remotePlay`/`localNetworkGameTransfers` firewall holes via `mkDefault`), `programs.gamemode`, and `services.flatpak`. Flathub remote and Hyprland window-rule split into separate Next-column rows.
+- _2026-04-26_ — Accessibility preset module (`core/system/accessibility.nix`). New `nomarchy.system.accessibility.{enable,cursorSize}` options (opt-in, default off — accessibility isn't a hardware-derived signal). Enables `services.gnome.at-spi2-core`, installs Orca, and sets `XCURSOR_SIZE=32` (configurable). Hyprland-side companion (key-repeat slowdown, Orca keybinding, high-contrast palette) split into a new Next-column row.
+- _2026-04-26_ — Desktop preset module (`core/system/desktop.nix`). New `nomarchy.system.desktop.enable` option; defaults to `formFactor == "desktop"` (mirror of the laptop preset's auto-enable). Pins `powerManagement.cpuFreqGovernor` to `"performance"` and enables `services.zfs.{autoScrub,trim}` so a future ZFS pool gets sensible maintenance for free.
+- _2026-04-26_ — Laptop preset module (`core/system/laptop.nix`). New `nomarchy.system.laptop.{enable,thermald}` options; `enable` defaults to `formFactor == "laptop"` so the installer's existing `formFactor` write auto-flips it on. Wires TLP (governors + 75/80 charge thresholds), force-disables `power-profiles-daemon`, enables `upower` and `thermald` (x86_64), adds the brightnessctl udev rule for backlight without root, and sets a logind lid-switch policy that defers to `hibernation.enable`. Closes both the Now item and the largest Next item.
+- _2026-04-25_ — Software-profile multi-select in the installer. Users can now pick Dev, Gaming, Office, Media, and CLI Utils profiles during install; logic emits corresponding `home.packages` and system toggles into the generated config.
+- _2026-04-25_ — Pillar 3 Phase B: script & menu audit. Ported/implemented/stubbed ~40 scripts including `nomarchy-version`, `nomarchy-debug`, `nomarchy-reinstall`, `nomarchy-rollback`, `nomarchy-update-firmware`, `nomarchy-pkg-*`, and `nomarchy-theme-*` wrappers. Moved desktop scripts to packaged utility directory.
+- _2026-04-25_ — Docker & fwupd support. Added `nomarchy.system.virtualization.docker.enable` and `nomarchy.hardware.fwupd` options. Wires system services and adds `docker-compose` and `fwupdmgr` to PATH.
+- _2026-04-25_ — Installer VM testing. Added `installerVm` to flake nixosConfigurations, packages, and apps. `nomarchy-test-installer` now uses `nix run .#installerVm`.
 - _2026-04-25_ — `docs/KEYBINDINGS.md` auto-generator. New repo-tooling script `bin/utils/nomarchy-docs-keybindings` parses every `bindd =` / `bindeld =` line into a Markdown doc; README's keybinding table slimmed to highlights + link.
 - _2026-04-25_ — Installer disk picker shows NAME / SIZE / TYPE / VENDOR / MODEL / SERIAL columns instead of bare `lsblk`. Type derived from `ROTA` + `TRAN` (NVMe / USB / SSD / HDD). Filters loop, ram, zram, sr.
 - _2026-04-25_ — Pillar 3 Phase A: script & menu audit. New `bin/utils/nomarchy-docs-scripts` generator produces `docs/SCRIPTS.md` with 136 scripts and the menu walk pre-tagged via heuristics (`kept` / `unused?` / `missing`). Phase B (per-batch porting / removal) opens.